How to Set Up AI Agent Tracking with Suvadu

AI coding assistants can execute shell commands with your permissions — installing packages, running tests, and modifying configs. Suvadu records commands covered by its shell hooks or dedicated agent integrations, adds executor metadata, and applies rule-based risk assessment. Prompt text is available only for integrations that capture prompt events.

This guide is the practical part: connect the agent you use, confirm it is recording, and inspect one test session end to end. For the full per-agent capability table (command capture, prompts, sessions, reported tokens, restart requirements, known gaps), see the compatibility matrix. Flags and options live in the agent integration reference.

How Detection Works

Suvadu uses two complementary approaches to attribute AI-driven commands:

1. Shell hook detection (environment variables) — When an IDE opens a terminal, it sets environment variables in that shell. Suvadu's shell hooks check them on every command and tag the executor, for example cursor, vscode, windsurf, or antigravity. This only covers interactive Zsh or Bash sessions that load Suvadu's hooks, and it records commands without prompts.
2. Dedicated hook/plugin integration — Tools that expose command and prompt events can be integrated directly, so commands are recorded even when the agent never starts a hooked shell. Suvadu provides dedicated integrations for Claude Code, Codex, Cursor, OpenCode, and pi; their exact event coverage depends on the host.

Both approaches write to the same local database, so commands from different tools appear in one history. A command reaches that history only when one of these paths reports it; the audit guide lists what falls outside both.

Before You Start: Shell Hooks

Install the binary, then enable Suvadu's hooks for your shell so human and IDE-terminal commands are recorded too:

# ~/.zshrc (use suv init bash in ~/.bashrc for Bash)
eval "$(suv init zsh)"

Open a new terminal, then run suv status to confirm recording is enabled. The installation guide covers import and first search.

Connect Your Agent

Run the init command for each agent you use. Each one prints what it changed and the exact restart step for that host.

Claude Code

suv init claude-code

This installs hook scripts and merges them into ~/.claude/settings.json (if it can't merge safely, it prints the snippet to add yourself). Suvadu listens to Claude Code's PostToolUse and PostToolUseFailure events for the Bash tool, UserPromptSubmit for prompt text, and Stop/SessionEnd to import the session's prompts, assistant responses, observed models, and provider-reported token usage. It also registers Suvadu's MCP server in ~/.claude.json.

Restart: relaunch Claude Code. For the VS Code extension, fully quit and reopen VS Code. Existing users upgrading to 0.4.1 need to rerun the command to pick up the session hooks.

Codex

suv init codex

This merges Suvadu's hooks into ~/.codex/hooks.json without removing other handlers, backing up the previous file, and registers the MCP server in ~/.codex/config.toml. Commands are recorded with the executor openai-codex.

Restart: in the Codex terminal CLI, open /hooks, review and trust the Suvadu hooks (including Stop and SessionEnd), then relaunch Codex. Until the hooks are trusted, Codex doesn't run them and nothing is recorded.

Cursor

suv init cursor

This configures Cursor's afterShellExecution hook for agent commands and beforeSubmitPrompt for prompt text in ~/.cursor/hooks.json, and registers the MCP server in ~/.cursor/mcp.json. Cursor captures commands and prompts; it does not import assistant responses or token usage.

Restart: restart Cursor. Commands you type in Cursor's integrated terminal are also labeled cursor through shell-hook detection.

OpenCode

suv init opencode

OpenCode runs commands from its Node.js process, not through your Zsh or Bash hooks, so it needs its own plugin. This installs the Suvadu plugin and registers it in ~/.config/opencode/opencode.jsonc's plugin array (OpenCode doesn't reliably auto-load a plugin from its directory alone), along with a local MCP server entry. Bash commands are recorded as they run, with the current prompt attached. When a session goes idle, the plugin imports its messages, including prompts, assistant responses, model, and token usage, through OpenCode's own session.messages API.

Restart: relaunch OpenCode.

pi

suv init pi

This writes a Suvadu extension to ~/.pi/agent/extensions/suvadu.ts. It records bash tool results with the executor pi and caches the prompt that started each agent run. pi loads the extension the next time it starts.

Antigravity and IDE terminals

suv init antigravity

Antigravity, VS Code, Windsurf, IntelliJ, and PyCharm terminals are recognized from environment variables, so there is nothing to install beyond the shell hooks. suv init antigravity only checks that your ~/.zshrc or ~/.bashrc loads Suvadu and tells you how to fix it if not. These tools get executor labels, not prompts.

Tools without an integration

If a tool runs commands inside a terminal that sets a distinctive environment variable, add a custom detection rule under the Agents tab in suv settings: the variable name and the executor label you want. For a script or tool that doesn't load shell hooks, you can run individual commands through suv wrap:

suv wrap --executor-type agent --executor my-agent -- npm test

Open an issue if you'd like a dedicated integration for a specific tool.

Verify the Integration

After restarting the agent, check the installation before relying on it:

suv doctor

suv doctor checks your shell hooks, the hook scripts installed for Claude Code, Codex, and Cursor, and MCP registration for Claude Code and Cursor, and names the suv init command to rerun when a script is stale or broken. It doesn't inspect the OpenCode plugin or pi extension, so for those the next check is the one that matters. Ask the agent to run one harmless command and look for it:

# Use the executor for your agent: claude-code, openai-codex, cursor, opencode, pi
suv history --executor claude-code -n 5

If nothing appears, the host didn't deliver an event. The usual causes are an agent that wasn't restarted, Codex hooks that weren't trusted, or a merged config that the host didn't reload.

Record and Inspect a Test Session

Before trusting the record for real work, run a short session you control and inspect every view of it. This example uses Claude Code; substitute your agent's executor name.

1. Start fresh in a scratch directory. mkdir -p ~/suv-test && cd ~/suv-test, then start a new agent session there.
2. Give it a prompt that runs known commands. For example: "Run git --version, then run ls missing-file, and tell me what happened." The second command fails on purpose, so you can check that exit codes are recorded.
3. Check the commands. From ~/suv-test, run suv history --executor claude-code --here. Expect both commands, the second with a non-zero status.
4. Check the prompt link. Run suv agent prompts --executor claude-code --here, select your prompt, and press Enter to see the two commands under it. See the Prompt Explorer reference.
5. Check the session. Run suv sessions and press Ctrl+T to show AI sessions. For Claude Code, Codex, and OpenCode, the timeline should show your prompt, the assistant's reply, both commands, and the model. Cursor and pi appear as command-backed sessions, without assistant replies, models, or token counts.
6. Check the report. Run suv agent report --executor claude-code --here. The failed ls should appear under failed commands.

If a step comes up empty, the sessions guide explains each field, including missing sessions and prompts with no commands, and the compatibility matrix lists known gaps per agent.

Where to Go Next

• Browse sessions and saved summaries — prompts, responses, commands, models, and reported tokens in one timeline.
• Agent reports — text, markdown, or JSON summaries of recorded agent activity, with an optional --fail-on risk gate.
• Agent dashboard — interactive view of recent agent commands with risk levels and details.
• Risk assessment — what each risk level means. It is informational and never blocks commands on its own.
• Investigate a failed agent run — a worked example using these commands.

Let your AI tools do what they do best. Then use Suvadu to check what they ran.