Skip to content
AI agentsOverview

Census for AI agents

Let your AI coding agent free disk space with census. It reads freely, deletes only what you approve, and the engine enforces the limits even if the agent gets it wrong.

View as Markdown
On this page

How it works

Your agent runs the same census commands you would, with --json, and reads the results. The census skill, which Disk Census installs for you, tells it the steps: clean the safe tier when you ask, show you everything else, and delete only what you choose.

It works with Claude Code, Codex, Cursor, Gemini CLI and any other agent that can run commands in your terminal. Setup takes one switch in the app.

What you can ask for

You askThe agent runsIt deletes
“What’s taking up space?”breakdown, top, findingsNothing
“Clean up junk.”clean --safeThe safe tier: caches, build output, logs, old agent versions
“What else could go?”reviewNothing, until you pick items
“Remove the duplicates in Downloads.”duplicates, then applyOnly the copies you pick
“Find big files I don’t use.”large, then applyOnly the files you pick
“Uninstall Slack.”app, then uninstallThe app and its data, after you say yes
“My Mac is slow.”maintainOnly the tasks you pick
“Empty the Trash.”empty-trashThe Trash, after you say yes

An example

Example conversation
You    Clean up my Mac.

Agent  census clean --safe --json
       Freed 2.0 GB: used space went from 46.7 GB to 44.7 GB. 2 items were in use and skipped.

       census review --json
       14 more items need your judgment (6.3 GB). The largest:
         1   3.1 GB   ~/proj/foo/target          Cargo build output
         2   1.4 GB   ~/Downloads/Xcode_15.xip   Installer in Downloads
       Which of these should I delete?

You    Just the Xcode installer.

Agent  Permanently delete this 1 item (1.4 GB)?

You    Yes.

Agent  census apply /tmp/census-selection.json --json
       Deleted ~/Downloads/Xcode_15.xip and freed 1.4 GB.

Asking it to clean junk is your approval for the safe tier, so it doesn’t ask again. Everything else waits for your choice, and the agent asks once more, with the total, before it deletes anything.

What keeps it safe

The skill tells the agent what to do. The engine makes sure it can’t do worse, whatever the agent decides:

  • Deletion is permanent, so the agent never deletes without your yes, except the safe tier when you asked it to clean.
  • It can delete only what census listed. apply refuses any path that isn’t in the newest review set, duplicate search or Large Files listing, and rejects the whole file if one path is wrong.
  • It rechecks every item on a fresh scan, and skips anything that changed or is in use.
  • It never uses rm, sudo or Finder. census refuses to delete as root, and the rules forbid other tools.
  • Your agents’ history stays. Conversations and sessions are listed with their size, never offered. See Cleaning agent data.
  • Your agent still asks you before each command, if it is set up to. The skill doesn’t pre-approve any command.

Rules for agents is the full list, written for the agent to read.

Next steps

  • Setup: turn on census for your agents and check that they can run it.
  • The workflow: each request, step by step, with the commands and JSON.
  • census serve: talk to the engine from your own program.

Updated · census JSON schema 5