Fix Missing History and Agent Capture

Find your symptom below. Each fix follows the same steps: check what is happening, repair only the part that is broken, and verify the fix with a result you can see. None of these fixes deletes history or replaces your shell startup files. This page describes Suvadu 0.4.1.

Before you start

suv --version    # the version you are running
suv status       # recording enabled/paused, database path, and number of recorded commands
suv doctor       # shell version, hooks line, config, database integrity, MCP registration, agent hook scripts

These checks have limits. suv status reports whether recording is turned on and not paused; it does not check whether commands are actually being captured. suv doctor confirms that your shell startup file contains suv init. It checks MCP registration only for Claude Code and Cursor. It checks hook scripts only in ~/.config/suvadu/hooks/, which covers Claude Code, Codex, and Cursor. It does not check the OpenCode plugin, the pi.dev extension, or the Codex MCP entry. The visible test at the end of each fix below is what confirms it worked.

Ctrl+R opens the wrong tool or native search

Check. Ask your shell which command Ctrl+R runs:

bindkey '^R'                   # Zsh: expect  "^R" suvadu-search
bind -X | grep -F '\C-r'       # Bash 4.3+: expect __suvadu_search_widget

If the result names another tool, or a built-in search such as history-incremental-search-backward, then either something bound Ctrl+R after Suvadu, or Suvadu's hook never loaded. The last binding set during shell startup wins. Search your startup file for other history tools:

grep -n 'suv init\|bindkey\|bind -x\|fzf\|atuin\|mcfly\|hstr' ~/.zshrc    # or ~/.bashrc

Suvadu's widget also falls back to the shell's own reverse search in three cases: no terminal device is readable, the suv binary cannot be found (see stale binary path), or recording is disabled (suv disable) or paused in this shell. In Bash, the widget does nothing in those cases.

Repair. Pick one history tool to own Ctrl+R. To make it Suvadu, move eval "$(suv init zsh)" (or bash) below the other tool's line, or comment out the other tool's key binding. Change only that line. If recording is disabled, run suv enable; if this shell is paused, run unset SUVADU_PAUSED. To undo, move the line back.

Verify. Open a new terminal, run bindkey '^R' (Zsh) or bind -X | grep -F '\C-r' (Bash) again, then press Ctrl+R. The Suvadu search screen should open.

History is enabled but a new command does not appear

Check. Run each of these in the shell that should be recording:

suv status                        # "Global Config: Enabled" and "Current Session: Active"?
echo "$SUVADU_PAUSED"             # empty means not paused
echo "$SUVADU_SESSION_ID"         # must not be empty
type _suvadu_precmd               # Zsh: the recording hook exists in this shell
type __suvadu_precmd              # Bash: the recording hook exists in this shell
echo $ZSH_VERSION $BASH_VERSION   # hooks require Zsh 5.1+ or Bash 4.0+

Common causes, each confirmed in the 0.4.1 source:

The hook is not loaded in this shell. The startup file is missing eval "$(suv init zsh)" or eval "$(suv init bash)", or it was added after this terminal opened. Hooks load in interactive shells that read your startup file.
The shell is too old. The hook turns itself off and prints a warning on Zsh older than 5.1 or Bash older than 4.0. The Bash that ships with macOS is 3.2.
No session ID. The Zsh hook uses uuidgen to create SUVADU_SESSION_ID. If uuidgen is not installed, the ID is empty and every command is dropped.
Recording is paused or disabled. eval $(suv pause) pauses only the current shell. suv disable stops recording everywhere.
The command was skipped on purpose. Commands that start with a space are never recorded. Commands that match your exclusion patterns are skipped. A .suvadu.toml in the command's directory or any parent directory can override enabled and exclusions.
The command is recorded but hidden. Agent, bot, CI, and script commands are hidden from search by default. See agent commands are hidden.

Repair. Fix only the cause you found:

Hook missing from the startup file: add the eval line once, as described in Shell Integration. If the file already has it, open a new terminal instead.
Paused shell: unset SUVADU_PAUSED. Disabled: suv enable. Both are safe to reverse.
Old shell: install a newer Zsh or Bash and make it your login shell. Keep the old one until the new one works.
Missing uuidgen: install your distribution's package that provides it (often util-linux), then open a new terminal.
Skipped on purpose: edit the matching exclusion pattern or .suvadu.toml setting, or leave it if the skip was intended.

Verify. In a new terminal, run a harmless, unique command, then look for it:

echo suvadu-check-1
suv history -n 3        # the echo line appears at the top

Shell still references a moved or uninstalled binary

Check. You see an error like suv binary not found (recorded path: …) or no such file or directory: /opt/homebrew/bin/suv. You may also see agent hooks fail with suvadu: binary not found; reinstall Suvadu and run suv init <agent>.

