Skip to content
AI agentsRules for agents

Rules for agents

The rules an AI agent follows when it frees disk space with census. Written for the agent to read, and complete on its own.

View as Markdown
On this page

Disk Census deletes permanently: nothing goes to the Trash. These rules keep every deletion a choice the person made. If you are an agent, follow them exactly; the steps for each request are in The workflow.

Before you run anything

  • Run census version --json. If census isn’t found, tell the person Disk Census isn’t installed or isn’t on PATH, and stop.
  • Use the whole startup drive, the default. Add --path FOLDER only when the person names a folder, and keep the same scope for every step.
  • Pass --json to every command. Read exit_code and errors from the JSON, not the text.

What needs the person’s yes

ActionApproval
Queries: breakdown, top, findings, large, duplicates, apps, app, review --json, maintain --json, empty-trash --jsonNone. They only read.
census clean --safeThe person asked you to clean junk, caches or build output. That request is the approval; don’t ask again.
census apply FILEThe person chose the items, then said yes to “Permanently delete these N items (X GB)?”
census uninstall NAME --yesThe person said yes to “Uninstall NAME and delete its data (X GB)?”
census maintain TASK ... --yesThe person chose the tasks.
census optimize --yesThe person asked to optimize or clean up everything, after you showed what it does.
census empty-trash --yesThe person asked to empty the Trash, then said yes to “Permanently delete N items (X GB) from the Trash?”

When you list items for the person to choose from, don’t suggest any. The person decides.

Never

  • Never put a path in a selection file that review --json, duplicates --json or large --json didn’t list. census refuses it anyway.
  • Never pass --safe unless the person asked you to clean, and never pass --yes to uninstall before the person said yes.
  • Never delete files with rm, trash, Finder, or any tool other than census’s own commands.
  • Never run census with sudo. It refuses to delete as root.
  • Never run census maintain with tasks, or census optimize, before the person said yes.
  • Never retry a failed apply with different paths without asking the person again.
  • Never empty the Trash as part of cleaning junk or optimizing.
  • Never quit an app yourself. On app_running, ask the person to quit it.
  • Never delete an AI agent’s history. census lists it as keep and never offers it.

Exit codes

CodeMeaningWhat to do
0Done. Skipped items are normal.Report the result.
1Bad request: confirmation_required, invalid_selection, review_stale, run_as_root, app_running, needs_admin, system_app, not_removable. Nothing was deleted.On review_stale, run census review --json again and show the new list. Otherwise report errors[0].message.
2Operational failure: cleanup_running, cleanup_failed, scan_failed, trash_unreadable.On cleanup_running, wait; don’t retry in a loop. Otherwise report the message.
4partial_cleanup: some items couldn’t be fully deleted. app_not_removed: the app stayed.Report each item whose outcome.result isn’t deleted, or the reason the app stayed.
7no_review: nothing to apply.Run census review --json first.
130Cancelled.Tell the person. What was deleted so far is in the audit log.

Why these rules hold

census doesn’t rely on you for safety. Whatever you run, apply deletes only paths census itself listed, every item is rechecked on a fresh scan, items in use are skipped, protected and synced folders are refused, and nothing runs as root. The rules above make sure that what census does delete is what the person chose.

Updated · census JSON schema 5