Axon (axon-terminal)

   ___   _  __ ___   _  __
  / _ | | |/ // _ \ / |/ /
 / __ |  / // // //    / 
/_/ |_| /_/  \___//_/|_/  
Terminal-Native Agentic Coding Assistant

⚡ Quick Start & Installation

Axon requires Python >= 3.10. Follow the 3-step setup below:

1️⃣ Try the Standard Install Command First

If you already have Python and pip installed, run the standard installation command directly:

# macOS / Linux / Configured Windows
pip install axon-terminal

# Windows Zero-Configuration Alternative (Works immediately via built-in py launcher):
py -m pip install axon-terminal

Once installed, launch Axon:

axon
# (Or on Windows if PATH is not configured: py -m axon)

2️⃣ If Python or Pip is Missing (1-Command Full Automated Setup)

If pip or python is missing entirely on your computer, use the 1-liner for your operating system:

• 🪟 Windows (PowerShell - 1-Click All-in-One): Run this single command in PowerShell. It automatically downloads Python, accepts agreements silently, bootstraps & upgrades Pip, refreshes the active session, and configures the system PATH:

  winget install --id Python.Python.3.12 --exact --source winget --accept-source-agreements --accept-package-agreements; $env:Path = [Environment]::GetEnvironmentVariable('Path','Machine') + ';' + [Environment]::GetEnvironmentVariable('Path','User'); python -m ensurepip --upgrade; python -m pip install --upgrade pip; $scripts = python -c "import sysconfig; print(sysconfig.get_path('scripts'))"; $userPath = [Environment]::GetEnvironmentVariable('Path','User'); if (($userPath -split ';') -notcontains $scripts) { [Environment]::SetEnvironmentVariable('Path', "$userPath;$scripts", 'User') }
  

• 🍎 macOS (Terminal - 1-Liner via Homebrew):

  brew install python && python3 -m pip install --upgrade pip
  

  (Or download the official installer directly from python.org/downloads).

• 🐧 Linux (Ubuntu / Debian - 1-Liner):

  sudo apt update && sudo apt install -y python3 python3-pip python3-venv && python3 -m pip install --upgrade pip
  

3️⃣ If pip Still Says "Not Recognized" on Windows (Quick PATH Fix)

If Python is already installed but typing pip or axon returns 'not recognized':

• Option A: 1-Line Automated PATH Fix (PowerShell):

  $pyScripts = (python -c "import sysconfig; print(sysconfig.get_path('scripts'))"); [Environment]::SetEnvironmentVariable('Path', [Environment]::GetEnvironmentVariable('Path', 'User') + ";$pyScripts", 'User'); Write-Host "✓ Added $pyScripts to PATH. Restart terminal to apply." -ForegroundColor Green
  

• Option B: Manual GUI Setup:

  1. Find your Scripts directory:

     py -m pip -V
     

  2. Press Win + R, type sysdm.cpl, and press Enter.
  3. Go to Advanced $\rightarrow$ Environment Variables... $\rightarrow$ Under User variables, select Path $\rightarrow$ Edit... $\rightarrow$ New.
  4. Paste the path to your ...\Scripts folder and click OK.
  5. Restart your terminal/IDE.

• Option C: 1-Click Repo Auto-Setup: Clone the repo and double-click install.bat (or run .\install.ps1).

🐧 Linux (Ubuntu / Debian / Fedora / Arch)

• Ubuntu / Debian:

  sudo apt update && sudo apt install -y python3 python3-pip python3-venv
  

• Fedora / RHEL:

  sudo dnf install -y python3 python3-pip python3-virtualenv
  

• Arch Linux:

  sudo pacman -S python python-pip python-virtualenv
  

• Universal (Without Root):

  curl -sSL https://bootstrap.pypa.io/get-pip.py | python3
  

💻 Axon Installation Methods

Method 1: Using pipx (Recommended for isolated CLI tools)

pipx installs Axon into its own isolated environment so it never conflicts with system packages:

# Install pipx (if not already installed)
# Windows: winget install pipx  OR  python -m pip install --user pipx
# macOS:   brew install pipx    OR  python3 -m pip install --user pipx
# Linux:   sudo apt install pipx

pipx install axon-terminal
axon

Method 2: Standard Pip Install

• Windows:

  pip install --upgrade axon-terminal
  axon
  

  (If pip is not in PATH, use: python -m pip install --upgrade axon-terminal and launch with python -m axon)

• macOS & Linux:

  pip3 install --user --upgrade axon-terminal
  axon
  

  (If axon is not in PATH, launch with: python3 -m axon)

Method 3: 1-Click Bootstrap from Source (Cloned Repository)

If you have cloned or downloaded the Axon repository, run the self-contained bootstrapper:

• Windows: Double-click install.bat or run:

  python setup_env.py
  

• macOS & Linux: Run:

  chmod +x install.sh && ./install.sh
  

  (Or directly: python3 setup_env.py)

🛠️ Troubleshooting Common Setup Errors

[!TIP] First-Time Setup: When you launch axon for the first time, it will automatically prompt you for your AXON_API_KEY, test it live against the API, and save it permanently to ~/.axon/.env (or %USERPROFILE%\.axon\.env on Windows). You only have to enter your key once!

🛠️ Troubleshooting Common Setup Errors

🔑 Environment & API Key Configuration

Axon requires only a single environment variable (AXON_API_KEY) to authenticate. All other settings (default model, base URL, effort tier, and token budgets) work automatically out of the box.

Option 1: Interactive First-Run (Easiest)

Simply run axon in your terminal. If no key is found, Axon will prompt you to enter it and will save it permanently in your user profile.

Option 2: Permanent Global Config

