Axon

A glass-box coding agent for your terminal. See every step: every LLM call, tool, token, cache hit and cent.

112 slash commands · 21 built-in tools · 15 provider presets

Axon is an agentic coding assistant that reads, searches, edits and runs code in your repository, much like Claude Code. The difference is that nothing is hidden. Each turn is drawn as a numbered timeline: the model that was called and why, the tokens it consumed, how much of the prompt came from cache, which tools ran with which arguments, what each one fed back to the model, who approved it, which hooks fired, and what it all cost, to four decimal places.

> fix the failing test in tests/test_cart.py

┌ Turn 1 · "fix the failing test in tests/test_cart.py"
│ ◆ Step 1  LLM call · claude-sonnet-4-5 · reads 1 message (~11.8k tokens)
│ ▎ I'll look at the test and the code it exercises.
│   ↪ replied in 2.1s · 11.8k in (92% cached) · 164 out · $0.0061 · ctx 6%/200k
│   → runs 2 tools in parallel, read-only
│   ● Read  tests/test_cart.py
│       reads a file
│     ⎿  48 lines · 375 B · 0.01s
│         1 │ line 1
│         2 │ line 2
│         3 │ line 3
│         4 │ line 4
│         5 │ line 5
│        … +43 more lines · /output 1 to view all
│   ● Grep  "def total" in src/
│       searches inside files
│     ⎿  1 match in 1 file · 0.04s
│        src/shop/cart.py · 1 match
│           31:     def total(self) -> Decimal:
│ 
│ ◆ Step 2  LLM call · claude-sonnet-4-5 · reads 4 messages (~12.5k tokens)
│   ↪ replied in 1.4s · 12.5k in (94% cached) · 96 out · $0.0052 · ctx 6%/200k
│   ● Bash  pytest -q tests/test_cart.py
│       runs a shell command
│       ✓ allowed by rule: Bash(pytest *)
│     ⎿  ██████████▒▒ 4 passed · 1 failed · 3 lines of output · 1.80s
│        F....
│        FAILED tests/test_cart.py::test_discount_rounding - assert Decimal('9.99') ==
│       Decimal('10.00')
│        1 failed, 4 passed in 0.21s
│ 
│ ◆ Step 3  LLM call · claude-sonnet-4-5 · reads 6 messages (~12.7k tokens)
│ ▎ The discount is truncated instead of rounded. Fixing `total()`.
│   ↪ replied in 2.6s · 12.7k in (98% cached) · 212 out · $0.0068 · ctx 6%/200k
│   ● Edit  src/shop/cart.py
│       edits a file
│       › hook PostToolUse ran (1 command)
│     ⎿  ✎ Edited src/shop/cart.py · +1 −1 · 0.03s
│            -         return (subtotal * rate).quantize(CENTS, ROUND_DOWN)
│            +         return (subtotal * rate).quantize(CENTS, ROUND_HALF_UP)
│ 
│ ◆ Step 4  LLM call · claude-sonnet-4-5 · reads 8 messages (~12.9k tokens)
│   ↪ replied in 1.2s · 12.9k in (97% cached) · 88 out · $0.0049 · ctx 7%/200k
│   ● Bash  pytest -q tests/test_cart.py
│       runs a shell command
│       ✓ allowed by rule: Bash(pytest *)
│     ⎿  ████████████ 5 passed · 2 lines of output · 1.70s
│        .....
│        5 passed in 0.19s
│ 
│ ◆ Step 5  LLM call · claude-sonnet-4-5 · reads 10 messages (~13.0k tokens)
│ ▎ Fixed. `Cart.total()` now rounds the discount with `ROUND_HALF_UP`, so 9.995
│ ▎ becomes 10.00. All 5 cart tests pass.
│   ↪ replied in 1.1s · 13.0k in (99% cached) · 58 out · $0.0045 · ctx 7%/200k
└ ✓ Done in 10.6s · 5 LLM calls · 5 tool calls · 62.9k in · 618 out · $0.0275

