Your shell history, searchable by meaning, with proof of what worked. For you and your AI agents.
Website: rdarshan10.github.io/reman
One fast Rust binary that remembers every command you and your AI agents run: where it ran, whether it worked, and what fixed it when it didn't. Find anything by describing it ("tear down containers", "run migrations"), not by remembering the exact text.
in this folder ─────────────────────────────────────────── │ docker compose down -v
▌✓ docker compose down -v 14× 2d │ docker: Stop and remove containers, networks,
✓ docker compose up -d 20× 1h │ images, and volumes created by `docker compose up`
✓ docker system prune -af --volumes 3× 1w │ ✓ worked every time (14 runs) · last 2 days ago
everywhere ─────────────────────────────────────────────── │ in ~/work/api
· docker compose logs -f api 11× 3d │ matched: close in meaning · shares your words
· docker images 4× 1w │
this folder first ←→ · by you F3 · any outcome F2 24 results
› tear down containers Recall Fixes Flows
Why
Shell history remembers text, not intent. You know you've done it before, but not the exact flags, the folder, or which of five variants actually worked.
- Up-arrow and Ctrl+R only match text. "Tear down containers" never finds
docker-compose down -v.
- History forgets outcomes. A command that failed twice looks the same as one that worked a hundred times.
- Fixes get lost. Last month you mistyped a command and then ran the right one. Nothing remembers that pair.
- AI agents start from zero. Claude Code, Codex and Cursor guess commands from scratch instead of reusing the ones that already work on your machine.
reman closes that loop: every run is captured with its folder, exit code, duration and who ran it (you or an agent), and all of it is searchable by meaning, in your terminal and by your agents.
Features
- Recall by meaning. Semantic plus fuzzy search over your real history.
run migrations finds alembic upgrade head even though the words don't match. Results from this folder come first, then everywhere; a folder with no good match never dead-ends. When nothing in your history is close, it says so instead of passing off a guess.
- Proof of what worked. Every command shows its track record: worked every time, failed every time, or the success rate. A command that only ever failed never leads a list.
- Fixes. After a failure, reman prints what worked last time (
gti status → git status), learned from what you actually ran next, with what it changes when it's a variant of what failed (adds --build, ci → install --legacy-peer-deps). Alt+F inserts it.
- The same error, a different command. reman keeps what a failed command printed. When a different command fails with the same error (
npm ci hitting the ERESOLVE that npm install hit last week), it offers what fixed the first one. Agents get it too by passing the error to reman_fixes.
- A warning before it fails. Press Enter on a command that failed every time it ran here, or the last 3 times in a row, and reman holds it once when failing costs something: its failures took 10s or more (
failed the last 3 times here, after about 2m each time), or it installs, builds, migrates or deploys. It says why, shows its last error and what worked instead (Alt+F inserts it), and Enter again runs it anyway. A command that fails in a blink just runs. It's an exact lookup on Enter, never while you type (PowerShell, zsh and fish).
- The finder, where you are. It opens in the 20 lines under your prompt, so what you were looking at stays in view (the whole screen, or 30 lines, in
reman settings). It lists your own commands; F3 adds what agents ran. Ctrl+O on a command shows every run of it: when, how long it took, whether it worked, the branch, the folder and who ran it, with what that run printed beside it, and Del Del forgets one run. Vim keys are a setting: Esc for normal mode, j k to move, dd to forget, i to type, q to close.
- What a command printed. What your agents' commands print is kept as they run. For your own,
reman shell runs your shell inside a terminal layer of reman's own (ConPTY on Windows, a pseudo-terminal elsewhere), passed through untouched, and keeps what each command printed, read the way your terminal drew it: colours gone, a progress bar as it ended, long output whole. , , or finds it by the command or by what it printed; agents read it through instead of running a command again. Secrets are masked, only the end of a long output is kept, and only for your newest 3000 runs. can open every new shell inside it.
Install
Windows (PowerShell)
irm https://raw.githubusercontent.com/rdarshan10/reman/master/install.ps1 | iex
Windows PowerShell blocks profile scripts by default on a fresh Windows 10/11 ("running scripts is disabled on this system"), and then reman can't load in new windows. Setup detects this and asks to allow your own scripts for your user only (Set-ExecutionPolicy RemoteSigned -Scope CurrentUser, the same step Scoop and oh-my-posh need). reman doctor reports it too.
macOS and Linux
curl -fsSL https://raw.githubusercontent.com/rdarshan10/reman/master/install.sh | sh
Both scripts download the latest release, verify its SHA-256 checksum, and run reman setup. Setup is the whole onboarding, with nothing to configure by hand:
- copies reman into
~/.reman/bin and starts its background daemon;
- wires your shells: the PowerShell profile and Command Prompt on Windows, your zsh / bash / fish config on macOS and Linux, and nushell and xonsh wherever they're installed;
- connects every coding tool it finds: Claude Code, Claude Desktop, Codex CLI, Cursor, VS Code, Windsurf, Gemini CLI, opencode and pi. Each gets the MCP server (pi has no MCP) and, when it runs shell commands, capture through its own hooks (or a small reman plugin for opencode and pi), so what the agent runs is remembered too. Each config gets a
.reman-bak backup first.
Everything it set up can be changed later on one page: reman settings. To skip connecting coding tools, set REMAN_NO_CONNECT=1 (or run reman setup --no-connect). The first start downloads the embedding model, about 130 MB, once. reman then downloads its own model, the same one trained on commands (about 115 MB, checked against a checksum built into reman), and moves your history to it in the background; Search model in reman settings switches between the two. With updates off, reman downloads nothing.
Manual download
Pick your file from the latest release:
| platform | file |
|---|
| Windows 10/11, x64 | reman-windows-x64.zip |
| macOS, Apple Silicon (M1 and later) | reman-macos-arm64.tar.gz |
| Linux, x64 | reman-linux-x64.tar.gz |
Intel Macs aren't supported: ONNX Runtime, which reman's search uses, publishes no build for them.
Unpack it and run reman setup (reman.exe setup on Windows). On macOS, a file downloaded through a browser may be quarantined; clear that with xattr -d com.apple.quarantine reman reman-hook.
From source
Requires Rust 1.85 or newer.
git clone https://github.com/rdarshan10/reman
cd reman/rust
cargo build --release
./target/release/reman setup
Updates
reman update # install the latest release now
reman update --check # only say whether one is out
reman update --auto off # just tell me when one is out (on: install them on their own again)
Once a day reman asks GitHub whether a new version is out, installs it on its own, and a desktop notification says it did. With --auto off a notification only tells you, once per version. reman settings has the same choice, plus never check, which keeps reman off the network entirely.
Every update is checked before anything runs. Each release's SHA256SUMS.txt is signed with reman's release key (Ed25519), whose public half is built into reman, so a release that wasn't signed with it, or a file changed after signing, is refused. The archive must then match its signed checksum. Only a newer version is installed, never an older one. Of GitHub's answer only the version number is used, and every download address is built by reman itself, over https only. An AI agent can't turn automatic updates on.
Uninstall
reman uninstall # lists everything it will remove, then asks
reman uninstall --purge # also delete your history, settings and the search model
It takes reman out of every coding tool (MCP entries, capture hooks, the HTTP endpoint), your PowerShell profile, your zsh / bash / fish config, Command Prompt's r / rr and your PATH, each by reman's own marker, so everything else in those files stays as it was. Then it stops the daemon and deletes the program. Your history stays in ~/.reman unless you pass --purge. --dry-run only lists; --yes skips the question.
Getting started
Open a new terminal after installing.
| you press / type | what happens |
|---|
↑ | the finder, for this folder |
Ctrl+R | the finder, for all folders |
Tab / Shift+Tab inside the finder | switch between Recall, Fixes and Flows |
Enter | put the command on your prompt (it never runs by itself) |
Ctrl+O inside the finder | every run of the selected command, and what each printed |
F3 inside the finder | your commands, yours and agents', or agents' only |
Alt+F | insert the fix suggested after a failed command |
F1 inside the finder | every key |
F10 inside the finder | settings |
In Command Prompt, type r (this folder), r docker (start with a query), or rr (everywhere).
From the command line:
reman search "tear down containers" # search by meaning
reman fixes "gti status" # what worked instead
reman next # what you usually run next here
reman check "docker compose up -d" # has this been run, and did it work?
reman flows --here # sequences you repeat in this folder
reman here # what you did in this folder last time
reman why # it used to work: what ran here since (or: reman why npm test)
reman runbook > RUNBOOK.md # how this project is run, from what worked
reman scrub # mask secrets in older history (dry run; --apply)
reman sessions migration last week # the agent session that did it
reman resume migration # reopen it, in its folder
reman shell # your shell inside reman's terminal layer: output kept
reman output --failed # what the last failed commands printed
reman delete "vault read" --yes # remove runs by their text
reman prune # apply ignore rules to older history
reman stats week
Settings
reman settings # or press F10 inside the finder
One page for everything setup configured. Every change is saved as you make it:
- Coding tools: connect or disconnect each one with Enter, and turn the local HTTP endpoint (for SDKs and scripts) on or off.
- What agents can see: share or unshare folders. Your busiest folders are suggested, with their run counts, and
a types in any other folder.
- Privacy: secrets in commands (mask the value, drop the command, or keep as typed for you while agents still get them masked), strict secret redaction for agents, and whether generic commands from old, folder-less history are shared.
- Updates: tell me when a new version is out (the default), install them on their own, or never check.
- Finder: where it opens (20 or 30 lines under the prompt, or the whole screen), whether it lists agents' commands from the start, and vim keys.
- Keys: every key reman takes, in your shell and in the finder. Press Enter on one and then the new key,
Del to turn it off (the key does what it did before reman), r for the preset's key. Presets: standard, gentle (reman leaves ↑, Tab and Enter alone) and vim. A key that's taken, types a character, or is one your shell or terminal needs is refused or flagged. From the command line: reman keys, reman keys set find_all Alt+J, reman keys set find_here off, reman keys preset gentle.
- What commands print: how many runs keep their output (the newest 3000, 300, or none), and whether new shells open inside
reman shell.
- Shells: whether PowerShell, Command Prompt, or your zsh / bash / fish is wired; Enter wires one that isn't.
- reman: daemon status, data folder, version.
Language model (optional)
reman works fully without one. When one is available, reman runbook asks it to arrange and explain the project's commands.
-
Found automatically on this machine: Ollama (localhost:11434), LM Studio (localhost:1234) or a llama.cpp server (localhost:8080). Nothing leaves your machine.
-
Any OpenAI-compatible endpoint, if you set one in ~/.reman/config.json. A remote endpoint is only used when set there:
"ai": { "endpoint": "https://api.openai.com/v1", "model": "gpt-4o-mini", "api_key_env": "OPENAI_API_KEY" }
The key is read from that environment variable (default REMAN_AI_KEY) and never stored.
-
What the model may do: order, summarise, add a few words per command, and place commands no rule knows into a section. Every command in its answer must be one from your history, character for character, or it is dropped. Commands are redacted before they are sent.
-
Speed: the answer is cached per project until its commands change. Agents never wait on a model: they get the history-only runbook at once, and the fuller one on their next call.
-
Off: reman settings (Language model), or reman runbook --static for one run.
AI agents
reman connect all # Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI
reman connect # status, plus folders agents can't see yet
reman connect --add-root ~/projects/api
reman connect http # local HTTP endpoint for the OpenAI Agents SDK, LangChain, curl
Agents get ten tools: reman_search, reman_check, reman_fixes, reman_recent, reman_failures, reman_flows, reman_next, reman_runbook (how the project is run, from what worked there; reman tells an agent new to a project to call it first), reman_output (what a command printed the last times it ran) and reman_running (the servers up right now in their folders, and who started each). Every command they get back is one that really ran; reman never generates commands. When nothing close is known, reman_search returns nothing rather than the least-bad guess, and says so; the same goes for a result a filter emptied or a folder the agent can't see. A query that names a tool you use (astro, vercel) is only ever answered with that tool. Commands from the agent's own project come first when matches are close.
What agents can see:
-
Only folders you approve. Nothing is visible to an agent until you share a folder, not even the project it's working in (a repo, a git worktree of it included; never your whole home folder or a drive).
-
Strict permissions, on by default: when an agent needs its project's history, only reman's own dialog box can let it in: a light or dark card on Windows, a native alert on macOS, zenity or kdialog on Linux. Allow for this session (nothing is saved; the next session asks again), Always allow, or Don't allow (not asked again this session). Your AI app's buttons and dialogs don't count, so an app set to approve tool calls by itself can't share anything. Where the dialog can't be shown (over SSH), nothing is shared. Only you can turn it off, in your own terminal (reman settings, under What agents can see).
-
With strict permissions off, approve it from the chat with your app's own buttons:
- in apps that support MCP elicitation (VS Code's Copilot, Cursor, Claude Code in a terminal), reman asks you there, with the same three choices;
- everywhere else (Claude Code in VS Code, Claude Desktop, Gemini CLI...), the agent calls
reman_share_project, and your app's usual tool approval (Allow / Deny) decides: Allow shares the project for this session only. After a No, the agent can't ask again that session.
Either way the decision is yours, not the AI's.
-
Or from your terminal: reman connect --add-root <folder> shares a folder with every agent for good (--remove-root undoes it); reman connect lists your busiest folders that aren't shared.
-
Secrets are redacted, and in strict mode (the default) anything still secret-looking is withheld.
Commands your agents run are recorded too, tagged with the agent's name, with how long they took and, when they fail, what they printed: Claude Code (Bash and PowerShell), Codex (approve its hooks once with /hooks), Cursor, VS Code's Copilot (and the Copilot CLI), Windsurf and Gemini CLI through their own hooks, opencode and pi through a small reman plugin. Where a tool gives no exit code, or a pipe hides it, the result is read from what the command printed; with nothing clear, the run is recorded with an unknown outcome rather than a guess. Agents that type into your terminal (Copilot, Cursor, Windsurf) are recorded once, with your shell's exact exit code.
Performance
Measured on a history of about 6,000 commands and 21,000 runs:
| operation | p50 |
|---|
| search by meaning | 7 to 9 ms |
| browse recent | 3.5 ms |
| did-you-mean | 4 ms |
| next-command prediction | 0.2 ms |
| capture, PowerShell | no process spawned |
| capture, bash / zsh / fish | 5 / 2 / 5 ms |
Architecture
rust/src/
├── daemon.rs warm daemon: model loaded when needed, whole history in memory, JSON lines on localhost
├── store.rs in-memory model of the history (vectors, provenance, per-folder stats)
├── search.rs hybrid ranking: meaning (bge-small) + fuzzy text + track record
├── dym.rs did-you-mean for failed commands
├── fixpairs.rs learned fixes: what you ran after a failure, and it worked
├── flows.rs repeated command sequences
├── predict.rs next-command prediction
├── tui.rs the finder
├── complete.rs Tab completion for reman itself, one engine for every shell
├── mcp.rs MCP server for agents, with the folder boundary
├── http.rs local HTTP endpoint (MCP Streamable HTTP + REST)
├── connect.rs `reman connect`: wires each agent's config
├── capture.rs recording, used by the shell hooks and reman-hook
├── pty.rs `reman shell`: the terminal layer that keeps what commands print
├── output.rs what a command printed, as kept: plain text, its end, redacted
└── init/ shell integrations: PowerShell, bash, zsh, fish, nushell, xonsh, Command Prompt
Detailed documentation, every key and the storage layout: rust/README.md. The real-terminal and agent test suites: rust/e2e.
Roadmap
- ✅ Capture everywhere: PowerShell, bash, zsh, fish, Command Prompt, Claude Code
- ✅ Hybrid search, fixes, flows, prediction
- ✅ The finder: sections, track record, flows you can walk through
- ✅ Agents: MCP server, HTTP endpoint, one-command connectors
- 🚧 Signed binaries for Windows and macOS
- 🚧 Homebrew tap and winget package
- 🚧 Sync between machines
Credits
- Atuin (MIT License): its secret patterns are adapted in
redact.rs, and reman shell follows the design of its terminal layer, on Windows too. Coming from Atuin? reman setup imports its history.
- tldr-pages (CC BY 4.0): the command descriptions reman shows and searches. PowerShell cmdlets tldr has no page for are described from Microsoft's PowerShell documentation (CC BY 4.0, examples MIT). A program neither covers is described from its own files on your machine (an npm package's description, a Python package's summary, an exe's version information, a script's opening comment), never by running it.
- bge-small-en-v1.5 by BAAI (MIT License), the search model, run by ONNX Runtime.
The full notices are in THIRD_PARTY_NOTICES.md; every Rust library reman is built from, with its license, is in THIRD_PARTY_LICENSES.html in each release.
License
reman is licensed under the Apache License 2.0. Contributions are accepted under the same license.
Contributing
Issues and pull requests are welcome, especially new shell integrations, agent connectors and search-quality examples. Please open an issue first for larger changes.
To run the tests:
cd rust
cargo test
python e2e/search_quality.py # search quality, and the website's examples
python e2e/powershell_terminal.py # real-terminal suites, see rust/e2e/README.md
