Agent Setup

Suvadu automatically detects who ran each command — whether it was you, an AI coding agent, your IDE, or a CI/CD pipeline — and records that executor alongside every history entry. This page explains how to set up agent tracking for each supported tool.

What Agent Tracking Does

Every command Suvadu records includes an executor field. When agent tracking is configured, Suvadu automatically tags commands with the name of the tool that ran them. This means you can:

• Filter your history to see only what a specific agent did (suv search --executor claude-code)
• Monitor agent activity in real-time with the Agent Dashboard
• Get per-agent analytics with Agent Stats
• Generate risk-assessed activity reports with Agent Reports
• See which prompts triggered which commands with the Prompt Explorer

Without agent tracking, commands that an agent runs in a Suvadu shell may still be recorded, labelled by environment detection or as programmatic, with no prompt attached.

What Each Integration Captures

Summary of what each suv init target sets up. Reviewed for 0.5.1, against its README and release notes; in 0.5.1 the cursor target gained session capture and the opencode plugin changed, so rerun both after upgrading. This table describes what the integration code does. It does not list agent versions that were tested. Compatibility is the canonical matrix, including test evidence and known gaps.

“Reported tokens” are the counts in the agent's own transcript. They are not billing data, and unknown usage is shown as unknown, not zero. Native sessions are browsed with suv sessions; see Agent Sessions for what each field means and what capture can miss. After setup, run one agent turn, then check suv sessions --list -n 5 (native sessions) or suv history --executor agent -n 5 (commands).

Agents That Require Setup

The following agents need a one-time init command. Each installs lightweight hooks into the agent's configuration so Suvadu can capture commands, exit codes, and (where supported) prompts. Hooks read up to 16 MB of input and keep only the fields Suvadu records, so since 0.5.1 a Bash call whose output runs to megabytes is still recorded.

Claude Code

suv init claude-code

This installs hooks into ~/.claude/settings.json:

• PostToolUse — records each successful Bash tool command (exit 0)
• PostToolUseFailure — records failed Bash tool commands, with the exit code parsed from the error message, and with failure output on, the end of the error text
• UserPromptSubmit — captures the prompts you send to Claude Code
• Stop / SessionEnd — incrementally import Claude Code's native transcript for prompts, assistant text, every observed model, and deduplicated provider-reported token usage, independent of shell commands

After running this command, relaunch Claude Code (for the VS Code extension, fully quit and reopen VS Code) for the hooks to take effect. The MCP server is also auto-configured in ~/.claude.json, and the built-in suvadu-session-memory skill is installed. Browse captured sessions with suv agent sessions / suv agent session, or suv sessions for the unified picker with a full timeline and summary panel.

Cursor

suv init cursor

This installs four hooks into ~/.cursor/hooks.json, beside any you already have there:

• afterShellExecution — records each shell command the Cursor agent runs, with exit code and duration, and with failure output on, the end of a failed command's output
• beforeSubmitPrompt — captures the prompts you send to Cursor
• afterAgentResponse and stop (since 0.5.1) — the final response of each turn and how the turn ended

Since 0.5.1 each Cursor conversation is a full agent session, cursor-<conversation_id>, in suv sessions, suv agent sessions and the MCP session tools: prompts, final responses, how each turn ended and the model, with the conversation's commands linked to the turn they ran in. The limits are Cursor's:

• Its hooks report no token usage, so a Cursor session's tokens are unavailable — never zero — and its capture status says so.
• They carry no timestamps, so events are timed when the hook receives them.
• Cursor sends only the final response text of a turn, so intermediate assistant messages, thinking and tool calls other than shell commands are not captured.
• An event is captured only when Cursor names a workspace, whose .suvadu.toml decides its redaction and exclusions. A hook that runs twice stores its event once.

After running this command, restart Cursor for the hooks to take effect; if you set Cursor up before 0.5.1, rerun suv init cursor to add the two new hooks. The MCP server is also auto-configured in ~/.cursor/mcp.json.

Codex

suv init codex

This installs hooks into ~/.codex/hooks.json, merging into any hooks you already have there (e.g. synapse, plannotator) rather than overwriting them:

• PostToolUse — captures every shell command Codex runs, and with failure output on, the end of a failed command's output when the response carries an exit code and its output text
• UserPromptSubmit — captures the prompts you send to Codex
• Stop / SessionEnd — incrementally import Codex's native transcript for prompts and final assistant answers, independent of shell commands, plus provider-reported token counters without double-counting cumulative updates (bounded to 16 MiB per record)

