Suvadu

Total recall for your terminal. Shared memory for your AI agents.

Suvadu replaces your shell history with a SQLite-backed store. Every command gets structured context — exit code, duration, directory, executor, session. AI agents can query it via MCP. 100% local.

• Measured, not asserted — at 100,000 entries on one M4 Max: 207 µs p95 to record a command, 0.05–15 ms p95 for a judged search over the whole history. One machine, one run — the harness, the corpus and what is still unmeasured are in BENCHMARKS.md
• AI agent tracking — full session capture for Claude Code, Codex, OpenCode and Cursor (Cursor without token usage); commands and prompts for pi.dev; commands for Antigravity's agent; command tagging alone for Windsurf, Aider, Continue and Copilot (what each tier means)
• Prompt Explorer — trace every recorded command back to the prompt that triggered it
• MCP Server — 22 read-only tools, 8 resources and 6 prompts, all read-only by default. The two write tools stay off until you turn their opt-in on. Agent session discovery, project context, failure learning, risk assessment, a shared skills library, your bookmarked command templates. Configurable via suv settings
• 100% local — no cloud, no telemetry, no account. The only request Suvadu makes on its own is a once-a-day check for a newer release, which you can turn off. MIT licensed.

Website & Docs: suvadu.sh · CLI Reference: suvadu.sh/cli · Blog: suvadu.sh/blog · What's new: CHANGELOG

---

Install

# Homebrew (macOS & Linux)

brew tap AppachiTech/suvadu && brew install suvadu

Install script (macOS & Linux)

curl -fsSL https://downloads.appachi.tech/suvadu/install.sh | bash

Install script, into ~/.local/bin without sudo

curl -fsSL https://downloads.appachi.tech/suvadu/install.sh | bash -s -- --user

Cargo (Rust 1.95 or newer)

cargo install suvadu

The install script puts suv in /usr/local/bin, using sudo only when that directory is not writable; --user or --dir DIR (or SUVADU_INSTALL_DIR) choose another place. Re-running it updates a script-installed suv where it already is — recognised by the suvadu link the script puts beside it — and when nothing has changed it downloads nothing but still repairs that link. If the suv on your PATH came from Homebrew or Cargo, it stops and names that package manager's update command; any other suv it did not install is left alone, and --user or --dir installs a separate copy on purpose. Run at a terminal, it offers to add the shell hook below to ~/.zshrc (or ~/.bashrc on Linux): it shows the line first, writes nothing unless you type y, keeps a copy of the file as .suvadu-backup, and never adds the hook twice. --no-modify-rc turns the offer off.

Then add shell hooks:

# Zsh

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

Bash

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

Verify: suv status

Each command is recorded with its directory and, inside a git repository, the branch it started on (the short commit hash for a detached HEAD). The branch is read from the repository's files — no git runs at your prompt — and shows in recall's detail pane. A command that changes directory, like cd ../other, is filed under the branch it was typed on; one that switches branches, under the branch it switched to. Turn it off with *Record Git Branch* in suv settings or [shell] capture_git_branch = false.

Staying up to date. Once a day, in the background, Suvadu looks up the newest release number (the same version.txt that suv update reads) and, when there is a newer one, says so in one line before a command you run at a terminal — at most once a day, with the update command for how you installed it (brew upgrade suvadu, cargo install suvadu or suv update). Nothing about you or your history is sent. It never runs in shell hooks, recall, scripts, pipes or CI. Turn it off with *Check for Updates* in suv settings, [update] check = false in config.toml, or SUVADU_NO_UPDATE_CHECK=1.

Up-arrow recall

In zsh, Up and Down recall from Suvadu as soon as the hook is loaded; there is nothing else to set up. Up brings back the newest command that starts with what you have typed, then older ones, newest first — the current directory only breaks ties between commands recorded at the same millisecond — and Down walks back towards what you typed. Only commands you typed are recalled: Alt+A shows AI-agent commands too, for that shell.

• Turn it off with *Enable Arrow Key Navigation* on the Shell tab of suv settings, or [shell] enable_arrow_navigation = false in config.toml. It takes effect in new shells (or exec zsh), which keep zsh's own Up/Down and leave Alt+A alone.
• Bash is not covered yet. The Bash hook binds only Ctrl+R; Up and Down keep Bash's own history.
• Check it: bindkey '^[[A' should print "^[[A" suvadu-up-arrow, and bindkey '^[OA' (the sequence many terminals send) "^[OA" suvadu-up-arrow.
• If something else answers Up, a plugin loaded after eval "$(suv init zsh)" rebound it — oh-my-zsh's key bindings, zsh-history-substring-search, zsh-vi-mode, fzf's key bindings, atuin and mcfly all bind Up. Put the eval "$(suv init zsh)" line last in ~/.zshrc, after your plugin manager and plugins, then exec zsh; a plain setting such as ZSH_AUTOSUGGEST_STRATEGY can still follow it. zsh-vi-mode binds its keys at the first prompt instead, so also set ZVM_INIT_MODE=sourcing before it loads.
• `suv doctor` reports it. Once per zsh, at its first prompt — when all of ~/.zshrc has run — the hook checks whether Up is still Suvadu's and notes what took it over; doctor's *Up-arrow* line names that widget and the fix, and the note is removed when a later zsh finds Up is Suvadu's again. The check prints nothing, costs about 0.8 ms per shell start (BENCHMARKS.md), and is skipped when arrow navigation is off.

