Supported Shells, Platforms and AI Agents

This page lists where Suvadu runs and what each integration records. It also separates what automated tests cover from what has only been reviewed in source code. Recognizing an agent's name is not the same as supporting it, so the tables below list captured fields rather than names.

Suvadu 0.4.1. Verified 19 September 2026 by reviewing the source code, tests, and release workflow at the v0.4.1 tag. Entries marked source review describe what the code does. They were not tested end to end against each agent, terminal, or operating-system version. Product versions that the project itself reports testing are shown as such.

Platforms and installation methods

Platform	Release binary	Automated tests	Install methods
macOS, Apple Silicon (`aarch64-apple-darwin`)	Yes	The release build runs `cargo test`. CI runs on `macos-latest`.	Homebrew tap, Cargo, manual download (the 0.4.1 install script requests the wrong macOS archive; see Installation)
macOS, Intel (`x86_64-apple-darwin`)	Yes (built on the macOS runner)	Not run for this target	Homebrew tap, Cargo, manual download (the 0.4.1 install script requests the wrong macOS archive; see Installation)
Linux x86_64 (`x86_64-unknown-linux-gnu`)	Yes	The release build runs `cargo test`. CI runs on `ubuntu-latest`.	Install script, Cargo, manual download; the Homebrew formula also has a Linux build
Linux ARM64 (`aarch64-unknown-linux-gnu`)	Yes (cross-compiled)	Not run for this target	Install script, Cargo, manual download; the Homebrew formula also has a Linux build
Windows	No	No	Not supported. The install script exits on any OS other than Linux or macOS.

The install script detects x86_64 or arm64/aarch64 and checks the download's SHA-256 checksum. It installs suv and a suvadu link into /usr/local/bin using sudo.
Linux release binaries target glibc (-gnu). No musl build is published. No minimum glibc version has been checked.
cargo install suvadu compiles from source on your machine. It is not tested beyond the CI runners listed above.

Commands and download links are on Installation.

Shells and recall behavior

Shell	Minimum	Records history	Ctrl+R	Up/Down recall	Notes
Zsh	5.1	Yes, through `preexec`/`precmd` hooks (`add-zsh-hook`)	Suvadu search screen, pre-filled with the current command line	Yes: prefix recall, newest first. `Alt+A` shows agent commands in this shell. Turn off with `shell.enable_arrow_navigation = false`.	Uses `uuidgen` to create the session ID
Bash	4.0	Yes, through a `DEBUG` trap and `PROMPT_COMMAND`; existing handlers are kept	Suvadu search screen (`bind -x`)	No. Bash keeps its own arrow-key history.	The Bash that ships with macOS (3.2) is too old; the hook turns itself off with a warning
Fish	n/a	No. There is no `suv init fish`.	No	No	Only completions: `suv completions fish`. Commands typed in Fish are not recorded.

In both Zsh and Bash, search and recall hide agent, bot, CI, and script commands by default; see agent commands are hidden. suv completions also generates Elvish and PowerShell completion scripts. Those shells have no recording hooks. No CI job runs the generated Zsh or Bash hooks inside a real shell; unit tests check the generated script text.

Agent capability matrix

This matrix covers every suv init agent target in 0.4.1, from a source review on 19 September 2026. Native session means Suvadu imports the agent's own session record: prompts, responses, observed models, and token counts reported by the provider. See Agent Sessions for how those appear.

Target	Command capture	Prompt capture	Native session, model, tokens	MCP auto-configuration	Activation after setup	Evidence
`claude-code`	Bash tool calls through `PostToolUse`; failures and exit codes through `PostToolUseFailure`. Executor `claude-code`.	Yes, through `UserPromptSubmit`. Prompts are linked to commands by turn.	Yes, imported at `Stop`/`SessionEnd`. Thinking blocks, attachments, images, file contents, and tool results are not stored.	Yes: adds `mcpServers.suvadu` to `~/.claude.json` only if it is missing	Relaunch Claude Code. VS Code extension: fully quit and reopen. If `~/.claude/settings.json` does not exist, add the printed snippet yourself.	Source review, plus an automated test that runs the session hook on a synthetic transcript. No tested Claude Code version is stated.
`codex`	Shell commands through `PostToolUse` (Bash). Executor `openai-codex`. Timestamps record when the hook was received, and the exit code is unknown unless Codex reports one.	Yes, through `UserPromptSubmit`, linked by turn	Yes, imported at `Stop`/`SessionEnd`. Also available manually with `suv agent import-session`.	Yes: `[mcp_servers.suvadu]` in `$CODEX_HOME/config.toml` (default `~/.codex`). The command path is updated on every run.	Review and trust the hooks in `/hooks` in the Codex terminal CLI, then relaunch. VS Code: fully quit and reopen.	Source review and automated tests with synthetic hook events. The README states that prompt and command hooks were tested with Codex CLI 0.153.4.
`opencode`	Bash commands through the plugin's `tool.execute.after` handler	Yes. The plugin saves prompts through Suvadu, which applies redaction and length limits.	Yes, imported when the session goes idle, using OpenCode's session messages. Token counts from each response are added together.	Yes: `mcp.suvadu` in `~/.config/opencode/opencode.jsonc`. If the file has comments, setup prints the lines to add instead.	Fully quit and relaunch OpenCode. Run setup again after upgrading OpenCode or Suvadu.	Source review and automated tests. The source and README state testing against OpenCode CLI 1.18.30.
`cursor`	Agent shell commands through `afterShellExecution`. Executor `cursor`. The exit code is recorded as 0 when Cursor does not report one.	Yes, through `beforeSubmitPrompt`. The conversation's latest prompt is attached to each later command.	No	Yes: adds `mcpServers.suvadu` to `~/.cursor/mcp.json` only if it is missing	Restart Cursor	Source review only. No end-to-end hook test was found, and no tested Cursor version is stated.
`pi`	Bash tool results through an extension at `~/.pi/agent/extensions/suvadu.ts`. Executor `pi`. Exit codes are approximate. The extension runs `suv` from `PATH`.	Yes, through `before_agent_start`. Prompts are cut to 500 characters and attached to commands.	No	No	pi.dev loads the extension the next time it starts	Source review only. No automated test and no tested version were found.
`antigravity`	Only for commands run in a shell that loaded Suvadu's Zsh or Bash hook. The agent is detected from `$ANTIGRAVITY_AGENT`.	No	No	No	Setup installs nothing. It checks your shell startup files and prints guidance.	Source review only

