# BurnZombies agent setup

Canonical guide: https://raw.githubusercontent.com/swordfish444/BurnZombies/main/llms.txt
Repository: https://github.com/swordfish444/BurnZombies
Requires macOS 14+, Apple Silicon or Intel. Claude Code or Codex is optional: with one installed and signed in, BurnZombies (BZ) uses it to judge new things; without one, BZ still cleans with its own rules and the operator's answers.

## Rules

- Install and configure only what the operator asked for. Setup is not cleanup: never start a sweep (Hunt Zombies, `autopilot sweep`), answer a question, burn, restore or stop anything as an installation test. Never turn look-only off: Start burning is the operator's decision.
- Do not change credentials, account routing, global MCP configuration, chat hooks or shell profiles. Preserve the operator's tool, model and thinking choices.
- If a login, usage limit or permission is refused, stop and report it. Never fall back to another tool or account.
- Never disable Gatekeeper, remove quarantine metadata or grant macOS permissions yourself. Report steps that need the human.

## Install

Check `sw_vers -productVersion` (14 or later), then `claude --version` and `codex --version`. A CLI being present doesn't prove it is signed in. Download, inspect, then run the installer:

```sh
installer="$(mktemp -t burnzombies-installer)"
curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/swordfish444/BurnZombies/main/install.sh -o "$installer"
bash "$installer"
rm "$installer"
```

- Default (`--mcp auto`): Claude Code if installed, otherwise Codex. If the operator named one, add `--mcp claude` or `--mcp codex`.
- Neither installed: run the same command. AI judging stays off. Once the operator installs and signs in to one, run `"$HOME/Applications/BurnZombies.app/Contents/MacOS/burnzombies" setup`.
- `--look-only`: BZ finds, sizes and asks as usual but burns nothing until the operator chooses Start burning in the menu (or picks another level in Settings). Add it if the operator wants to see what BZ would burn first. Works with every `--mcp` choice.
- `--observe-only`: AI judging off. Not a dry run: the starter rules and the operator's answers still burn. Add it only if the operator asks; `burnzombies setup --with-ai` turns it back on.
- `--no-open`: install without starting the app.

The installer checks the release checksum, archive paths and bundle signature, installs `~/Applications/BurnZombies.app` (or `$BURNZOMBIES_INSTALL_DIR`; substitute that path below if the operator set it) and starts it in the menu bar. No account, API key or sudo. Releases are not notarized; if macOS blocks opening, report the exact prompt.

## Verify (read-only)

```sh
bz="$HOME/Applications/BurnZombies.app/Contents/MacOS/burnzombies"
"$bz" version
"$bz" doctor
"$bz" access-status
"$bz" autopilot
```

- `doctor`: `appResponding` and `runningAppMatchesCLI` must be true. `configuredHarness` is `claude`, `codex` or `none`; `backgroundReviewsEnabled` says whether AI judging is on. It never starts the AI or a burn, and can't prove a login. An old or mismatched running app is not a verified update.
- `access-status`: Full Disk Access state.
- `autopilot`: snapshot of counts, open questions and rules; changes nothing. Empty counts in the first minute are not a failure; the first look may still be running. `lookOnly: true` means every burn is held.

## Tell the operator what happens next

- BZ looks right away and every minute for its first half hour. Within about a minute the menu-bar panel (the skull) shows how much it found, and "BZ has N quick questions" when something needs a decision.
- Installed with `--look-only`, nothing burns on its own (not the rules below, not yes answers, not the AI) until the operator chooses Start burning in the menu-bar panel; then BZ starts burning what waited right away. The panel says "Look-only · nothing burns" and how much it would burn.
- Otherwise, from the first minute, starter rules burn on their own (each can be switched off in Settings → Burns without asking):
  - programs whose app or chat is gone, idle 6+ hours, with no open port (a program that has barely used the CPU since it started counts as idle from its start);
  - old project copies (git worktrees) already merged, unchanged and untouched for a month, always backed up first;
  - rebuildable folders (node_modules, build output) inside copies untouched for two weeks.
