Frequently Asked Questions

Run suv skills to browse, add, edit, delete, sync, and review reusable instructions. MCP clients can discover active skills with list_skills, get_skill, and search_skills. Use suv skills sync --dry-run to preview native files for Claude Code, Cursor, and Codex, then suv skills sync to write them.

The default MCP tools only read skills. Enabling mcp.allow_skill_proposals adds propose_skill, which creates pending proposals. A human approves or rejects them in suv skills with Ctrl+P before other agents can discover them as active instructions.

No. It assesses a single quoted command string and returns 0 below the chosen risk threshold, or 2 when blocked. High is the default threshold. A script or shell widget must use that result to control execution.

Put .suvadu.toml in the project or a parent directory. The nearest file merges over global config; arrays replace existing arrays. In 0.4.0, recording settings, CLI risk rules, and theme use overlays. Search options and MCP still use global config.

The canonical names are now suv bookmarks, suv aliases, and suv sessions; the old singular names remain aliases. Bare bookmarks and aliases open interactive managers. Replace the old suv bookmark pick invocation with suv bookmarks, and reload your shell after upgrading.

The dashboard, Prompt Explorer, and session picker accept search text as you type. In the dashboard use Ctrl+F for period, Ctrl+A for executor, Ctrl+R for risk, and Ctrl+P for prompts. In Prompt Explorer use Ctrl+P for period, Ctrl+A for executor, and Ctrl+S for the session timeline. In statistics, Ctrl+H toggles human-only activity.

Zsh stores history in a text file and can include timestamps and durations when configured. Suvadu records commands into a SQLite database with WAL mode and adds fields such as exit code, working directory, session ID, and executor origin, enabling structured queries and filtering.

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.

Installing the binary does not activate recording. First add eval "$(suv init zsh)" to .zshrc and reload the shell. Your existing .zsh_history file remains untouched; import it with suv import --from zsh-history ~/.zsh_history, using --dry-run to preview first.

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

Check whether Homebrew and your terminal are running as arm64 or x86_64, then use the matching supported package. The installation page lists the current Homebrew, install-script, Cargo, and manual-download options at downloads.appachi.tech.

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/tech.appachi.suvadu/ (macOS) or ~/.local/share/suvadu/ and ~/.config/suvadu/ (Linux) is not modified by the update.

Suvadu stores its history database locally at ~/Library/Application Support/tech.appachi.suvadu/history.db on macOS (~/.local/share/suvadu/history.db on Linux) and has no account, telemetry, or built-in cloud sync. Besides commands, it stores captured agent prompts, imported agent-session prompts and responses with model and token metadata, skills, and any session summaries you let agents save; the privacy page lists everything. Exports are plaintext, and a connected AI client receives any history or context it requests through Suvadu's local MCP server; that client may send the returned data to its provider under its own settings.

Suvadu records synchronously through its shell hook so a newly completed command is immediately available to recall. Actual latency and search time depend on the machine, shell configuration, and history size.

Size depends on command and prompt length, metadata, indexes, and stored skills. Version 0.4.0 adds a trigram search index, so older size estimates may not apply. Check your local history.db and its SQLite WAL files for actual disk use.

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.

Suvadu applies built-in patterns for common API keys, tokens, passwords, and connection strings before writing captured commands, and supports extra patterns. Pattern-based redaction cannot guarantee detection of every secret, so avoid placing secrets directly in command lines.

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) gives commands recorded in exactly your current directory a score boost (50% by default) when you type a query in suv search. The boost only reorders results within the same match tier, and subdirectories are not boosted. Smart mode does not rank by command frequency or exit status. Press Ctrl+S to toggle between Smart and Recent modes.

In 0.4.1, a query typed inside the open search TUI is matched against the newest 5,000 entries that pass your active filters, so an older match can be missing even though it is still stored. A fix is planned. Until then, run suv search -q "your text" (or type the text at your prompt before pressing Ctrl+R), which queries the whole database for that phrase, or narrow the search with --after/--before, --here, or other filters, which are applied before the 5,000-entry window.

Up/Down arrow recall is recency-first. If you have typed a prefix, Suvadu returns the newest matching commands first; the current directory is only a secondary tie-breaker within the same recency tier.

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 bookmarks 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 Ctrl+P in the agent dashboard. Prompt Explorer groups recorded prompts with commands by session. Prompt data appears only for integrations that capture it, such as the dedicated Claude Code, Cursor, Codex, OpenCode, and pi integrations.

Suvadu detects the executor through dedicated hooks/plugins and environment variables. Claude Code, Cursor, Codex, OpenCode, and pi have dedicated integrations that can capture commands and prompts. Environment-variable detection for tools such as Antigravity, Aider, and Windsurf identifies commands running through an integrated shell but does not by itself capture prompt text.

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 Cursor command and prompt hooks and registers the local Suvadu MCP server. Shell integration separately records commands typed in Cursor's integrated terminal. Restart Cursor after setup.

Run suv init codex. This installs PostToolUse and UserPromptSubmit hooks into ~/.codex/hooks.json — merging into any hooks you already have there rather than overwriting them — and auto-registers the suvadu MCP server in ~/.codex/config.toml. Restart Codex after setup.

The agent dashboard (suv agent dashboard) is an interactive TUI for commands captured from configured AI integrations. 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 a local MCP (Model Context Protocol) server that lets connected AI clients query your shell history. It provides 21 tools by default (including shared skills and captured agent sessions), 8 resources, and 5 prompts. Two optional write tools are off by default: propose_skill saves skill proposals that stay pending until you approve them, and save_session_summary saves a summary the agent wrote when you ask it to. Enable them with allow_skill_proposals or allow_session_summaries in the [mcp] section of config.toml (they are not in suv settings in 0.4.1), then restart the AI client. The MCP connection is auto-configured by suv init claude-code, suv init cursor, suv init codex, or suv init opencode. Returned history is visible to the connected client and may be sent to its AI provider under that client's settings.

Run suv init opencode. This installs a plugin at ~/.opencode/plugins/suvadu.js and registers it in ~/.config/opencode/opencode.jsonc, including a local MCP server entry under the mcp key so OpenCode can query your shell history directly. Bash commands are recorded immediately with captured prompt context; when a session goes idle, the plugin also imports the full session — prompts, assistant responses, model, and token usage — via OpenCode's own session.messages API, browsable with suv agent sessions / suv sessions and summarizable the same way as Claude Code and Codex sessions. Restart OpenCode after setup.

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).