Contents

Start here: What you need · Install · Set up a model · Your first task · Cheat sheet · Reading a turn · Update or uninstall · Your data · FAQ · Troubleshooting

Reference: Highlights · Providers · Glass-box tracing · Commands · Tools · Extending Axon · Memory · Settings · Storage · Analytics · Solver · SDK and HTTP API · Testing · Project structure · Docs

What you need

Check Python (open a terminal: Terminal on macOS, PowerShell on Windows):

python3 --version      # macOS / Linux
py --version           # Windows (or: python --version)

You need 3.10 or higher. If it is missing or older:

Install

Copy one line into your terminal and press Enter. It installs Axon in its own environment (nothing else on your system changes) and adds an axon command. Run the same line again any time to update.

macOS · Linux · WSL

curl -fsSL https://raw.githubusercontent.com/gpr-27/axon/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/gpr-27/axon/main/install.ps1 | iex

Windows (Command Prompt)

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/gpr-27/axon/main/install.ps1 | iex"

When it finishes, close the terminal and open a new one (so it finds the new axon command), then check it works:

axon --version

The installer uses uv or pipx if you already have them, and otherwise a private virtual environment in ~/.axon/venv (%USERPROFILE%\.axon\venv on Windows).

git clone https://github.com/gpr-27/axon.git
cd axon
./install.sh        # macOS / Linux / WSL / Git Bash   -> ~/.local/bin/axon
.\install.ps1       # PowerShell                       -> %USERPROFILE%\.axon\bin\axon.cmd
install.bat         # cmd, or double-click

# pin a branch, tag or commit
curl -fsSL https://raw.githubusercontent.com/gpr-27/axon/main/install.sh | bash -s -- --ref v0.27.2
# force a method: auto | uv | pipx | venv
curl -fsSL https://raw.githubusercontent.com/gpr-27/axon/main/install.sh | bash -s -- --method venv
# show what it would do without changing anything
curl -fsSL https://raw.githubusercontent.com/gpr-27/axon/main/install.sh | bash -s -- --dry-run

$env:AXON_INSTALL_REF = "v0.27.2"; irm https://raw.githubusercontent.com/gpr-27/axon/main/install.ps1 | iex

Set up a model

Run the guided setup once:

axon setup

It asks three things: which provider, your API key (typed hidden, checked live before it is saved) and which model. Keys are stored in ~/.axon/.env on your machine only.

Where to get a key:

No key, no cost, works offline: install Ollama, run ollama pull qwen2.5-coder:7b, then pick Ollama (Local) in axon setup.

You can change any of this later from inside Axon: /model (switch model), /provider (switch provider), /keys (add, replace, test or remove keys), /endpoint (use a proxy or custom URL) and /settings (every option in one menu). axon doctor checks that everything is set up correctly.

Your first task

Go to a project folder and start Axon there. It works on the files in that folder:

cd path/to/your/project
axon

Then just type what you want, in plain words, and press Enter:

explain how this project is structured
find why the tests in tests/test_cart.py fail and fix it
add a --verbose flag to the CLI and update the README

Axon plans the work, reads and searches your files, runs commands and edits code, and shows every step as it goes (what each mark means). Things to know:

• Approvals. Out of the box Axon runs in bypass mode and does not ask before running tools. Press Shift+Tab to switch to default (asks before edits and commands), acceptEdits (edits freely, asks before commands) or plan (read-only: it only plans). Dangerous commands such as rm -rf / are blocked in every mode.
• Talk while it works. Type a message while Axon is busy: it is queued and shown to the model between steps. /btw <question> asks a quick side question without interrupting. Esc stops the current turn.
• Undo. Axon snapshots files before changing them: /rewind restores code, the conversation, or both.
• Pick up later. axon -c continues your last session in that folder, axon -r lets you choose one.
• Shell commands. Start a line with ! to run it yourself (!git status); Axon reads the output and explains it.

