Your agents forget. retroagent remembers.

It keeps every Claude Code and Codex session from every machine in a private Git repo that you own. One command searches them all.

Quick start · Commands · How it works · Pages & retros · Config

---

• Sync: the sync writes each session as a short Markdown file in your data repo. It redacts secrets, and gitleaks scans every commit that the sync makes.
• Search: kb find "how did I fix the flaky test" searches a local SQLite index at a very low token cost. Skills tell Claude Code and Codex to search there first. Optional semantic search uses a local model to also find paraphrases and other languages. It works in cloud sessions too. retroagent also collects Claude Code cloud sessions.
• Pages and retros (optional): the pages routine runs in the cloud. It keeps one project page for each project and one retro for each week. Each bullet links to its source session.

retroagent uses two repos. This public repo holds the code and no data. Your private data repo holds the data, and you own it.

readme-720p.mp4

_{A 4.5-minute video explains retroagent: the sync, the two repos, cloud sessions, search with kb by words or by meaning, project pages, hints when a command fails, and weekly retros. The retros propose changes to the environment of your agent.}

Quick start

You need these tools:

• git
• Python 3.9+

The setup downloads gitleaks if your machine does not have it. The GitHub CLI gh is optional: without it, you create the private data repo on github.com.

Let your agent do it

Paste this prompt into Claude Code or Codex:

Set up retroagent on this machine for me: https://github.com/gabe4coding/retroagent
1. If ~/.retroagent does not exist, clone the repo there.
2. Read ~/.retroagent/skills/setup/SKILL.md and follow it step by step. Use ~/.retroagent/bin/kb while `kb` is
   not on my PATH yet.
3. Ask me one question at a time, and show me each command before it creates a repo, pushes or changes anything
   outside this machine. My data repo must be private.
4. install.sh also installs the Claude Code and Codex plugins: tell me if it prints a WARNING, and at the end
   remind me to start a new session (and, in Codex, to trust the retroagent hook with /hooks).
5. Never ask me for a token or a secret: I type those in my own terminal.

The agent asks you before each step. It does these steps:

1. It creates or picks your private data repo.
2. It installs the plugins and the kb CLI.
3. It runs the first sync. Search works after approximately one minute, and the rest of the sync continues in the background.
4. When the first sync is complete, automatic syncs start.

After the setup, start a new session. The plugin loads only in a new session.

Or with the Claude Code plugin

/plugin marketplace add gabe4coding/retroagent
/plugin install retroagent@retroagent
/retroagent:setup

To install by hand, read Installation.

Use it

kb find flaky test timeout     # ranked pages, memories and sessions
kb summary 9a1be7d2            # decisions, outcome, files and PRs of one session
kb show 9a1be7d2 --grep error  # only the part you need
kb stats                       # how you use your agents

You can also ask your agent: "how did I fix this last time?" or "retro of last week".

Documentation

Page
Installation	Requirements, plugin and manual install, host names, updates
Commands	Every kb command
How the sync works	What the sync writes and when, and the one-writer-per-host rule
Pages routine	The optional cloud routine for project pages and weekly retros
Configuration	Every key of config.json
Troubleshooting	kb repair and common errors
Development	Layout, tests, releases

License

MIT. See LICENSE.