How to Track Claude Code with Suvadu

Claude Code is Anthropic's CLI agent for software engineering. It reads your codebase, writes code, and runs shell commands — all from your terminal. A single prompt like "refactor auth to use JWT" can trigger 30+ shell commands: reading files, installing packages, running tests, modifying configs. Suvadu doesn't just track these commands. It captures the prompts that triggered them, provides a dedicated agent dashboard, and generates risk-assessed reports of every session.

What Makes Claude Code Different

Most IDE terminals (Cursor, VS Code, Windsurf) run commands through standard shell sessions. Suvadu detects these via environment variables — it works, but you only get the commands themselves.

Claude Code is different. It provides a hook system — specifically PostToolUse and UserPromptSubmit hooks — that lets external tools intercept tool calls at a deeper level. Suvadu uses both hooks to capture not just what Claude ran, but why it ran it.

This means Suvadu captures three things other history tools can't:

1. Your prompt. The exact instruction you gave Claude Code, stored alongside the commands it executed.
2. Structured tool data. Exit codes, working directory, and session identifiers directly from Claude's tool call JSON — not inferred from shell state.
3. Complete coverage. Even commands that bypass normal shell hooks (backgrounded processes, piped operations) are captured through the PostToolUse hook.

Setup

One command installs both hooks:

$ suv init claude-code
✓ PostToolUse hook installed
✓ UserPromptSubmit hook installed
✓ ~/.claude/settings.json updated
  Restart Claude Code to activate.

This does three things:

1. Creates hook scripts in ~/.config/suvadu/hooks/
2. Registers them in ~/.claude/settings.json so Claude Code calls them automatically
3. The PostToolUse hook fires on every Bash tool call; the UserPromptSubmit hook fires when you send a prompt

If you already have other hooks configured in Claude Code, Suvadu merges its hooks into your existing settings without overwriting anything.

Prompt Capture

This is the feature that changes how you think about agent history. When you type a prompt in Claude Code — say, "add rate limiting to the API" — Suvadu's UserPromptSubmit hook captures it and caches it locally. When Claude subsequently runs shell commands, Suvadu attaches the prompt to each command record.

The result: you don't just see what commands ran. You see why they ran.

$ suv search --executor claude-code --after today

 # │ Command                               │ Dir         │ Exit │ Prompt
───┼───────────────────────────────────────┼─────────────┼──────┼──────────────────────────
 1 │ cat src/api/middleware.ts              │ ~/project   │  0   │ add rate limiting to the API
 2 │ npm install express-rate-limit         │ ~/project   │  0   │ add rate limiting to the API
 3 │ npm test -- --testPathPattern=rate     │ ~/project   │  1   │ add rate limiting to the API
 4 │ npm test -- --testPathPattern=rate     │ ~/project   │  0   │ add rate limiting to the API
 5 │ git diff --stat                        │ ~/project   │  0   │ add rate limiting to the API
 6 │ cat tsconfig.json                      │ ~/project   │  0   │ fix the TypeScript strict mode errors
 7 │ npx tsc --noEmit                       │ ~/project   │  1   │ fix the TypeScript strict mode errors
 8 │ npx tsc --noEmit                       │ ~/project   │  0   │ fix the TypeScript strict mode errors

Commands 1-5 all trace back to your rate limiting prompt. Commands 6-8 came from a different prompt. Without this context, you'd be staring at a flat list of commands with no idea which task triggered which.

The Agent Dashboard

Suvadu includes a dedicated interactive dashboard for monitoring AI agent activity:

$ suv agent dashboard

The dashboard is a full TUI (terminal UI) built with ratatui that gives you:

