Skip to content
Back to search

suvadu

Shell history replacement with AI agent tracking and MCP server. Built in Rust, 100% local.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/appachitech--suvadu/badge.svg)](/listings/appachitech--suvadu)

HTML

<a href="/listings/appachitech--suvadu"><img src="/api/listings/appachitech--suvadu/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

# Homebrew (macOS)
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
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`

**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`.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 872 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="assets/suvadu-logo.svg" alt="Suvadu" width="180">
  3. </p>
  4. <p align="center"><strong>Total recall for your terminal. Shared memory for your AI agents.</strong></p>
  5. <p align="center">
  6. <a href="https://github.com/AppachiTech/suvadu/actions/workflows/ci.yml"><img src="https://github.com/AppachiTech/suvadu/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  7. <a href="https://crates.io/crates/suvadu"><img src="https://img.shields.io/crates/v/suvadu.svg" alt="crates.io"></a>
  8. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
  9. <a href="https://github.com/AppachiTech/suvadu/releases"><img src="https://img.shields.io/github/v/release/AppachiTech/suvadu?label=latest" alt="Latest Release"></a>
  10. </p>
  11. <p align="center">
  12. <img src="demo/hero.gif" alt="Suvadu 0.5.0 — Ctrl+R search with fictional command history" width="700">
  13. </p>
  14. **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.
  15. - **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](BENCHMARKS.md)
  16. - **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](#what-each-agent-actually-gives-you))
  17. - **Prompt Explorer** — trace every recorded command back to the prompt that triggered it
  18. - **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`
  19. - **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.
  20. > **Website & Docs:** [suvadu.sh](https://suvadu.sh) &middot; **CLI Reference:** [suvadu.sh/cli](https://suvadu.sh/cli/) &middot; **Blog:** [suvadu.sh/blog](https://suvadu.sh/blog/) &middot; **What's new:** [CHANGELOG](CHANGELOG.md)
  21. ---
  22. ## Install
  23. ```bash
  24. # Homebrew (macOS & Linux)
  25. brew tap AppachiTech/suvadu && brew install suvadu
  26. # Install script (macOS & Linux)
  27. curl -fsSL https://downloads.appachi.tech/suvadu/install.sh | bash
  28. # Install script, into ~/.local/bin without sudo
  29. curl -fsSL https://downloads.appachi.tech/suvadu/install.sh | bash -s -- --user
  30. # Cargo (Rust 1.95 or newer)
  31. cargo install suvadu
  32. ```
  33. The install script puts `suv` in `/usr/local/bin`, using sudo only when that
  34. directory is not writable; `--user` or `--dir DIR` (or `SUVADU_INSTALL_DIR`)
  35. choose another place. Re-running it updates a script-installed `suv` where it
  36. already is — recognised by the `suvadu` link the script puts beside it — and
  37. when nothing has changed it downloads nothing but still repairs that link. If
  38. the `suv` on your PATH came from Homebrew or Cargo, it stops and names that
  39. package manager's update command; any other `suv` it did not install is left
  40. alone, and `--user` or `--dir` installs a separate copy on purpose.
  41. Run at a terminal, it offers to add the shell hook below to `~/.zshrc` (or
  42. `~/.bashrc` on Linux): it shows the line first, writes nothing unless you type
  43. `y`, keeps a copy of the file as `.suvadu-backup`, and never adds the hook
  44. twice. `--no-modify-rc` turns the offer off.
  45. Then add shell hooks:
  46. ```bash
  47. # Zsh
  48. echo 'eval "$(suv init zsh)"' >> ~/.zshrc && source ~/.zshrc
  49. # Bash
  50. echo 'eval "$(suv init bash)"' >> ~/.bashrc && source ~/.bashrc
  51. ```
  52. Verify: `suv status`
  53. Each command is recorded with its directory and, inside a git repository, the
  54. branch it started on (the short commit hash for a detached HEAD). The branch
  55. is read from the repository's files — no `git` runs at your prompt — and shows
  56. in recall's detail pane. A command that changes directory, like `cd ../other`,
  57. is filed under the branch it was typed on; one that switches branches, under
  58. the branch it switched to. Turn it off with *Record Git Branch* in
  59. `suv settings` or `[shell] capture_git_branch = false`.
  60. **Staying up to date.** Once a day, in the background, Suvadu looks up the
  61. newest release number (the same `version.txt` that `suv update` reads) and,
  62. when there is a newer one, says so in one line before a command you run at a
  63. terminal — at most once a day, with the update command for how you installed
  64. it (`brew upgrade suvadu`, `cargo install suvadu` or `suv update`). Nothing
  65. about you or your history is sent. It never runs in shell hooks, recall,
  66. scripts, pipes or CI. Turn it off with *Check for Updates* in `suv settings`,
  67. `[update] check = false` in `config.toml`, or `SUVADU_NO_UPDATE_CHECK=1`.
  68. ### Up-arrow recall
  69. In zsh, Up and Down recall from Suvadu as soon as the hook is loaded; there
  70. is nothing else to set up. Up brings back the newest command that starts with
  71. what you have typed, then older ones, newest first — the current directory
  72. only breaks ties between commands recorded at the same millisecond — and Down
  73. walks back towards what you typed. Only commands you typed are recalled:
  74. `Alt+A` shows AI-agent commands too, for that shell.
  75. - **Turn it off** with *Enable Arrow Key Navigation* on the Shell tab of
  76. `suv settings`, or `[shell] enable_arrow_navigation = false` in
  77. `config.toml`. It takes effect in new shells (or `exec zsh`), which keep
  78. zsh's own Up/Down and leave `Alt+A` alone.
  79. - **Bash is not covered yet.** The Bash hook binds only `Ctrl+R`; Up and Down
  80. keep Bash's own history.
  81. - **Check it:** `bindkey '^[[A'` should print `"^[[A" suvadu-up-arrow`, and
  82. `bindkey '^[OA'` (the sequence many terminals send) `"^[OA" suvadu-up-arrow`.
  83. - **If something else answers Up**, a plugin loaded after
  84. `eval "$(suv init zsh)"` rebound it — oh-my-zsh's key bindings,
  85. zsh-history-substring-search, zsh-vi-mode, fzf's key bindings, atuin and
  86. mcfly all bind Up. Put the `eval "$(suv init zsh)"` line last in
  87. `~/.zshrc`, after your plugin manager and plugins, then `exec zsh`; a
  88. plain setting such as `ZSH_AUTOSUGGEST_STRATEGY` can still follow it.
  89. zsh-vi-mode binds its keys at the first prompt instead, so also set
  90. `ZVM_INIT_MODE=sourcing` before it loads.
  91. - **`suv doctor` reports it.** Once per zsh, at its first prompt — when all
  92. of `~/.zshrc` has run — the hook checks whether Up is still Suvadu's and
  93. notes what took it over; doctor's *Up-arrow* line names that widget and the
  94. fix, and the note is removed when a later zsh finds Up is Suvadu's again. The
  95. check prints nothing, costs about 0.8 ms per shell start (BENCHMARKS.md),
  96. and is skipped when arrow navigation is off.
  97. **zsh-autosuggestions.** The zsh hook ships a strategy for
  98. [zsh-autosuggestions](https://github.com/zsh-users/zsh-autosuggestions) that
  99. suggests what [Up-arrow would recall](#up-arrow-recall) — the newest command
  100. starting with what you typed, with AI-agent commands hidden unless `Alt+A`
  101. revealed them. Enable it in `~/.zshrc`, falling back to zsh's own history when
  102. Suvadu has nothing:
  103. ```zsh
  104. ZSH_AUTOSUGGEST_STRATEGY=(suvadu history)
  105. ```
  106. Each suggestion is one `suv get` lookup, the same one Up-arrow makes (its
  107. cost is in BENCHMARKS.md). zsh-autosuggestions 0.7 fetches suggestions
  108. asynchronously by default, so typing does not wait for it.
  109. ---
  110. ## Troubleshooting
  111. **`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:
  112. ```bash
  113. exec zsh # or: exec bash
  114. ```
  115. (or just open a new terminal). Also make sure the new location, such as `~/.cargo/bin`, is on your `PATH`.
  116. **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](#up-arrow-recall).
  117. More at [suvadu.sh/cli/shell-integration](https://suvadu.sh/cli/shell-integration/).
  118. ---
  119. ## Quick Start
  120. ```bash
  121. suv # Home: find any feature by what you want to do (also suv home)
  122. suv search # Interactive search TUI (also Ctrl+R)
  123. suv history # Print last 25 commands (pipeable)
  124. suv history --json -n 100 # Last 100 commands as JSONL
  125. suv stats # Stats dashboard with heatmap
  126. suv replay --after today # Timeline of today's commands
  127. suv sessions # Browse shell and AI sessions together
  128. suv doctor # Check installation health
  129. suv agent dashboard # Monitor AI agent activity
  130. suv agent prompts # Browse prompts and their commands
  131. suv agent sessions # List captured Codex/Claude sessions and reported tokens
  132. suv skills # Interactive skills management (browse, add, edit, sync, review)
  133. suv skills add my-skill # Add a skill any MCP-capable agent can read
  134. suv skills sync # Materialize skills into Claude Code/Cursor/Codex
  135. suv skills edit my-skill --rename new-name # Rename a skill (--move-to here: change its scope)
  136. suv skills trust # Trust this repo's .suvadu/skills/*.md so sync writes them
  137. suv bookmarks get box --set host=db1 # Print a bookmark with its {{placeholders}} filled
  138. ```
  139. ### Team skills in the repository
  140. Commit skills next to the code, one Markdown file each, in
  141. `.suvadu/skills/`:
  142. ```markdown
  143. ---
  144. name: release # optional; defaults to the file name (release.md)
  145. description: How we cut a release
  146. triggers: [release, tag]
  147. targets: [claude-code, codex] # optional; default: every agent
  148. ---
  149. 1. Bump the version in Cargo.toml.
  150. 2. Tag, then push the tag.
  151. ```
  152. Everyone who clones the repository gets them, so Suvadu treats them as
  153. **untrusted** until you have read them:
  154. ```bash
  155. suv skills list # repo skills show origin 'repo' and 'untrusted'
  156. suv skills show release # read one (its file path, trust, body)
  157. suv skills trust --dry-run # list this repository's skills and their state
  158. suv skills trust # trust them (or: suv skills trust release)
  159. suv skills sync # from the repository root: writes them like project skills
  160. ```
  161. - The project is the nearest directory with a `.suvadu/skills/` folder,
  162. looking up from where you are but never above the git repository's root.
  163. Repo skills sync from that directory, into its `.claude/skills/`,
  164. `.cursor/rules/` and `AGENTS.md`, exactly where a project skill would go.
  165. - Trust is recorded per file with a hash of its content (`suv skills trust
  166. --repo PATH` for another checkout). When the file changes — after a pull,
  167. say — it is *changed since trusted*: the next sync stops writing it and
  168. removes the copy it wrote, until you trust it again. `suv skills untrust`
  169. takes trust back, and the next sync removes the copies.
  170. - Suvadu never edits, moves or deletes a repo skill file: edit the file. In
  171. `suv skills` they are read-only and show their path; `edit`, `rm` and
  172. `disable` refuse them and say which file to change.
  173. - A trusted repo skill takes the place of a library skill scoped to the
  174. same project with the same name (and shadows a global one there), and the
  175. sync says so. An untrusted one changes nothing.
  176. - Deleting the file removes its synced copies on the next sync — only
  177. copies Suvadu wrote and nobody edited since.
  178. - Over MCP, `list_skills`, `get_skill` and `search_skills` include the
  179. repo skills of the project the agent names (`scope`) or the server runs
  180. in, with `source repo`, the file path and the trust state. An untrusted
  181. or changed one is listed by name and path only: its description and body
  182. are not served until you trust it.
  183. - A file is skipped, with a warning naming it, when its name is not
  184. letters, digits, `-` and `_`, it is a symlink, it is over 256 KB or not
  185. UTF-8, it has no body, or its `targets` names an unknown agent.
  186. ### Bookmarks with placeholders
  187. A bookmark can be a template:
  188. ```bash
  189. suv bookmarks add "ssh {{user:root}}@{{host}} -p {{port:22}}" -l box
  190. suv bookmarks # pick it: a popup asks for user, host, port
  191. suv bookmarks get box --set host=db1 # prints: ssh root@db1 -p 22
  192. ```
  193. - `{{name}}` is a placeholder; `{{name:default}}` gives it a default
  194. (everything after the first `:`, verbatim). Names start with a letter or
  195. `_` and continue with letters, digits, `_` or `-`; `{{ name }}` is fine.
  196. - A placeholder used more than once is asked for once and filled everywhere.
  197. - `\{{` is a literal `{{`. Anything else in double braces that is not a
  198. placeholder — `{{.State.Status}}` in a `docker inspect -f`, a `{{` with
  199. no `}}` — is left exactly as typed.
  200. - Values are inserted **verbatim**: you are typing shell syntax, so quote a
  201. value with spaces or `$` the way the shell needs.
  202. - In the picker's popup, `Tab`/`Enter` moves to the next value, `Enter` on
  203. the last puts the filled command on your prompt (it is never run), and
  204. `Esc` goes back to the list. `suv bookmarks get` fails with the names of
  205. any placeholders left without a value or default.
  206. - Filled values are never stored.
  207. - The MCP `list_snippets` tool lists your bookmarks with each one's
  208. placeholders and defaults (read-only), so an agent can fill one with
  209. `suv bookmarks get … --set …` rather than retyping it.
  210. ---
  211. ## Find a feature: `suv`
  212. Run `suv` on its own (or `suv home`) to open Home: a searchable map of what
  213. Suvadu can do, grouped by task:
  214. find a command, review a session, organize commands, understand your
  215. activity, review AI activity, connect tools, and manage Suvadu. Type to
  216. search the features — not your history — with words like *failed*,
  217. *backup*, *prompts* or *atuin*; each feature shows what it does and the
  218. real command behind it.
  219. Enter opens what is selected, and never runs anything in your shell:
  220. - **Screens** (settings, sessions, stats, the agent dashboard, …) open as
  221. they would from the shell; Esc brings you back to the same place.
  222. - **Pickers** (search, bookmarks) show the command you chose, with a
  223. *Copy command* button. It has not been run — `Ctrl+R` from your shell is
  224. still the way to put a command on your prompt.
  225. - **Reports** (status, doctor, version, history, tags, the agent report)
  226. are shown inside Home.
  227. - Anything that changes data or your shell — imports, deletion, updates,
  228. pausing, shell setup — opens **instructions** with copyable examples.
  229. `F1` lists the keys and `F2` opens the command reference: the overview
  230. `suv --help` prints and every command's own help.
  231. To have a bare `suv` print the classic command overview instead, set the
  232. *Startup Screen* to `help` in `suv settings`, or in your `config.toml`:
  233. ```toml
  234. [home]
  235. startup = "help" # or "home" (the default)
  236. icons = "ascii" # or "unicode" for the category markers
  237. ```
  238. This is read from your own config only — a project's `.suvadu.toml` cannot
  239. change it. Scripts, pipes and `TERM=dumb` always get the overview, on
  240. stderr with exit status 2 as before, so nothing that runs a bare `suv`
  241. non-interactively changes. `suv home` opens Home whatever the setting says,
  242. and `suv --help` always prints the overview.
  243. ---
  244. ## How recall matches and ranks
  245. Matching decides **which** commands are eligible, scope decides **where** to
  246. look, and ranking decides only the **order**. They are three separate
  247. controls, and changing one never changes what another does.
  248. **Matching** — `--match`, or `^X` in the search UI:
  249. | Mode | Rule |
  250. |---|---|
  251. | `terms` (default) | every whitespace-separated word must appear as a substring, in any order — and if nothing does, the same words with separators ignored (below) |
  252. | `literal` | the whole query must appear exactly as typed, spaces and punctuation included |
  253. | `prefix` | the command must start with the query |
  254. | `fuzzy` | the query's letters must appear in order, gaps allowed (`gco` finds `git checkout`) |
  255. Words are ANDed, never ORed. There is no quoting syntax and punctuation is
  256. never stripped, so `git-push` is one word. Matching is case-insensitive.
  257. `terms` and `fuzzy` fold Unicode case too: `ÉCHO` finds `écho`, `σ` finds
  258. `ΟΔΟΣ` and `straße` finds `STRASSE`. In `terms` that applies to a word with a
  259. non-ASCII letter in it; a word typed in plain ASCII is looked up in the
  260. search index, which folds ASCII case only, so `STRASSE` does not find
  261. `straße`. `fuzzy` folds every query. `literal` and `prefix` are answered by
  262. SQLite's `LIKE`, which folds ASCII only. There are no language-specific
  263. rules: Turkish `İ` folds to `i` plus a combining dot, and dotless `ı` stays
  264. its own letter. **Every mode narrows in the database, so how old a match is
  265. never decides whether it is found.**
  266. **Separators — the one fallback.** When a `terms` query matches *nothing* in
  267. the current scope and filters, it is asked again with separators ignored —
  268. whitespace, `-`, `_`, `.`, `/` and `:` are dropped from both your words and
  269. the commands. `hiveagent` then finds `hive-agent`, `hive_agent`, `hive.agent`,
  270. `hive/agent` and `hive:agent`, and `hive-agent` finds `hiveagent`. Every word
  271. must still appear. The results title says `ignoring punctuation (-_./:)`, the
  272. status row says `Match terms (loose)`, and the matched text — separators
  273. inside it included — is marked as usual. It never mixes with exact matches:
  274. if anything matches as typed, only that is shown, so the count and every page
  275. come from one rule. `literal`, `prefix` and `fuzzy` have no fallback. The MCP
  276. `search_commands` tool falls back the same way for its whole query, and its
  277. response notes `no exact matches; showing matches ignoring punctuation
  278. (-_./:)`.
  279. **Scope** — `--scope`, `^P` to cycle, `^R` to reset:
  280. | Scope | Looks at |
  281. |---|---|
  282. | `all` (default) | everything recorded |
  283. | `directory` | commands run in **exactly** the current directory — not its subdirectories. `--here` is the same thing |
  284. | `workspace` | commands run anywhere under the nearest enclosing Git repository. A linked worktree is its own workspace, and a nested repository wins over its parent |
  285. | `session` | commands from the current shell session |
  286. A scope that cannot apply here (no repository, no session) says so on stderr
  287. and falls back explicitly; it never silently widens.
  288. **Ranking** — `terms` and `fuzzy` order matches by how well they match:
  289. whole-query prefix first, then a contiguous substring, then your words in
  290. query order, then in any order. **That tier always comes first: nothing below
  291. lifts a command over a closer textual match.** Within a tier, one score
  292. decides. It is a fuzzy score, adjusted for command length and for having been
  293. typed by you rather than by an agent, and — in Smart rank (`^S`,
  294. `search.context_boost`, on by default) — multiplied by:
  295. - **this directory**: having run in *exactly* this directory
  296. (`search.cwd_boost_percent`);
  297. - **frecency**: how often *and* how recently you have run that exact
  298. command. Each run counts 16 in its first hour, 8 that day, 4 for three
  299. days, 1 for a week, 0.5 for a month and 0.25 after that; the boost is the
  300. fourth root of one plus the sum, so twenty runs a day or two ago (×3.0)
  301. beat one run five minutes ago (×2.0) without burying it. It is the same
  302. definition the MCP `suggest_next` tool ranks by;
  303. - **outcome**: a command that usually fails — more than half of at least
  304. three runs with a known exit status — is scaled down, to a quarter when it
  305. has never succeeded. One failure among many successes changes nothing, and
  306. a run stopped with Ctrl+C (exit 130) is not a failure;
  307. - **sequence**: what you usually run next after the command you just ran
  308. in this shell. Recall looks at the newest 500 runs of that command in
  309. your history and, for each, at the next command recorded in the
  310. same session within 10 minutes. A command seen there at least twice is
  311. boosted by up to ×3, in proportion to how often it was the one that came
  312. next — so after `git add -A`, `git commit` comes before the `git status`
  313. you run far more often. It needs the shell session (`$SUVADU_SESSION_ID`,
  314. set by the shell hook), and `search.sequence_boost = false` (*Sequence
  315. Boost* in `suv settings`) turns off this boost alone.
  316. Frecency, outcomes and sequences count every run of that exact text in your history, not
  317. only the matching ones; agent runs count only while agent commands are shown.
  318. Ties go to interactively typed commands, then to the newest (Executions) or
  319. the most-run (Commands). **Recent rank** (`^S` again) leaves those four
  320. boosts out: within a tier, the fuzzy score and the human boost alone, then the
  321. same ties. `literal`, `prefix` and an empty query are
  322. not re-ranked at all: those come back newest first.
  323. At most 5,000 matches are ordered. That caps the ranking work, not how much
  324. history was searched, and not how much of it you can reach: matching and
  325. counting finish in the database, so the result count is the real number of
  326. matches and every page of it can be opened. Pages past the ranked window
  327. come back newest first — a relevance order computed from only part of the
  328. result set would be arbitrary there.
  329. **Typing never waits for a search.** Each query runs on a background thread
  330. with its own read-only connection. A keystroke that changes the query abandons
  331. the search still running — SQLite stops it mid-scan — and results that arrive
  332. for an older query are discarded. Enter, the arrow keys and every other key
  333. that acts on the results first waits for the results of what is typed now, so
  334. what you accept always matches the query on screen; until they arrive the
  335. results title says `searching…`.
  336. **Reading the list.** The characters your query matched are underlined and
  337. emphasised in every row, over the usual syntax colours, so it is clear why a
  338. command matched. Recall opens in **Commands**, where identical commands share
  339. one row showing when the command last ran and how many runs matched, so a
  340. command you ran fifty times does not push every other candidate off the
  341. screen. `^U` switches to **Executions** — every recorded run, with its time,
  342. directory and outcome — and back; the results title says which you are
  343. looking at and counts in those units, and the command you had selected stays
  344. selected across the switch. To start in Executions instead, set
  345. `search.show_unique_by_default = false` (or turn off *Start in Commands View*
  346. in `suv settings`). A row too long
  347. for the list ends in `…`; the selected row wraps so all of it is visible.
  348. A command is grouped only with *exactly* the same text, so whitespace that
  349. would otherwise be invisible is drawn: `·` for a leading or trailing space,
  350. `↵` and `⇥` for line breaks and tabs. When a command holds something that
  351. cannot be read off the screen — a tab, a zero-width space, a direction
  352. override — the detail pane adds its escaped *Raw* form. `^V` opens that raw
  353. view for any command, scrollable however long it is: every space drawn as `·`,
  354. every hidden character escaped, a line per line break, with its exact length.
  355. **Enter puts the command on your prompt** (or prints it, from `suv search`) —
  356. it never runs anything. The footer keeps to the core keys; `?` lists every
  357. shortcut.
  358. Up/Down arrow recall is a different, simpler path: prefix match, newest
  359. first, no deduplication, with the current directory used only to break ties
  360. between commands recorded at the same millisecond — see
  361. [Up-arrow recall](#up-arrow-recall).
  362. `suv search --compact` draws the same UI inline under your prompt instead of
  363. taking over the screen, so the output you were reading stays visible.
  364. **Making a choice stick.** `search.match_mode`, `search.scope` and
  365. `search.compact` set the default for every recall. Set them on the Search tab
  366. of `suv settings` (*Default Match Mode*, *Starting Scope*, *Compact Recall*),
  367. or in the `[search]` section of `config.toml`, in the config directory listed
  368. under [Data Storage](SECURITY.md#data-storage). Saving from `suv settings`
  369. keeps every other key in that file, including ones it does not recognise. All
  370. three default to the behaviour of earlier releases.
  371. ---
  372. ## Bring your existing history
  373. ```bash
  374. suv import --from bash-history --dry-run ~/.bash_history # preview counts, writes nothing
  375. suv import --from bash-history ~/.bash_history # import
  376. suv import --from zsh-history ~/.zsh_history # zsh equivalent
  377. ```
  378. The input file is only read, never modified, and re-running the same import
  379. adds nothing while genuinely repeated executions in the file are all kept.
  380. Both importers apply your redaction and exclusion patterns exactly as live
  381. recording does, and report excluded/redacted counts without echoing any
  382. command text. Neither takes a backup of your Suvadu database first — only
  383. the Atuin importer does that; run `suv backup` yourself if you want one.
  384. What a Bash history file can and cannot give you:
  385. | Field | Imported |
  386. |-------|----------|
  387. | Command text | Yes — redaction and your exclusion patterns apply, exactly as for live recording |
  388. | Timestamp | Only if `HISTTIMEFORMAT` was set when the command ran (`#<epoch>` lines). Otherwise an explicitly synthetic 1970-01-01 placeholder — never an invented time |
  389. | Multi-line commands | Reconstructed in timestamped files (the `#<epoch>` line is the record boundary). A plain file has no boundaries, so each line is imported as its own command |
  390. | Directory, exit code, duration, executor | Not in the file — stored as unknown, never guessed, and never recorded as a successful exit |
  391. ### Coming from Atuin
  392. ```bash
  393. suv import --from atuin-db --dry-run ~/.local/share/atuin/history.db # preview, writes nothing
  394. suv import --from atuin-db ~/.local/share/atuin/history.db # import
  395. ```
  396. The Atuin database is opened **read-only** — Suvadu never writes to it, never
  397. copies the file behind SQLite's back, and reads the whole history inside one
  398. transaction so a running Atuin can keep recording. Before writing, Suvadu takes
  399. a consistent backup of *its own* database and prints the `cp` command that
  400. restores it, then verifies afterwards that the Atuin file is byte-identical and
  401. that the entries it claims to have written are really there. Re-running the
  402. import adds nothing.
  403. Tested against Atuin 18.0.0 – 18.23.0 (history schema `20210422143411` –
  404. `20260818000000`); 18.23.0 by importing a database the real Atuin 18.23.0
  405. binary wrote, with [`scripts/test-atuin-import.sh`](scripts/test-atuin-import.sh). A database carrying a migration this release has not been
  406. tested against is rejected with the migration id rather than guessed at — run
  407. `suv update` and try again.
  408. | Atuin field | Imported as |
  409. |-------------|-------------|
  410. | `command` | Command text, verbatim (multi-line and Unicode preserved). Redaction and your exclusion patterns apply, exactly as for live recording — resolved from the directory Atuin recorded the row in, so a project `.suvadu.toml` governs imported history too |
  411. | `timestamp` (nanoseconds) | `started_at`, truncated to milliseconds, and nothing else. Two runs inside one millisecond keep the same `started_at` and stay separate entries: a row is identified by its Atuin `id`, never by its time |
  412. | `duration` (nanoseconds) | `duration_ms` / `ended_at`, truncated to milliseconds. Atuin's `-1` ("never finished") is stored as unknown, not as zero work |
  413. | `exit` | `exit_code`. Atuin's `-1` becomes `NULL` — never a fabricated success |
  414. | `cwd` | Directory. Empty or Atuin's literal `"unknown"` becomes unknown |
  415. | `session` | A Suvadu session per Atuin session, id `atuin-<session>` |
  416. | `hostname` (`host:user`) | Session hostname, plus `atuin_user` in the entry's context |
  417. | `author`, `author_kind` | `executor` and `executor_type` (`1`→human, `2`→agent). An unstated kind stays `unknown`: Atuin guesses "agent" from known author names, Suvadu records only what was stated |
  418. | `id`, `intent`, `shell` | Kept in the entry's `context` (`atuin_id`, `atuin_intent`, `atuin_shell`) — Suvadu has no columns for them. `atuin_id` is also what makes a re-import a no-op. The free-text ones go through the same redaction and exclusions as the command; a field an exclusion matched is withheld and named in `context.withheld_fields` |
  419. | `deleted_at` | Rows you deleted in Atuin are skipped and counted, never resurrected |
  420. | — | Sub-millisecond precision is lost (the rows are kept; only their ordering inside a millisecond is). Atuin has no tags, notes or command output to carry over, and Suvadu keeps no Atuin sync/record-store state |
  421. ---
  422. ## AI Agent Setup
  423. ```bash
  424. suv init claude-code # Claude Code — commands, sessions, tokens + MCP
  425. suv init codex # Codex — commands, sessions, tokens + MCP
  426. suv init cursor # Cursor — commands, sessions (no tokens) + MCP
  427. suv init opencode # OpenCode — plugin + full session capture (commands, sessions, tokens)
  428. suv init pi # pi.dev — extension + prompt capture
  429. suv init antigravity # Antigravity — agent commands (via ~/.zshenv)
  430. ```
  431. After setup, relaunch the configured agent. For either VS Code extension, fully quit and reopen VS Code. Codex also requires reviewing/trusting the Suvadu hooks when prompted (or through `/hooks`). Both installers preserve unrelated hooks and configure the Suvadu MCP server; Codex backs up an existing `hooks.json` before changing it and uses `CODEX_HOME` when set.
  432. ### What each agent actually gives you
  433. Three different things get called "AI agent support". Here is which one you get:
  434. | Agent | `suv init` | Commands | Prompts | Native session timeline | Tested against |
  435. |---|---|---|---|---|---|
  436. | Claude Code | `claude-code` | yes (hooks) | yes | **yes** | not pinned to a version — see the caveat below |
  437. | Codex | `codex` | yes (hooks) | yes | **yes** | CLI 0.153.4 |
  438. | OpenCode | `opencode` | yes (plugin) | yes | **yes** | CLI 1.18.30 |
  439. | Cursor | `cursor` | yes (hooks) | yes | **yes** — prompts, final responses and turn ends; no token usage | not pinned |
  440. | pi.dev | `pi` | yes (extension) | yes (capped at 500 characters by the extension) | no | not pinned |
  441. | Antigravity | `antigravity` | yes (`~/.zshenv` capture script) | no | no | Antigravity IDE 2.5.5 with zsh 5.9 |
  442. | Windsurf, Aider, Continue, Copilot | — | via the shell hook | no | no | — |
  443. The last row is **command tagging, not an integration**: the shell hook
  444. recognises the environment variable those tools set and labels commands with
  445. the right executor. There is nothing to install and no prompt is captured.
  446. Antigravity's agent runs each command as `zsh -c '<command>'` from its language
  447. server, a shell that never reads `~/.zshrc`, so the shell hook cannot see it.
  448. `suv init antigravity` writes a capture script to
  449. `~/.config/suvadu/hooks/antigravity-zsh.sh` and adds a marked block to
  450. `~/.zshenv` (`$ZDOTDIR/.zshenv` when set), backing up the previous file as
  451. `.zshenv.suvadu-backup-<id>`. The block sources the script only when
  452. `$ANTIGRAVITY_AGENT` is set in a non-interactive zsh running a `-c` command;
  453. every other shell skips it. Each agent command is recorded when its shell
  454. exits, with exit code, duration and directory, in a session per Antigravity
  455. run (`antigravity-<pid>`). Only zsh is covered. A command Antigravity starts
  456. with `exec`, or one killed by a signal, is not recorded. To make the shell wait
  457. for the command so it can record it, the script sets a no-op `EXIT` trap,
  458. which replaces an `EXIT` trap set earlier in `~/.zshenv` in those shells only.
  459. `suv uninstall` removes the block.
  460. Only the Codex and OpenCode figures above are versions Suvadu has actually
  461. been exercised against; nothing enforces them at runtime except for Atuin
  462. imports, where the schema really is checked. If an agent changes its hook or
  463. plugin contract, capture can degrade silently — `suv doctor` reports per
  464. agent whether its process was detected, its integration is installed, and
  465. commands, native sessions and MCP registration have been seen.
  466. ### Why it failed: failure output (opt-in)
  467. With `[capture] failure_output = true` (*Keep Failure Output* in
  468. `suv settings`; off by default), a command that fails keeps the last 4 KB it
  469. printed — where Suvadu already has that output:
  470. | Path | Output kept |
  471. |---|---|
  472. | Claude Code | the `PostToolUseFailure` error text, without its `Exit code N` line |
  473. | Cursor | `afterShellExecution`'s `output` |
  474. | Codex | the `PostToolUse` response's `output`, `aggregated_output` or `stdout`/`stderr` text, when it also carries an exit code |
  475. | OpenCode | the bash tool's output, sent by the plugin (rerun `suv init opencode`) |
  476. | `suv wrap -- cmd` | the command's stderr, passed through to your terminal unchanged as it runs |
  477. | zsh and Bash hooks | **nothing** — capturing a terminal's output means standing between the program and the terminal, which breaks interactive programs |
  478. Recall's detail pane shows it under a failed command (`Shift+Tab` scrolls a
  479. long one), and the MCP `what_failed`, `command_status` and
  480. `learn_from_failures` tools and the `failures/recent` resource show its last
  481. three lines (all of it with `detail=true`), marked as the command's own text
  482. rather than instructions; without it they say plainly that why a command
  483. failed is not known.
  484. Escape codes and progress redraws are stripped, secrets are redacted with
  485. the same rules and per-directory policy as the command (before the text is
  486. cut), an excluded command keeps nothing, and a project's `.suvadu.toml` can
  487. turn it off but not on. Under `suv wrap` the command's stderr is a pipe, so a
  488. program that colours or animates only on a terminal prints plainly there, and
  489. a background process it leaves running loses its stderr once `suv wrap`
  490. exits. The output goes with its command on `suv delete`, travels in JSON and
  491. JSONL exports, and `suv gc --failure-output` deletes all of it while keeping
  492. the commands.
  493. ### "Last time this failed, you fixed it with …"
  494. For a failed command, recall's detail pane says what fixed it before —
  495. `Last time this failed, you fixed it with: git status (3×)` — and the MCP
  496. `what_failed` and `learn_from_failures` tools add a `fixed before
  497. (inferred)` line. Nothing new is recorded for it: it is worked out from your
  498. history when asked, from the newest 50 failures of exactly that command
  499. (exit status other than 0 and Ctrl+C's 130). After each one, Suvadu looks at
  500. the next 20 commands of the same session, started within 15 minutes, in the
  501. same directory, skipping other failures:
  502. - a successful command **similar** to the failed one is its fix — the same
  503. program with the same first non-flag argument (`cargo build` →
  504. `cargo build --release`), or a small edit of the line (`gti status` →
  505. `git status`, at most one change per eight characters);
  506. - if that is the failed command again, unchanged, then a **setup step**
  507. that passed before it — the same program (`npm install` before
  508. `npm test`) or a package install — is the fix (`you fixed it with: npm
  509. install, then reran it`); with no setup step it *passed when you reran it
  510. unchanged*;
  511. - looking around in between (`cd`, `ls`, `cat`, `git status`/`diff`/`log`/
  512. `show`, an editor) is skipped, and any other successful command ends the
  513. search without a fix.
  514. Fixes are counted across those failures and the most common is shown. It is
  515. an inference from what ran next, never an observed cause. Each lookup takes
  516. under a millisecond on a 100,000-command history (BENCHMARKS.md), and recall
  517. makes it once per selected failed command.
  518. ### What changed: agent git snapshots
  519. When a Claude Code, Codex, OpenCode or Cursor session works in a git repository,
  520. Suvadu takes a **git snapshot** of it at the session's first prompt and again
  521. at each turn end (Claude Code and Codex `UserPromptSubmit` and
  522. `Stop`/`SessionEnd`; OpenCode's prompt and `session.idle`): the commit and
  523. branch checked out, and which paths `git status` reports as staged,
  524. unstaged, untracked, renamed, deleted or conflicted. **Paths only — never
  525. file contents, never diffs.** The first snapshot is kept; each turn end
  526. replaces the last one, so a session holds at most two.
  527. - `git` runs only at those moments, never per command, as
  528. `git --no-optional-locks status --porcelain=v2 --branch -z` with
  529. `core.fsmonitor` off, so it never takes the index lock from under the agent
  530. and a repository's own config cannot make it run a program. It gets 2
  531. seconds; if it is slower, missing from `PATH` or the directory is not in a
  532. repository, nothing is recorded and the agent's hook carries on. Outside a
  533. repository no `git` process starts. In a 10,000-file repository a snapshot
  534. adds about 30–35 ms to the hook that takes it, nearly all of it `git status`
  535. (Apple M4 Max; see BENCHMARKS.md); later prompts add under 1 ms.
  536. - Paths matching your `exclusions` are left out (and counted), the rest and
  537. the branch name are redacted like command text, and at most 500 paths are
  538. kept — a snapshot says when more changed.
  539. - Turn it off with *Record Agent Git Snapshots* in `suv settings` or
  540. `[agent] record_git_snapshots = false`; a project's `.suvadu.toml` can turn
  541. it off but not back on. Paused capture records none.
  542. - Snapshots go with their session on `suv agent delete-session`; `suv gc`
  543. removes those a day old whose session left no other record. They are not
  544. exported, like the agent sessions they belong to.
  545. Cursor sessions get them too, at `beforeSubmitPrompt` and `stop`.
  546. The MCP `what_changed` tool reads them. Given a `session_id`, it compares the
  547. session's two snapshots and reports, with `provenance: observed`, the paths
  548. whose git status changed in between and the commits made between the two
  549. HEADs, which it asks the repository for at that moment (`git rev-list`,
  550. `git log`, `git diff --name-only`, under the same 2-second limit) — so a
  551. commit made during the session is listed with its subject and the files it
  552. touched. Those subjects and paths are never stored, and get the repository's
  553. own exclusions and redaction before they are shown; if the repository or the
  554. commits are gone, it gives just the two HEADs. A path changed in the
  555. repository, **not necessarily by the agent**, and a path that already showed
  556. a change at the start and shows the same one at the end is not listed even if
  557. it changed again. Without both snapshots it falls back to reading the
  558. session's commands for their likely effect, marked inferred, and says why.
  559. Asked about a directory and a time window instead, it lists the sessions there
  560. that have snapshots before its usual command-text breakdown.
  561. In `suv sessions`, an AI session's timeline header says what its snapshots
  562. saw — `Changed: 3 files, 1 commit` — on terminals at least 100 columns wide,
  563. and the handoff scaffold (`h`) lists the commits and changed paths under
  564. *Changed-file evidence*, citing the two snapshots.
  565. ### What is never captured
  566. - **Command output and file contents.** Suvadu records that a command ran,
  567. how it exited, how long it took and where — never what it printed or what
  568. it changed — except the opt-in failure output above, the end of what a
  569. failed agent or `suv wrap` command printed. Agent git snapshots name the
  570. paths that changed, never their contents.
  571. - **From native transcripts:** thinking blocks, attachments, images, file
  572. contents and raw tool results. Codex commentary and reasoning, injected
  573. AGENTS/environment context and developer instructions are excluded too.
  574. - **Non-shell tool calls and file edits**, and child sessions started from a
  575. session — stated on every session header as `capture.unverifiable`.
  576. - **Size limits:** hook input is read up to 16 MiB, keeping only the fields
  577. Suvadu records, so a large tool output never costs the command; past
  578. 16 MiB the command is still recorded when it arrived before the cut, and
  579. the hook fails with a named error otherwise. A single native transcript
  580. record is capped at 16 MiB; an oversize record is rejected with a named
  581. error rather than silently truncated. Prompt text is capped at
  582. `agent.prompt_capture_max_chars` (default 4000).
  583. - **Timing and exit codes are not equally trustworthy per agent.** Codex and
  584. Claude Code hook timestamps are *receipt* time, not execution time (Codex
  585. records `timing_source = hook_received`). Codex leaves the exit code
  586. unknown when it does not supply a structured one; Claude Code and Cursor
  587. infer 0 from a success hook; pi.dev's bash tool does not expose one, so its
  588. extension guesses.
  589. A session header therefore reports what Suvadu *knows* it missed
  590. (`known_missing`: a paused window, a directory where capture was switched
  591. off, token counters it could not follow) separately from what it never
  592. observes at all. `complete` means no gap was recorded — never that
  593. everything the agent did is here.
  594. ```bash
  595. suv history --executor openai-codex
  596. suv agent prompts --executor openai-codex
  597. ```
  598. Codex shell commands link to the prompt from the same turn. Prompts without recorded commands do not appear in the prompt explorer. Capture respects Suvadu's recording and redaction settings. Hook timestamps reflect receipt time; exit status stays unknown when Codex does not provide a structured exit code. This requires a Codex version supporting `UserPromptSubmit` and `PostToolUse` hooks (tested with CLI 0.153.4). Stop and SessionEnd hooks also incrementally import Codex's native transcript for prompts, final assistant answers, and provider-reported token usage, independent of shell commands (bounded to 16 MiB per record) — this part requires a Codex version supporting `Stop`/`SessionEnd` hooks too.
  599. Claude Code commands link to their native prompt turn after transcript reconciliation. Stop and SessionEnd hooks incrementally import local transcript records for prompts, assistant text, models, and provider-reported token usage. Thinking blocks, attachments, images, file contents, and raw tool results are not stored in Suvadu.
  600. `suv init opencode` installs a plugin at `~/.opencode/plugins/suvadu.js` and also registers that directory in `~/.config/opencode/opencode.jsonc`'s `plugin` array — OpenCode does not reliably auto-load plugins from the directory alone. If your `opencode.jsonc` already has JSONC-style comments (which this step can't safely parse and rewrite without risking the rest of your config), it prints the exact line to add yourself instead. Bash commands OpenCode executes are recorded immediately; prompts, assistant responses, model, and token usage are captured when a session goes idle, via OpenCode's own `session.messages` API. The plugin hands Suvadu only what it stores — each message's text, model and token counts, never tool output or reasoning — and only the messages it has not already imported, so a long session costs each idle only its new messages. Rerun `suv init opencode` after upgrading Suvadu or OpenCode, then fully quit and relaunch OpenCode so the updated plugin and config take effect. Tested against OpenCode CLI 1.18.30; if OpenCode reports a plugin load error after an OpenCode upgrade, its plugin contract may have changed again and `suv init opencode` will need a matching update.
  601. `suv init cursor` registers four hooks in `~/.cursor/hooks.json`, beside any you already have there: `afterShellExecution` (commands), `beforeSubmitPrompt` (prompts), and `afterAgentResponse` and `stop` (the final response of each turn and how it ended). Each Cursor conversation becomes one session, `cursor-<conversation_id>`, with the conversation's commands linked to the turn (Cursor's generation id) they ran in. The caveats are Cursor's: its hooks report **no token usage**, so a Cursor session's tokens are *unavailable* — never zero — and its capture status says so; they carry no timestamps, so events are timed when the hook receives them; Cursor sends only the final response text of a turn, so intermediate assistant messages, thinking (`afterAgentThought`, not installed) and tool calls other than shell commands are not captured; and an event is captured only when Cursor names a workspace, whose `.suvadu.toml` decides its redaction and exclusions. Rerun `suv init cursor` and restart Cursor after upgrading Suvadu.
  602. For agents configured with MCP, ask: *"What commands failed in this project recently?"*
  603. ### Prompt Explorer or session timeline?
  604. Both show "what the agent did", from two different stores, and neither
  605. subsumes the other.
  606. - **Prompt Explorer** (`suv agent prompts`) is built from **recorded shell
  607. commands**. It groups them by the prompt that was live when they ran and
  608. reports that turn's command count, successes, failures and total time. A
  609. prompt that produced no recorded command never appears — there is nothing
  610. to group. It works for every agent whose prompt is captured, including
  611. pi.dev, which has no session timeline, and it browses across
  612. sessions with a time window and an executor filter.
  613. - **Session timelines** (`suv sessions`, and `suv agent sessions` for the
  614. non-interactive view) are built from the agent's **own transcript**,
  615. imported incrementally. They show prompts, assistant responses,
  616. interrupted turns, every observed model and provider-reported token
  617. totals — including sessions with no commands at all — plus capture
  618. completeness, saved summaries (`s`) and the handoff scaffold (`h`). Only
  619. Claude Code, Codex, OpenCode and Cursor have one.
  620. ### MCP: read-only by default
  621. The server advertises **22 read-only tools, 8 resources and 6 prompts**.
  622. Every one of them reads. There are exactly two write tools, and both are off
  623. until you turn their opt-in on:
  624. | Write tool | Opt-in | What it can do |
  625. |---|---|---|
  626. | `save_session_summary` | `mcp.allow_session_summaries` | store a summary the calling agent generated, when you ask it to |
  627. | `propose_skill` | `mcp.allow_skill_proposals` | propose a skill, always as **pending review**, never active until you approve it in `suv skills` (`Ctrl+P`) |
  628. To turn one on: run `suv settings`, go to the **MCP** tab (`Tab` to cycle),
  629. and under **Writes** press `Enter` on the row. Save with `Ctrl+S`, **then
  630. restart your MCP client** — the server reads its configuration once at
  631. startup, so a running client keeps the old settings until it reconnects.
  632. Then ask: *"Summarize and save current session."*
  633. The same tab lists every tool and resource with its *effective* state. A
  634. write tool shows **why** it is off — because its opt-in is off, because you
  635. turned that tool off, or both — instead of two switches that can disagree.
  636. Turning an opt-in back off stops new writes; summaries already saved are
  637. kept.
  638. **Which config the server reads.** Tool and resource availability, the two
  639. write opt-ins, `mcp.exclude_dirs` and the MCP defaults come from the
  640. **global `config.toml` only** — a project `.suvadu.toml` overlay does not
  641. change which MCP capabilities are on. Redaction, exclusions and your custom
  642. risk rules *are* resolved through the overlay, but from the directory the
  643. MCP server process was started in, once, at startup. Both are another reason
  644. a change needs a client restart.
  645. Every response follows one convention, so a caller can calibrate its trust:
  646. RFC 3339 timestamps, `unknown` as the only missing-value token, percentages
  647. that always carry their fraction, `limit`/`offset` with `next_offset`,
  648. visible truncation, a stable `command-<id>` on every row, and a
  649. `provenance:` line saying **observed** (records Suvadu stored), **inferred**
  650. (anything derived from them) or **caller-reported** (text an agent wrote).
  651. Anything inferred also repeats that Suvadu records commands, exit codes and
  652. timings — never file contents, and command output only as the opt-in end of
  653. a failed agent or `suv wrap` command.
  654. A saved summary is the agent's own text, stored back. Suvadu invokes no
  655. model and generates no prose. The writing agent and model are recorded as
  656. **caller-declared metadata, not verified identity**, and the summary's cited
  657. evidence IDs are checked to exist in that session. Suvadu resolves the
  658. current Codex, Claude Code or OpenCode session without guessing: no working
  659. directory means no resolution, and more than one match is always your
  660. choice. A later request extends an append-only checkpoint from its saved
  661. event and command offsets; if the evidence it was written from changed, the
  662. agent rebuilds from the full session.
  663. See the [full integration guide](https://suvadu.sh/blog/track-ai-agent-commands-with-suvadu/) and [MCP server docs](https://suvadu.sh/cli/mcp-server/).
  664. To add the MCP server to any other client by hand, run `suvadu mcp-serve` (or `suv mcp-serve`) as a stdio server.
  665. - MCP Registry name: `mcp-name: io.github.AppachiTech/suvadu`
  666. ---
  667. ## Key Features
  668. | Feature | Details |
  669. |---------|---------|
  670. | **Home** | A bare `suv` (or `suv home`) — search Suvadu's features by task, see the real command behind each, open screens, pickers and reports, or read copyable instructions for anything that changes data; *Startup Screen* in `suv settings` brings back the classic overview |
  671. | **Search** | Full-history search TUI with four [matching modes](#how-recall-matches-and-ranks) (`^X`) and four scopes (`^P`), matches highlighted in each row, every run or identical commands grouped with last-used and run counts (`^U`), your own commands by default (`Ctrl+A` shows agents, `Ctrl+E` failures only), filters, Smart rank, detail pane, a raw inspector for exact text (`^V`), the timeline of the session a command ran in (`^K`), bookmarks, and `--compact` inline recall |
  672. | **History** | Non-interactive `suv history` with filters, `--json`, pipeable to other tools |
  673. | **Agent Dashboard** | Timeline, risk assessment, per-agent analytics, exportable reports; `suv agent report --fail-on <low\|medium\|high\|critical>` for local CI / git-hook gating |
  674. | **MCP Server** | 22 read-only tools, 8 resources and 6 prompts, plus two opt-in write tools that are off by default — agent session replay and incremental cross-agent summary checkpoints, project context, failure learning; one response convention with explicit provenance |
  675. | **Skills Library** | `suv skills` — interactive TUI to browse, add, edit, delete, sync, and review shared skills any MCP-capable agent can read instead of each tool keeping its own copy. `sync --dry-run` diffs the managed region of each generated file; a region edited outside Suvadu is reported as a conflict and skipped, not overwritten (`--force` overrides), and the files of skills since removed or disabled are removed. Team skills committed in `.suvadu/skills/*.md` sync once you trust them — see [Team skills in the repository](#team-skills-in-the-repository). `add/list/show/edit/rm/disable/enable/sync/cleanup/trust/untrust` also work as scriptable subcommands |
  676. | **Prompt Explorer** | `suv agent prompts` groups **recorded commands** by the prompt that triggered them, with that turn's successes, failures and duration. A prompt that ran no recorded command does not appear — for the agent's own transcript, use a session timeline |
  677. | **Unified Sessions** | `suv sessions` browses human and AI sessions together, with a **Capture** column that reports `full` or `gaps: N` from recorded gaps alone — never inferred from exit codes. Native Codex, Claude Code and OpenCode sessions show prompts, responses, commands, every observed model and provider-reported token totals; `s` opens saved summaries (badged CURRENT / NEW ACTIVITY / EVIDENCE CHANGED; `Tab` toggles rendered/raw, `Ctrl+Y` copies) and `h` builds a handoff scaffold from captured records only |
  678. | **Stats** | Heatmap, hourly distribution, top commands, executor breakdown; `--human` (or `Ctrl+H` in the TUI) excludes AI-agent activity |
  679. | **Doctor** | `suv doctor` separates what blocks shell-history capture from optional integrations, gives each check its own repair, reports what the stored data actually proves, and lists storage by category next to the retention rule that changes it |
  680. | **Organization** | Tags, bookmarks (`suv bookmarks` opens an interactive picker that recalls one into your prompt; a bookmark with `{{name}}`/`{{name:default}}` placeholders asks for each value first, and `suv bookmarks get <label> --set name=value` prints it filled — see [Bookmarks with placeholders](#bookmarks-with-placeholders)), notes, and `suv aliases` — an interactive manager (add/edit/delete) for shell aliases, plus suggestions for your frequently-typed long commands |
  681. | **Privacy & Safety** | Space-prefix exclusion, regex patterns, secret redaction (extend via `redaction.extra_patterns`), local-only — applied to every ingestion path, imports and saved summaries included. `suv redact` masks secrets in history already stored. `suv backup`, an automatic snapshot before any `suv delete`, and `suv delete --dry-run` to see the matched commands and what a delete leaves behind. See [SECURITY.md](SECURITY.md). |
  682. | **Arrow Keys** | Recency-first Up/Down recall — your most recent commands surface first, prefix-matched, with the current directory used only to separate commands recorded at the same millisecond. Agent commands are hidden by default; reveal them with `Alt+A` (per shell) or `--include-agents`. Zsh only (Bash keeps its own Up/Down), and `suv doctor` warns when a plugin loaded later takes Up over — see [Up-arrow recall](#up-arrow-recall). The same lookup drives a [zsh-autosuggestions](https://github.com/zsh-users/zsh-autosuggestions) strategy: `ZSH_AUTOSUGGEST_STRATEGY=(suvadu history)`. |
  683. | **Git Branch** | Every command recorded inside a git repository keeps the branch it started on, read from `.git` with no `git` process, shown in recall's detail pane and in detailed MCP rows. Worktrees and submodules are followed; a detached HEAD is kept as its short hash. |
  684. | **Vim Bindings** | Optional vim-style `j`/`k`/`Ctrl+U`/`Ctrl+D` navigation in search TUI |
  685. Full feature documentation at [suvadu.sh/cli](https://suvadu.sh/cli/).
  686. ---
  687. <details>
  688. <summary><strong>More demos</strong></summary>
  689. <p><em>Recorded in Suvadu 0.5.0 with fictional data. The search demo above
  690. shows Ctrl+R recall; the demos below cover feature discovery and AI sessions.
  691. The AI example uses staged records, not a live agent run.</em></p>
  692. <p align="center">
  693. <img src="demo/suvadu-home.gif" alt="Suvadu Home — browse features, find failed commands, and open filtered history" width="960">
  694. <br>
  695. <em>Discover features — run suv, search by task, and open a tool</em>
  696. </p>
  697. <p align="center">
  698. <img src="demo/suvadu-ai.gif" alt="Suvadu AI session — read a prompt, inspect a failed test and successful retry, then read the recorded response" width="960">
  699. <br>
  700. <em>AI activity — follow the prompt, commands, exit status, and response in one timeline</em>
  701. </p>
  702. Watch the [video versions](https://suvadu.sh/#demo), or read the
  703. [Home guide](https://suvadu.sh/cli/home/) and
  704. [session guide](https://suvadu.sh/cli/sessions/).
  705. </details>
  706. ---
  707. ## Development
  708. ```bash
  709. git clone https://github.com/AppachiTech/suvadu.git
  710. cd suvadu
  711. make dev # Run the app
  712. make test # Run tests
  713. make lint # Run clippy + format check
  714. ```
  715. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and the release
  716. checklist, and [BENCHMARKS.md](BENCHMARKS.md) for how search is measured.
  717. ## Security
  718. See [SECURITY.md](SECURITY.md) for vulnerability reporting, data storage design, and privacy details.
  719. ## License
  720. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.