Kitlight for coding agents
Kitlight can tell a coding agent what its work left on this Mac, and let the agent hand a cleanup plan to its
user. The agent never deletes anything: the person approves the plan in the Kitlight app, Kitlight rechecks every
item, and the agent reads back a receipt. Plans, receipts and the MCP server are part of Kitlight Pro;
explain_item and the read-only CLI are free.
Connect
# Claude Code
claude mcp add kitlight -- /Applications/Kitlight.app/Contents/MacOS/kitlight-cli mcp
Any MCP client works the same way: the server is kitlight-cli mcp on stdio (newline-delimited JSON-RPC 2.0).
Optional, for exact ownership evidence: Kitlight › Settings › Coding sessions › Connect Claude Code… adds two
hooks (SessionStart, SessionEnd) that record each session's processes and temporary folders. The sheet shows the
exact commands, backs up ~/.claude/settings.json first, and Disconnect removes exactly those entries. Without
hooks, sessions are read from the tools' own transcript files (marked inferred).
Tools
| Tool | Pro | What it does |
|---|---|---|
plan_cleanup {project?, session?} |
✓ | Read-only scan of the AI checks; returns the plan id, a kitlight://plan/<id> link, each item with its owner, confidence (session / project / none) and evidence, what is kept and why, and checks that couldn't run. |
open_plan {plan_id} |
✓ | Opens the plan in Kitlight. Safe items start ticked, Check first ones don't; anything that changed since the plan is left alone. |
get_receipt {plan_id, wait_seconds?} |
✓ | pending until the user is done; then cleaned or declined with approved / unticked / skipped items, space cleared, what went to the Trash and the disk's free-space change, plus a one-sentence summary. |
explain_item {path} |
Which project and session a path belongs to, how Kitlight knows, and which processes are using it right now. |
A suggested flow for an agent finishing a task: plan_cleanup with the project path → tell the user what's in it →
open_plan → get_receipt with wait_seconds → pass the receipt's summary on.
Command line
kitlight-cli scan --json # every check: items, kept items with reasons, unavailable checks
kitlight-cli clean --recipe ai.scratch --json # dry run, saved as a plan (prints its id)
kitlight-cli clean --plan <id> --yes # clean exactly that plan; prints a receipt (new/changed items stay)
kitlight-cli plan --project ~/Code/app --json # (Pro) project-scoped plan for hand-off
kitlight-cli receipt <id> --wait 300 # (Pro) what the user did with it
kitlight-cli session list [--json] # recorded (●) and inferred (○) sessions
kitlight-cli license <key> # check a Kitlight Pro key offline
Exit codes: 0 ok, 2 usage, 3 needs Kitlight Pro. Without the app's settings (CI, another account), set
KITLIGHT_LICENSE to a licence key; it is verified like any other.
JSON shapes
plan_cleanup / plan --json:
{ "plan": "37a14e9d", "openURL": "kitlight://plan/37a14e9d", "bytes": 1691648, "project": "/Users/me/Code/app",
"items": [{ "id": "…", "label": "…", "bytes": 0, "recipe": "ai.checkpoints", "path": "…",
"owner": "Claude Code session · ended 42 minutes ago", "confidence": "session",
"why": ["The Claude Code session 7f3a2c had this folder open (recorded when it ended)."] }],
"kept": [{ "id": "…", "label": "app-wt · fix", "recipe": "ai.worktrees", "reason": "Has files git ignores, like .env …" }],
"unavailable": [{ "recipe": "ai.models", "reason": "Ollama isn't installed." }] }
Receipt:
{ "plan": "37a14e9d", "status": "cleaned", "approved": 3, "unticked": ["…"], "skipped": {"…": "Changed since the preview"},
"cleared": 630000000, "movedToTrash": 0, "freeSpaceChange": 612000000, "failures": {},
"summary": "Tidied 3 items (630 MB); free space changed by +612 MB. The user kept 1 item." }
Everything stays on this Mac: no network calls, no account.