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 still get recorded — they just show up as human (the default executor).

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 three hooks into ~/.claude/settings.json:

• PostToolUse — captures every command Claude Code runs and its exit code
• PostToolUseFailure — captures failed tool invocations
• UserPromptSubmit — captures the prompts you send to Claude Code

After running this command, restart Claude Code for the hooks to take effect. The MCP server is also auto-configured during this step, giving Claude Code direct access to your shell history.

Cursor

suv init cursor

This installs two hooks into ~/.cursor/hooks.json:

• afterShellExecution — captures every command Cursor runs
• beforeSubmitPrompt — captures the prompts you send to Cursor

After running this command, restart Cursor for the hooks to take effect.

OpenCode

suv init opencode

This installs a plugin at ~/.opencode/plugins/suvadu.js that captures commands and prompts from OpenCode sessions.

After running this command, restart OpenCode for the plugin to load.

Antigravity

suv init antigravity

Antigravity is auto-detected via the $ANTIGRAVITY_AGENT environment variable. This init command configures the detection rule. Antigravity does not have a hooks system, so only commands are captured — prompt capture is not available.

Auto-Detected Agents (No Setup Needed)

The following agents and tools are detected automatically by Suvadu using environment variables, process names, or other signals. You do not need to run any init command for these:

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

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 -- npm test --executor my-agent --executor-type agent

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 show as human, check that you restarted the agent after running suv init.