After running this command, restart Codex and trust the Suvadu hooks when prompted (or via /hooks). The MCP server is also auto-configured in ~/.codex/config.toml, edited in place so your existing comments and formatting are preserved. Browse captured sessions with suv agent sessions / suv agent session, import a transcript directly with suv agent import-session, or use suv sessions for the unified picker.

Setup uses CODEX_HOME when set, otherwise ~/.codex, and backs up existing hooks before changing them. Codex must support UserPromptSubmit and PostToolUse hooks for command/prompt capture, and Stop/SessionEnd hooks for native session capture. Commands are recorded as openai-codex and linked to the prompt from the same turn; prompts without recorded commands do not appear in the explorer. Hook timestamps reflect receipt time, and exit status remains unknown when the hook supplies no structured exit code. Recording and redaction settings still apply.

suv history --executor openai-codex
suv agent prompts --executor openai-codex

OpenCode

suv init opencode

This installs a plugin at ~/.opencode/plugins/suvadu.js and registers its directory in ~/.config/opencode/opencode.jsonc's plugin array automatically — OpenCode does not reliably auto-load plugins from the directory alone. If your opencode.jsonc already has JSONC-style comments this step can't safely rewrite without risking the rest of your config, it prints the exact line to add yourself instead.

Bash commands OpenCode executes are recorded immediately. Prompts, assistant responses, model, and token usage are captured when a session goes idle, via OpenCode's own session.messages API. Since 0.5.1 the plugin hands Suvadu only what it stores — each message's text, model and token counts, never tool output or reasoning — and only the messages not already imported, so a long session costs each idle only its new messages and keeps being captured past 16 MB of history. Rerun suv init opencode after upgrading to install it; sessions already captured continue where they left off. Browse captured sessions with suv agent sessions / suv agent session, or suv sessions for the unified picker.

Since 0.5.3 the plugin also looks up whether a session is a sub-session, one OpenCode's task tool started, and passes its parent along, so the sub-session is linked to its parent by parent_id in suv agent session and the get_agent_session MCP tool, as Codex forks already are. A sub-session captured earlier gets its parent at its next capture. Rerun suv init opencode after upgrading to install this plugin.

After running this command, fully quit and restart OpenCode for the plugin and config to take effect. The MCP server is also auto-configured, under opencode.jsonc's mcp key, giving OpenCode direct access to your shell history. Tested against OpenCode CLI 1.18.30; if OpenCode reports a plugin load error after an OpenCode upgrade, its plugin contract may have changed again and suv init opencode will need a matching update.

pi.dev

suv init pi

This installs a TypeScript extension at ~/.pi/agent/extensions/suvadu.ts that subscribes to pi.dev's event system to capture bash commands and prompts. Commands are recorded with executor=pi. The extension keeps the first 500 characters of each prompt.

pi.dev will automatically load the extension on next start. MCP is not configured automatically; to connect pi.dev, add a local MCP server that runs suv mcp-serve, if your pi.dev setup supports MCP.

Antigravity

suv init antigravity

Antigravity's agent runs each command as zsh -c '<command>' from its language server. That shell never reads ~/.zshrc, so your shell hook never sees it. Since 0.5.1, suv init antigravity writes a capture script to ~/.config/suvadu/hooks/antigravity-zsh.sh and adds a marked block to ~/.zshenv ($ZDOTDIR/.zshenv when set). It backs up the previous file as .zshenv.suvadu-backup-<id> first, and running it again changes nothing.

The block loads the script only in a non-interactive zsh running a -c command with $ANTIGRAVITY_AGENT set. Every other shell skips it. Each agent command is recorded when its shell exits, labelled antigravity, with its exit code, duration and directory, in one session per Antigravity run. A command's output and exit status are unchanged, and a zsh started inside it is not recorded twice. Restart Antigravity after setup, then check with suv search --executor antigravity.

Limits: zsh only; a command started with exec or killed by a signal is not recorded. To make the shell wait for the command, the script sets a no-op EXIT trap, which in those shells replaces an EXIT trap set earlier in ~/.zshenv. suv uninstall removes the block. Prompts, sessions, and MCP are not set up: Antigravity has no hooks for them.

Auto-Detected Agents (No Setup Needed)