Cheat sheet

axon "explain the auth flow"                         # start with a prompt
axon -p "list TODOs in src/" --output-format json    # one answer, no interactive session (scripts, CI)
axon --mode plan                                     # read-only planning
axon --model deepseek-v4-flash --context-limit 256k  # choose model and context size for this run
axon -w feature-x                                    # work in a separate git worktree

Reading a turn

Every turn is drawn as a timeline. Each kind of row has its own mark, so you can always tell what the model thought, what it did and what it said:

 › fix the failing test

┌ Turn 3 · "fix the failing test"                       deepseek-v4-flash · bypass mode
│ ◆ Step 1  LLM call · deepseek-v4-flash · reads 5 messages (~9.3k tokens)
│   ✻ Thinking
│   ┊ The test fails on rounding. Let me run it first.
│   ✻ thought for 1.2s
│   ↪ replied in 3.8s · 9.1k in · 287 out · $0.0398 · context █░░░░░░░ 1% of 1M
│   ● Bash  pytest -q tests/test_cart.py
│       runs a shell command · why: Let me run it first.
│     ⎿  exit code 1 · 3 lines of output · 1.80s
│        FAILED tests/test_cart.py::test_discount_rounding
│        1 failed, 4 passed in 0.21s
│
│ ◆ Step 2  LLM call · deepseek-v4-flash · reads 8 messages (~10.4k tokens)
│   → includes 1 tool result from step 1 (128 B · ~32 tokens)
│ ▎ The discount is truncated instead of rounded. Fixing it.
│   ↪ replied in 2.5s · 10.4k in (89% cached) · 128 out · $0.0093
└ ✓ Done in 6.4s · 2 LLM calls · 1 tool call · 19.5k in · 415 out · $0.0491

While Axon works, the bottom of the screen shows a spinner with a live timer for the current tool or step, the tokens streamed so far, and a tip underneath. Ctrl+F (or /transcript) opens the whole session full-screen, where every block can be expanded or collapsed with a click.

Update or uninstall

Update: run the same install line again (it picks up the newest version).

Uninstall:

# macOS / Linux / WSL
curl -fsSL https://raw.githubusercontent.com/gpr-27/axon/main/install.sh | bash -s -- --uninstall

# Windows
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/gpr-27/axon/main/install.ps1))) -Uninstall

Uninstalling keeps your settings, keys and sessions in ~/.axon. Delete that folder too if you want everything gone.

Your data

Everything stays on your computer, under ~/.axon (%USERPROFILE%\.axon on Windows), organised per project. Nothing is deleted automatically.

/project shows the folder for the project you are in. /delete moves a session to a trash folder (/restore brings it back). axon purge is the only thing that really deletes data, and it asks first. ~/.axon/README.md explains the layout in detail.

FAQ

Does it cost money? Axon itself is free. The model provider charges for the tokens each request uses; Axon shows the cost of every step, every turn (/cost) and over time (/stats). Local models through Ollama or LM Studio cost nothing. Use /budget 2 to stop a session at $2.

Is my code sent anywhere? Only to the model provider you chose, and only what the model needs for your request (the files it reads, command output). Nothing is sent to Axon's authors. With a local model nothing leaves your machine.

Which model should I use? deepseek-v4-flash (the default on AgentRouter) is fast and cheap for most work; switch to a larger model (/model) for hard problems. /model lists what your provider offers.

Does it work on Windows? Yes: PowerShell 7, Windows PowerShell 5.1, Command Prompt, Windows Terminal, Git Bash and WSL. See docs/windows.md.

Can I use it in scripts or CI? Yes: axon -p "…" --output-format json prints one answer (or stream-json for every event) and exits. There is also a Python SDK and a local HTTP API (below).

