Doctor

The suv doctor command runs a series of health checks on your Suvadu installation and reports pass, warning, or fail for each component. Use it to diagnose setup issues, then confirm each repair by recording a real command.

Usage

suv doctor

Doctor reports problems but does not repair your rc file, hooks, or client configuration. Repairs are listed below.

Example Output

Doctor reports in two groups. Required for shell history capture covers what every setup needs; Optional integrations has one row per AI agent, and only the agents you actually use need to pass. A healthy Zsh setup on macOS with Claude Code in use (synthetic values):

Suvadu Doctor

Required for shell history capture
  Shell ................. ✓ zsh 5.9 (minimum: 5.1)
  Shell hooks ........... ✓ found in ~/.zshrc
  Config ................ ✓ valid (~/Library/Application Support/tech.appachi.suvadu/config.toml)
  Database .............. ✓ healthy — schema v9, 18204 entries
  Recording ............. ✓ enabled in config
  Capture evidence ...... ✓ most recent record received 2 minutes ago, from this shell session

Optional integrations (only the ones you actually use need to pass)
  Claude Code ........... ✓ in use — 1342 commands captured
      process: detected · integration: installed · commands: 1342 · native sessions: 87 · MCP: registered
  Codex ................. ○ not in use (optional: suv init codex)
  Cursor ................ ○ not in use (optional: suv init cursor)
  Antigravity ........... ○ not in use (optional: suv init antigravity)
  OpenCode .............. ○ not in use (optional: suv init opencode)
  pi.dev ................ ○ not in use (optional: suv init pi)

Verify capture end-to-end
  1. In the shell you want recorded, run:  echo suvadu-capture-check
  2. Search for it:                        suv get suvadu-capture-check
  3. Confirm the stored record:            suv history --limit 3

  7 passed, 0 warnings, 0 failed, 5 not configured (optional)

The same machine after the shell hook line was removed from ~/.zshrc, the shell was paused, and the suv binary was moved. Every problem gets a line under Repairs:

Suvadu Doctor

Required for shell history capture
  Shell ................. ✓ zsh 5.9 (minimum: 5.1)
  Shell hooks ........... ✗ no `suv init` line in ~/.zshrc
  Config ................ ✓ valid (~/Library/Application Support/tech.appachi.suvadu/config.toml)
  Database .............. ✓ healthy — schema v9, 18204 entries
  Recording ............. ⚠ paused in this shell
  Capture evidence ...... ⚠ hook observed earlier (newest record 3 hours old) — not verified since

Optional integrations (only the ones you actually use need to pass)
  Claude Code ........... ✗ integration installed but broken: claude-code-post-tool.sh: saved binary is missing and suv is not on PATH
      process: detected · integration: installed but broken · commands: 1342 · native sessions: 87 · MCP: registered
  …

Repairs
  Shell hooks: add to ~/.zshrc: eval "$(suv init zsh)", then start a new shell
  Recording: unset SUVADU_PAUSED …
  Claude Code: re-run suv init claude-code
  …

The exact wording of each repair line depends on your shell and setup. Agents you do not use show ○ not in use, which is not a failure.

What Gets Checked

Check	What It Verifies	What It Does Not Prove
Shell	The login shell in `$SHELL` is Zsh 5.1+ or Bash 4.0+	Which shell the current terminal is running
Shell hooks	The text `suv init` appears in `~/.zshrc` (Zsh) or `~/.bashrc` (Bash)	That the hook loaded in this terminal, or that a startup file such as `~/.bash_profile` reads `~/.bashrc`
Config	`config.toml` parses, or no file exists and defaults are in use	Project-level `.suvadu.toml` overrides
Database	The database exists, opens, reports a schema version, and passes `PRAGMA integrity_check`; shows the entry count	That new commands are being added
Recording	Recording is enabled in the config and `SUVADU_PAUSED` is not set in this shell	That the hook captured anything
Capture evidence	Whether a record captured by a shell hook has arrived, how long ago, and whether it came from this shell session. Imported or restored history never counts as capture	That the command you are about to run will be recorded — run the verification sequence for that
One row per agent (Claude Code, Codex, Cursor, Antigravity, OpenCode, pi.dev)	Whether the agent is running, whether its integration is installed (and, for hook scripts, that each is executable and points at a `suv` binary that exists), how many of its commands were captured, how many native sessions were captured (Claude Code, Codex and OpenCode), and whether Suvadu's MCP server is registered (read for Claude Code in `~/.claude.json` and Cursor in `~/.cursor/mcp.json`)	That the running agent loaded its hooks or MCP server, or that you have reviewed and trusted them where the agent asks

An agent row passes once commands from that agent have been captured. One you have not set up and are not running is reported as not in use, never as a failure. Doctor does not read the Codex or OpenCode MCP configuration (their rows say MCP: not supported); suv init codex writes ~/.codex/config.toml and suv init opencode writes ~/.config/opencode/opencode.jsonc. See Agent Setup.

Configuration is not capture. Before 0.4.2, suv status announced that history was being recorded whenever recording was enabled and not paused — even in a terminal where the hook never loaded. It now reports Recording: (what the config says) and Capture: (whether a record arrived, how long ago, and whether it came from this shell) as two independent facts, and suv doctor separates blockers from optional integrations. A command that appears in history is still the end-to-end proof. Use the check below after every repair.

