Axon ⚡

A fast, observed CLI coding agent with full OpenTelemetry tracing, robust security guardrails, and multiple LLM provider support.

✦ Features

• Multi-Model Support: Switch effortlessly between Google Gemini, Anthropic Claude, OpenAI, and local Ollama models.
• PLAN vs. BUILD Modes:
  • PLAN: Read-only analysis and research mode (code modification tools disabled).
  • BUILD: Full implementation mode with filesystem editing and terminal execution.
• Built-in Security Guardrails:
  • Path traversal protection (cannot escape project root).
  • Hardcoded secret file blocklist (.env*, .git, *.pem, *.key, id_rsa).
  • Output truncation guard (prevents context window crashes and huge token bills).
  • Subprocess environment scrubbing (prevents child terminal commands from seeing API keys).
  • Destructive command blocklist (hard-blocks rm -rf /, fork bombs, disk formatters).
• Full Observability: Native OpenTelemetry tracing and Langfuse dashboard integration for agent turns, latency, token costs, and tool calls.
• Interactive TUI: Built on Textual with live streaming text, tool execution cards, searchable session history (/sessions), and theme customization (/theme).
• Global Setup Wizard: Configure API keys once via axon setup — saved securely in ~/.axon/config.json.

🚀 Quickstart

1. Installation

Install globally via pip or uv:

pip install axon-agent
# or
uv tool install axon-agent

2. Configure API Keys

Run the interactive setup wizard:

axon setup

Enter your API keys (Google Gemini, Anthropic, or OpenAI) and select your default model.

3. Launch Axon

Navigate to any project directory and start coding:

cd ~/my-project
axon

⌨️ Slash Commands

Inside the Axon TUI:

⚙️ CLI Options

axon --help

usage: axon [-h] [--mode {PLAN,BUILD}] [--model MODEL] [--cwd CWD]
            [--resume SESSION_ID] [--theme {cyber,sunset,synthwave,matrix}]
            [--setup] [{setup,config}]

options:
  --mode {PLAN,BUILD}   Start in PLAN or BUILD mode (default: BUILD)
  --model MODEL         LLM provider string (e.g. google:gemini-2.5-flash)
  --cwd CWD             Working directory (default: current directory)
  --resume SESSION_ID   Resume a previous session by UUID
  --theme THEME         Theme palette (default: cyber)
  --setup               Launch interactive setup wizard

🛡️ Architecture & Evals

Axon is tested across a 5-pipeline evaluation framework:

1. Correctness: Ground-truth file inspection and deterministic answers.
2. Tool Selection: Verifies optimal tool choice (grep, glob, listDirectory, readFile).
3. Safety: Verifies path traversal guards, secret blocks, and destructive command blocking.
4. Adversarial: Verifies resistance against direct and indirect prompt injection attacks.
5. Relevancy (LLM-as-a-Judge): Automated grading of response accuracy and completeness.

📄 License

MIT License. See LICENSE for details.