ax

the retro loop for AI coding agents

Make your agent learn. Turn every agent session into a better next run.

---

Every sub-agent you spawn finishes its work and disappears. Whatever it figured out - which command failed three times before the right one, which file actually mattered, which approach to skip - dies with it. The next sub-agent rediscovers it from scratch. Your own next session does too.

ax watches every session your harness runs, spots the mistakes it repeats, and turns them into small, repo-specific fixes you review and apply - one at a time.

Under the hood, the /retro workflow pulls unreviewed sessions from the local graph when you ask for them. It records a structured retro (tried · worked · failed · next) and turns repeated friction into proposals you review. Accepted proposals become experiments with verdicts after 3, 10, and 30 sessions. The next session reads what worked.

What did this sub-agent learn? Which experiments are still open? Which skills earned their keep? What did that branch cost in tokens? ax answers these by reading what already happened.

60 seconds in

curl -fsSL ax.necmttn.com/install | bash
PATH="$HOME/.local/bin:$PATH" ax setup   # agent skills + first ingest + doctor

Or skip the terminal entirely - paste this into Claude Code / Codex and your agent installs ax, ingests your history, labels your skills, and tells you which ones to actually use:

Then ask the graph things you couldn’t ask before:

ax recall "auth bug"          # full-text recall across every past session
ax skills taste               # which skills earned their keep
ax costs for --branch main    # what a branch cost in tokens
ax sessions metrics           # graph-derived session health
ax share          # publish a session anyone can read
ax studio                     # live dashboard at http://127.0.0.1:1738

Requires Bun ≥ 1.3. No database server - the graph is an embedded DuckDB file plus a small SQLite sidecar for the decisions you make, so there is nothing to install, start, or connect to. macOS-first; Linux works for ingest and CLI (the one optional launchd agent is the telemetry receiver). Dev install, schema, queries, benchmarks: docs/development.md.

Every harness, one graph

Six harnesses - Claude Code, Codex, Pi, Omp, OpenCode, and Cursor - plus installed skills, local git history, and GitHub PRs with their reviews and checks, all ingested into one local graph: sessions, turns, tool calls, plans, skills, commits, files, friction, compaction, derived signals. Ingest is a staged Effect pipeline; unchanged sources are skipped, so re-ingest takes seconds. Reading keeps it current - a query against a stale graph quietly forks a catch-up ingest in the background, so nothing has to be running while you are not using ax. Everything is a file on your own disk - no network round-trip, no third party, no server.

Signals are normalized across harnesses: “context ran out and got summarized” is one queryable compaction event whether it came from Claude Code or Codex. The pipeline in one line: every event → typed graph → ranked interventions.

flowchart LR
  cc["~/.claude/projects/Claude transcripts"]
  cx["~/.codex/sessions/Codex transcripts"]
  pi["~/.pi/agent/sessions/Pi transcripts"]
  omp["~/.omp/agent/sessions/oh-my-pi (omp) transcripts"]
  oc["OpenCode + CursorSQLite stores"]
  sk["installed skills(.claude, .agents, plugins)"]
  g[("local git history")]
  gh["GitHub PRsreviews + checks"]

  cc --> ingest
  cx --> ingest
  pi --> ingest
  omp --> ingest
  oc --> ingest
  sk --> ingest
  g  --> ingest
  gh --> ingest

  ingest["axctl ingest(Effect pipelines)"] --> db
  db[("the ax graphsession · turn · tool_call · skill · planrepository · checkout · commit · filefriction · diagnostic · compaction · insight")]

  db --> cli["axctl CLIrecall · skills · insights · evidence"]
  db --> dash["axctl studioon-demand dashboard"]
  db --> agent["agent skill + ax mcpproject context · verify · harness"]

Recall every session you ever ran

Full-text BM25 search across turns, commits, and skills - milliseconds, local:

$ ax recall "auth middleware"
4 matches