I use Claude Code. Does my setup carry over? Axon reads CLAUDE.md, .claude/commands, .claude/agents, .claude/skills, .mcp.json and the same hook format. Claude Code's own model choice is not used; Axon's model comes from /model.

Highlights

Providers

Pick a model with /model, or switch provider with /provider and --provider <id>. The endpoint and key follow the model you select. Keys are read from the environment, then from ~/.axon/.env.

Any other OpenAI-compatible endpoint works with --base-url and AXON_API_KEY. Use /pricing to see per-model token prices and /keys to check which keys are configured.

Glass-box tracing

Every turn is recorded as a structured trace and rendered live at one of four levels. Set the level with --trace, /trace, Ctrl+O, or trace_level in settings.

Related commands:

• Ctrl+F / /transcript opens the session full-screen; click or press Enter on a block to expand or collapse it.
• /output <n> prints tool call n in full (/output list shows what is kept); in terminals with link support, the /output n hint itself is clickable and opens the full output.
• /inspect [n] replays the timeline of a stored turn. The default is the last turn.
• /explain [n] summarises a turn in plain language, without an LLM call.
• /payload shows the exact prompt sent to the model, with token counts per section.
• /context [--why] draws a coloured grid of context usage by category.
• /cost shows spend by source and model, the cache hit rate and savings, and the last cache-miss cause.
• /focus hides everything except prompts, one-line tool summaries and answers.
• --debug [api,hooks,...] writes a debug log to ~/.axon/debug/<session>.log.

Commands

112 built-in commands. Run /help for the list or /help <command> for details; the full reference is in docs/commands.md.

Subcommands run outside the REPL: axon setup, axon doctor, axon mcp …, axon stats, axon report, axon serve, axon map, axon new and axon purge. For every flag, see docs/commands.md.

Tools

MCP tools appear as mcp__<server>__<tool>. Use --tools "Read,Grep" to restrict the set, and --allowedTools / --disallowedTools (or permissions rules) to control approval.

Extending Axon

Every extension point is a plain file. The full formats are in docs/extending.md, and ready-to-copy files are in examples/.

The matching .claude/ locations are read too.

MCP in practice:

axon mcp add github --env 'GITHUB_TOKEN=${GITHUB_TOKEN}' -- npx -y @modelcontextprotocol/server-github
axon mcp add --transport http docs https://example.com/mcp --header 'Authorization: Bearer ${DOCS_TOKEN}'
axon mcp add --scope project db -- python tools/db_mcp.py   # saved to <project>/.mcp.json
axon mcp list

${VAR} and ${VAR:-default} are expanded when the server starts, so the file keeps the reference and not the secret. Inside a session, /mcp manages servers, tools, resources, prompts and logs. MCP prompts become slash commands.

Hooks run at SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStop, PreCompact, Notification and SessionEnd. Each hook receives the event as JSON on stdin. Exit code 2 blocks the action, and JSON on stdout can allow, ask, deny or add context. /hooks lists the hooks that are loaded.

Subagents. The model delegates work through the Task tool. The built-in agents are general-purpose, explore, plan, code-reviewer, test-runner and analytics. Use /agents to create your own, /subagents to open a subagent's transcript, and --agent <name> to run the whole session as one.

Output styles. Built-in styles are default, explanatory, learning and concise, plus any custom Markdown style you add. Switch with /output-style.

Memory

Instruction files load broadest first and are concatenated, so a narrower file never overrides a broader one:

1. Managed policy: /Library/Application Support/Axon/AXON.md (macOS), /etc/axon/AXON.md (Linux), C:\Program Files\Axon\AXON.md (Windows)
2. User: ~/.axon/AXON.md and ~/.axon/rules/**/*.md
3. Project: in each directory from the filesystem root down to the workspace, AXON.md, .axon/AXON.md, CLAUDE.md, .claude/CLAUDE.md, .axon/rules/**/*.md, then AXON.local.md. AGENTS.md is used when no AXON or CLAUDE file exists.
4. On demand: AXON.md files in subdirectories, and rules with paths: frontmatter, load the first time a tool touches a matching file.
5. Auto memory: ~/.axon/projects/<project>/memory/MEMORY.md
6. Saved items: # note, /learn and /memory add

