Disk Census documentation
census is the engine inside Disk Census, as a command. Use it from your terminal and your scripts, or let your AI agent free space with it, with your approval at every step.
Command line
Every census command, its options and its JSON, for your terminal and your scripts.
Get started
- Overviewcensus is the Disk Census engine as a command. It runs the app's scan, findings and cleanup from your terminal, your scripts and your AI agents.
- QuickstartScan your Mac, see what is using the space, clean what is safe and review the rest, in five steps.
- Scans and scopesWhat census scans, how to choose a scope, where the saved scan lives, and how queries reuse it.
Concepts
- Safety and deletionWhat census reads, what it can delete, how it asks, and the checks every item passes before it is deleted.
- JSON outputEvery command's --json output is one envelope on stdout, with the same fields for every command. Read it from scripts, and follow long jobs with progress events.
- Exit codes and errorsWhat each census exit code means, every error code it can report, and what to do about each one.
Commands
- Seeing what uses spaceScan a scope, then ask the saved scan where the space went, by folder, file, bucket, file type and over time.
- Finding what to removeFind cleanup candidates, large and forgotten files, duplicate copies, and apps with their leftovers. Every command here only reads.
- Cleaning upDelete the safe tier, choose from what needs review, delete exact paths from a selection file, empty the Trash, and uninstall apps.
- MaintenanceList and run the maintenance tasks, such as rebuilding Quick Look's cache or deleting local snapshots, and optimize the Mac in one step.
- Reports and exportsSave a scan as JSON, Markdown, a self-contained HTML page or CSV, with home-folder names hidden when you share it.
- UtilitiesCommand syntax and help, Full Disk Access checks, versions, the self-test, and census serve.
AI agents
How Claude Code, Codex, Cursor and other agents free space with census, and only with your approval.
Get started
- OverviewLet 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.
- SetupTurn on census for your AI agents in the Disk Census app, check that your agent can run it, and give it the access it needs.
Using census
- The workflowEach request an agent handles with census, step by step: the commands it runs, what it shows the person, and when it must ask.
- Rules for agentsThe rules an AI agent follows when it frees disk space with census. Written for the agent to read, and complete on its own.
- Cleaning agent dataWhat census finds in the folders AI coding agents use, what it deletes, and what it never touches, agent by agent.
Docs for agents
Every page is also plain Markdown, for AI agents and LLMs. Add .md to a page's address, or ask for it with an Accept: text/markdown header. /docs.md lists every page, and /llms.txt describes the app.
# The rules an agent follows, as Markdown
curl https://diskcensus.com/docs/agents/rules.md
# The same page, asked for by type
curl -H 'Accept: text/markdown' https://diskcensus.com/docs/agents/rules