whence -p suv           # Zsh: where the binary is now (empty = not on PATH)
type -P suv             # Bash: the same check
echo "$_SUVADU_BIN"     # the path this shell recorded at startup
suv doctor              # "Agent hooks" fails if a hook's saved binary is missing and suv is not on PATH

The Zsh and Bash hooks save the binary's absolute path when the shell starts. The saved path goes stale after you switch package managers, unlink with Homebrew, or reinstall somewhere else. The hooks try to recover by looking up suv on your PATH. Agent hook scripts in ~/.config/suvadu/hooks/ do the same.

Repair.

Make sure the new location, such as ~/.cargo/bin, is on your PATH. Then reload the shell with exec zsh or exec bash, or open a new terminal.
For agent hooks, run suv init <agent> again, then relaunch the agent. This rewrites Suvadu's hook scripts with the current binary path. The Codex setup saves a backup of hooks.json before it changes the file. For Claude Code, back up your settings first if you want an easy undo: cp ~/.claude/settings.json ~/.claude/settings.json.bak.
The pi.dev extension runs suv from your PATH, so it only needs the binary to be on the PATH that pi.dev sees.
If an MCP client cannot start the server, see stale MCP configuration.

Verify. Run echo suvadu-check-2, then suv history -n 3; the line should appear. suv doctor should show Agent hooks passing.

Existing history has not been imported

Check. Suvadu records new commands after its hook loads. It does not import your old shell history automatically. In 0.4.1, suv import reads two formats: Zsh history files, and JSONL files that Suvadu exported. There is no Bash-history importer and no Atuin importer.

Repair. Preview the import first, then run it:

suv import --from zsh-history --dry-run ~/.zsh_history   # shows the count; writes nothing
suv import --from zsh-history ~/.zsh_history             # imports; skips entries already present

The import leaves the source file alone. Imported entries go into a new session named import-zsh-…. If the result is not what you wanted, restore the database from a backup. Run suv backup before a large import so you have one. See Import & Export and Backup.

Verify. Use the -q flag to search the full database for an old command you remember:

suv search -q "some old command"

Agent commands are hidden by recall filters

Check. By default, search, Ctrl+R, and Zsh Up-arrow recall hide commands whose executor type is agent, bot, ci, or programmatic. Commands with no known executor type are shown. Confirm the agent's commands were recorded:

suv history --executor agent -n 10     # suv history never hides agent commands
suv history --executor claude-code -n 10

Repair. Pick the narrowest option:

In the search screen, press Ctrl+A to show or hide agent commands.
For one search: suv search --include-agents, or suv search --executor <name>. Filtering by executor includes agent commands.
For Zsh Up/Down recall in the current shell, press Alt+A.
To show agent commands by default everywhere, set recall_show_agents = true in the [search] section of config.toml. Delete the line to undo.

Verify. Open suv search and press Ctrl+A. The status line reads Agent commands shown, and the agent's commands appear in the list.

If suv history --executor … finds nothing either, the commands were not recorded. See the next section.

An integration records commands but not prompts or sessions

Check. First confirm the integration can capture what you expect. Only Claude Code, Codex, and OpenCode import native sessions with prompts, responses, models, and tokens. Cursor and pi.dev attach prompts to commands. Antigravity and other agents detected through the shell record commands only. See the capability matrix. Then check what has arrived:

suv agent sessions                          # native sessions (Claude Code, Codex, OpenCode)
suv agent prompts --executor claude-code    # commands that have a linked prompt
suv doctor                                  # Agent hooks / MCP lines

The turn is still running. Native session content is imported when a turn finishes: at Stop or SessionEnd for Claude Code and Codex, and when an OpenCode session goes idle. Finish one turn, then check again.
Hooks are from an older Suvadu. Setups from before 0.4.1 lack the Stop and SessionEnd hooks. Interactive suv commands print "your Codex hooks need refreshing" or "your Claude Code hooks need refreshing" when this applies.
Codex hooks are not trusted. Codex does not run the new hooks until you review and trust them in /hooks in the Codex terminal CLI.
Claude Code settings were not updated. If ~/.claude/settings.json did not exist, suv init claude-code printed a settings snippet for you to add instead of reporting Settings auto-configured.
OpenCode config could not be edited. If ~/.config/opencode/opencode.jsonc contains comments, suv init opencode does not edit it. It prints the exact lines to add instead.
Only shell-tool commands are recorded. For Claude Code, only Bash tool calls are recorded. Other tools do not create command rows.
Capture was paused or excluded. Records skipped while paused, or in a disabled or excluded directory, are not added later.

