The retro loop · for AI coding agents

Make your agent
learn.

Reflects. Experiments. Improves. ax runs a structured retro at the end of every Claude Code and Codex session - main or sub-agent - and indexes the result as a typed experiment in a local graph.

Reflect every session Track every experiment 100% local

Install in 30 seconds

$ curl -fsSL https://raw.githubusercontent.com/Necmttn/ax/main/install.sh | bash

macOS-first · Linux works for CLI · requires Bun ≥ 1.3 and SurrealDB ≥ 3.0

Try the studio → Read the manifesto View on GitHub

It reflects.

So your agent learns.

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. ax is the loop that closes before the session ends.

Structured retro at session end
A Stop hook asks the agent for what was tried, what worked, what failed, what to try next. JSON by default; free-form opt-in.
Every retro is a proposal
Friction patterns become skill / hook / guidance candidates you accept, reject, or skip - one explicit yes per row.
Every proposal becomes an experiment
Accepted artifacts get a t+7 / t+30 / t+90 verdict - adopted, ignored, regressed, partial, or no longer needed. The loop closes locally.

Hackable. Out of the box.

One graph. Two readers.
Zero network round-trips.

Everything runs on 127.0.0.1. The agent and the CLI both read the same graph; the dashboard is a thin React view over the same queries. Local DB underneath, MIT all the way.

~/.claude/projects/
~/.codex/sessions/
~/.claude/skills/
local git history

axctl ingest the ax graph session · turn · tool_call · skill · file · friction · insight

axctl CLI
ax studio
agent skills

see as a static diagram

flowchart LR cc["~/.claude/projects/
Claude transcripts"] cx["~/.codex/sessions/
Codex transcripts"] sk["~/.claude/skills/
installed skills"] g[("local git history")] cc --> ingest cx --> ingest sk --> ingest g --> ingest ingest["axctl ingest
(Effect pipelines)"] --> db db[("the ax graph
session · turn · tool_call · skill
repository · checkout · commit · file
friction · diagnostic · insight")] db --> cli["axctl CLI
recall · skills · insights · evidence"] db --> dash["axctl serve
live dashboard"] db --> agent["agent skill
project context · verify · harness"]

The loop, end to end.

Retro. Propose. Verdict.

1. Agent emits a retro at session end

The Stop hook asks for structured JSON before the session is allowed to close.

$ ax retro --session=$AX_SESSION_ID{
  "tried":  ["bun check before every commit", "rg over node_modules"],
  "worked": ["scoped rg with -t ts", "stash + worktree per agent"],
  "failed": ["bun check pre-commit (slow)", "edit-then-tsc loop"],
  "next":   ["replace bun check with oxlint pre-commit",
             "add stop-hook: refuse commits without tsc clean"]
}

retro saved · session 019e533c · 4 fields · 0 free-form

2. Friction patterns become proposals

Skills, hooks, and guidance candidates ranked by how often they would have fired.

$ ax improve list --status=open  freq  conf    form        title
  1072  high    skill       Session closure quality guardrail
    26  high    skill       Post-feature verification checklist
    26  high    skill       Ingest pipeline regression checklist
    12  high    skill       Schema change guardrail
     7  low     guidance    Block main-branch edits in multi-agent projects
     7  high    skill       Graph query dogfood checklist

triage with: ax improve accept <sig> · reject <sig> · show <sig>

3. Accepted proposals become experiments

Every artifact gets a t+7 / t+30 / t+90 verdict locked back into the graph.

$ ax improve verdict skill__292666ce747117eeexperiment   skill / Schema change guardrail
created      2026-05-19  (t+7 checkpoint due 2026-05-26)
opportunities  12 in window
addressed       8 (66.7%)
suggested verdict   adopted

lock with: ax improve verdict skill__292666ce747117ee --set adopted

Install

30 seconds. Then you're indexing.

Requires Bun ≥ 1.3 and SurrealDB ≥ 3.0. macOS-first; Linux works for ingest + CLI.

$ curl -fsSL https://raw.githubusercontent.com/Necmttn/ax/main/install.sh | bash
$ PATH="$HOME/.local/bin:$PATH" axctl ingest --since=7
$ axctl serve   # live dashboard at http://127.0.0.1:8520

For dev setup, schema, and benchmarks, see docs/development.md.

Why retros compound

Every sub-agent dies with what it learned.

Memory is what you remember. Retro is what you reflect on, structure, and turn into the next bet. The agent stack has compute, tools, and logs. It does not have a reflection loop. ax is that loop. - from the manifesto

Verbal self-reflection at the engineering layer. Reflexion for software. Open reference, MIT, runs on your laptop.

Read why ax exists → Read the full manifesto →

Make your agentlearn.