• Session overview. Total commands, success rate, risk summary, and agent breakdown — all at a glance.
• Risk assessment. Every command is evaluated for security risk. Package installs, permission changes (chmod), script executions, and destructive operations (rm -rf) are flagged with risk levels from low to critical.
• Time filtering. Press 1-4 to switch between today, 7 days, 30 days, or all time.
• Agent filtering. Press a to cycle through executors: all agents, Claude Code only, Cursor only, etc.
• Risk filtering. Press r to toggle high-risk-only mode — instantly surfacing commands that deserve your attention.
• Detail pane. Press Tab on any command to see full metadata: working directory, exit code, duration, executor, and the prompt that triggered it.
• Copy to clipboard. Press Ctrl+Y to copy the selected command.

Think of it as your flight recorder for AI-assisted development. Everything Claude Code did, organized and risk-assessed.

Agent Reports

Need a summary instead of an interactive dashboard? Suvadu generates structured reports:

# Plain text report (default)
$ suv agent report

# Markdown — paste into a PR description
$ suv agent report --format markdown

# JSON — pipe into other tools
$ suv agent report --format json

Reports include:

• Agent activity summary — total commands, success rate, time range
• Risk assessment — high and critical risk commands highlighted with categories
• Package audit — every package installed by an agent, grouped by package manager
• Failed commands — commands with non-zero exit codes, useful for debugging
• Agent breakdown — command counts and percentages per executor

The markdown format is designed for PR descriptions. After an AI-assisted coding session, generate a report and paste it into your PR to give reviewers full context on what the agent did:

$ suv agent report --format markdown --after today

## Agent Activity Report
- **Period**: Feb 13, 2026
- **Total commands**: 47
- **Success rate**: 91.5%

### High-Risk Commands
| # | Command | Risk | Category |
|---|---------|------|----------|
| 1 | npm install jsonwebtoken | Medium | Package install |
| 2 | chmod +x scripts/migrate.sh | Medium | Permission change |

### Packages Installed
- npm: jsonwebtoken, @types/jsonwebtoken, express-rate-limit

### Failed Commands
- `npx tsc --noEmit` (exit 1) — TypeScript compilation errors
- `npm test -- --testPathPattern=rate` (exit 1) — Test initially failed

Querying Claude Code Commands

Beyond the dashboard and reports, all standard Suvadu search features work with Claude Code commands:

# All Claude Code commands today
$ suv search --executor claude-code --after today

# Only in the current project
$ suv search --executor claude-code --here

# Failed commands (what Claude tried and couldn't do)
$ suv search --executor claude-code --exit-code 1

# Combined with other agents
$ suv search --executor-type agent --after "7 days ago"

# Stats breakdown
$ suv agent stats --days 30

How the Hooks Work

Under the hood, Suvadu registers two hooks in Claude Code's settings:

PostToolUse Hook

Fires after every Bash tool call. Claude Code sends a JSON payload containing the command, working directory, exit code, and session ID. Suvadu parses this and writes a database entry with executor_type=agent and executor=claude-code. The session ID is prefixed with claude- to avoid collisions with regular shell sessions.

UserPromptSubmit Hook

Fires when you submit a prompt. Suvadu caches the prompt text (truncated to 500 characters) to a local file keyed by session ID. When subsequent PostToolUse events arrive for the same session, the cached prompt is attached to each command's context field. This is how prompts and commands are linked together.

Both hooks run locally. No data leaves your machine. The prompt cache is stored at ~/.config/suvadu/prompts/ and is automatically cleaned up.

Why This Matters

Claude Code is powerful precisely because it's autonomous. It reads your codebase, reasons about changes, and executes commands without requiring your approval for each one. That's the value proposition.

But autonomy without observability is a risk. You need to know what packages were installed, what scripts were run, what permissions were changed. And you need that information organized, risk-assessed, and queryable — not buried in a scrolling chat sidebar.

Suvadu gives you the observability layer. Every command is captured with its prompt context, assessed for risk, and stored in a local SQLite database you can query instantly. The agent dashboard puts it all in one view. Reports let you share it with your team.

Let Claude Code do what it does best. Then use Suvadu to verify what it did.

Install Suvadu, run suv init claude-code, and get complete visibility into your AI-assisted development workflow — including the prompts that drive it.