zsh-autosuggestions. The zsh hook ships a strategy for zsh-autosuggestions that suggests what Up-arrow would recall — the newest command starting with what you typed, with AI-agent commands hidden unless Alt+A revealed them. Enable it in ~/.zshrc, falling back to zsh's own history when Suvadu has nothing:

ZSH_AUTOSUGGEST_STRATEGY=(suvadu history)

Each suggestion is one suv get lookup, the same one Up-arrow makes (its cost is in BENCHMARKS.md). zsh-autosuggestions 0.7 fetches suggestions asynchronously by default, so typing does not wait for it.

---

Troubleshooting

`no such file or directory` pointing at an old path (e.g. suv:8: no such file or directory: /opt/homebrew/bin/suv) — The shell hook records the absolute path of the suv binary when your session starts. If you move the binary — switching package managers (e.g. Homebrew → Cargo), running brew unlink suvadu, or uninstalling and reinstalling elsewhere — already-open shells keep pointing at the old, now-deleted path. Reload the shell to pick up the new location:

exec zsh    # or: exec bash

(or just open a new terminal). Also make sure the new location, such as ~/.cargo/bin, is on your PATH.

Up-arrow shows zsh's own history, not Suvadu's — Check: bindkey '^[[A' or bindkey '^[OA' prints a widget other than suvadu-up-arrow (such as up-line-or-beginning-search or history-substring-search-up), and suv doctor's *Up-arrow* line says what took it over. Cause: a plugin loaded after the hook rebound the key, arrow navigation is off (*Enable Arrow Key Navigation* in suv settings), or the shell is Bash, whose Up keeps Bash's own history. Repair: move eval "$(suv init zsh)" to the end of ~/.zshrc and run exec zsh, or turn the setting back on. See Up-arrow recall.

More at suvadu.sh/cli/shell-integration.

---

Quick Start

suv                         # Home: find any feature by what you want to do (also suv home)

suv search # Interactive search TUI (also Ctrl+R) suv history # Print last 25 commands (pipeable) suv history --json -n 100 # Last 100 commands as JSONL suv stats # Stats dashboard with heatmap suv replay --after today # Timeline of today's commands suv sessions # Browse shell and AI sessions together suv doctor # Check installation health suv agent dashboard # Monitor AI agent activity suv agent prompts # Browse prompts and their commands suv agent sessions # List captured Codex/Claude sessions and reported tokens suv skills # Interactive skills management (browse, add, edit, sync, review) suv skills add my-skill # Add a skill any MCP-capable agent can read suv skills sync # Materialize skills into Claude Code/Cursor/Codex suv skills edit my-skill --rename new-name # Rename a skill (--move-to here: change its scope) suv skills trust # Trust this repo's .suvadu/skills/*.md so sync writes them suv bookmarks get box --set host=db1 # Print a bookmark with its {{placeholders}} filled

Team skills in the repository

Commit skills next to the code, one Markdown file each, in .suvadu/skills/:

---

name: release # optional; defaults to the file name (release.md) description: How we cut a release triggers: [release, tag] targets: [claude-code, codex] # optional; default: every agent

---

1. Bump the version in Cargo.toml.
2. Tag, then push the tag.

Everyone who clones the repository gets them, so Suvadu treats them as untrusted until you have read them:

suv skills list                 # repo skills show origin 'repo' and 'untrusted'

suv skills show release # read one (its file path, trust, body) suv skills trust --dry-run # list this repository's skills and their state suv skills trust # trust them (or: suv skills trust release) suv skills sync # from the repository root: writes them like project skills

• The project is the nearest directory with a .suvadu/skills/ folder, looking up from where you are but never above the git repository's root. Repo skills sync from that directory, into its .claude/skills/, .cursor/rules/ and AGENTS.md, exactly where a project skill would go.
• Trust is recorded per file with a hash of its content (suv skills trust --repo PATH for another checkout). When the file changes — after a pull, say — it is *changed since trusted*: the next sync stops writing it and removes the copy it wrote, until you trust it again. suv skills untrust takes trust back, and the next sync removes the copies.
• Suvadu never edits, moves or deletes a repo skill file: edit the file. In `suv s