Troubleshooting#

First moves, ordered by how often each symptom turns up. The permissions page has the full TCC reference behind the permission rows.

Symptom	First move
`bite: command not found` after install	`$CARGO_HOME/bin` not on `PATH`
helper install fails in setup	read the rendered error's fix (usually `xcode-select --install`), retry `bite setup`
install refuses a `swift` on `PATH`	intentional: the PATH entry is writable or foreign — use the stock toolchain (`xcode-select`)
agent doesn't list bite tools	restart the CLI; then `bite doctor` (client lines)
setup exit 2	read the stderr summary — fix the named config, re-run (details)
permission denied on a call	`bite doctor --fix`; the full flows
Mail tools work but indexing fails (`bite doctor` exits 2 on the crawler line)	crawler TCC identity — approve the Mail automation prompt once from your terminal; see macOS 27+
`Could not script Messages. Is it installed?`	launch Messages once — the error is `app_not_running`, not a permission problem
a Mail call answers `deferred: true` with an `indexing_in_progress` hint	the first crawl is still walking Mail — retry soon (the index serves it instantly), or re-call with `force_live: true` to accept a slow live query
`helper_exited` on a call	the native helper process died mid-call; read-only tools are retried transparently, mutating ones return a not-replayed error with a re-check hint (why)
indexing stuck in `waiting_mail`	Mail isn't answering Apple Events — launch Mail, then `bite index rebuild`; the state heartbeats for 24 h before failing
search returns nothing right after install	the index is still crawling; live tools keep working meanwhile, and `bite index status` shows progress
slow first `bite` command after install	the helper compiles once during `bite setup`; later starts are instant
`target/` in a bite checkout is many GB	normal Cargo behavior — `cargo clean` and rebuild; `bite doctor` reports the build tree's size and when cleaning is worth it

When nothing else helps#

bite doctor --json — the whole environment as one object (helper, per-app states, storage, clients). Its problems count is the fastest triage.
bite index status — rows per app, crawl state, pending batches, and a hint when something needs action.
The entity index page covers rebuilds, deltas, purges and wipes; the architecture page explains what each process does, so log lines have context.

bite deliberately runs no shell, no dynamic code, and keeps all state in one directory — when in doubt, bite doctor first, delete ~/Library/Application Support/bite last.