Setup

Turn on census for your agents

Open Disk Census, go to the CLI and Agents tab, and turn on the command line. The app adds census to your shell and installs the census skill: the instructions your agent follows to clean safely. There is nothing else to download or buy.

census and the skill update with the app.

Check that your agent can run census

Start a new agent session, so it picks up the skill and the new PATH, and ask it:

Run census version --json and tell me the version.

The agent should run the command and get one JSON document back:

{
  "schema_version": 5,
  "command": "version",
  "status": "ok",
  "exit_code": 0,
  "errors": [],
  "warnings": [],
  "scan": null,
  "results": { "version": "0.1.0", "schema_version": 5 }
}

If the agent reports command not found, check that the command line is on in the CLI and Agents tab, then restart the agent’s terminal or app. The skill tells agents to stop and say so when census is missing, rather than look for another way to delete files.

Give it Full Disk Access

census gets Full Disk Access from whatever started it, and an agent starts it from its own terminal or app. Without access, scans can’t read folders such as Mail, Messages and Safari, and can’t read the Trash, so empty-trash stops with trash_unreadable.

To give access, add the app your agent runs in (Terminal, iTerm, your editor, or the agent’s desktop app) under System Settings › Privacy & Security › Full Disk Access, then restart it. Ask your agent to check:

census access --json

results.status should be granted.

Keep approvals on

Most agents ask before they run a command. Keep that on for the commands that delete: clean, apply, uninstall, optimize, empty-trash and maintain with tasks. Queries such as findings, top, large, duplicates and review --json only read, so approving them freely is safe.

The census skill doesn’t approve anything on its own. Your agent’s permission prompt is an extra check on top of the agent asking you in the conversation.

Agents without skills

Any agent that can run commands can use census, even one that doesn’t read skills. Point it at the rules, which are also available as plain Markdown. For example, in your project’s AGENTS.md:

## Disk space

Before cleaning or deleting anything on this Mac, read
https://diskcensus.com/docs/agents/rules.md and follow it exactly.
Use only census commands to delete files.