Save your key directly into the global Axon configuration directory:

• Windows (PowerShell):

  New-Item -ItemType Directory -Force -Path "$HOME\.axon"
  Set-Content -Path "$HOME\.axon\.env" -Value 'AXON_API_KEY="your_api_key_here"'
  

• Windows (Command Prompt):

  if not exist "%USERPROFILE%\.axon" mkdir "%USERPROFILE%\.axon"
  echo AXON_API_KEY="your_api_key_here" > "%USERPROFILE%\.axon\.env"
  

• macOS & Linux:

  mkdir -p ~/.axon
  echo 'AXON_API_KEY="your_api_key_here"' > ~/.axon/.env
  

Option 3: Local Project .env

Copy .env.example to .env in the root of any repository:

cp .env.example .env    # On Windows CMD: copy .env.example .env

🚀 How to Use Axon

Once installed, navigate to any codebase or repository on your computer and launch Axon:

# 1. Start interactive coding session
axon

# 2. Run a one-shot instruction or query
axon -p "Review this repository and write unit tests for edge cases"

# 3. Resume your latest conversation
axon --continue

# 4. Launch with a specific model override
axon --model claude-opus-5

🧠 What is Axon? (Complete Architectural Overview)

Axon is engineered from first principles in pure Python to provide a full-featured, developer-first coding agent inside your terminal without third-party framework bloat:

┌─────────────────────────────────────────────────────────────────────────┐
│                              USER PROMPT                                │
└────────────────────────────────────┬────────────────────────────────────┘
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                        AXON REACT ENGINE LOOP                           │
│                                                                         │
│   ┌───────────────────┐    Prompt + History    ┌────────────────────┐   │
│   │                   │ ─────────────────────> │                    │   │
│   │   LLM REASONING   │                        │   6-LAW SECURITY   │   │
│   │  & THINKING TRACE │ <───────────────────── │  PERMISSION MATRIX │   │
│   │                   │      Tool Decisions    │                    │   │
│   └─────────┬─────────┘                        └─────────┬──────────┘   │
│             │                                            │              │
│             │ Executes Tool Call                         │              │
│             ▼                                            ▼              │
│   ┌─────────────────────────────────────────────────────────────────┐   │
│   │               24 NATIVE RUNTIME AGENT TOOLS                     │   │
│   │   File I/O  ·  Ripgrep/AST  ·  Shell  ·  Subagents  ·  Research  │   │
│   └─────────────────────────────────────────────────────────────────┘   │
└────────────────────────────────────┬────────────────────────────────────┘
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│             GLOBAL ~/.axon/ LEDGER & AUTO CHECKPOINT ROLLBACK           │
└─────────────────────────────────────────────────────────────────────────┘

Key Architectural Pillars

1. ⚡ Native ReAct Loop with Real-Time Thinking Traces: Built with zero dependencies on LangChain or CrewAI. Streams reasoning tokens live, self-corrects on tool execution errors, and manages structured multi-turn conversation context.

2. 🔒 6-Law Security & Permission Matrix: Enforces strict boundaries. Tools are partitioned into read-only, workspace mutation, external shell, and privileged execution tiers. Instantly toggle between default (ask), acceptEdits, plan (read-only), and bypass modes with Tab.

3. ⏪ Atomic File Checkpoints & Undo (/rewind): Every file edit takes an in-memory SHA256 snapshot before touching disk. If a patch fails or tests break, roll back your workspace modifications instantly.

4. 👥 Concurrent Subagents (Task Tool & Subagent Monitor): Axon can spawn isolated subagent workers to research documentation, run background tasks, or explore repositories concurrently without polluting the main conversation context.

5. 💰 Prompt Cache & Exact Token Cost Ledger: Full visibility into cache read/write tokens and real-time dollar costs per session, logged append-only into ~/.axon/sessions/.

📂 Zero-Pollution Global Storage (~/.axon/)

To keep your project workspaces 100% clean, Axon isolates all state and history in your user home directory:

~/.axon/ (or %USERPROFILE%\.axon\ on Windows)
├── config.toml       # Global defaults (default model, effort tier, permissions)
├── .env              # Global API credentials
├── sessions/         # Append-only JSONL transcripts, cost ledgers, and switcher data
├── memory/           # Universal long-term learned conventions (from /learn --global)
├── skills/           # Custom reusable workflows (from /skill create or /skill install)
├── research/         # Full deep-research markdown briefs
├── images/           # Multimodal image ingestion cache & vision attachments
└── bin/              # Precompiled native helpers

🛠️ 24 Built-In Native Tools

⌨️ Shortcuts & Slash Commands

🩺 Multi-Model Diagnostic Suite (check_models.py)

Test and benchmark live connectivity and latency across all supported model endpoints:

python check_models.py

⚡ Testing connectivity for 5 models (2 rounds · Base: https://agentrouter.org)...

--- [Round #1 of 2] 16:53:01 ---
deepseek-v4-flash    | ● WORKING |   1279 ms | OK
gpt-5.6-sol          | ● WORKING |   5251 ms | OK. I'm ChatGPT.
glm-5.3              | ● WORKING |   1803 ms | OK
claude-opus-5        | ● WORKING |   2026 ms | OK
claude-opus-4-8      | ● WORKING |   1772 ms | OK. I'm Claude, made by Anthropic.

✓ Model verification complete (2 rounds finished).

🧪 Test Suite

Axon is backed by a comprehensive suite of 528 automated unit and integration tests covering all security jails, permission matrices, session ledgers, cross-platform tools, and UI rendering:

pytest

============================= 528 passed in 5.1s ==============================

📄 License

MIT License. Designed and built for seamless terminal-native AI engineering.