Confirm Recording Works

Run these in a new terminal window, so it loads your current rc file:

echo suvadu-check
suv history -n 3

The first line of the suv history output should be the echo you just ran:

2026-09-19 10:42:07  ✓        2ms  ~/projects/app        echo suvadu-check

If it is missing, run echo $SUVADU_SESSION_ID. An empty result means the shell hook did not load in this terminal. See a new command does not appear in Troubleshooting.

Repair Steps by Check

Shell

⚠ fish — shell capture supports zsh and bash only — Recording requires Zsh or Bash; agent capture does not depend on your shell. Run Suvadu from a Zsh or Bash shell, or change your login shell with chsh -s /bin/zsh.
✗ bash 3.2 is below minimum 4.0 — Common on macOS, which ships Bash 3.2. The Bash hook does not load below 4.0. Install a newer Bash (for example brew install bash) and make it your login shell, or use Zsh.

Confirm: open a new terminal and run suv doctor. The Shell line should show ✓.

Shell hooks

✗ no `suv init` line in ~/.zshrc — Add the line once, then start a new shell:
```
echo 'eval "$(suv init zsh)"' >> ~/.zshrc
source ~/.zshrc
```
For Bash, use suv init bash and ~/.bashrc.
⚠ ~/.bashrc not found or unreadable — Create ~/.bashrc with the Bash line above. If your terminal opens login shells, make sure ~/.bash_profile sources ~/.bashrc. See Shell Integration.

Confirm: run the recording check in a new terminal. A ✓ on this line only means the text is in the file.

Config

✗ with a parse error — The message names the problem in config.toml. Fix the TOML syntax at that location. If you cannot find it, copy the file somewhere safe and remove the original; Suvadu then uses defaults until you restore your settings.

Confirm: suv doctor shows valid (…) or using defaults (no config file).

Database

⚠ not created yet (no command has been recorded) — Nothing has been recorded yet. Fix any Shell hooks failure, then run a command in a new terminal.
✗ cannot open: … mentioning a newer schema version — A newer Suvadu build has already upgraded the database. Upgrade this binary (suv update or brew upgrade suvadu). Run which -a suv to find older copies earlier on your PATH.
✗ integrity check failed — Do not delete the database. Close your terminals, copy the database file (its path is shown by suv status), and open an issue. suv gc --vacuum compacts a healthy database but does not repair corruption.

Confirm: suv doctor shows healthy, and the entry count goes up after the recording check.

Recording

⚠ paused in this shell — This shell was paused with eval $(suv pause), which sets SUVADU_PAUSED=1. suv enable does not clear that variable, and since 0.4.2 suv doctor says so in its repair line. Run unset SUVADU_PAUSED in that terminal, or open a new terminal.
✗ disabled in config — Recording is off globally. Run suv enable.

Confirm: the Recording line shows enabled in config, then run the recording check.

Capture evidence

⚠ configuration present, capture not yet verified or not yet verified — no captured command found — No record from a shell hook has arrived yet. Fix any Shell hooks or Recording problem above, then run the verification sequence doctor prints in a new terminal.
⚠ not yet verified — all … stored shell record(s) came from an import — Imported history is stored history, not proof that this machine records. Run the verification sequence.
⚠ hook observed earlier … not verified since or a record arrived … but from another shell — Capture worked in the past or in another terminal, but not provably in this one. Check that this shell loaded the hook (echo $SUVADU_SESSION_ID is not empty), then run the verification sequence here.

Confirm: re-run suv doctor; Capture evidence shows most recent record received … ago, from this shell session.

Agent integrations

Each agent has its own row. Only the agents you use need attention.

○ not in use (optional: suv init …) — Nothing to do unless you want that agent's commands captured.
⚠ running, but the integration is not installed — The agent is running but suv init <agent> has not been run. Run it, then restart the agent.
⚠ integration installed, nothing captured yet — Restart the agent, ask it to run a harmless command, and re-run suv doctor. For Codex, review and trust the hooks in /hooks first.
⚠ running, nothing captured yet (Antigravity) — Its terminal is captured by the shell hooks, so there is nothing to install: open a new terminal inside it.
✗ integration installed but broken: <script>: saved binary is missing…, script is not executable or unrecognized hook script — Usually happens after suv moved (for example, switching from Cargo to Homebrew). Re-run the suv init <agent> command named in the repair line; it rewrites the scripts with the current binary path.
MCP: not registered or MCP: cannot read config (…) in the row's details (Claude Code and Cursor) — Run suv init <agent>; if the client's config file is not valid JSON, fix it first. If the entry exists but points to an old suv path, suv init does not replace it; see stale MCP configuration.

Confirm: fully quit and restart the agent (including VS Code, if it runs there), ask it to run a harmless command, and check it appears with suv history --executor agent -n 3; its doctor row then shows in use. For MCP, check that the client lists the suvadu server, then ask it a history question such as “What were my last three commands?” If commands appear but prompts or session fields do not, see missing agent fields.

Status Icons

✓ — Check passed
⚠ — Warning (something to check or finish setting up)
✗ — Failed (something is broken and needs fixing)
○ — Not configured (an optional integration you are not using)

Still stuck? Troubleshooting covers each symptom separately: Ctrl+R opening the wrong tool, commands not being recorded, stale binaries, missing imports, hidden agent commands, and MCP configuration.