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. Source review, 19 Sep 2026, Suvadu 0.4.1: 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.

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
• 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 two hooks into ~/.cursor/hooks.json:

• afterShellExecution — records each shell command the Cursor agent runs, with exit code and duration
• beforeSubmitPrompt — captures the prompts you send to Cursor

After running this command, restart Cursor for the hooks to take effect. The MCP server is also auto-configured in ~/.cursor/mcp.json. Cursor has no native session import, so assistant responses, models, and tokens are not captured.

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
• 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. Browse captured sessions with suv agent sessions / suv agent session, or suv sessions for the unified picker.

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

Suvadu's Zsh/Bash hook labels a command as antigravity when the $ANTIGRAVITY_AGENT environment variable is set. suv init antigravity does not install anything: it checks that your shell hook is set up and tells you how to add it if not. Only commands run in a shell that loads the hook are recorded. Prompts, sessions, and MCP are not set up.

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.

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.