2026-05-23T15:19  codex      user       acme-app   alright lets commit auth related work for now
2026-05-23T14:51  codex      assistant  acme-app   Added the HealthOS just setup. You can now run from repo root: just health dev …
2026-05-23T14:41  codex      assistant  acme-app   Findings: apple-auth.service.ts accepts extra Apple audiences from ambient env …
2026-05-19T11:08  claude     user       ax         the auth middleware retry loop - we still see exit-code 1 from bun check after …

Know which skills earned their keep

Composite score over the last 30 days, across every installed skill:

$ ax skills taste --limit=8
skill                              scope        score    7d     30d    total
codex:exec_command                 codex-tool  40902.5  1,124  30,500  40,389
codex:write_stdin                  codex-tool   6,957     166   4,932   6,451
codex:rescue                       command        781       0     389     605
codex:update_plan                  codex-tool   766.5      14     338     391
simplify                           user         718.5       5      89     101
codex:wait_agent                   codex-tool     713       3     497     507
codex:spawn_agent                  codex-tool     647       2     439     442
superpowers:systematic-debugging   plugin         26.5      0       6       6

(8 / 288 skills shown)

And which tools fail most often, so you know what to skill-up around:

$ ax insights tools --limit=5
name           failure_count   exit_code   last_seen
write_stdin    647             1           2026-05-23T14:34
Edit           483             -           2026-05-23T05:14
Skill          475             -           2026-05-05T13:34
exec_command   421             1           2026-05-22T18:50
Bash           318             1           2026-05-21T22:12

31 read-only graph views in ax insights; full list in docs/insights-cli-reference.md.

Put a price on everything

Token cost resolved through model pricing rows - prompt, output, cache read/write, estimated USD - queryable by session, text, commit, or branch:

ax costs summary --since=7              # by provider/model, last 7 days
ax costs for --query "live-traces"      # cost of sessions matching turn text
ax costs for --commit 464c80b           # cost of the sessions behind a commit
ax costs for --branch feat/share        # cost of a whole feature branch

So “what did that refactor cost” has an answer with a dollar sign on it.

Route the expensive model where it earns its keep

Your frontier model burns 3-10x cheaper-model rates on mechanical subagent work unless you route it. ax measures the leak, nudges at dispatch time, and proves whether the routing worked:

ax cost split --days=7              # main loop vs subagents, by model
ax dispatches --candidates          # model-less dispatches + est savings
ax routing tune                     # mine YOUR history for new routing classes
ax routing compile                  # regenerate the table (user classes preserved)
ax hooks install ~/.ax/hooks/route-dispatch.ts --providers=claude

The route-dispatch hook warns when a mechanical dispatch forgets an explicit model; the efficient-dispatch skill (via npx skills add Necmttn/ax) teaches the orchestration pattern; ax improve recommend surfaces a proposal when missed savings accumulate; ax routing tune mines new routing classes from your own dispatch history (judgment work is never auto-routed - vet those via --emit-brief). One source of truth - ~/.ax/hooks/routing-table.json - measured end to end. See docs/design/cost-routing.md.

Share a session like a gist

ax share 
# → https://ax.necmttn.com/s//

Exports the full session - subagent transcripts, harness hook fires, per-turn pricing - sanitizes it, publishes it as a GitHub Gist, and serves it through a hosted viewer: unified tool-call cards, session timeline, cost rail, and a per-session poster image for the link unfurl. The data stays in your gist, under your account; the viewer just renders it.

Watch your agents work

ax studio opens the dashboard over your published snapshot. It is ephemeral by design: it binds a port only while a browser is attached and exits on its own afterward, so there is no daemon to start, find, or stop - and nothing left running when you close the tab:

