The workflow

This is what the census skill tells an agent to do. Every command takes --json and prints one JSON document: read exit_code and errors, not the text.

Before you start

1. Run census version --json. If the command isn’t found, tell the person Disk Census isn’t installed or census isn’t on PATH, and stop.
2. Work on the whole startup drive, the default. Add --path FOLDER only when the person names a folder, and use the same scope for every step.

Clean junk

When the person asks to clean junk, caches or build output:

1. Run census clean --safe --json. It deletes only the safe tier: caches, build output, logs and old versions that rebuild themselves. Being asked to clean junk is the person’s approval for this tier, so don’t ask again.
2. Report the result in one line, from results: freed bytes, used space before and after, and how many items were skipped.
3. If results.review.items is more than 0, go on to review what’s left.

census clean --safe --json

{
  "schema_version": 5,
  "command": "clean",
  "status": "ok",
  "exit_code": 0,
  "errors": [],
  "warnings": [],
  "results": {
    "freed_bytes": 2041856000,
    "used_before_bytes": 50146312192,
    "used_after_bytes": 48104456192,
    "audit": { "display": "/Users/me/Library/Application Support/census/audit/clean-1790950000000.ndjson", "lossy": false },
    "items": ["…"],
    "review": { "review_id": "rv-1790950000000-1a2b3c4d", "items": 14, "allocated_bytes": 6300000000 }
  }
}

If the exit code isn’t 0, report errors[0].message and stop. cleanup_running means another cleanup is running: wait for it, and don’t retry in a loop.

Review what’s left

1. Run census review --json.
2. Show the person every item: its number, allocated_bytes in a readable size, path, title and reason, largest first, as listed. Items with selectable: false can only be chosen in census review in a terminal.
3. Ask which to delete. Don’t suggest any: the person decides.

census review --json

{
  "results": {
    "review_id": "rv-1790950000000-1a2b3c4d",
    "items": [
      {
        "path": "/Users/me/proj/foo/target",
        "selectable": true,
        "kind": "folder",
        "rule": "cargo.target",
        "title": "Cargo build output",
        "reason": { "kind": "needs_review" },
        "allocated_bytes": 3100000000
      }
    ]
  }
}

Delete what the person chose

1. Write a JSON array of exactly the chosen path strings, copied from review --json without changes, to a new temporary file.
2. Show the final list and its total once, and ask: “Permanently delete these N items (X GB)?” Wait for an explicit yes.
3. Run census apply FILE --json.
4. Report the freed bytes, and every item whose outcome.result isn’t deleted, with its reason.

cat > /tmp/census-selection.json <<'EOF'
["/Users/me/proj/foo/target", "/Users/me/Downloads/Xcode_15.xip"]
EOF
census apply /tmp/census-selection.json --json

If apply fails with review_stale, run census review --json again and show the person the new list. Never retry with different paths without asking again.

Remove duplicate files

1. Run census duplicates --json. Show each set in results.groups: its size, reclaimable_bytes, and every member’s path. Members marked clone: true share storage, so removing them frees little.
2. Ask which copies to delete, or which to keep. At least one copy of every set must stay; census skips a copy whose set would lose every copy.
3. Write the chosen members’ paths to a selection file, confirm once (“Permanently delete these N copies (X GB)?”), then run census apply FILE --json.
4. Report the freed bytes, and every copy whose outcome.result isn’t deleted.

census duplicates --under ~/Downloads --json

Find large or old files

1. Run census large --json, adding --min-size SIZE, --not-opened DAYS or --folders when the person asks for them. Show each of results.items: path.display, allocated_bytes in a readable size, and opened_unix_ms as a date, or “never opened” when it is null. Items with selectable: false are kept by a rule: say so, and don’t offer them.
2. Ask which to delete. Don’t suggest any: these are the person’s own files.
3. Write exactly the chosen path.display strings to a selection file, confirm once (“Permanently delete these N items (X GB)?”), then run census apply FILE --json.
4. Report the freed bytes, and every item whose outcome.result isn’t deleted, with its reason.

census large --min-size 1G --not-opened 365 --json

Uninstall an app

1. Run census app NAME --json and show what an uninstall removes: the app, and each leftovers item with confidence high or medium that is neither shared nor needs_admin. Show the other items as kept.
2. Ask once: “Uninstall NAME and delete its data (X GB)?” Wait for an explicit yes. If the person wants a different set, list exactly those paths, the app’s own path among them.
3. Run census uninstall NAME --yes --json, adding the chosen paths as arguments when the person changed the set.
4. Report the freed bytes and results.kept. On app_running, ask the person to quit the app. Never quit it yourself.

census app Slack --json
census uninstall Slack --yes --json

Speed up or fix the Mac

1. Run census maintain --json and show the tasks that match the problem, with fixes, interrupts and restart.
2. Ask which to run. Before running them, say that snapshots deletes local Time Machine snapshots and that finder stops a copy in progress.
3. Run census maintain TASK ... --yes --json with exactly the chosen tasks.
4. Report each task’s result and detail, and results.restart if it isn’t empty.

census maintain --json
census maintain quicklook open-with --yes --json

census optimize --yes --json deletes the safe tier and runs the quick tasks. Use it only when the person asks to optimize or clean up everything, after showing what it does.

Empty the Trash

1. Run census empty-trash --json. Without --yes it only lists. Show results.count, and allocated_bytes in a readable size for each of results.trashes, by name. If the person wants to see or choose items, show each Trash’s items: name, size, and trashed_unix_ms as a date.
2. Ask once: “Permanently delete N items (X GB) from the Trash?”, naming what stays if the person chose. Wait for an explicit yes.
3. Run census empty-trash --yes --json, adding the chosen items[].path strings as arguments when the person chose only some. Report the freed bytes, and every item whose outcome.result isn’t deleted, with its reason.
4. On trash_unreadable, report the message: the app running census needs Full Disk Access.

Never empty the Trash as part of cleaning junk or optimizing, only when the person asks for it.

AI agents’ own data

For the space AI coding agents take, run census findings --category ai_agents --json. Their history has safety: keep and is never deleted. See Cleaning agent data.