Runtime Prune
Intro
runtime-prune gives agents a provider-neutral cleanup workflow for
runtime-manager-owned state. It inventories selected cleanup scopes,
produces a dry-run plan, applies low-risk processkit-owned cleanup from
an explicit allowlist, and returns structured host-action evidence for
high-risk runtime-owner cleanup. It does not invoke host orchestrator
commands from inside the processkit runtime.
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 may remove
only explicit processkit-owned allowlist targets; provider/runtime
owner cleanup returns an external host-action result for the owner.
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) |
Apply processkit allowlist cleanup and return external host-action evidence for unsupported scopes. |
Scopes
| Scope |
What it covers |
Apply policy |
runtime-home |
Bounded runtime-home cache, diagnostics, tmp, and runtime paths. |
Processkit allowlist cleanup. |
build-cache |
Explicit build-cache paths such as Rust incremental and build subdirectories. |
Processkit allowlist cleanup. |
agent-worktrees |
Provider-created or runtime-manager-owned Git worktrees discovered from Git metadata. |
External host action after explicit confirmation. |
containers |
Host runtime container cleanup. |
External host action; no direct Docker or Podman calls. |
e2e-companion |
Nested companion environment cleanup. |
External host action; companion access must use owner-approved reachability checks. |
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.
apply_prune() may
clean processkit-owned allowlist targets, but worktrees, containers,
and companion state must return structured external host-action
evidence instead of invoking a host orchestrator command.
- Do not remove the whole runtime home.
runtime-home targets only
narrow cache, diagnostics, tmp, and runtime subpaths, not the whole
.aibox-home tree.
- Do not inspect local Docker or Podman for E2E companion cleanup.
Companion state is remote from the devcontainer's perspective; use
the owner-approved host workflow that checks 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 the host
runtime manager 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, apply_owner,
expected_reclaim_bytes, targets, dry_run_command, and
apply_command
apply_prune() accepts only the exact required_confirmation value
from the matching plan. For runtime-home and build-cache, it removes
only the allowlisted paths from the plan. For external scopes, it records
per-scope host-action evidence and leaves execution to the owner outside
the container.
1---2name: runtime-prune-23description: Inspect, plan, and invoke safe cleanup for runtime-manager-owned state without binding the workflow to a specific host orchestrator or agent provider.4---5
6# Runtime Prune
7
8## Intro
9
10`runtime-prune` gives agents a provider-neutral cleanup workflow for
11runtime-manager-owned state. It inventories selected cleanup scopes,
12produces a dry-run plan, applies low-risk processkit-owned cleanup from
13an explicit allowlist, and returns structured host-action evidence for
14high-risk runtime-owner cleanup. It does not invoke host orchestrator
15commands from inside the processkit runtime.
16
17## Overview
18
19Use this skill when a project has accumulated runtime-home caches,
20build caches, agent worktree state, container storage, or E2E companion
21state and the user wants to inspect or reclaim disk space safely.
22
23The workflow is:
24
251. Call `analyze_disk_usage(project_root, scopes)` to inventory
26 configured cleanup scopes without modifying the filesystem.
272. Call `plan_prune(project_root, scopes)` to produce a dry-run plan,
28 expected reclaimed bytes, risk labels, and the exact confirmation
29 token needed for apply.
303. Call `apply_prune(project_root, scopes, confirmation)` only after
31 the user has explicitly approved the plan. The apply tool may remove
32 only explicit processkit-owned allowlist targets; provider/runtime
33 owner cleanup returns an external host-action result for the owner.
34
35### MCP Tools
36
37| Tool | Purpose |
38|---|---|
39| `analyze_disk_usage(project_root, scopes)` | Return structured size and risk data for selected cleanup scopes. |
40| `plan_prune(project_root, scopes)` | Return a dry-run prune plan and required confirmation token. |
41| `apply_prune(project_root, scopes, confirmation)` | Apply processkit allowlist cleanup and return external host-action evidence for unsupported scopes. |
42
43### Scopes
44
45| Scope | What it covers | Apply policy |
46|---|---|---|
47| `runtime-home` | Bounded runtime-home cache, diagnostics, tmp, and runtime paths. | Processkit allowlist cleanup. |
48| `build-cache` | Explicit build-cache paths such as Rust incremental and build subdirectories. | Processkit allowlist cleanup. |
49| `agent-worktrees` | Provider-created or runtime-manager-owned Git worktrees discovered from Git metadata. | External host action after explicit confirmation. |
50| `containers` | Host runtime container cleanup. | External host action; no direct Docker or Podman calls. |
51| `e2e-companion` | Nested companion environment cleanup. | External host action; companion access must use owner-approved reachability checks. |
52
53## Gotchas
54
55- **Do not treat analysis as approval.** `analyze_disk_usage()` and
56 `plan_prune()` are read-only. Apply still needs the exact confirmation
57 token returned by the plan.
58- **Do not hand-roll destructive provider cleanup.** `apply_prune()` may
59 clean processkit-owned allowlist targets, but worktrees, containers,
60 and companion state must return structured external host-action
61 evidence instead of invoking a host orchestrator command.
62- **Do not remove the whole runtime home.** `runtime-home` targets only
63 narrow cache, diagnostics, tmp, and runtime subpaths, not the whole
64 `.aibox-home` tree.
65- **Do not inspect local Docker or Podman for E2E companion cleanup.**
66 Companion state is remote from the devcontainer's perspective; use
67 the owner-approved host workflow that checks reachability.
68- **Do not count arbitrary project files as reclaimable.** Only
69 explicitly scoped runtime and cache paths contribute to expected
70 reclaimed bytes.
71- **Do not delete provider worktrees by path heuristics.** Worktrees
72 are inventoried for visibility, but deletion is delegated to the host
73 runtime manager because it owns provider-specific safety checks.
74- **Keep paths provider-neutral in user-facing output.** Report scopes
75 like `agent-worktrees` and `runtime-home`, not Claude-, Codex-, or
76 shell-specific state unless a discovered path itself contains that
77 name.
78
79## Full reference
80
81`analyze_disk_usage()` resolves `project_root` to an existing directory
82and defaults to all scopes when none are supplied. It never follows
83symlinks during size walks.
84
85`plan_prune()` returns:
86
87- `required_confirmation`, formatted as
88 `apply-prune:<comma-separated-scopes>`
89- per-scope actions with `risk`, `apply_owner`,
90 `expected_reclaim_bytes`, `targets`, `dry_run_command`, and
91 `apply_command`
92
93`apply_prune()` accepts only the exact `required_confirmation` value
94from the matching plan. For `runtime-home` and `build-cache`, it removes
95only the allowlisted paths from the plan. For external scopes, it records
96per-scope host-action evidence and leaves execution to the owner outside
97the container.
projectious-work