# The workflow

> Each request an agent handles with census, step by step: the commands it runs, what it shows the person, and when it must ask.

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](#review).

```sh
census clean --safe --json
```

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

```sh
census review --json
```

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

```sh
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`.

```sh
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.

```sh
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.

```sh
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.

```sh
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](https://diskcensus.com/docs/agents/agent-data.md).