get_storage_use
Read what komrad takes on disk in the latest measurement, against the storage limit, split into each worktree and komrad's own parts with the largest entries in each part's directory, with each worktree's place in the storage candidate list, the worktrees komrad keeps and why, and the worktrees it deleted today.
read-onlyidempotentMCP toolSystem
Calling it#
curl -X POST http://127.0.0.1:8787/komrad.system.v1.SystemService/GetStorageUse \
-H 'Content-Type: application/json' \
-d '{}'komrad rpc get-storage-use{
"name": "get_storage_use",
"arguments": {}
}Offered by the komrad MCP server to writer, reviewer, orchestrator agents.
Request#
Empty#
No fields.
Response#
GetStorageUseResponse#
| Field | Type | Description |
|---|---|---|
limit_bytes | int64 | The storage limit. Zero when no limit is set. |
total_bytes | int64 | What every part takes together. |
measured_at | timestamp | When komrad measured it. |
parts | StorageOwner[] | Every part, largest first. |
kept | KeptWorktree[] | The archived tasks' worktrees komrad won't delete, longest archived first. |
deleted | DeletedWorktree[] | The worktrees komrad deleted since midnight, newest first. |
shrunk | ShrunkWorktree[] | The worktrees komrad shrank since midnight, newest first. |
pressure | LimitPressure | How close the latest measurement stands to the storage limit, with a tenth of the limit as its margin. |
Types#
StorageOwner#
StorageOwner is a worktree or a part of komrad's own share, with what it takes on disk.
| Field | Type | Description |
|---|---|---|
part | StoragePart | Which part this is. |
dir | string | The directory the part was measured under. |
size_bytes | int64 | What the part takes on disk. |
task_id | string | The task the worktree belongs to. Set only on a worktree. |
last_active_at | timestamp | When an agent last worked in the worktree. Set only on a worktree. |
candidate | StorageCandidate | Where the worktree stands in the storage candidate list. Unset on a part that isn't in it. |
contents | Entry[] | The largest entries at the top of the directory, largest first. Set only on a part of komrad's own share. |
content_count | int32 | How many entries sit at the top of the directory. Set only on a part of komrad's own share. |
KeptWorktree#
KeptWorktree is an archived task's worktree komrad won't delete, since deleting it would lose work.
| Field | Type | Description |
|---|---|---|
task_id | string | The task the worktree belongs to. |
dir | string | The worktree's directory. |
size_bytes | int64 | What the worktree takes on disk. |
reason | string | Why deleting the worktree would lose work. |
checked_at | timestamp | When komrad last asked git about the worktree. |
DeletedWorktree#
DeletedWorktree is an archived task's worktree komrad deleted.
| Field | Type | Description |
|---|---|---|
task_id | string | The task the worktree belonged to. |
dir | string | The worktree's directory. |
freed_bytes | int64 | What the worktree took on disk. |
reason | WorktreeDeleteReason | Why komrad deleted it. |
deleted_at | timestamp | When komrad deleted it. |
ShrunkWorktree#
ShrunkWorktree is an archived task's worktree komrad shrank.
| Field | Type | Description |
|---|---|---|
task_id | string | The task the worktree belongs to. |
dir | string | The worktree's directory. |
freed_bytes | int64 | What shrinking the worktree freed on disk. |
shrunk_at | timestamp | When komrad shrank it. |
StorageCandidate#
StorageCandidate is where a worktree stands in the storage candidate list, the ranked list of archived tasks' worktrees komrad deletes to keep under its storage limit.
| Field | Type | Description |
|---|---|---|
place | int32 | Where the worktree stands in the list, from 1 for the worktree komrad deletes first. |
rule | StorageRule | The rule that put the worktree there. |
Entry#
Entry is one file or directory in a measured directory, with the largest of what it holds.
| Field | Type | Description |
|---|---|---|
path | string | The entry's path, relative to the directory or entry holding it. |
size_bytes | int64 | The disk space the entry takes, in bytes, counting blocks and each hard-linked file once. |
dir | bool | Whether the entry is a directory. |
children | Entry[] | The largest entries the directory holds, largest first, down to three levels below the measured directory. Empty on a file. |
LimitPressure#
LimitPressure is how close komrad stands to a memory or storage limit.
StoragePart#
StoragePart is one part of komrad's disk use.
WorktreeDeleteReason#
WorktreeDeleteReason is why komrad deleted an archived task's worktree.
| Value | Description |
|---|---|
over_limit | Komrad took more disk than its storage limit. |
past_max_age | The task stayed archived past |
StorageRule#
StorageRule is why the storage candidate list ranks a worktree where it does, the first rule it matched.