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

A healthy Zsh setup on macOS with Claude Code connected (synthetic values):

Suvadu Doctor

  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 ............. ✓ active
  MCP (Claude Code) ..... ✓ registered in ~/.claude.json
  MCP (Cursor) .......... ⚠ not registered (run: suv init cursor)
  Agent hooks ........... ✓ 4 executable hook script(s), binary paths available

  7 passed, 1 warnings, 0 failed

The same machine after the shell hook line was removed, a shell was paused, and the suv binary was moved:

Suvadu Doctor

  Shell ................. ✓ zsh 5.9 (minimum: 5.1)
  Shell hooks ........... ✗ not found in ~/.zshrc (add: eval "$(suv init zsh)")
  Config ................ ✓ valid (~/Library/Application Support/tech.appachi.suvadu/config.toml)
  Database .............. ✓ healthy — schema v9, 18204 entries
  Recording ............. ⚠ paused (run: suv enable)
  MCP (Claude Code) ..... ✓ registered in ~/.claude.json
  MCP (Cursor) .......... ⚠ not registered (run: suv init cursor)
  Agent hooks ........... ✗ claude-code-post-tool.sh: saved binary is missing and suv is not on PATH (run: suv init claude-code)

  3 passed, 2 warnings, 2 failed

An MCP warning only matters if you use that client. Cursor shows a warning until you run suv init cursor, even if you never use Cursor.

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 globally and `SUVADU_PAUSED` is not set in this shell	That the hook captured anything
MCP (Claude Code)	`~/.claude.json` has an `mcpServers.suvadu` entry	That the running client loaded it
MCP (Cursor)	`~/.cursor/mcp.json` has an `mcpServers.suvadu` entry	That the running client loaded it
Agent hooks	Every `.sh` script in `~/.config/suvadu/hooks/` is executable and points to a `suv` binary that still exists	That the agent has registered or trusted the hooks

Doctor does not check Codex or OpenCode MCP registration. suv init codex writes ~/.codex/config.toml and suv init opencode writes ~/.config/opencode/opencode.jsonc; see Agent Setup for those clients.

Doctor and suv status check settings, not capture. suv status prints “History IS being recorded” whenever recording is enabled and not paused — even in a terminal where the hook never loaded. The only proof is a command that appears in history. 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 (only zsh and bash are supported) — Recording requires Zsh or Bash. 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

✗ not found in ~/.zshrc — Add the line once, then reload:
```
echo 'eval "$(suv init zsh)"' >> ~/.zshrc
source ~/.zshrc
```
For Bash, use suv init bash and ~/.bashrc.
⚠ ~/.bashrc not found — 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 found (run some commands first) — 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 (run: suv enable) — This shell was paused with eval $(suv pause), which sets SUVADU_PAUSED=1. In Suvadu 0.4.1, suv enable does not clear that variable. Run unset SUVADU_PAUSED in that terminal, or open a new terminal.
✗ disabled (run: suv enable) — Recording is off globally. Run suv enable.

Confirm: the Recording line shows active, then run the recording check.

MCP (Claude Code / Cursor)

⚠ not registered (run: suv init …) — Run the command shown, for example suv init claude-code. It also installs that agent's hooks.
⚠ cannot parse ~/.claude.json — The client's config file is not valid JSON. Fix the file first, then rerun suv init.

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 client (including VS Code, if the agent runs there). Check that the client lists the suvadu MCP server, then ask it a history question, such as “What were my last three commands?”

Agent hooks

⚠ no hook scripts or cannot read hooks directory — No agent integration is installed. This is expected if you only want shell history. Otherwise, run suv init <agent>.
✗ saved binary is missing…, script is not executable, or unrecognized hook script — Usually happens after suv moved (for example, switching from Cargo to Homebrew). Rerun the suv init <agent> command named in the message. It rewrites the scripts with the current binary path.

Confirm: suv doctor shows binary paths available. Restart the agent (for Codex, review and trust the hooks in /hooks first). Ask it to run a harmless command, then check it appears with suv history --executor agent -n 3. If commands appear but prompts or session fields do not, see missing agent fields.

Status Icons

✓ — Check passed
⚠ — Warning (not configured, or an optional component is missing)
✗ — Failed (something is broken and needs fixing)

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.