- Everything else becomes a one-tap yes/no question. Yes burns all the matches now and later; No keeps them.
- With Claude Code or Codex, the first AI sweep starts about 10 minutes after install. After that, sweeps run when there is something new to judge, at most every 30 minutes, rechecking every 4 hours, each capped at 15 minutes. The AI may burn on its own only an orphaned program with no open port, a known junk folder, or a copy nothing uses that wasn't made by Codex, Claude or Conductor.
- A new install starts at login, so a restart doesn't stop BZ; macOS shows a notice when BZ adds itself to login items. Settings → Start at login turns that off, and updates keep that choice. An install updated from v0.13.0 or earlier keeps its old setting: off unless the operator turned it on.
- Never asked about or touched: macOS, apps, anything a running chat is working in, main project folders.
- Undo: old copies restore from Findings for 30 days (restore points are `refs/burnzombies/retired/…` in each repository; ignored files over 5 MB aren't saved). Junk folders are rebuilt by the operator's tools. Programs get SIGTERM, which can't be undone.

## Cost

Claude Code uses Sonnet by default; Codex uses its own default. Roughly $0.30–$1.20 per AI sweep on API pricing; on a Claude or ChatGPT subscription it uses plan usage instead. Looking around between sweeps uses no AI. Model: How smart in Settings. AI off: Which AI → Off in Settings, or `"$bz" setup --observe-only` (back on: `--with-ai`); the Autopilot switch in the menu (or Off in Settings) pauses all of Autopilot; it's on from install. Spend: Settings → Used this week.

## Full Disk Access (optional, human only)

Without it, BZ covers everything except the places macOS protects (Desktop, Documents, Downloads, iCloud Drive, Mail, Messages, Photos, other apps' data, external drives) and says what it skipped. With it, those are covered too. AI sweeps run either way. Granting it needs the human: Allow Full Disk Access in the menu-bar banner, or System Settings → Privacy & Security → Full Disk Access → enable BurnZombies. If macOS asks again after an update, re-enable it there. `"$bz" access-check` re-verifies an existing grant; it cannot grant access.

## Update

Read `version`, `doctor` and `access-status` first. Rerun the inspected installer without `--mcp`: it keeps the selected tool, model, thinking level, on/off state, Start at login and look-only. Add `--observe-only` or `--look-only` only if the operator asks. If the selected tool is missing, setup stops; it never switches tools. The installer closes only its own previous app and refuses a forced replacement.

On an explicit request to change tool or model:

```sh
"$bz" setup --harness claude        # or: --harness codex
"$bz" setup --model MODEL_ID --thinking high
"$bz" setup --model default --thinking default
```

Setup writes only BZ's private configuration, keeps unspecified settings and never grants cleanup. Run `doctor` afterward.

## How each tool runs

- Claude Code: each sweep runs the installed CLI with its existing login, a private MCP config, read-only file tools (no shell, no edits), no hooks, no CLAUDE.md files and no saved session. No edits to ~/.claude.json or ~/.claude/settings.json.
- Codex: each sweep runs an owned, bounded Codex session with only BZ's MCP tools; apps, plugins, memories, shell and web search are off. No global Codex config edits.
- Only Claude Code and Codex run AI sweeps. Do not run the legacy `install` or `install-skill` commands for normal setup.

## Uninstall

1. Ask the operator to switch off Settings → Start at login (it needs the human). Then `"$HOME/Applications/BurnZombies.app/Contents/MacOS/burnzombies" stop-observer "$HOME/Applications/BurnZombies.app"`
2. Delete `~/Applications/BurnZombies.app`.
3. Delete `~/Library/Application Support/BurnZombies`.

If the app was deleted first and BurnZombies is still listed in System Settings → General → Login Items, the operator can remove it there.

Restore points stay in each repository and are the only way back for burned copies. Delete them only if the operator asks, inside the repository: `git for-each-ref --format='%(refname)' refs/burnzombies/ | xargs -n1 git update-ref -d`

## More read-only commands

- `findings [OFFSET]`: the advanced findings inbox; blocked or unknown is not zero.
- `evidence PID [PID ...]`: up to 16 exact process identities; sends no signals.
- `status`: saved totals; does not prove the app is running.

Report installation, AI judging on/off, Full Disk Access and what Autopilot found separately. Destructive tests must use sacrificial targets, never real work.

User guide: https://github.com/swordfish444/BurnZombies/blob/main/docs/USER_GUIDE.md
Autopilot: https://github.com/swordfish444/BurnZombies/blob/main/docs/AUTOPILOT.md
Install & uninstall: https://github.com/swordfish444/BurnZombies/blob/main/docs/INSTALL.md
Safety: https://github.com/swordfish444/BurnZombies/blob/main/docs/SAFETY.md