ax CLI
A CLI that gathers Claude Code and Codex session history into a local graph, searches it and turns repeated mistakes into fixes
- 123 ★ on the repository
- Last commit
- AGPL-3.0
Extended access
Why this level
- Reads transcripts, git history and tool calls, writes a local graph and on request edits instruction files.
- The install script is downloaded from the network.
Install
- Works in
Manual install
curl -fsSL ax.necmttn.com/install | bashThe first command of 60 seconds in; then ax setup for skills, the first ingest and a doctor check.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Reads transcripts, git history and tool calls, writes a local graph and on request edits instruction files.
- The install script is downloaded from the network.
This is third-party code. Review the repository files before installing.
What it does
ax is a retrospective loop for AI agents. The utility reads transcripts, git history and tool calls into a local DuckDB graph and uploads nothing. The graph supports search (`ax recall "auth bug"`), seeing which skills earned their keep (`ax skills taste`), counting token cost per branch or commit (`ax costs`) and opening the `ax studio` dashboard at 127.0.0.1:1738. The main function: after a session ax writes a structured note of tried, worked, failed and next, derives recommendations for `AGENTS.md`, `CLAUDE.md` and skills from repeated friction and tracks accepted proposals as experiments with verdicts after 3, 10 and 30 sessions. An agent that gets the notes reads what worked last time.
Who it is for. People who work a lot with Claude Code and Codex and want repeated agent mistakes to become reviewable edits to instruction files.
Good fit when
- An agent makes the same mistake in a project again and again and you need to find the pattern.
- You must recall which past session discussed an authorization bug.
- You want to know how many tokens a branch or commit cost.
- You need to decide which installed skills are really used and which can go.
Not a fit when
- Bun 1.3 or newer is missing: the utility is built on it.
- You need a Windows platform: the focus is macOS while Linux works for ingest and the CLI.
- The AGPL license conflicts with your policy: the author sells a commercial license for such cases.
Example request
Run ax recall for retry loop and show the three latest sessions where the agent got stuck on the same error.Limitations
Bun 1.3 or newer is required and the graph lives in an embedded DuckDB file with a small SQLite sidecar. macOS is the main platform; on Linux ingest and the CLI work, while the optional launchd telemetry agent is macOS only. Publishing a profile, a widget and contributing patterns (`ax profile publish`, `ax profile widget`, `ax contribute pattern`) reach outside and are opt-in only. Accepted proposals are written to `.ax/tasks` files that you hand to the agent yourself. The license is AGPL-3.0 with a commercial license available separately. The latest commit is from October 2026.
How to disable. Delete the installed `ax` binary from `~/.local/bin`, the data directory with the graph and the skills added by `ax setup`. If you installed the launchd telemetry agent, unload it separately.
FAQ
What leaves my machine when ax runs?
Nothing by default: the graph is local with no account or cloud. Only the explicit `ax profile publish`, `ax profile widget` and `ax contribute pattern` commands reach outside.
How does the retro loop work?
After a session `ax retro emit` writes a note, `ax improve recommend` ranks proposals, `ax improve accept` creates a task file and `ax improve verdict` records a verdict after 3, 10 and 30 sessions.
How do I count cost?
With `ax costs summary --since=7` by provider and model for a week or `ax costs for --commit <hash>` for the sessions behind a commit.
How do I install ax?
With `curl -fsSL ax.necmttn.com/install | bash`, then `ax setup`. You can also paste the setup prompt into an agent and it installs ax itself.
What license does ax use?
AGPL-3.0-only. A commercial license is available for uses the AGPL does not permit.
Discussion
No questions or reviews yet.
Related
CLI toolsclaude-history searches and opens past Claude Code, Codex and Pi conversations in the terminal and gives Claude a history skill
CLI and /trajex skill: Claude Code, Codex and Pi sessions in one SQLite index that an agent queries with JS
An MCP server and CLI that find in Claude Code and Codex sessions why a file became what it is: who asked the agent what, when and what changed
Skill that reads your prompt history, finds the asks you repeat and turns each into a short command such as /sent
Local search across all coding agent sessions with a return to the original CLI and token usage stats.
The aise utility searches local session history of Claude Code, Codex, Cursor and six more agents and serves it over MCP.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| ax (this card) | no | 123 | |
| claude-reflect | no | 1,942 | extracts lessons from sessions into Claude memory; ax builds a graph across harnesses and tracks experiments with verdicts |
| Claude-Mem | no | 116,457 | a memory plugin with automatic session compression; ax searches history and proposes instruction edits |
README in short
The README shows sections on gathering history from different harnesses, session search, skill scoring, cost tracking, routing the expensive model and sharing a session. Locality and consent for every outbound action are stressed.