agent-improvement-loop CLI
A CLI that reads local Claude Code, Codex and Hermes sessions, finds repeated failures and stages fixes for manual review
- 73 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The script reads session transcripts in full, which can contain paths, commands and code fragments from work projects
- Fleet mode exchanges redacted bundles between machines, so review them before sharing
Install
- Works in
Manual install
pipx install git+https://github.com/cathrynlavery/agent-improvement-loopRequires Python 3.10 or newer. uv tool install also works in place of pipx.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The script reads session transcripts in full, which can contain paths, commands and code fragments from work projects
- Fleet mode exchanges redacted bundles between machines, so review them before sharing
This is third-party code. Review the repository files before installing.
What it does
A daily self-improvement loop for agents. The script collects local Claude Code transcripts from ~/.claude/projects, Codex sessions from ~/.codex/sessions and Hermes profile logs, normalizes them into a small event model with tool calls, shell commands, skill use, failures and user corrections, and redacts sensitive data. Improvement signals come from actual tool use and words in chat do not count: the phrase "don't use that CLI" is not counted as the CLI failing. The result lands in ~/.agent-improvement/ as a proposal queue and a readable review packet. The script does not edit skills, memory, runbooks, configs or source: scanning and staging are automated, applying stays manual. A proposal that keeps recurring rises to the top of the packet. Closed targets live in a resolutions.json registry with fixed, wontfix or ignored, and after fixed new evidence goes to a regressions section. In fleet mode each machine writes a redacted bundle and one leader merges them into a shared report. The second half of the system, the learnings store and the learn-loop skill, works through accumulated findings in batches of up to three.
Who it is for. People who maintain their own skills, hooks and commands for Claude Code and Codex and want to find in session logs what gets in the way most often.
Good fit when
- The same command or tool fails across sessions and you need to find where
- A week of sessions has piled up while skills and rules have not been updated for a long time
- Several machines run agents and you want one summary report without moving raw logs
- Before editing CLAUDE.md or a skill you want evidence from real transcripts
Not a fit when
- You need skills and configs edited automatically: the loop applies nothing itself
- You need content-level analysis of model answers: the tool looks for tool failures and corrections
- Sessions of agents other than Claude Code, Codex and Hermes: other formats are not read
Example request
Scan my sessions from the last day and show which tool failures repeat most often.Limitations
Python 3.10 or newer is required, with no external dependencies. The script reads your transcripts in full and redacts sensitive data automatically, so look through the review packet before sending it anywhere. The --full mode turns off fleet bundle output so unredacted data does not enter the shared handoff.
Claude Code, Codex and Hermes profiles are supported. Fleet mode needs one leader machine: the author advises against several leaders on one shared queue. Keep the learnings store out of Dropbox and other cloud folders with several writers. The last commit is from October 30, 2026.
How to disable. Delete the cloned folder or run pipx uninstall agent-improvement-loop. Remove the ~/.agent-improvement/ directory with the queue and registry by hand. If you installed a schedule, remove the cron or launchd job created by install_learnings_cron.py and install_learnings_launchd.py.
FAQ
Does agent-improvement-loop change my skills and configs?
No. The loop only reads transcripts and writes proposals to ~/.agent-improvement/. You decide what to apply.
How do I install agent-improvement-loop?
Run pipx install git+https://github.com/cathrynlavery/agent-improvement-loop, then use the agent-improvement-loop command. uv tool install works too, or you can run it from a clone with ./bin/daily-improvement-loop.
How do I preview the result without writing the queue?
Add the --dry-run flag: proposals print as JSON and the queue and state stay untouched.
How do I close a reviewed proposal?
Use --resolve with a target like tool:edge-cli and --decision fixed, wontfix or ignored. After fixed, new evidence for the target goes to the regressions section.
Can it read Claude Code sessions only?
Yes. The --source claude flag keeps only Claude Code sessions and --source codex keeps only Codex.
Discussion
No questions or reviews yet.
Related
CLI toolsOne config for Claude Code and Codex in every repo: shared rules, skill packs, second-model review and a destructive-command guard
A CLI with a TUI that finds Claude Code, Codex and Gemini CLI sessions and continues them in another agent as native ones
A self-improvement plugin for Claude Code, Codex and OpenCode: turns corrections into rules the agent follows in later sessions
ClawMetry reads the session files agents already write and shows the timeline, tool calls, tokens and cost in one dashboard.
The ee CLI gives agents durable local memory: rules, decisions and anti-patterns with scores and provenance
The session-recall command reads an agent’s local sessions and returns past conversations in compact form, with no MCP or hooks.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| agent-improvement-loop (this card) | no | 73 | |
| Coding Agent Session Search (cass) | no | 1,205 | searches the history of sessions across agents, while this one finds repeated failures and prepares a queue of fixes |
| Claude Session Dashboard | no | 77 | shows Claude Code sessions in a dashboard, while this one extracts proposals for improving skills and tools |
README in short
A small local utility on the Python standard library that turns agent work history into a queue of reviewable improvements. It comes with a learnings store that merges several machines and a learn-loop skill for working through findings.