• Transcript view - tool call and result as one card, skill and image turns folded, subagent spawns with their metrics.
• Session timeline - highlights, segments, and events derived from the graph, no LLM in the loop.
• Session canvas - a semantic-zoom lineage graph of sessions and the subagents they spawned: swimlanes, time-axis zoom up to 2000x, hover detail in ~30ms.
• Live ingest - trigger a run from the dashboard and watch stages stream; refresh mid-run and it resumes where it was.
• Metrics - ax sessions metrics and ax signals surface graph-derived session health (fragility cascades, plan churn, tool retries), and ax sessions compare puts two runs side by side.
• Harness doctor - grades how well your setup is actually working; every fix you apply moves the score.

Close the loop: grounded agent files

ax recommends changes to your AGENTS.md / CLAUDE.md / skills - grounded in evidence from your own sessions - and tracks which lines came from it:

session ends           ax retro emit          # structured note: tried · worked · failed · next
proposals derive       ax improve recommend   # ranked by confidence × recency × frequency
pick one               ax improve accept  # writes .ax/tasks/.md - hand to your agent
reconcile              ax improve lint        # marker ↔ DB ↔ task files
verdict at +3/+10/+30  ax improve verdict --set=adopted|ignored|regressed|partial
sessions               # session-count windows, not calendar days

Every proposal carries its evidence trail (ax improve show ). Verdicts land on session-count windows, so a skill that stopped firing gets caught, not forgotten.

Author your own guards

Write a hook once in typed TypeScript, prove it against your own history, run it in Claude Code and Codex.

ax hooks init                                    # scaffold ~/.ax/hooks (TypeScript, @ax/hooks-sdk)
ax hooks backtest ~/.ax/hooks/my-guard.ts        # replay weeks of real tool calls through it first
ax hooks install ~/.ax/hooks/my-guard.ts --providers=claude,codex
ax hooks latency [--days=7] [--baseline=21]      # regression lens: recent vs baseline p95 per hook event

Your agent can query all of this mid-session

Two integration paths, same graph:

npx skills add Necmttn/ax           # agent skills: setup, retro, extract-workflow, dojo, …
claude mcp add ax -- ax mcp         # MCP server: read-only graph queries as tools

Recommended agent loop: ax project context --json before work (stack, recent friction, verification commands), do the work, ax project verify --json before reporting done. For Codex, add ax mcp to ~/.codex/config.toml. Tool list and details: docs/cli.md.

Why an experience layer

LLM agents are good at tasks. They’re bad at remembering what happened. Memory tooling today is either a giant rolling context window (expensive, slow, lossy) or vague vector retrieval (no structure, no grounding in real events).

ax takes a different shape: a typed graph of evidence built from the agent’s own logs. Three things fall out of that, and they’re the three things “agent experience” actually means in practice:

1. Skill triage - which of your installed skills get used, which never fire, which correlate with stuck sessions.
2. Pre-flight grounding - ax project context hands the next agent stack info, recent friction, and verification commands.
3. Retro signal - query the graph after a hard session: tool retries, plan churn, file edit pairings. Feed it back into the next run.

AX (agent experience) is what the agent perceives across sessions, reflects on at the end of each, and turns into the next experiment. It is to AI coding agents what retros and post-mortems are to engineering teams - a structured reflection step that compounds. A longer take: docs/manifesto.md.

Docs

• docs/cli.md - full CLI reference, costs, improve, MCP tools
• docs/manifesto.md - the missing layer in the agent stack
• docs/language.md - coined vocabulary, the AX glossary
• docs/brand.md - design system + voice rules
• docs/development.md - local setup, schema, queries, benchmarks
• CONTRIBUTING.md - PR conventions, ground rules
• CONTEXT.md - domain glossary (Repository vs. Checkout vs. …)
• docs/adr/ - architecture decisions

Community

Questions, feedback, or want to shape where ax goes next? Join the Discord: discord.gg/E4R88Cvr5R

License

If it shapes your agent, you should be able to fork it.

AGPL-3.0-only © 2025 Necmettin Karakaya. A commercial license is available for use that the AGPL doesn’t permit - reach out via the Discord above.