Runtime Prune
Intro
runtime-prune gives agents a provider-neutral cleanup workflow for
aibox-managed runtime state. It inventories selected cleanup scopes,
produces a dry-run plan, and invokes aibox prune for the destructive
path when that command is available.
Overview
Use this skill when a project has accumulated runtime-home caches,
build caches, agent worktree state, container storage, or E2E companion
state and the user wants to inspect or reclaim disk space safely.
The workflow is:
- Call
analyze_disk_usage(project_root, scopes) to inventory
configured cleanup scopes without modifying the filesystem.
- Call
plan_prune(project_root, scopes) to produce a dry-run plan,
expected reclaimed bytes, risk labels, and the exact confirmation
token needed for apply.
- Call
apply_prune(project_root, scopes, confirmation) only after
the user has explicitly approved the plan. The apply tool delegates
to aibox prune; it does not duplicate destructive provider cleanup
logic inside processkit.
MCP Tools
| Tool |
Purpose |
analyze_disk_usage(project_root, scopes) |
Return structured size and risk data for selected cleanup scopes. |
plan_prune(project_root, scopes) |
Return a dry-run prune plan and required confirmation token. |
apply_prune(project_root, scopes, confirmation) |
Invoke aibox prune with approved scopes and return command evidence. |
Scopes
| Scope |
What it covers |
Apply policy |
runtime-home |
Managed .aibox-home and bounded .aibox runtime cache or diagnostics paths. |
Delegated to aibox prune. |
build-cache |
Explicit build-cache paths such as Rust incremental and build subdirectories. |
Delegated to aibox prune. |
agent-worktrees |
Provider-created or aibox-managed Git worktrees discovered from Git metadata. |
Delegated to aibox prune after explicit confirmation. |
containers |
aibox-owned container cleanup. |
Delegated to aibox prune; no direct Docker or Podman calls. |
e2e-companion |
Nested companion environment cleanup. |
Delegated to aibox prune; companion access must be via SSH reachability. |
Gotchas
- Do not treat analysis as approval.
analyze_disk_usage() and
plan_prune() are read-only. Apply still needs the exact confirmation
token returned by the plan.
- Do not hand-roll destructive provider cleanup. If
aibox prune
is unavailable, apply_prune() must return an error instead of
deleting worktrees, containers, or caches itself.
- Do not inspect local Docker or Podman for E2E companion cleanup.
Companion state is remote from the devcontainer's perspective; use
the aibox workflow that checks SSH reachability.
- Do not count arbitrary project files as reclaimable. Only
explicitly scoped runtime and cache paths contribute to expected
reclaimed bytes.
- Do not delete provider worktrees by path heuristics. Worktrees
are inventoried for visibility, but deletion is delegated to aibox
because it owns provider-specific safety checks.
- Keep paths provider-neutral in user-facing output. Report scopes
like
agent-worktrees and runtime-home, not Claude-, Codex-, or
shell-specific state unless a discovered path itself contains that
name.
Full reference
analyze_disk_usage() resolves project_root to an existing directory
and defaults to all scopes when none are supplied. It never follows
symlinks during size walks.
plan_prune() returns:
required_confirmation, formatted as
apply-prune:<comma-separated-scopes>- per-scope actions with
risk, expected_reclaim_bytes, targets,
dry_run_command, and apply_command
- whether
aibox prune is currently available on PATH
apply_prune() accepts only the exact required_confirmation value
from the matching plan. If the token matches and aibox prune is on
PATH, it runs:
aibox prune --scope <scope> ... --yes --json
The tool records stdout, stderr, exit code, and the command arguments in
the returned evidence. A non-zero aibox prune exit code is returned to
the caller as structured evidence instead of being hidden.
1---2name: runtime-prune-33description: Inspect, plan, and invoke safe cleanup for aibox-managed runtime state without binding the workflow to a specific agent provider.4---56# Runtime Prune78## Intro910`runtime-prune` gives agents a provider-neutral cleanup workflow for11aibox-managed runtime state. It inventories selected cleanup scopes,12produces a dry-run plan, and invokes `aibox prune` for the destructive13path when that command is available.1415## Overview1617Use this skill when a project has accumulated runtime-home caches,18build caches, agent worktree state, container storage, or E2E companion19state and the user wants to inspect or reclaim disk space safely.2021The workflow is:22231. Call `analyze_disk_usage(project_root, scopes)` to inventory24 configured cleanup scopes without modifying the filesystem.252. Call `plan_prune(project_root, scopes)` to produce a dry-run plan,26 expected reclaimed bytes, risk labels, and the exact confirmation27 token needed for apply.283. Call `apply_prune(project_root, scopes, confirmation)` only after29 the user has explicitly approved the plan. The apply tool delegates30 to `aibox prune`; it does not duplicate destructive provider cleanup31 logic inside processkit.3233### MCP Tools3435| Tool | Purpose |36|---|---|37| `analyze_disk_usage(project_root, scopes)` | Return structured size and risk data for selected cleanup scopes. |38| `plan_prune(project_root, scopes)` | Return a dry-run prune plan and required confirmation token. |39| `apply_prune(project_root, scopes, confirmation)` | Invoke `aibox prune` with approved scopes and return command evidence. |4041### Scopes4243| Scope | What it covers | Apply policy |44|---|---|---|45| `runtime-home` | Managed `.aibox-home` and bounded `.aibox` runtime cache or diagnostics paths. | Delegated to `aibox prune`. |46| `build-cache` | Explicit build-cache paths such as Rust incremental and build subdirectories. | Delegated to `aibox prune`. |47| `agent-worktrees` | Provider-created or aibox-managed Git worktrees discovered from Git metadata. | Delegated to `aibox prune` after explicit confirmation. |48| `containers` | aibox-owned container cleanup. | Delegated to `aibox prune`; no direct Docker or Podman calls. |49| `e2e-companion` | Nested companion environment cleanup. | Delegated to `aibox prune`; companion access must be via SSH reachability. |5051## Gotchas5253- **Do not treat analysis as approval.** `analyze_disk_usage()` and54 `plan_prune()` are read-only. Apply still needs the exact confirmation55 token returned by the plan.56- **Do not hand-roll destructive provider cleanup.** If `aibox prune`57 is unavailable, `apply_prune()` must return an error instead of58 deleting worktrees, containers, or caches itself.59- **Do not inspect local Docker or Podman for E2E companion cleanup.**60 Companion state is remote from the devcontainer's perspective; use61 the aibox workflow that checks SSH reachability.62- **Do not count arbitrary project files as reclaimable.** Only63 explicitly scoped runtime and cache paths contribute to expected64 reclaimed bytes.65- **Do not delete provider worktrees by path heuristics.** Worktrees66 are inventoried for visibility, but deletion is delegated to aibox67 because it owns provider-specific safety checks.68- **Keep paths provider-neutral in user-facing output.** Report scopes69 like `agent-worktrees` and `runtime-home`, not Claude-, Codex-, or70 shell-specific state unless a discovered path itself contains that71 name.7273## Full reference7475`analyze_disk_usage()` resolves `project_root` to an existing directory76and defaults to all scopes when none are supplied. It never follows77symlinks during size walks.7879`plan_prune()` returns:8081- `required_confirmation`, formatted as82 `apply-prune:<comma-separated-scopes>`83- per-scope actions with `risk`, `expected_reclaim_bytes`, `targets`,84 `dry_run_command`, and `apply_command`85- whether `aibox prune` is currently available on `PATH`8687`apply_prune()` accepts only the exact `required_confirmation` value88from the matching plan. If the token matches and `aibox prune` is on89`PATH`, it runs:9091```sh92aibox prune --scope <scope> ... --yes --json93```9495The tool records stdout, stderr, exit code, and the command arguments in96the returned evidence. A non-zero `aibox prune` exit code is returned to97the caller as structured evidence instead of being hidden.
projectious-work