Question 1

What's the difference between Suvadu and built-in Zsh history?

Accepted Answer

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.

Question 2

Is Suvadu compatible with Bash or Fish?

Accepted Answer

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

Question 3

What platforms are supported?

Accepted Answer

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.

Question 4

How do I migrate from standard Zsh history?

Accepted Answer

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.

Question 5

Can I use Suvadu with tmux or screen?

Accepted Answer

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

Question 6

Homebrew install fails on my Mac (Rosetta). What do I do?

Accepted Answer

If your Mac runs Homebrew under Rosetta (x86 emulation), the Homebrew tap may not work correctly. Install manually instead: curl -sL https://downloads.appachi.tech/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.

Question 7

How do I update Suvadu?

Accepted Answer

If installed via Homebrew: brew upgrade suvadu. For manual installs: suv update downloads and replaces the binary automatically.

Question 8

Does Suvadu store data locally or in the cloud?

Accepted Answer

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.

Question 9

What's the performance impact on my shell?

Accepted Answer

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

Question 10

What's the database size for 100,000 commands?

Accepted Answer

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.

Question 11

Can I ignore certain commands from being recorded?

Accepted Answer

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.

Question 12

Is Suvadu open source?

Accepted Answer

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

Question 13

Can I search history by exit code?

Accepted Answer

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. Great for debugging recurring build or test issues.

Question 14

Can I see history for just this directory?

Accepted Answer

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 at any time. A "dir" badge shows when the filter is active.

Question 15

What is Smart mode in search?

Accepted Answer

Smart mode (enabled by default) automatically ranks commands from your current directory higher in search results. Local results get green-highlighted paths so you can tell at a glance. Press Ctrl+S to toggle between Smart and Recent modes. You can change the default in suv settings under Search > Context Boost.

Question 16

How do Smart arrow keys work?

Accepted Answer

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 (last hour, day, week, month). Same-directory commands get priority. This means the commands you actually need are always near the top.

Question 17

What is the detail preview pane?

Accepted Answer

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. Press Tab again to close it.

Question 18

Can I save favorite commands?

Accepted Answer

Yes. Use suv bookmark add "your command" to bookmark any command. Add an optional label with -l for context. Bookmarked commands show a ★ indicator in search results. Toggle bookmarks directly in the search TUI with Ctrl+B.

Question 19

Can I add notes to commands?

Accepted Answer

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.

Question 20

Can I see usage statistics?

Accepted Answer

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. Use --days 30 to scope to recent activity, or --top 5 to limit rankings.

Question 21

Can I replay what I did in a session?

Accepted Answer

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 like --after yesterday --exit-code 1 to see yesterday's failures. The output is pipeable text, so you can grep it or save it to a file.

Question 22

Can I export or import my history?

Accepted Answer

Yes. Run suv export to export your entire history as JSONL (one JSON object per line) to stdout. You can also export as CSV with suv export --format csv. Filter by date range with --after and --before flags. To import on another machine, use suv import history.jsonl. Use --dry-run to preview what would be imported without writing anything.

Question 23

How does auto-tagging work?

Accepted Answer

You define directory-to-tag mappings in your config file. For example, map ~/work to a 'Work' tag and ~/personal to 'Personal'. Suvadu automatically applies the correct tag based on your working directory when recording commands.

Question 24

How does Suvadu detect AI agent commands?

Accepted Answer

Suvadu detects the executor environment using environment variables and process context. It automatically identifies commands from Claude Code, VS Code, Cursor, Antigravity, Terminal, CI/CD pipelines, and more. You can also use suv wrap to explicitly record commands from any agent or script.

Question 25

How do I set up Claude Code integration?

Accepted Answer

Run suv init claude-code. This installs a PostToolUse hook script and auto-configures ~/.claude/settings.json so that every Bash command Claude Code executes is recorded in your Suvadu history. Restart Claude Code after setup. Verify with suv search --executor agent.

Question 26

How do I set up Cursor integration?

Accepted Answer

Run suv init cursor. Suvadu auto-detects Cursor's integrated terminal via the $CURSOR_INJECTION and $CURSOR_TRACE_ID environment variables — as long as your shell hooks are set up (eval "$(suv init zsh)" in .zshrc or equivalent for Bash), commands in Cursor's terminal are tracked automatically. Verify with suv search --executor cursor.

Question 27

How do I set up Antigravity IDE integration?

Accepted Answer

Run suv init antigravity. Suvadu auto-detects Antigravity's integrated terminal via the $ANTIGRAVITY_AGENT environment variable — as long as your shell hooks are set up (eval "$(suv init zsh)" in .zshrc or equivalent for Bash), commands in Antigravity's terminal are tracked automatically. Verify with suv search --executor antigravity.

Question 28

What is the agent dashboard?

Accepted Answer

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. A timeline panel lists commands chronologically with risk level and exit status indicators. Press Tab to see full details for any command, including the working directory, duration, and risk classification. Filter by agent (a) or risk level (r), and switch time periods with 1-4.

Question 29

What is the agent stats view?

Accepted Answer

Agent stats (suv agent stats) shows per-agent analytics cards: total commands, success rate, average duration, and risk breakdown for each detected agent. It also surfaces top commands and top directories per agent, along with a high-risk commands table you can drill into with a detail pane. Use --days to scope the analysis to a recent window, or --text for plain text output.

Question 30

How does risk assessment work?

Accepted Answer

Suvadu automatically classifies every agent command into a risk level: Critical (rm -rf, DROP TABLE, force-push to main), High (chmod 777, package installs, config overwrites), Medium (git reset, docker run, env modifications), Low (file writes, branch operations), or Safe (read-only commands like git status, ls, grep). Risk levels appear in the agent dashboard timeline and are aggregated per-session in agent stats. You can filter by risk level to focus on the commands that matter.

Question 31

Can I export an agent activity report?

Accepted Answer

Yes. Run suv agent report to generate a text report of all agent activity, including session replay and risk assessment summary. Use --format markdown to save as a markdown document, or --format json for structured data you can pipe into other tools. Add --after "3 days ago" to scope the report to a specific time range.

Frequently Asked Questions

Getting Started