@path imports are followed up to 4 levels deep. /init writes an AXON.md from an analysis of the repository, and /memory lists everything that was loaded.

Settings

Settings are applied from lowest to highest priority:

1. Built-in defaults
2. ~/.axon/config.toml, then <project>/.axon/config.toml
3. ~/.axon/settings.json, then <project>/.claude/settings.json, <project>/.axon/settings.json, <project>/.claude/settings.local.json and <project>/.axon/settings.local.json
4. --settings <file|json>
5. .env files (<project>/.env, ~/.axon/.env)
6. AXON_* environment variables
7. Command-line flags

Permission rules and hooks are merged across all of these layers rather than replaced. Project files may not set api_key or base_url.

Every key, with its environment variable and settings.json spelling, is listed in docs/configuration.md.

Storage layout

All state lives under ~/.axon, or under AXON_HOME if you set it. Axon writes inside your project only when you ask it to, for example with /init or a project-scoped memory. Everything a project produces is kept in that project's own folder; ~/.axon/README.md (generated) explains every file, and /project (alias /where) shows which project you opened and where its data is.

~/.axon/
  README.md                                           generated guide to this folder
  settings.json  config.toml  .env  mcp.json  AXON.md    user-level config & memory
  agents/  commands/  skills/  plugins/  rules/  output-styles/
  memory/                                             user-wide memory (all projects)
  history.jsonl                                       prompt history (all projects)
  usage.jsonl                                         every LLM call: tokens + cost
  logs/  cache/                                       logs and scratch data
  backup/<timestamp>/                                 originals kept by migrations
  projects/index.json                                 every project: path, last opened, size
  projects/<project-key>/
    project.json  README.md                           name, workspace path, git, counts
    activity.jsonl                                    append-only journal of everything
    sessions/<session-id>.jsonl                       full transcript (+ _sub_<n> subagents)
    outputs/<session-id>/                             full tool/shell outputs cut for the model
    screen/<stamp>-<session-id>.log                   plain-text copy of the terminal
    traces/<session-id>.jsonl                         per-turn glass-box traces
    checkpoints/<session-id>/                         file snapshots for /rewind (+ rewound/)
    memory/MEMORY.md                                  auto memory for this project
    todos/<session-id>.json                           todo list state
    trash/                                            deleted sessions (/restore)
    images/  pastes/  exports/  plans/  debug/        attachments, exports, debug logs

Nothing is deleted automatically: cleanup_period_days defaults to 0 (keep forever). Set it to N > 0 to prune sessions, traces and todos older than N days at startup (the journal, memory, screen logs and trash are never pruned). /delete moves a session to the project's trash/ and /restore <id> brings it back. Run axon purge [project|caches|all] to delete stored data on purpose.

The activity journal records every prompt, slash command, ! shell command, # note, /btw question and answer, queued message, permission decision, settings change, turn (stop reason and cost), tool call, error, retry, rewind, resume and delete, with secrets redacted. Read it with /activity [N] [--kind k] [--session id] [--since 2h] [--all-projects] [--export file.md|.jsonl] or axon activity with the same flags; axon projects lists every project, and /history all shows a transcript including messages a rewind removed. Transcripts that older versions kept in ~/.axon/sessions/ are moved into their project once (copied, verified, the originals kept in ~/.axon/backup/).

Analytics

Every LLM call is appended to ~/.axon/usage.jsonl, recording model, source, tokens, cache use, latency and cost.

• /stats [today|7d|30d|all] and axon stats show cost, tokens, cache, models, sources, tools and the most expensive turns.
• /report and axon report [--days N] [--out PATH] [--all-projects] [--open] write a self-contained HTML dashboard (inline SVG, no scripts).
• /insights asks the analytics subagent to explain your spending and suggest savings.
• /budget [amount|off] sets a spending limit for the session.
• The UsageStats tool lets the model answer questions about usage from the same data.