Repair. Run the setup command for your agent again with the current binary. Relaunch the agent; for its VS Code extension, fully quit and reopen VS Code.

suv init claude-code    # then relaunch Claude Code
suv init codex          # then open /hooks in the Codex terminal CLI, trust Suvadu's hooks, relaunch Codex
suv init opencode       # then fully quit and relaunch OpenCode
suv init cursor         # then restart Cursor

Re-running setup preserves unrelated hooks. Codex keeps a timestamped hooks.json.suvadu-backup-… copy of the previous file. For a Claude Code or Codex session that already ended, you can import its transcript file directly. Running this again only imports new records:

suv agent import-session /path/to/transcript.jsonl

Verify. Start a fresh agent turn that runs one harmless command, such as echo suvadu-agent-check. Let the turn finish, then run suv sessions, find the session, and open it. The timeline should show the prompt, the command, and the response. For Cursor or pi.dev, run suv agent prompts and look for the prompt with its command.

Summary saving is disabled or MCP has stale configuration

Check. Look for these symptoms:

The agent says save_session_summary is not available, or reports "Tool 'save_session_summary' is disabled; enable mcp.allow_session_summaries…".
The agent cannot connect to the Suvadu MCP server at all.
MCP connects but uses old settings.

Saving summaries is off by default. In 0.4.1, the suv settings screen does not include this option. The MCP server reads config.toml once when it starts. Project .suvadu.toml files do not change MCP settings.

grep -n -A8 '^\[mcp\]' "$HOME/Library/Application Support/tech.appachi.suvadu/config.toml"   # macOS
grep -n -A8 '^\[mcp\]' ~/.config/suvadu/config.toml                                         # Linux
suv doctor                                                                                   # MCP (Claude Code), MCP (Cursor)

Repair.

To enable summaries, add allow_session_summaries = true to the [mcp] section. Create the section if it does not exist. Remove save_session_summary from disabled_tools if it is listed there. Then restart the agent so it starts a new MCP server. To undo, set the value back to false. See Save a summary.
If the MCP entry points to a binary that no longer exists, fix it for your agent. suv init codex updates the command in Codex's config.toml every time it runs. suv init claude-code and suv init cursor add an entry only if none exists, so they do not repair a stale path. For those, back up ~/.claude.json or ~/.cursor/mcp.json, then change mcpServers.suvadu.command to the binary's current path. Get it with whence -p suv in Zsh or type -P suv in Bash. Plain command -v suv returns the shell wrapper function when Suvadu's hook is loaded. suv init opencode also leaves an existing mcp.suvadu entry in opencode.jsonc unchanged; edit its command the same way.
If the MCP server reports a database schema error, a different Suvadu build has updated the database. The agent may be running an older suv path. Point the entry at the current binary.

Verify. Restart the agent and ask it to list its Suvadu tools. save_session_summary should appear. Then ask it to "summarize and save the current session". Open the session in suv sessions and press s; the new summary is labeled CURRENT.

An older command exists but typed search misses it

Known limitation, not yet fixed. Affected: Suvadu 0.4.1. Earlier releases have a similar candidate limit, according to the source history. Fixed in: no released version as of 19 September 2026. Nothing is deleted; the command is still in your database.

Check. Search the whole database for the command:

suv search -q "exact text"               # the first results come from a database query over all history

If the command appears here but not when you type the same text in the open search screen, you have hit this limitation. When you type or edit a query in the search screen, Suvadu loads only the newest 5,000 entries that pass your filters. It then matches your text against those entries. Unique mode (--unique) uses the same 5,000-entry limit.

Work around it. Each of these searches beyond the newest 5,000 entries:

Start with the query. Run suv search -q "text", or type the text at your prompt before pressing Ctrl+R. The first result list comes from the database. It matches the text as one continuous phrase. Editing the query switches back to the limited search.
Narrow the filters. Filters are applied in the database before the 5,000-entry limit. They include date (--after/--before or the Ctrl+F panel), directory (--here), tag, exit code, executor, failed-only, and bookmarks. For example: suv search --before 2026-01-01, then type your text.
Use a text pipeline. suv history --before 2026-01-01 -n 100000 | grep "text".
Ask a connected agent. The MCP search_commands tool searches the full database.

Verify. The workaround works when the older command appears in the results. See Search for more detail.

Still stuck? Report a reproducible problem

Open an issue at github.com/AppachiTech/suvadu/issues. Include:

The output of suv --version and suv doctor
Your operating system and CPU architecture, shell and version, and terminal (plus tmux or screen, if you use one)
The agent name and version, if the problem involves an agent
The smallest sequence of steps that reproduces the problem

Do not include history, prompts, or configuration that contain secrets or private paths.