Suvadu CLI Documentation

Suvadu is a shell history replacement and AI agent memory tool, built in Rust with SQLite. It records the commands you run through its shell hooks and agent integrations, enriches them with metadata (directory, duration, exit code, executor), and gives you a TUI to search, replay, and analyze your terminal activity. All data is stored locally on your machine; connected AI clients can retrieve it through the local MCP server.

Version 0.4.1: Native Codex, Claude Code, and OpenCode session capture (prompts, responses, models, and token usage), cross-agent MCP session summaries (saving is opt-in through config.toml), and a unified suv sessions browser. See the release notes for all changes.

Quick Install

The fastest way to install Suvadu is via Homebrew:

brew tap AppachiTech/suvadu && brew install suvadu

See the full Installation guide for Cargo, manual downloads, and the install script.

Quick Start

Get up and running in four steps:

Install Suvadu using Homebrew, Cargo, or a manual download.
```
brew tap AppachiTech/suvadu && brew install suvadu
```

Set up shell integration so commands are recorded automatically.

# Zsh
echo 'eval "$(suv init zsh)"' >> ~/.zshrc && source ~/.zshrc

# Bash
echo 'eval "$(suv init bash)"' >> ~/.bashrc && source ~/.bashrc

Verify everything works by checking status.
```
suv status
```
You should see "History IS being recorded." That reflects your settings, not proof that a command was captured: open a new terminal, run echo hello, then press Ctrl+R and check that it appears.
Search your history with the interactive TUI.
```
suv search
```

Commands by Category

Getting Started

Command	Description	Docs
`suv init <shell>`	Output shell hooks for Zsh or Bash to enable automatic recording	Shell Integration
`suv status`	Show recording settings, database path, and recorded command count	Shell Integration

Core Features

Command	Description	Docs
`suv search`	Interactive search TUI with literal-word matching, ranked results, filters, and a directory-aware Smart mode	Search
`suv replay`	Chronological timeline of commands with date, directory, and executor filters	Session Replay
`suv sessions`	Interactive session browser TUI	Session Replay
`suv history`	Non-interactive history dump with filters, `--json` output, pipeable	History
`suv stats`	Shell usage statistics: top commands, daily activity, error rates	Statistics
`suv settings`	View and modify Suvadu configuration	Settings

Organization

Command	Description	Docs
`suv bookmarks`	Bookmark important commands for quick access	Bookmarks
`suv note`	Attach notes to commands for future reference	Notes
`suv tag`	Tag sessions for categorization and filtering	Tags
`suv aliases`	Create named aliases for frequently used commands	Aliases

AI Agent Integration

Command	Description	Docs
`suv agent`	Show AI agent tracking status	Agent Setup
`suv agent dashboard`	Interactive dashboard for AI agent activity	Agent Dashboard
`suv agent stats`	Statistics on AI agent command usage and patterns	Agent Stats
`suv agent prompts`	Browse and search AI agent prompts	Prompt Explorer
`suv agent report`	Generate reports on agent activity	Agent Reports
`suv mcp-serve`	Start the Model Context Protocol server for AI tool integration	MCP Server

Shared Instructions and Safety

Command	Description	Docs
`suv skills`	Browse, add, edit, sync, and review reusable AI instructions	Shared Skills
`suv guard '<command>'`	Check risk before execution; return non-zero at the chosen threshold	Command Guard
`suv backup`	Snapshot the local database	Backup

suv --help now groups commands by purpose. The old names suv bookmark, suv alias, and suv session remain aliases for suv bookmarks, suv aliases, and suv sessions. Replace the former suv bookmark pick invocation with bare suv bookmarks.

Data Management

Command	Description	Docs
`suv import`	Import Suvadu JSONL exports or Zsh history	Import & Export
`suv export`	Export history to JSONL, JSON, or CSV	Import & Export
`suv delete`	Delete individual entries or purge history by criteria	Delete & Cleanup

Maintenance

Command	Description	Docs
`suv doctor`	Diagnose installation health: shell, hooks, config, database, MCP, agent hooks	Doctor
`suv update`	Check for and install Suvadu updates	Update & Uninstall
`suv completions <shell>`	Generate shell completions for Zsh, Bash, or Fish	Completions
`suv pause`	Pause recording for the current shell session	Shell Integration
`suv enable` / `suv disable`	Globally enable or disable command recording	Shell Integration

Short questions about shell support, privacy, performance, or what each AI integration captures are answered in the FAQ. For a symptom you can reproduce, start at Troubleshooting.

What's Unique About Suvadu

Most shell history tools stop at recording commands. Suvadu goes further:

AI agent tracking — Suvadu automatically detects when commands are executed by AI coding agents (Claude Code, Cursor, Windsurf, Copilot, Aider, etc.) versus by you. Every entry records which executor ran it, so you can audit, review, and understand agent behavior alongside your own shell activity.
MCP server built in — Suvadu ships with a Model Context Protocol (MCP) server. AI agents that support MCP can query your shell history, check what commands failed, see what changed in a directory, and get context-aware suggestions — all from your local database with zero cloud dependencies.
Rich metadata on every command — Each entry captures the working directory, duration, exit code, hostname, session ID, and timestamp. This makes filtering, replaying, and analyzing your history far more powerful than plain-text history files.
Local storage — All data is stored in a local SQLite database. No accounts, no cloud sync, no telemetry. Connected AI clients can retrieve history via MCP and may send it to their model provider.
Built in Rust — Suvadu is a single compiled binary with no runtime dependencies. Command recording is designed for low overhead, and 0.4.0 adds a trigram index for database-level substring queries. Reproducible benchmark results have not been published yet; see the recording design article.