komrad

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 '{}'

Request#

Empty#

No fields.

Response#

GetStorageUseResponse#

FieldTypeDescription
limit_bytesint64

The storage limit. Zero when no limit is set.

total_bytesint64

What every part takes together.

measured_attimestamp

When komrad measured it.

partsStorageOwner[]

Every part, largest first.

keptKeptWorktree[]

The archived tasks' worktrees komrad won't delete, longest archived first.

deletedDeletedWorktree[]

The worktrees komrad deleted since midnight, newest first.

shrunkShrunkWorktree[]

The worktrees komrad shrank since midnight, newest first.

pressureLimitPressure

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.

FieldTypeDescription
partStoragePart

Which part this is.

dirstring

The directory the part was measured under.

size_bytesint64

What the part takes on disk.

task_idstring

The task the worktree belongs to. Set only on a worktree.

last_active_attimestamp

When an agent last worked in the worktree. Set only on a worktree.

candidateStorageCandidate

Where the worktree stands in the storage candidate list. Unset on a part that isn't in it.

contentsEntry[]

The largest entries at the top of the directory, largest first. Set only on a part of komrad's own share.

content_countint32

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.

FieldTypeDescription
task_idstring

The task the worktree belongs to.

dirstring

The worktree's directory.

size_bytesint64

What the worktree takes on disk.

reasonstring

Why deleting the worktree would lose work.

checked_attimestamp

When komrad last asked git about the worktree.

DeletedWorktree#

DeletedWorktree is an archived task's worktree komrad deleted.

FieldTypeDescription
task_idstring

The task the worktree belonged to.

dirstring

The worktree's directory.

freed_bytesint64

What the worktree took on disk.

reasonWorktreeDeleteReason

Why komrad deleted it.

deleted_attimestamp

When komrad deleted it.

ShrunkWorktree#

ShrunkWorktree is an archived task's worktree komrad shrank.

FieldTypeDescription
task_idstring

The task the worktree belongs to.

dirstring

The worktree's directory.

freed_bytesint64

What shrinking the worktree freed on disk.

shrunk_attimestamp

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.

FieldTypeDescription
placeint32

Where the worktree stands in the list, from 1 for the worktree komrad deletes first.

ruleStorageRule

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.

FieldTypeDescription
pathstring

The entry's path, relative to the directory or entry holding it.

size_bytesint64

The disk space the entry takes, in bytes, counting blocks and each hard-linked file once.

dirbool

Whether the entry is a directory.

childrenEntry[]

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.

ValueDescription
under

Komrad takes less than the limit less its margin, or no limit is set.

near

Komrad takes more than the limit less its margin, and less than the limit.

over

Komrad takes the limit or more.

StoragePart#

StoragePart is one part of komrad's disk use.

ValueDescription
worktree

One worktree directory.

postgres

The embedded Postgres's data directory.

cache

Everything under komrad's cache directory.

state

Everything under komrad's state directory outside the worktrees and the embedded Postgres.

WorktreeDeleteReason#

WorktreeDeleteReason is why komrad deleted an archived task's worktree.

ValueDescription
over_limit

Komrad took more disk than its storage limit.

past_max_age

The task stayed archived past archived_worktree_max_age.

StorageRule#

StorageRule is why the storage candidate list ranks a worktree where it does, the first rule it matched.

ValueDescription
landed

Nothing in the worktree is uncommitted, and its base branch holds every commit.

merged

Nothing in the worktree is uncommitted, and a pull request on its task merged.

committed

Nothing in the worktree is uncommitted, and it holds commits its base branch lacks.