Detected by environment only

When a command runs through Suvadu's Zsh or Bash hook, environment variables tell Suvadu who ran it. The hook labels these executors:

Agents: claude-code, openai-codex, aider, continue-dev, copilot, cursor, antigravity
IDE terminals: windsurf, cursor, vscode, intellij, pycharm
CI: github-actions, gitlab, circleci
Your own agents: any [agents.<name>] entries in config.toml, detected by their environment variable

These labels are not support claims. A command is recorded only if the tool runs it in a shell that loaded your Zsh or Bash startup file. Many agents start non-interactive shells that do not load it. Those commands carry no prompt, session, model, or token data. For a tool without hooks, suv wrap -- <command> records one command explicitly. See Agent Setup.

Known gaps

suv doctor checks MCP registration only for Claude Code and Cursor. It checks hook scripts only in ~/.config/suvadu/hooks/. It does not check Codex's config.toml, OpenCode's plugin or config, or the pi.dev extension.
suv init claude-code, suv init cursor, and suv init opencode do not change an MCP entry that already exists. If the binary moved, fix the path yourself; see stale MCP configuration.
Native session content is imported only when a turn ends, so the turn in progress is not visible yet.
Saving session summaries over MCP is off by default, and suv settings cannot turn it on in 0.4.1. See Save a summary.
suv import reads Zsh history and Suvadu JSONL only. It cannot import Bash or Atuin history.
The search screen's typed search checks only the newest 5,000 entries that match your filters; see known search limitation.

Terminals and multiplexers

Untested: no automated test or CI job runs Suvadu inside a particular terminal emulator, or inside tmux, screen, or Zellij. Any combination not listed below is untested.

The source code handles these cases, but no test checks them:

The Zsh Ctrl+R widget saves and restores the terminal state around the search screen. The source mentions iTerm2 with Powerlevel10k as the case this handles. It also clears the Zsh display first, for compatibility with Powerlevel10k instant prompt.
If $TTY cannot be read, the widget uses /dev/tty. If neither can be read, Ctrl+R uses the shell's own search. The source mentions AWS SSM sessions as an example.
Suvadu does not turn on mouse capture. Terminals that turn trackpad or scroll-wheel movement into Up/Down key presses move the selection in its screens.
Each shell creates its session ID when it starts, unless the environment already has one. A shell started from a shell that already runs Suvadu inherits SUVADU_SESSION_ID and joins that session. A multiplexer that copies the starting environment into new panes may therefore group several panes into one session. This has not been tested.

If you use a terminal or multiplexer with Suvadu and something breaks, please report it. Include the exact versions.

Upgrade and restart

Upgrade with the same method you used to install. Update & Uninstall describes suv update and each method. After upgrading:

Reload your shells. Run exec zsh or exec bash, or open new terminals. Already-open shells keep the old hook code. They find a moved binary on PATH when they can.
Run agent setup again for each agent you use, for example suv init claude-code or suv init codex. This is required for native session capture if you set up an agent before 0.4.1. Interactive suv commands print a reminder when Claude Code or Codex hooks need refreshing.
Relaunch each agent. Codex also needs you to trust the updated hooks in /hooks. For VS Code extensions, fully quit and reopen VS Code. OpenCode needs a full quit and relaunch.
Restart MCP clients after you change config.toml. The MCP server reads its configuration only when it starts.
Check: run suv --version and suv doctor. Then run one command in a shell and finish one agent turn, and confirm both appear in suv history -n 3 and suv sessions.

Report a reproducible problem

If a combination on this page does not work as described, open an issue at github.com/AppachiTech/suvadu/issues. Include suv --version, suv doctor output, your OS and architecture, shell and version, terminal and multiplexer, the agent and its version, and the smallest set of steps that reproduces it. Leave out history or prompts that contain secrets. For common fixes, see Troubleshooting.