{"id":50417732,"url":"https://github.com/necmttn/ax","last_synced_at":"2026-06-03T04:01:01.398Z","repository":{"id":360203597,"uuid":"1232710515","full_name":"Necmttn/ax","owner":"Necmttn","description":"the agent experience layer · observability + memory for AI coding agents (Claude Code + Codex) · local-first, typed, yours","archived":false,"fork":false,"pushed_at":"2026-05-31T06:09:27.000Z","size":12584,"stargazers_count":6,"open_issues_count":10,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T07:21:21.853Z","etag":null,"topics":["agent-memory","agent-observability","ai-agents","bun","claude-code","codex","developer-tools","effect-ts","evidence-graph","llm-observability","surrealdb","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Necmttn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-08T07:34:30.000Z","updated_at":"2026-05-31T06:09:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Necmttn/ax","commit_stats":null,"previous_names":["necmttn/ax"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/Necmttn/ax","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Necmttn%2Fax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Necmttn%2Fax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Necmttn%2Fax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Necmttn%2Fax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Necmttn","download_url":"https://codeload.github.com/Necmttn/ax/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Necmttn%2Fax/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33847265,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","agent-observability","ai-agents","bun","claude-code","codex","developer-tools","effect-ts","evidence-graph","llm-observability","surrealdb","typescript"],"created_at":"2026-05-31T07:01:28.700Z","updated_at":"2026-06-03T04:01:01.370Z","avatar_url":"https://github.com/Necmttn.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ax\n\n###### the retro loop for AI coding agents\n\n**Make your agent learn.**\nReflects. Experiments. Improves. Across every session.\n\n---\n\nEvery sub-agent you spawn finishes its work and disappears. Whatever it\nfigured out - which command failed three times before the right one, which\nfile actually mattered, which approach to skip - dies with it. The next\nsub-agent rediscovers it from scratch. Your own next session does too.\n\n`ax` is the loop that closes before the session ends. A Stop hook fires\nat session-end (main or sub-agent), asks the agent for a structured retro\n(*tried · worked · failed · next*), and indexes the result as a typed\nexperiment in a local graph. Friction patterns become proposals you\ntriage. Accepted proposals become experiments with t+7 / t+30 / t+90\nverdicts. The next session reads what worked.\n\n\u003e *What did this sub-agent learn? Which experiments are still open?\n\u003e Which skills earned their keep? Which hooks blocked anything useful?*\n\u003e `ax` answers these by reading what already happened.\n\n![ax · the retro loop for AI coding agents](docs/images/og.png)\n\n## What is AX\n\n`AX` (agent experience) is what the agent perceives across sessions,\nreflects on at the end of each, and turns into the next experiment. It\nis to AI coding agents what retros and post-mortems are to engineering\nteams - a structured reflection step that compounds.\n\n`ax` (lowercase) is the reference implementation. Local typed graph,\nStop-hook-driven retros, agent-readable queries, React dashboard, MIT.\nA longer take: [`docs/manifesto.md`](docs/manifesto.md). Vocabulary:\n[`docs/language.md`](docs/language.md).\n\n## How it fits together\n\n```mermaid\nflowchart LR\n  cc[\"~/.claude/projects/\u003cbr/\u003eClaude transcripts\"]\n  cx[\"~/.codex/sessions/\u003cbr/\u003eCodex transcripts\"]\n  sk[\"~/.claude/skills/\u003cbr/\u003einstalled skills\"]\n  g[(\"local git history\")]\n\n  cc --\u003e ingest\n  cx --\u003e ingest\n  sk --\u003e ingest\n  g  --\u003e ingest\n\n  ingest[\"axctl ingest\u003cbr/\u003e(Effect pipelines)\"] --\u003e db\n  db[(\"the ax graph\u003cbr/\u003esession · turn · tool_call · skill\u003cbr/\u003erepository · checkout · commit · file\u003cbr/\u003efriction · diagnostic · insight\")]\n\n  db --\u003e cli[\"axctl CLI\u003cbr/\u003erecall · skills · insights · evidence\"]\n  db --\u003e dash[\"axctl serve\u003cbr/\u003elive dashboard\"]\n  db --\u003e agent[\"agent skill\u003cbr/\u003eproject context · verify · harness\"]\n```\n\nEverything runs on `127.0.0.1`. The agent and the CLI both read the same\ngraph; the dashboard is a thin React view over the same queries.\n\n## A taste of the output\n\nWhich skills earned their keep, by composite score over the last 30 days:\n\n```text\n$ axctl skills taste --limit=8\nskill                              scope        score    7d     30d    total\ncodex:exec_command                 codex-tool  40902.5  1,124  30,500  40,389\ncodex:write_stdin                  codex-tool   6,957     166   4,932   6,451\ncodex:rescue                       command        781       0     389     605\ncodex:update_plan                  codex-tool   766.5      14     338     391\nsimplify                           user         718.5       5      89     101\ncodex:wait_agent                   codex-tool     713       3     497     507\ncodex:spawn_agent                  codex-tool     647       2     439     442\nsuperpowers:systematic-debugging   plugin        26.5       0       6       6\n\n(8 / 288 skills shown)\n```\n\nRecall past work across every session, in milliseconds:\n\n```text\n$ axctl recall \"auth middleware\"\n4 matches\n\n2026-05-23T15:19  codex      user       acme-app   alright lets commit auth related work for now\n2026-05-23T14:51  codex      assistant  acme-app   Added the HealthOS just setup. You can now run from repo root: just health dev …\n2026-05-23T14:41  codex      assistant  acme-app   Findings: apple-auth.service.ts accepts extra Apple audiences from ambient env …\n2026-05-19T11:08  claude     user       ax         the auth middleware retry loop - we still see exit-code 1 from bun check after …\n```\n\nWhich tools fail most often, so you know what to skill-up around:\n\n```text\n$ axctl insights tools --limit=5\nname           failure_count   exit_code   last_seen\nwrite_stdin    647             1           2026-05-23T14:34\nEdit           483             -           2026-05-23T05:14\nSkill          475             -           2026-05-05T13:34\nexec_command   421             1           2026-05-22T18:50\nBash           318             1           2026-05-21T22:12\n```\n\n## Why an experience layer\n\nLLM agents are good at tasks. They're bad at remembering what happened.\nMemory tooling today is either a giant rolling context window (expensive,\nslow, lossy) or vague vector retrieval (no structure, no grounding in real\nevents).\n\n`ax` takes a different shape: a **typed graph of evidence** built from the\nagent's own logs. Sessions, turns, tool calls, plans, skills, commits, files,\nfriction, and derived signals - all queryable, all local, no\nnetwork round-trip, no third party.\n\nThree things fall out of that, and they're the three things \"agent\nexperience\" actually means in practice:\n\n1. **Skill triage** - which of your installed skills get used, which never\n   fire, which correlate with stuck sessions.\n2. **Pre-flight grounding** - `axctl project context` hands the next agent\n   stack info, recent friction, and verification commands.\n3. **Retro signal** - query the graph after a hard session: tool retries,\n   plan churn, file edit pairings. Feed it back into the next run.\n\n## Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Necmttn/ax/main/install.sh | bash\nPATH=\"$HOME/.local/bin:$PATH\" axctl ingest --since=7\n```\n\nSkills are distributed via the [skills.sh](https://skills.sh) marketplace.\nAfter the CLI is installed, drop the agent skills into your Claude Code\nsession with:\n\n```bash\nnpx skills add Necmttn/ax           # installs ax:setup + ax:retro skills\n```\n\nRequires Bun ≥ 1.3 and SurrealDB ≥ 3.0. macOS-first; Linux works for ingest\nand CLI (no launchd reactivity).\n\nFor dev install, schema, queries, and benchmarks, see\n[`docs/development.md`](docs/development.md).\n\n## Quickstart\n\n```bash\naxctl ingest --since=7     # backfill last 7 days of transcripts + skills + git\naxctl serve                # live dashboard at http://127.0.0.1:8520\naxctl skills taste         # CLI view: which skills earned their keep\naxctl recall \"auth bug\"    # full-text recall across past sessions\n```\n\n## Agent integration\n\n`ax` ships two installable skills so a Claude Code / Codex agent can query\nits own evidence graph mid-session:\n\n```bash\nnpx skills add git@github.com:Necmttn/ax.git --skill axctl    -g -a claude-code -a codex -y\nnpx skills add git@github.com:Necmttn/ax.git --skill retro -g -a claude-code -a codex -y\n```\n\nRecommended agent loop:\n\n1. `axctl project context --json` before work - stack, recent friction,\n   verification commands.\n2. Do the work.\n3. `axctl project verify --json` before reporting done - runs the checks\n   the project actually expects.\n\n## CLI shape\n\n```text\naxctl ingest [--since=N] [--reset]         # backfill the graph\naxctl ingest here [--since=Nd]             # scope ingest to the git repo at $PWD\naxctl derive-signals                        # re-run derive pass standalone\naxctl derive-intents                        # re-run user-intent derive standalone\naxctl serve                                 # live web dashboard (API for ax studio)\naxctl report                                # one-shot static HTML\naxctl tui                                   # interactive terminal dashboard\n\naxctl recall \u003cquery\u003e [--sources=turn,commit,skill] [--scope=here|all]\n                                            # cross-session BM25 full-text search\naxctl context [file] [\u003cquery\u003e]              # file/agent-context grounding\naxctl skills \u003csearch|taste|unused|pairs|recovery|classify|tag|lint|weighted|by-role|roles\u003e\naxctl insights \u003cview\u003e                       # 19 read-only graph views\naxctl classifiers \u003clist|eval|explain\u003e       # classifier coverage and turn explanations\naxctl costs \u003csummary\u003e                       # token/cost usage by provider/model quality\naxctl sessions \u003chere|around \u003cdate\u003e|near \u003csha\u003e|show \u003cid\u003e\u003e\n                                            # windowed session queries\naxctl costs summary [--since=N]             # estimated token cost by provider/model\naxctl costs for --session \u003cid\u003e              # cost for one session\naxctl costs for --query \u003ctext\u003e [--limit=N]  # cost for sessions matching turn text\naxctl costs for --terms \u003ca,b,c\u003e [--since=N] # cost for sessions matching any term\naxctl costs for --commit \u003csha\u003e              # cost for sessions that produced a commit\naxctl costs for --branch \u003cname\u003e             # cost for sessions linked to a branch\naxctl pricing [--query \u003cmodel\u003e]             # inspect imported model pricing rows\naxctl share \u003csession-id\u003e                    # publish a sanitized session share via GitHub Gist\naxctl roles                                 # list role labels with skill counts\naxctl project \u003ccontext|verify|harness\u003e\naxctl evidence \u003cguidance-next|session-summary|weekly\u003e\naxctl improve \u003clist|show|accept|reject|verdict|checkpoint|reset\u003e\naxctl retro \u003cemit|list|reflect|plan\u003e        # the retro-loop CLI\naxctl hook \u003cfire\u003e                           # hook helper invoked from settings.json\naxctl hooks \u003csummary|invocations|backtest\u003e\n\naxctl daemon \u003cstatus|start|stop|restart\u003e\naxctl doctor                                # local-install health check\naxctl install                               # wire launchd + hooks + DB\naxctl uninstall                             # remove launchd + bin symlink\naxctl update [--check]                      # pull latest release\naxctl version [--check|--banner]\n```\n\nFull reference: [`docs/insights-cli-reference.md`](docs/insights-cli-reference.md).\n\n### Token cost queries\n\n`axctl costs` reads the local `session_token_usage` graph. Provider adapters\nwrite actual token counters when they exist; otherwise ax falls back to a rough\ntranscript-byte estimate. `session-health` resolves model names through\n`agent_model` pricing rows and stores prompt, output, cache-read, cache-write,\nand total estimated USD.\n\nExamples:\n\n```bash\naxctl costs summary --since=2\naxctl costs for --query \"live-traces\" --limit=20\naxctl costs for --terms \"live trace,livetrace,live-traces\" --since=2 --limit=50\naxctl costs for --terms \"live trace,livetrace,live-traces\" --since=2 --project /Users/me/project\naxctl costs for --query \"checkout bug\" --since=7 --here\naxctl costs for --commit 464c80b\naxctl costs for --branch main --limit=20\naxctl sessions show \u003csession-id\u003e\naxctl pricing --query gpt-5.5\n```\n\n`--query` and `--terms` can be constrained with `--since=N`, `--project \u003cpath\u003e`,\nor `--here`. `--here`, `--commit`, and `--branch` use repository graph evidence\nfrom the current git checkout. Direct `--pr \u003cnumber\u003e` is not wired yet; use the\nPR branch or a commit SHA for now.\n\n### Grounded agent files\n\nax can recommend changes to your `AGENTS.md` / `CLAUDE.md` (and skill files)\nand track which lines came from it.\n\nEnd-to-end flow:\n\n```text\nsession ends           axctl retro emit        # structured note: tried · worked · failed · next\nproposals derive       axctl improve recommend # ranked by confidence × recency × frequency\npick one               axctl improve accept \u003cid\u003e\n                       # default: writes .ax/tasks/\u003cid\u003e.md - hand to your agent\n                       # --auto-scaffold:    skips the brief, writes SKILL.md directly\n                       # --with-agent:       scaffolds + dispatches `claude -p` subagent\n                       #                     to enrich the stub with real triggers + steps\nreconcile              axctl improve lint     # marker ↔ DB ↔ task files\nverdict at +3/+10/+30  axctl improve verdict --set=adopted|ignored|regressed|partial\nsessions               # session-count windows, not calendar days (#83)\n```\n\nCommands:\n\n- `axctl improve recommend [--limit=N] [--form=skill] [--apply]` - print N\n  ranked proposals as paste-ready blocks (already wrapped in `\u003c!--ax:id--\u003e`\n  provenance markers). `--apply` enters an interactive accept loop.\n- `axctl improve accept \u003cid\u003e [--with-agent] [--auto-scaffold] [--force]` -\n  Default emits `.ax/tasks/\u003cid\u003e.md`, a brief your agent (Claude Code,\n  Codex) executes. `--auto-scaffold` writes `SKILL.md` directly.\n  `--with-agent` adds a `claude -p` subagent pass that reads the stub +\n  sibling skills and rewrites it with concrete triggers, steps, and\n  anti-patterns. Optionally writes a sibling `PLAN.md`.\n- `axctl improve lint [--root=\u003cdir\u003e] [--stale-days=N]` - scan grounded agent\n  files, reconcile markers with the DB, remove consumed task files, warn on\n  orphans or tasks older than `--stale-days` (default 7).\n- `axctl improve show \u003cid\u003e` - full evidence trail for one proposal.\n- `axctl improve list [--status=open|accepted|rejected|all]` - browse the\n  proposal queue.\n- `axctl improve verdict \u003cid\u003e [--set=...]` - inspect or lock the +30-session verdict.\n- `axctl improve reject \u003cid\u003e [--reason=...]` - dedupes future re-proposals\n  of the same trigger.\n\n## Docs\n\n- [`docs/manifesto.md`](docs/manifesto.md) - the missing layer in the agent stack\n- [`docs/origin.html`](docs/origin.html) - origin notes on the loop ax closes\n- [`docs/language.md`](docs/language.md) - coined vocabulary, the AX glossary\n- [`docs/brand.md`](docs/brand.md) - design system + voice rules\n- [`docs/development.md`](docs/development.md) - local setup, schema, queries, benchmarks\n- [`CONTRIBUTING.md`](CONTRIBUTING.md) - PR conventions, ground rules\n- [`CONTEXT.md`](CONTEXT.md) - domain glossary (Repository vs. Checkout vs. …)\n- [`docs/adr/`](docs/adr/) - architecture decisions\n\n## License\n\n[MIT](LICENSE) © 2025 Necmettin Karakaya\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnecmttn%2Fax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnecmttn%2Fax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnecmttn%2Fax/lists"}