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.