Suvadu — Claude Code MCP server: shell history and agent sessions
Replaces shell history with a SQLite store: every command keeps its exit code, duration, directory and session. Agents query it over MCP.
Open on GitHubWhat Suvadu does
Suvadu hooks into your shell and writes each command to a local SQLite database. Entries carry context: exit code, duration, directory, executor, session. Inside a git repository it also records the branch the command was typed on. Nothing leaves the machine — no cloud, no telemetry, no account.
The MCP server exposes 22 read-only tools, 8 resources and 6 prompts. Two write tools stay off until you opt in. Through them an agent searches the history, learns from past failures, assesses command risk, and traces a command back to the prompt that triggered it. Configuration lives in suv settings.
Install comes from Homebrew, an install script, or Cargo — the last one needs Rust 1.95 or newer. Then the shell hook goes in: eval "$(suv init zsh)" in ~/.zshrc, or the bash equivalent. Without it nothing gets recorded. Up-arrow recall is a separate matter: oh-my-zsh, zsh-history-substring-search, zsh-vi-mode, fzf, atuin and mcfly all bind Up, so the eval line has to sit last in ~/.zshrc. Bash only gets Ctrl+R for now.
What it helps with
- find the command that failed yesterday in another directory
- trace a command back to the prompt that caused it
- assess a risky command before running it
- keep Claude and Codex sessions in one searchable place
- recall a recent command from its first few characters
Example prompts for the agent
- Search my history for commands that failed in this project
- Show which prompt triggered the last build command
- Assess the risk of
rm -rf buildbased on past runs
How to install Suvadu
Install
The MCP registry has no launch command for it: see the repository README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Suvadu
How do I install Suvadu in Claude Code?
Install the binary first: brew tap AppachiTech/suvadu && brew install suvadu. Then add the shell hook — echo 'eval "$(suv init zsh)"' >> ~/.zshrc && source ~/.zshrc for zsh, or the same line with bash and ~/.bashrc. Check it with suv status.
What does Suvadu do?
It keeps shell history in SQLite with exit code, duration, directory and session attached to each command. An agent reads that over MCP to search commands, learn from failures and assess risk.
Why did my up arrow stop working after installing Suvadu?
A plugin loaded after the eval "$(suv init zsh)" line rebound it. Put that line last in ~/.zshrc and run exec zsh. The suv doctor command names the widget that took over.
