Frequently Asked Questions

Standard Zsh history stores commands in a plain text file with limited metadata. Suvadu stores everything in a SQLite database with WAL mode, capturing duration, exit code, working directory, session ID, and executor origin for every command. This enables structured queries, filtering, and sub-10ms search even with millions of entries.

Suvadu supports Zsh and Bash. Fish support is on the roadmap. The core SQLite engine is shell-agnostic — only the hook integration is shell-specific.

Suvadu supports macOS (Apple Silicon and Intel) and Linux with Zsh or Bash. Zsh 5.1+ ships with macOS by default since Catalina; Bash is available on all major Linux distributions.

After installing Suvadu, new commands are automatically recorded. Your existing .zsh_history file remains untouched. To import your legacy history, run suv import --from zsh-history ~/.zsh_history. Use --dry-run to preview what would be imported first.

Yes. Suvadu works in tmux, screen, and any terminal multiplexer. Each pane gets its own session ID for accurate tracking.

If your Mac runs Homebrew under Rosetta (x86 emulation), the Homebrew tap may not work correctly. Install manually instead: curl -sL https://downloads.suvadu.sh/macos/suv-macos-latest.tar.gz | tar xz && sudo mv suv /usr/local/bin/. The download includes a universal binary that works on both Apple Silicon and Intel Macs.

Depends on how you installed it. Homebrew: brew update && brew tap AppachiTech/suvadu && brew upgrade suvadu. Cargo: cargo install suvadu. Manual install (curl/tar): run suv update, which auto-detects your platform and architecture, verifies the download, and replaces the binary.

No. Your history database and config are stored separately from the binary. Updating only replaces the suv executable — your data at ~/Library/Application Support/suvadu/ (macOS) or ~/.local/share/suvadu/ (Linux) is never touched.

100% local. Your history database is stored at ~/Library/Application Support/suvadu/history.db on macOS. No data ever leaves your machine. There's no account, no telemetry, and no cloud sync.

Minimal. Recording uses native shell timestamps and SQLite writes, adding less than 2ms overhead per command. Search queries return in under 10ms even with hundreds of thousands of entries.

Approximately 15–25 MB for 100,000 commands, depending on average command length. SQLite with WAL mode is extremely space-efficient. Even a million commands typically stays under 200 MB.

Yes. Use suv settings to configure exclusion patterns (regex). Common patterns like ^ls$, ^cd, and ^pwd$ can be added to keep noise out of your database.

Yes. Suvadu automatically detects API keys, tokens, and passwords in commands and redacts them before they are written to the database. Your secrets never touch disk.

Yes, MIT licensed. Source code at https://github.com/AppachiTech/suvadu.

Yes. In the TUI (suv search), press Ctrl+F to open the filter panel and enter an exit code. Use exit code 0 for successful commands, or any non-zero code to find failures.

Yes. Use suv search --here to filter history to commands run in your current working directory. In the TUI, press Ctrl+L to toggle the directory filter on or off.

Smart mode (enabled by default) automatically ranks commands from your current directory higher in search results. Press Ctrl+S to toggle between Smart and Recent modes.

When Smart mode is enabled, the Up/Down arrow keys use frecency ranking instead of pure recency. Frecency combines how often you run a command with how recently you ran it, weighted by time tiers.

Press Tab in the search TUI to toggle a side panel that shows full metadata for the selected entry: command text, working directory, timestamp, duration, exit code, session ID, tag, executor type, bookmark status, and note indicator.

Yes. Enable vim_mode in suv settings → Search tab (or set vim_mode = true in config.toml under [search]). This adds modal navigation: Esc switches to Normal mode where j/k navigate, Ctrl+U/Ctrl+D scroll half-page, g/G jump to top/bottom, / or i returns to Insert (search) mode, and q quits.

Yes. Use suv bookmark add "your command" to bookmark any command. Bookmarked commands show a ★ indicator in search results. Toggle bookmarks directly in the search TUI with Ctrl+B.

Yes. Use suv note <id> -c "your note" to annotate any history entry with context. Notes appear in search results with a memo indicator, and you can add or edit notes directly in the TUI with Ctrl+N.

Yes. Run suv stats to see a full analytics dashboard: total and unique commands, success rate, average duration, top commands, busiest hours, top directories, and executor breakdown.

Yes. Run suv replay to see a chronological timeline of commands from your current session. Add --after today for today's commands, --here for the current directory, or combine filters.

Yes. Run suv export to export your entire history as JSONL or CSV. To import on another machine, use suv import history.jsonl. Use --dry-run to preview.

Use suv agent prompts or press p in the agent dashboard. The Prompt Explorer shows each prompt with the commands it triggered, grouped by session.

Suvadu detects the executor environment using hooks and environment variables. Claude Code, Cursor, and OpenCode have dedicated integrations (suv init claude-code / suv init cursor / suv init opencode) that capture commands, exit codes, and prompts. Antigravity, Codex, Aider, Windsurf, and others are auto-detected via environment variables.

Run suv init claude-code. This installs PostToolUse, PostToolUseFailure, and UserPromptSubmit hooks and auto-configures ~/.claude/settings.json. Restart Claude Code after setup.

Run suv init cursor. This configures Suvadu to detect Cursor's environment variables and capture commands from its integrated terminal. Restart Cursor after setup.

The agent dashboard (suv agent dashboard) is an interactive TUI that gives you a real-time overview of every command your AI agents have run. It shows a summary panel with agent count, total commands, success rate, and risk counts.

Suvadu automatically classifies every agent command into a risk level: Critical (rm -rf, DROP TABLE, force-push), High (chmod 777, package installs), Medium (git reset, docker run), Low (file writes, branch operations), or Safe (read-only commands).

Suvadu includes an MCP (Model Context Protocol) server that lets AI agents query your shell history directly. It provides 11 tools (search, risk assessment, failure analysis) and 5 browsable resources. Auto-configured when you run suv init claude-code or suv init cursor.

Run suv init opencode. This installs a plugin at ~/.opencode/plugins/suvadu.js that automatically captures every bash command OpenCode executes, including the user prompt.

Yes. Go to suv settings → Agents tab and add a detection rule with the tool's name, its environment variable, and executor type (agent, ide, or ci).