Solver: verify, fix, plan

To replace the detected checks, set verify_commands in your settings.

SDK and HTTP API

from axon.features.sdk import AxonOptions, query, run

for event in query("explain src/app.py", AxonOptions(mode="plan")):
    if event["type"] == "text_delta":
        print(event["text"], end="")

result = run("fix the failing test", AxonOptions(mode="acceptEdits", max_turns=20))
print(result.text, result.cost_usd, result.session_id)

Each event is a JSON-serialisable dict, such as llm_call_start, tool_use, permission, tool_result, llm_call_end (with usage and cost), cache_status and finally result. Approvals are non-interactive: anything that would need a human is denied unless you pass can_use_tool.

axon serve exposes the same events over HTTP:

axon serve --port 8765            # binds 127.0.0.1 and prints a bearer token
curl -N -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{"prompt":"summarise README.md","stream":true}' http://127.0.0.1:8765/v1/query

The endpoints are GET /health, GET /v1/sessions, GET /v1/usage and POST /v1/query (SSE or JSON). Binding to a non-loopback address requires --allow-remote.

Troubleshooting

Testing

python -m pip install -e ".[dev]"
python -m pytest -q -m "not e2e"          # unit and integration suite
python -m pytest -q -m e2e tests/e2e      # end-to-end: the real CLI against a fake LLM server

The end-to-end suite (about 1,000 tests) starts the real axon process against a local fake OpenAI/Anthropic-compatible server and a fake MCP server, so it needs no network access and no API key. For details, see docs/testing.md.

Project structure

axon/
├── install.sh · install.ps1 · install.bat   installers: one-line remote install or from a clone
├── .github/workflows/                       CI (lint, tests on Linux/macOS/Windows, installers) and PyPI release
├── pyproject.toml                           package metadata and the only dependency list
├── check_models.py                          live latency/health check across models
├── scripts/
│   ├── setup_env.py                         installer core used by install.*
│   ├── axon_run.py                          run from a checkout without installing
│   └── gen_docs.py                          regenerates the reference parts of the docs
├── src/axon/
│   ├── cli.py                               argument parsing, print mode, REPL, subcommands
│   ├── config.py · storage.py · platform.py settings, on-disk layout, OS/terminal layer
│   ├── agent/                               loop, prompt, context, memory, subagents, trace, worktrees
│   ├── providers/                           Anthropic + OpenAI-compatible clients, catalog, pricing, failover
│   ├── tools/                               built-in tools (files, search, shell, web, tasks, …)
│   ├── permissions/                         rules engine, path jail
│   ├── commands/                            slash-command registry and the built-in commands
│   ├── hooks/ · mcp/ · skills/              extension systems
│   ├── session/                             transcripts, checkpoints, cost ledger
│   ├── features/                            analytics, solver, planner, SDK, server, scaffolding, onboarding
│   └── ui/                                  renderer, markdown, input editor, pickers, theme
├── examples/                                ready-to-copy config, hooks, agents, commands, skills
├── docs/                                    architecture, configuration, commands, extending, Windows, testing
└── tests/                                   unit/integration suites and tests/e2e

Documentation

Contributing

1. Fork the repository and create a branch.
2. Run python -m pip install -e ".[dev]".
3. Make your change, adding tests next to the existing ones in tests/.
4. Run ruff check src scripts tests and the test suite. Both must pass.
5. If you changed commands, tools, providers or settings, run python scripts/gen_docs.py to refresh the generated reference sections. --check exits non-zero when they are stale.
6. Open a pull request that describes the change and how you verified it.

License

No license file has been published yet, so all rights are reserved by the author until one is added. Please open an issue if you would like to use Axon under specific terms.