# 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.

## 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](https://diskcensus.com/docs/agents/setup.md) takes one switch in the app.

## What you can ask for

| You ask | The agent runs | It deletes |
| --- | --- | --- |
| "What's taking up space?" | `breakdown`, `top`, `findings` | Nothing |
| "Clean up junk." | `clean --safe` | The safe tier: caches, build output, logs, old agent versions |
| "What else could go?" | `review` | Nothing, until you pick items |
| "Remove the duplicates in Downloads." | `duplicates`, then `apply` | Only the copies you pick |
| "Find big files I don't use." | `large`, then `apply` | Only the files you pick |
| "Uninstall Slack." | `app`, then `uninstall` | The app and its data, after you say yes |
| "My Mac is slow." | `maintain` | Only the tasks you pick |
| "Empty the Trash." | `empty-trash` | The Trash, after you say yes |

## An example

```text title="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](https://diskcensus.com/docs/agents/agent-data.md).
- **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](https://diskcensus.com/docs/agents/rules.md) is the full list, written for the agent to read.

## Next steps

- [Setup](https://diskcensus.com/docs/agents/setup.md): turn on census for your agents and check that they can run it.
- [The workflow](https://diskcensus.com/docs/agents/workflow.md): each request, step by step, with the commands and JSON.
- [census serve](https://diskcensus.com/docs/agents/serve.md): talk to the engine from your own program.