ax

ax is an observability and memory layer for AI coding agents, positioned as an "agent experience layer," primarily serving coding agents such as Claude Code and Codex. Its core idea is to let agents remember across sessions what has happened, turning each session into a basis for improving the next run.

[Problems solved] Each subagent disappears once it finishes its work, and the failed commands it discovered, key files, and practices to avoid are lost with it, leaving the next subagent or next session to figure things out from scratch. By observing each session and discovering recurring errors and friction, ax turns them into small correction suggestions for a specific code repository, for users to review and apply one by one.

[Main capabilities]

1. Unified graph: ingests six harnesses—Claude Code, Codex, Pi, Omp, OpenCode, and Cursor—as well as installed skills, local git history, GitHub PRs and their review and check statuses, into a single local graph, including sessions, turns, tool calls, plans, skills, commits, files, friction, compactions, derived signals, and more. Ingestion uses a staged pipeline, and unchanged sources are skipped; on read, catch-up ingestion is silently performed in the background for stale graphs. All data consists of files on the user's disk, with no network round trips, no third parties, and no server. Signals are normalized across harnesses; for example, "context exhausted and summarized" corresponds to the same queryable compaction event whether it comes from Claude Code or Codex.
2. Session recall: BM25-based full-text search enables millisecond-level local search of historical sessions across turns, commits, and skills.
3. Skill evaluation: gives a composite score for all installed skills over the past 30 days, identifying which skills are actually effective, which have never triggered, and which are associated with stuck sessions; it also counts which tools fail most frequently. ax insights provides 31 read-only graph views.
4. Cost accounting: resolves token costs through model pricing rows, covering prompts, outputs, cache reads and writes, and estimated dollar amounts, and can be queried by session, text, commit, or branch to answer "how much did this refactor cost."
5. Cost routing: measures waste when expensive models are used for mechanical subagent work, gives reminders at dispatch time (route-dispatch hook), and provides the efficient-dispatch skill (via npx skills add Necmttn/ax installation) teaches orchestration patterns; ax improve recommend gives proposals when missing savings accumulate; ax routing tune mines new routing categories from dispatch history (judgment-type work is not automatically routed and requires manual review via --emit-brief). The single source of truth for the routing table is ~/.ax/hooks/routing-table.json.
6. Session sharing: export the complete session (sub-agent records, harness hook triggers, per-turn pricing), desensitize it, and publish it as a GitHub Gist, presenting unified tool-call cards, a session timeline, and a cost track through a hosted viewer, as well as a session poster image for link previews. Data remains in the user's own Gist account.
7. Studio dashboard: ax studio opens a dashboard based on a published snapshot and is ephemeral by design—it occupies a port only while a browser is connected and then exits on its own; there is no daemon to start, find, or stop. It includes a transcript view (tool calls and results merged into one card, skill and image turns collapsed, sub-agent spawns and their metrics), a session timeline, a session canvas (a semantic zoom lineage graph of a session and its sub-agents, supporting lanes, up to 2000x timeline zoom, and about 30ms hover details), live ingestion (runs can be triggered from the dashboard and stages streamed, and a mid-run refresh can resume), metrics (ax sessions metrics and ax signals present graph-derived session health, such as fragile cascades, plan changes, and tool retries; ax sessions compare compares two runs side by side), and harness doctor (scores the actual effect of configuration, with the score increasing each time a fix is applied).
8. Landing into agent files: ax suggests modifications to AGENTS.md / CLAUDE.md / skills based on the user's own session evidence, and tracks which lines come from it; each proposal comes with an evidence chain (ax improve show <id>), and verdicts are based on session-count windows.
9. Custom guards: write a hook once in typed TypeScript, validate it on your own history, and run it in Claude Code and Codex.
10. In-session queries: the recommended agent loop is to run ax project context --json before work (to obtain the tech stack, recent friction, and verification commands),and run ax project verify --json after work; Codex users can add ax mcp in ~/.codex/config.toml.

[Usage and Dependencies] Requires Bun >= 1.3. No database server is needed: the graph is an embedded DuckDB file plus a small SQLite sidecar for recording decisions, so there is no need to install, start, or connect to anything. macOS-first; Linux can be used for ingestion and the CLI (the only optional launchd agent is the telemetry receiver). For development installation, schema, queries, and benchmarks, see docs/development.md. In addition, you can paste the installation prompt directly into Claude Code / Codex, and the agent will install ax itself, ingest history, annotate skills, and tell you which skills are worth using; you can also issue queries against the graph that could not previously be asked.

[Applicable Scenarios]

• Developers who need to track AI coding agent behavior, failure modes, and skill effectiveness across sessions.
• Teams or individuals who need token cost accounting and routing optimization for agent work.
• Engineering practices that want to turn historical session evidence into AGENTS.md/CLAUDE.md and skill improvements.
• Developers who need to share and review a difficult session.

[Limitations and License] The tool is local-first, with no network round trips; macOS-first, with Linux supporting ingestion and the CLI. Judgment-type work is not automatically routed. Data remains on the user's own disk and in their own Gist account. Licensed under AGPL-3.0-only, © 2025 Necmettin Karakaya; commercial licensing is available for uses not permitted by the AGPL. More details such as pricing, specific charges, effectiveness data, and platform support scope are not yet provided in the materials.