Suvadu's shell hook labels commands automatically when it finds a known environment variable. No init command is needed, but only commands run in a shell that loads the hook are recorded, and no prompts are captured:

Commands from these tools are automatically labeled with the correct executor name as soon as Suvadu's shell integration is active.

Share Instructions Across Agents

The new shared skills library lets MCP clients discover reusable instructions. Run suv skills to manage them, or suv skills sync --dry-run to preview native files for Claude Code, Cursor, and Codex. Native sync is separate from agent hook setup.

Custom Agents

If you use an agent or tool that Suvadu doesn't auto-detect, you can add custom detection rules:

suv settings

Navigate to the Agents tab in the settings TUI. For each custom agent, you can configure:

• Name — the label that appears in history (e.g., my-agent)
• Environment variable — the env var that, when present, indicates this agent is running
• Executor type — the category: agent, ide, or ci

Running Commands as an Agent

You can manually attribute a command to a specific executor using suv wrap:

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

This records the command npm test in your history with the executor set to my-agent and the type set to agent. This is useful for scripts, automation, or testing your custom agent detection. With failure output on, suv wrap passes the command's stderr through to your terminal unchanged and keeps its end if the command fails; the command then sees a pipe, not a terminal, on stderr.

Why It Failed: Failure Output (Opt-in)

Since 0.5.1, with Keep Failure Output on in suv settings (off by default), a command that fails keeps the last 4 KB it printed — where Suvadu already has that output:

[capture]
failure_output = true

• Only a command that exited non-zero keeps it; Ctrl+C's 130 does not count.
• Escape codes and progress redraws are stripped, and the text is redacted with the same rules and per-directory policy as the command before it is cut. An excluded command keeps nothing, and a project's .suvadu.toml can turn it off but not on.
• Recall's detail pane shows it under an Output row (Shift+Tab scrolls a long one), and the MCP what_failed, command_status and learn_from_failures tools and the failures/recent resource show its last three lines (all of it with detail=true), marked as the command's own text rather than instructions. Without it, they say why it is missing and how to turn it on.
• It goes with its command on suv delete, travels in JSON and JSONL exports, and suv gc --failure-output deletes all of it while keeping the commands.

For a failed command, recall and the failure tools also say what fixed it last time, worked out from what you ran next; see how that is worked out.

What Changed: Agent Git Snapshots

Since 0.5.1, when a Claude Code, Codex, OpenCode or Cursor session works in a git repository, Suvadu takes a git snapshot at the session's first prompt and again at each turn end (Claude Code and Codex UserPromptSubmit and Stop/SessionEnd; OpenCode's prompt and session.idle; Cursor's beforeSubmitPrompt and stop). There is nothing to reinstall for Claude Code, Codex and OpenCode. A snapshot holds the commit and branch checked out and which paths git status reports as staged, unstaged, untracked, renamed, deleted or conflicted. Paths only — never file contents, never diffs. The first snapshot is kept and each turn end replaces the last, so a session holds at most two.

• git runs only at those moments, never per command, without taking the index lock and with core.fsmonitor off. It gets 2 seconds; if it is slower, missing from PATH, or the directory is not a repository, nothing is recorded and the agent's hook carries on.
• In a 10,000-file repository a snapshot added about 30–35 ms to the hook that took it, nearly all of it git status; a later prompt added under 1 ms (Apple M4 Max; BENCHMARKS.md).
• Paths matching your exclusions are left out and counted, the rest and the branch are redacted like command text, and at most 500 paths are kept, with the full count.
• Turn it off with Record Agent Git Snapshots in suv settings or [agent] record_git_snapshots = false; a project's .suvadu.toml can turn it off but not back on.

The MCP what_changed tool reads them to report what a session changed with provenance: observed, and session timelines show Changed: 3 files, 1 commit.

Verify Agent Tracking

After setting up an agent, verify that commands are being tracked correctly:

# Search for commands from a specific agent
suv search --executor claude-code

# Open the agent dashboard to see all agent activity
suv agent dashboard

If commands from your agent are appearing with the correct executor label, everything is working. If they are missing or show as human or programmatic, check that you restarted the agent after running suv init, and run suv doctor. Agent commands are hidden from Up-arrow recall and suv search by default; use suv search --include-agents or --executor to see them (see agent commands are hidden). For more symptoms, see Troubleshooting.