Recoil

recoil

Memory for AI coding agents. It remembers the things that go wrong — a failed command, a revert, a correction — and reminds your agent when it's about to hit them again. One Go binary, a plain text file, no embeddings.

What it does

• Remembers a lesson tied to the situation it happened in — the files, the error text, the keywords around it.
• Brings that lesson back when your agent is in a similar situation again, matched by plain keyword overlap (an unrelated task gets nothing).
• Records failures automatically: recoil watch -- <cmd> remembers anything that exits non-zero, no manual step.
• Records git reverts automatically, via a post-commit hook.
• Warns the agent before it repeats a known-bad change — a git pre-commit hook that flags when a change touches something that went wrong here before.
• Surfaces the lessons that keep mattering — each recall makes one a little louder.
• Lets unused lessons fade, and recoil decay clears out the ones that stopped mattering — recall keeps the useful ones alive.
• Keeps everything in one plain-text file you can read and edit by hand.

Install

recoil is a single binary that needs to be on your PATH. No Go toolchain needed for the prebuilt builds:

curl -sSfL https://raw.githubusercontent.com/EclipseElips/recoil/main/install.sh | sh -s -- -b /usr/local/bin

Or download an archive for your platform from the releases page.

recoil is a command-line tool — you run it from a terminal. After you unpack a prebuilt archive, put the binary somewhere on your PATH and run it from a shell:

Windows.

.\recoil.exe init
.\recoil.exe version

Move recoil.exe into a folder on your PATH to run recoil from anywhere.

macOS.

xattr -d com.apple.quarantine ./recoil
chmod +x ./recoil
./recoil version

Linux.

chmod +x ./recoil
./recoil version

With a Go toolchain:

go install github.com/EclipseElips/recoil@latest

From source — stdlib only, so that's the whole build:

go build -o recoil .

Then create the store, once per repo:

recoil init

Use it with your coding agent

recoil ships as a skill, so the agent knows when to reach for it: recall and guard before it touches your files, encode a lesson when something goes wrong.

Claude Code — recoil is submitted to Anthropic's community plugin directory. Once it's listed there:

/plugin marketplace add anthropics/claude-plugins-community
/plugin install recoil@claude-community

Until then — or to install straight from this repo — add it as its own marketplace:

/plugin marketplace add EclipseElips/recoil
/plugin install recoil@recoil

Either way you get the skill plus a warn-only pre-edit guard hook. The recoil binary itself still needs to be on your PATH (see Install). Update later from the Marketplaces tab in /plugin.

Codex — install the plugin from this repo as a marketplace source, or just drop the skill into any repo:

cp -r skills/recoil .agents/skills/recoil

A short AGENTS.md stanza is included as a fallback for older Codex builds.

Any agent — the skill is just instructions wrapped around the CLI. Point your agent at recoil recall, recoil guard, and recoil encode (see Commands).

Use

Record a lesson with the situation it happened in:

recoil encode --trigger test-fail \
  --gist "Don't name a Unity folder Build/, .gitignore untracks it" \
  --cue  "unity build folder gitignore"

Later, recall by what you're doing now. Matching is plain keyword overlap, so an unrelated task gets nothing back:

$ echo "editing .gitignore and a new Build dir" | recoil recall
>> Don't name a Unity folder Build/, .gitignore untracks it
   [test-fail w=2 hits=0] matched: build gitignore

A lesson gets a little louder each time it's recalled, so the ones that keep mattering stay near the top.

Auto-capture

Wrap a command. If it fails, recoil records it:

recoil watch -- go test ./...

Warn before repeating it

recoil guard checks what's about to change against the things that went wrong before — errors, reverts, corrections, not plain notes — and warns if a change is walking back into one: