axon-gpr 0.27.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- axon_gpr-0.27.0/PKG-INFO +275 -0
- axon_gpr-0.27.0/README.md +257 -0
- axon_gpr-0.27.0/pyproject.toml +24 -0
- axon_gpr-0.27.0/setup.cfg +4 -0
- axon_gpr-0.27.0/src/axon/__init__.py +17 -0
- axon_gpr-0.27.0/src/axon/__main__.py +8 -0
- axon_gpr-0.27.0/src/axon/agent/__init__.py +21 -0
- axon_gpr-0.27.0/src/axon/agent/context.py +70 -0
- axon_gpr-0.27.0/src/axon/agent/images.py +372 -0
- axon_gpr-0.27.0/src/axon/agent/loop.py +515 -0
- axon_gpr-0.27.0/src/axon/agent/memory.py +238 -0
- axon_gpr-0.27.0/src/axon/agent/prompt.py +131 -0
- axon_gpr-0.27.0/src/axon/agent/state.py +299 -0
- axon_gpr-0.27.0/src/axon/agent/subagent.py +397 -0
- axon_gpr-0.27.0/src/axon/cli.py +393 -0
- axon_gpr-0.27.0/src/axon/commands/__init__.py +6 -0
- axon_gpr-0.27.0/src/axon/commands/builtin.py +1435 -0
- axon_gpr-0.27.0/src/axon/config.py +157 -0
- axon_gpr-0.27.0/src/axon/errors.py +47 -0
- axon_gpr-0.27.0/src/axon/hooks/__init__.py +6 -0
- axon_gpr-0.27.0/src/axon/hooks/runner.py +41 -0
- axon_gpr-0.27.0/src/axon/permissions/__init__.py +15 -0
- axon_gpr-0.27.0/src/axon/permissions/engine.py +105 -0
- axon_gpr-0.27.0/src/axon/permissions/paths.py +56 -0
- axon_gpr-0.27.0/src/axon/permissions/rules.py +48 -0
- axon_gpr-0.27.0/src/axon/providers/__init__.py +48 -0
- axon_gpr-0.27.0/src/axon/providers/anthropic.py +174 -0
- axon_gpr-0.27.0/src/axon/providers/base.py +166 -0
- axon_gpr-0.27.0/src/axon/providers/openai_compat.py +401 -0
- axon_gpr-0.27.0/src/axon/providers/registry.py +53 -0
- axon_gpr-0.27.0/src/axon/session/__init__.py +11 -0
- axon_gpr-0.27.0/src/axon/session/checkpoint.py +76 -0
- axon_gpr-0.27.0/src/axon/session/interactive.py +228 -0
- axon_gpr-0.27.0/src/axon/session/ledger.py +92 -0
- axon_gpr-0.27.0/src/axon/session/store.py +286 -0
- axon_gpr-0.27.0/src/axon/skills/__init__.py +6 -0
- axon_gpr-0.27.0/src/axon/skills/importer.py +118 -0
- axon_gpr-0.27.0/src/axon/skills/interactive.py +257 -0
- axon_gpr-0.27.0/src/axon/skills/manager.py +269 -0
- axon_gpr-0.27.0/src/axon/tools/__init__.py +82 -0
- axon_gpr-0.27.0/src/axon/tools/base.py +42 -0
- axon_gpr-0.27.0/src/axon/tools/code_symbols.py +123 -0
- axon_gpr-0.27.0/src/axon/tools/deep_research.py +186 -0
- axon_gpr-0.27.0/src/axon/tools/diff_tool.py +55 -0
- axon_gpr-0.27.0/src/axon/tools/doctor.py +34 -0
- axon_gpr-0.27.0/src/axon/tools/env_tool.py +68 -0
- axon_gpr-0.27.0/src/axon/tools/file_tree.py +91 -0
- axon_gpr-0.27.0/src/axon/tools/fs_read.py +74 -0
- axon_gpr-0.27.0/src/axon/tools/fs_write.py +187 -0
- axon_gpr-0.27.0/src/axon/tools/git.py +103 -0
- axon_gpr-0.27.0/src/axon/tools/http_tool.py +77 -0
- axon_gpr-0.27.0/src/axon/tools/patch.py +97 -0
- axon_gpr-0.27.0/src/axon/tools/process_tool.py +77 -0
- axon_gpr-0.27.0/src/axon/tools/registry.py +67 -0
- axon_gpr-0.27.0/src/axon/tools/search.py +201 -0
- axon_gpr-0.27.0/src/axon/tools/shell.py +106 -0
- axon_gpr-0.27.0/src/axon/tools/table_search.py +166 -0
- axon_gpr-0.27.0/src/axon/tools/task.py +58 -0
- axon_gpr-0.27.0/src/axon/tools/todo.py +45 -0
- axon_gpr-0.27.0/src/axon/tools/web.py +49 -0
- axon_gpr-0.27.0/src/axon/tools/web_search.py +113 -0
- axon_gpr-0.27.0/src/axon/ui/__init__.py +44 -0
- axon_gpr-0.27.0/src/axon/ui/approve.py +45 -0
- axon_gpr-0.27.0/src/axon/ui/input.py +794 -0
- axon_gpr-0.27.0/src/axon/ui/live_turn.py +11 -0
- axon_gpr-0.27.0/src/axon/ui/markdown.py +574 -0
- axon_gpr-0.27.0/src/axon/ui/picker.py +63 -0
- axon_gpr-0.27.0/src/axon/ui/render.py +1313 -0
- axon_gpr-0.27.0/src/axon/ui/subagent_monitor.py +308 -0
- axon_gpr-0.27.0/src/axon/ui/switcher.py +465 -0
- axon_gpr-0.27.0/src/axon/ui/theme.py +45 -0
- axon_gpr-0.27.0/src/axon_gpr.egg-info/PKG-INFO +275 -0
- axon_gpr-0.27.0/src/axon_gpr.egg-info/SOURCES.txt +80 -0
- axon_gpr-0.27.0/src/axon_gpr.egg-info/dependency_links.txt +1 -0
- axon_gpr-0.27.0/src/axon_gpr.egg-info/entry_points.txt +2 -0
- axon_gpr-0.27.0/src/axon_gpr.egg-info/requires.txt +12 -0
- axon_gpr-0.27.0/src/axon_gpr.egg-info/top_level.txt +1 -0
- axon_gpr-0.27.0/tests/test_invariants.py +355 -0
- axon_gpr-0.27.0/tests/test_permissions.py +47 -0
- axon_gpr-0.27.0/tests/test_session.py +492 -0
- axon_gpr-0.27.0/tests/test_tools.py +296 -0
- axon_gpr-0.27.0/tests/test_ui_markdown.py +250 -0
axon_gpr-0.27.0/PKG-INFO
ADDED
|
@@ -0,0 +1,275 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: axon-gpr
|
|
3
|
+
Version: 0.27.0
|
|
4
|
+
Summary: A terminal-native agentic coding assistant.
|
|
5
|
+
Requires-Python: >=3.11
|
|
6
|
+
Description-Content-Type: text/markdown
|
|
7
|
+
Requires-Dist: anthropic>=0.40.0
|
|
8
|
+
Requires-Dist: httpx>=0.27.0
|
|
9
|
+
Requires-Dist: pydantic>=2.9.0
|
|
10
|
+
Requires-Dist: pydantic-settings>=2.6.0
|
|
11
|
+
Requires-Dist: tomli-w>=1.0.0
|
|
12
|
+
Requires-Dist: beautifulsoup4>=4.12.0
|
|
13
|
+
Provides-Extra: dev
|
|
14
|
+
Requires-Dist: pytest; extra == "dev"
|
|
15
|
+
Requires-Dist: pytest-cov; extra == "dev"
|
|
16
|
+
Requires-Dist: ruff; extra == "dev"
|
|
17
|
+
Requires-Dist: mypy; extra == "dev"
|
|
18
|
+
|
|
19
|
+
# Axon (vGPR_27)
|
|
20
|
+
|
|
21
|
+
<div align="center">
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
▲█▲ A X O N
|
|
25
|
+
█⚡█ Terminal-Native Agentic Coding Assistant
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
[](tests/)
|
|
29
|
+
[](pyproject.toml)
|
|
30
|
+
[](docs/01-ARCHITECTURE.md)
|
|
31
|
+
[](LICENSE)
|
|
32
|
+
|
|
33
|
+
**Axon** is a production-grade, terminal-native AI coding assistant built from first principles. It reads entire codebases, architects multi-step plans, performs surgical code edits, executes shell workflows, validates test results, and coordinates concurrent subagents — with full prompt cache cost accounting, rollback checkpoints, and zero external agent frameworks.
|
|
34
|
+
|
|
35
|
+
</div>
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## 🚀 Quick Setup & Getting Started
|
|
40
|
+
|
|
41
|
+
Follow these step-by-step instructions to get Axon running on your machine in under 1 minute.
|
|
42
|
+
|
|
43
|
+
### Step 1: Clone the Repository
|
|
44
|
+
```bash
|
|
45
|
+
git clone https://github.com/gpr-27/axon.git
|
|
46
|
+
cd axon
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
### Step 2: Install Required Dependencies
|
|
50
|
+
You can install dependencies using either the automatic installer script or standard pip:
|
|
51
|
+
|
|
52
|
+
#### Option A: Automated One-Step Setup (Recommended)
|
|
53
|
+
```bash
|
|
54
|
+
./install.sh
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
#### Option B: Manual Setup via Virtual Environment
|
|
58
|
+
```bash
|
|
59
|
+
# 1. Create and activate a virtual environment
|
|
60
|
+
python3 -m venv .venv
|
|
61
|
+
source .venv/bin/activate
|
|
62
|
+
|
|
63
|
+
# 2. Install production dependencies
|
|
64
|
+
pip install -r requirements.txt
|
|
65
|
+
|
|
66
|
+
# 3. Install Axon in editable mode to register the global 'axon' command
|
|
67
|
+
pip install -e .
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
### Step 3: Configure Your API Key in `.env`
|
|
73
|
+
Axon comes with a pre-configured `.env.example` with optimal defaults for model selection, token limits, reasoning effort, and tool permissions. **You only need to supply your API key**:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
# Copy example configuration to .env
|
|
77
|
+
cp .env.example .env
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Open `.env` in any text editor and **replace only the API key**:
|
|
81
|
+
```ini
|
|
82
|
+
# ─── 1. Provider & Authentication ──────────────────────────────────────────
|
|
83
|
+
# Replace with your actual key (AgentRouter, Anthropic, or OpenAI-compatible)
|
|
84
|
+
AXON_API_KEY="your_api_key_here"
|
|
85
|
+
|
|
86
|
+
# All other configurations below are pre-configured and ready out of the box!
|
|
87
|
+
AXON_BASE_URL="https://agentrouter.org"
|
|
88
|
+
AXON_MODEL="deepseek-v4-flash"
|
|
89
|
+
AXON_EFFORT="quantum"
|
|
90
|
+
AXON_THINKING=true
|
|
91
|
+
AXON_MODE="bypass"
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
> **Note**: No other variables need to be changed. Axon will automatically pick up your `.env` file from the current directory, parent folders, or `~/.axon/.env`.
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
### Step 4: Start Axon
|
|
99
|
+
|
|
100
|
+
Launch the assistant in your terminal with a single command:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
# Open interactive terminal assistant in the current directory:
|
|
104
|
+
axon
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
▲█▲ A X O N vGPR_27
|
|
109
|
+
█⚡█ Model: deepseek-v4-flash · Effort: quantum · Mode: bypass
|
|
110
|
+
|
|
111
|
+
> Ask anything, use / for commands, @ for files, ! for shell...
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
#### Additional Ways to Launch:
|
|
115
|
+
| Command | What it does |
|
|
116
|
+
| :--- | :--- |
|
|
117
|
+
| **`axon`** | Opens the interactive full-featured terminal REPL in your workspace. |
|
|
118
|
+
| **`axon -p "Your prompt"`** | Runs a one-shot query or task directly from the CLI and exits. |
|
|
119
|
+
| **`axon --continue`** | Resumes the most recent conversation session right where you left off. |
|
|
120
|
+
| **`axon --model claude-opus-5`** | Starts Axon with a specific LLM model override. |
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
### 🩺 Verifying Model Connectivity (`check_models.py`)
|
|
125
|
+
|
|
126
|
+
You can test and verify connectivity and response latency across all 5 supported models (`deepseek-v4-flash`, `gpt-5.6-sol`, `glm-5.3`, `claude-opus-5`, `claude-opus-4-8`) using the included diagnostic script (runs 2 verification rounds and exits):
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
# Run 2 validation rounds across all models:
|
|
130
|
+
python3 check_models.py
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
**Sample Output:**
|
|
134
|
+
```
|
|
135
|
+
⚡ Testing connectivity for 5 models (2 rounds · Base: https://agentrouter.org)...
|
|
136
|
+
|
|
137
|
+
--- [Round #1 of 2] 16:53:01 ---
|
|
138
|
+
deepseek-v4-flash | ● WORKING | 1279 ms | OK
|
|
139
|
+
gpt-5.6-sol | ● WORKING | 5251 ms | OK. I'm ChatGPT.
|
|
140
|
+
glm-5.3 | ● WORKING | 1803 ms | OK
|
|
141
|
+
claude-opus-5 | ● WORKING | 2026 ms | OK
|
|
142
|
+
claude-opus-4-8 | ● WORKING | 1772 ms | OK. I'm Claude, made by Anthropic.
|
|
143
|
+
|
|
144
|
+
--- [Round #2 of 2] 16:53:18 ---
|
|
145
|
+
deepseek-v4-flash | ● WORKING | 1280 ms | OK
|
|
146
|
+
gpt-5.6-sol | ● WORKING | 6013 ms | OK — I'm ChatGPT.
|
|
147
|
+
glm-5.3 | ● WORKING | 1994 ms | OK
|
|
148
|
+
claude-opus-5 | ● WORKING | 1897 ms | OK
|
|
149
|
+
claude-opus-4-8 | ● WORKING | 1727 ms | OK. I'm Claude, made by Anthropic.
|
|
150
|
+
|
|
151
|
+
✓ Model verification complete (2 rounds finished).
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## 🧠 How Axon Works (System Overview)
|
|
157
|
+
|
|
158
|
+
Axon operates as an autonomous, multi-turn **ReAct (Reasoning + Action)** agent loop with built-in subagent fan-out, persistent session memory, and atomic tool safety invariants:
|
|
159
|
+
|
|
160
|
+
```
|
|
161
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
162
|
+
│ USER INPUT / PROMPT │
|
|
163
|
+
└──────────────────────────────────────┬──────────────────────────────────────┘
|
|
164
|
+
▼
|
|
165
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
166
|
+
│ SYSTEM PROMPT BUILDER │
|
|
167
|
+
│ • Workspace context · File state table · AGENTS.md conventions · Memory │
|
|
168
|
+
└──────────────────────────────────────┬──────────────────────────────────────┘
|
|
169
|
+
▼
|
|
170
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
171
|
+
│ NEURAL REASONING & LLM │
|
|
172
|
+
│ • Models: DeepSeek-V4, Claude Opus 4.8/5, GPT-5.6 Sol, GLM-5.3 │
|
|
173
|
+
│ • Thinking stream (quantum/synapse/balanced/reflex) + Ephemeral Caching │
|
|
174
|
+
└──────────────────────────────────────┬──────────────────────────────────────┘
|
|
175
|
+
▼
|
|
176
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
177
|
+
│ PERMISSION ENGINE │
|
|
178
|
+
│ • Checks mode (default / acceptEdits / plan / bypass) & Hard Invariants │
|
|
179
|
+
└──────────────────────────────────────┬──────────────────────────────────────┘
|
|
180
|
+
▼
|
|
181
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
182
|
+
│ TOOL EXECUTION LAYER │
|
|
183
|
+
│ • Read · Write · Edit · MultiEdit · Patch · Diff · CodeSymbols · Bash │
|
|
184
|
+
│ • Subagent Task Launching · TableSearch · DeepResearch · Process · Git │
|
|
185
|
+
└──────────────────────────────────────┬──────────────────────────────────────┘
|
|
186
|
+
▼
|
|
187
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
188
|
+
│ BATCH TOOL RESULTS & LEDGER COST │
|
|
189
|
+
│ • Formats tool results into a single turn message (Law 2 Invariant) │
|
|
190
|
+
│ • Records exact tokens, cache read hits, and USD billing per turn │
|
|
191
|
+
└─────────────────────────────────────────────────────────────────────────────┘
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## 📂 Understanding the `.axon` Directories
|
|
197
|
+
|
|
198
|
+
```
|
|
199
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
200
|
+
│ 1. GLOBAL PROFILE: ~/.axon/ (Across Your Entire Computer) │
|
|
201
|
+
├─────────────────────────────────────────────────────────────────────────────┤
|
|
202
|
+
│ • Path: ~/.axon/ │
|
|
203
|
+
│ • Purpose: Universal configuration and credentials applied everywhere. │
|
|
204
|
+
│ • Contents: │
|
|
205
|
+
│ ├── config.toml -> Global default model, reasoning tier, token caps │
|
|
206
|
+
│ ├── .env -> Universal API keys and provider endpoints │
|
|
207
|
+
│ ├── skills/ -> User-wide custom skills & slash commands │
|
|
208
|
+
│ └── memory/ -> Global knowledge & developer preferences │
|
|
209
|
+
└─────────────────────────────────────────────────────────────────────────────┘
|
|
210
|
+
|
|
211
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
212
|
+
│ 2. WORKSPACE DIRECTORY: <project-root>/.axon/ (This Specific Repository) │
|
|
213
|
+
├─────────────────────────────────────────────────────────────────────────────┤
|
|
214
|
+
│ • Path: ./my-project/.axon/ │
|
|
215
|
+
│ • Purpose: Local, project-scoped state isolated to the current repo. │
|
|
216
|
+
│ • Contents: │
|
|
217
|
+
│ ├── sessions/ -> Append-only JSONL transcripts & subagent charts │
|
|
218
|
+
│ ├── memory/ -> Learned project rules and AGENTS.md conventions │
|
|
219
|
+
│ ├── outputs/ -> Full un-truncated command logs (latest_output.log)│
|
|
220
|
+
│ └── research/ -> Cached deep-research trees and scraped tables │
|
|
221
|
+
└─────────────────────────────────────────────────────────────────────────────┘
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## 🛠️ 24 Built-In Native Tools
|
|
227
|
+
|
|
228
|
+
Axon comes pre-equipped with 24 native tools designed for terminal-first development:
|
|
229
|
+
|
|
230
|
+
| Category | Tools | Description |
|
|
231
|
+
| :--- | :--- | :--- |
|
|
232
|
+
| **File I/O** | `Read`, `Write`, `Edit`, `MultiEdit`, `Patch`, `Diff` | Surgical edits with `(mtime, sha256)` staleness detection and read-before-edit enforcement. |
|
|
233
|
+
| **Navigation** | `Ls`, `FileTree`, `Glob`, `Grep`, `CodeSymbols` | AST-aware code symbol extraction and fast regex workspace searching. |
|
|
234
|
+
| **Execution** | `Bash`, `Process`, `Env`, `Git`, `Doctor` | Direct shell execution, process monitoring, proxy diagnostics, and git status analysis. |
|
|
235
|
+
| **Research & Web** | `DeepResearch`, `TableSearch`, `WebSearch`, `WebFetch`, `Http` | Multi-round technical research, table querying, and web exploration. |
|
|
236
|
+
| **Planning & Tasks** | `Task`, `TodoWrite`, `ExitPlanMode` | Concurrent subagent workers, multi-step checklists, and plan-mode control. |
|
|
237
|
+
|
|
238
|
+
---
|
|
239
|
+
|
|
240
|
+
## ⌨️ Useful Commands & Shortcuts
|
|
241
|
+
|
|
242
|
+
Inside the Axon prompt, you can use these shortcuts:
|
|
243
|
+
|
|
244
|
+
- **`Tab`**: Cycle permission modes (`manual` → `auto-accept edits` → `plan mode` → `bypass permissions`).
|
|
245
|
+
- **`←` (Left Arrow)**: Open the interactive **Previous Chats / Session Switcher** dashboard.
|
|
246
|
+
- **`!` (Exclamation)**: Execute direct shell commands (e.g. `!pytest`, `!git status`, `!npm test`).
|
|
247
|
+
- **`@` (At symbol)**: Fuzzy search and link project files directly into your prompt context.
|
|
248
|
+
- **`/cost`**: View detailed token breakdown, prompt cache hits, subagent costs, and workspace lifetime billing.
|
|
249
|
+
- **`/subagents`**: Open the subagent monitor to inspect isolated subagent transcripts and costs.
|
|
250
|
+
- **`/main`**: Return to the main chat session from any subagent view.
|
|
251
|
+
- **`/model`**: Switch active LLM on the fly (`deepseek-v4-flash`, `claude-opus-5`, `gpt-5.6-sol`, `glm-5.3`).
|
|
252
|
+
- **`/effort`**: Adjust reasoning effort level (`reflex`, `balanced`, `synapse`, `quantum`).
|
|
253
|
+
- **`/clear`**: Reset the conversation and start a clean session.
|
|
254
|
+
- **`?` or `/help`**: Show the categorized interactive commands cheat sheet.
|
|
255
|
+
|
|
256
|
+
---
|
|
257
|
+
|
|
258
|
+
## 🧪 Running Unit Tests (519 Tests)
|
|
259
|
+
|
|
260
|
+
To run the automated test suite covering all tools, invariants, sessions, and edge cases:
|
|
261
|
+
|
|
262
|
+
```bash
|
|
263
|
+
# Run the complete test suite
|
|
264
|
+
pytest tests -v
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
```
|
|
268
|
+
============================= 519 passed in 4.5s ==============================
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
---
|
|
272
|
+
|
|
273
|
+
## 📄 License
|
|
274
|
+
|
|
275
|
+
MIT License. Designed and built for seamless terminal-native AI engineering.
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
# Axon (vGPR_27)
|
|
2
|
+
|
|
3
|
+
<div align="center">
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
▲█▲ A X O N
|
|
7
|
+
█⚡█ Terminal-Native Agentic Coding Assistant
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
[](tests/)
|
|
11
|
+
[](pyproject.toml)
|
|
12
|
+
[](docs/01-ARCHITECTURE.md)
|
|
13
|
+
[](LICENSE)
|
|
14
|
+
|
|
15
|
+
**Axon** is a production-grade, terminal-native AI coding assistant built from first principles. It reads entire codebases, architects multi-step plans, performs surgical code edits, executes shell workflows, validates test results, and coordinates concurrent subagents — with full prompt cache cost accounting, rollback checkpoints, and zero external agent frameworks.
|
|
16
|
+
|
|
17
|
+
</div>
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## 🚀 Quick Setup & Getting Started
|
|
22
|
+
|
|
23
|
+
Follow these step-by-step instructions to get Axon running on your machine in under 1 minute.
|
|
24
|
+
|
|
25
|
+
### Step 1: Clone the Repository
|
|
26
|
+
```bash
|
|
27
|
+
git clone https://github.com/gpr-27/axon.git
|
|
28
|
+
cd axon
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
### Step 2: Install Required Dependencies
|
|
32
|
+
You can install dependencies using either the automatic installer script or standard pip:
|
|
33
|
+
|
|
34
|
+
#### Option A: Automated One-Step Setup (Recommended)
|
|
35
|
+
```bash
|
|
36
|
+
./install.sh
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
#### Option B: Manual Setup via Virtual Environment
|
|
40
|
+
```bash
|
|
41
|
+
# 1. Create and activate a virtual environment
|
|
42
|
+
python3 -m venv .venv
|
|
43
|
+
source .venv/bin/activate
|
|
44
|
+
|
|
45
|
+
# 2. Install production dependencies
|
|
46
|
+
pip install -r requirements.txt
|
|
47
|
+
|
|
48
|
+
# 3. Install Axon in editable mode to register the global 'axon' command
|
|
49
|
+
pip install -e .
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
### Step 3: Configure Your API Key in `.env`
|
|
55
|
+
Axon comes with a pre-configured `.env.example` with optimal defaults for model selection, token limits, reasoning effort, and tool permissions. **You only need to supply your API key**:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
# Copy example configuration to .env
|
|
59
|
+
cp .env.example .env
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Open `.env` in any text editor and **replace only the API key**:
|
|
63
|
+
```ini
|
|
64
|
+
# ─── 1. Provider & Authentication ──────────────────────────────────────────
|
|
65
|
+
# Replace with your actual key (AgentRouter, Anthropic, or OpenAI-compatible)
|
|
66
|
+
AXON_API_KEY="your_api_key_here"
|
|
67
|
+
|
|
68
|
+
# All other configurations below are pre-configured and ready out of the box!
|
|
69
|
+
AXON_BASE_URL="https://agentrouter.org"
|
|
70
|
+
AXON_MODEL="deepseek-v4-flash"
|
|
71
|
+
AXON_EFFORT="quantum"
|
|
72
|
+
AXON_THINKING=true
|
|
73
|
+
AXON_MODE="bypass"
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
> **Note**: No other variables need to be changed. Axon will automatically pick up your `.env` file from the current directory, parent folders, or `~/.axon/.env`.
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
### Step 4: Start Axon
|
|
81
|
+
|
|
82
|
+
Launch the assistant in your terminal with a single command:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
# Open interactive terminal assistant in the current directory:
|
|
86
|
+
axon
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
```
|
|
90
|
+
▲█▲ A X O N vGPR_27
|
|
91
|
+
█⚡█ Model: deepseek-v4-flash · Effort: quantum · Mode: bypass
|
|
92
|
+
|
|
93
|
+
> Ask anything, use / for commands, @ for files, ! for shell...
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
#### Additional Ways to Launch:
|
|
97
|
+
| Command | What it does |
|
|
98
|
+
| :--- | :--- |
|
|
99
|
+
| **`axon`** | Opens the interactive full-featured terminal REPL in your workspace. |
|
|
100
|
+
| **`axon -p "Your prompt"`** | Runs a one-shot query or task directly from the CLI and exits. |
|
|
101
|
+
| **`axon --continue`** | Resumes the most recent conversation session right where you left off. |
|
|
102
|
+
| **`axon --model claude-opus-5`** | Starts Axon with a specific LLM model override. |
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
### 🩺 Verifying Model Connectivity (`check_models.py`)
|
|
107
|
+
|
|
108
|
+
You can test and verify connectivity and response latency across all 5 supported models (`deepseek-v4-flash`, `gpt-5.6-sol`, `glm-5.3`, `claude-opus-5`, `claude-opus-4-8`) using the included diagnostic script (runs 2 verification rounds and exits):
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
# Run 2 validation rounds across all models:
|
|
112
|
+
python3 check_models.py
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
**Sample Output:**
|
|
116
|
+
```
|
|
117
|
+
⚡ Testing connectivity for 5 models (2 rounds · Base: https://agentrouter.org)...
|
|
118
|
+
|
|
119
|
+
--- [Round #1 of 2] 16:53:01 ---
|
|
120
|
+
deepseek-v4-flash | ● WORKING | 1279 ms | OK
|
|
121
|
+
gpt-5.6-sol | ● WORKING | 5251 ms | OK. I'm ChatGPT.
|
|
122
|
+
glm-5.3 | ● WORKING | 1803 ms | OK
|
|
123
|
+
claude-opus-5 | ● WORKING | 2026 ms | OK
|
|
124
|
+
claude-opus-4-8 | ● WORKING | 1772 ms | OK. I'm Claude, made by Anthropic.
|
|
125
|
+
|
|
126
|
+
--- [Round #2 of 2] 16:53:18 ---
|
|
127
|
+
deepseek-v4-flash | ● WORKING | 1280 ms | OK
|
|
128
|
+
gpt-5.6-sol | ● WORKING | 6013 ms | OK — I'm ChatGPT.
|
|
129
|
+
glm-5.3 | ● WORKING | 1994 ms | OK
|
|
130
|
+
claude-opus-5 | ● WORKING | 1897 ms | OK
|
|
131
|
+
claude-opus-4-8 | ● WORKING | 1727 ms | OK. I'm Claude, made by Anthropic.
|
|
132
|
+
|
|
133
|
+
✓ Model verification complete (2 rounds finished).
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## 🧠 How Axon Works (System Overview)
|
|
139
|
+
|
|
140
|
+
Axon operates as an autonomous, multi-turn **ReAct (Reasoning + Action)** agent loop with built-in subagent fan-out, persistent session memory, and atomic tool safety invariants:
|
|
141
|
+
|
|
142
|
+
```
|
|
143
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
144
|
+
│ USER INPUT / PROMPT │
|
|
145
|
+
└──────────────────────────────────────┬──────────────────────────────────────┘
|
|
146
|
+
▼
|
|
147
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
148
|
+
│ SYSTEM PROMPT BUILDER │
|
|
149
|
+
│ • Workspace context · File state table · AGENTS.md conventions · Memory │
|
|
150
|
+
└──────────────────────────────────────┬──────────────────────────────────────┘
|
|
151
|
+
▼
|
|
152
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
153
|
+
│ NEURAL REASONING & LLM │
|
|
154
|
+
│ • Models: DeepSeek-V4, Claude Opus 4.8/5, GPT-5.6 Sol, GLM-5.3 │
|
|
155
|
+
│ • Thinking stream (quantum/synapse/balanced/reflex) + Ephemeral Caching │
|
|
156
|
+
└──────────────────────────────────────┬──────────────────────────────────────┘
|
|
157
|
+
▼
|
|
158
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
159
|
+
│ PERMISSION ENGINE │
|
|
160
|
+
│ • Checks mode (default / acceptEdits / plan / bypass) & Hard Invariants │
|
|
161
|
+
└──────────────────────────────────────┬──────────────────────────────────────┘
|
|
162
|
+
▼
|
|
163
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
164
|
+
│ TOOL EXECUTION LAYER │
|
|
165
|
+
│ • Read · Write · Edit · MultiEdit · Patch · Diff · CodeSymbols · Bash │
|
|
166
|
+
│ • Subagent Task Launching · TableSearch · DeepResearch · Process · Git │
|
|
167
|
+
└──────────────────────────────────────┬──────────────────────────────────────┘
|
|
168
|
+
▼
|
|
169
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
170
|
+
│ BATCH TOOL RESULTS & LEDGER COST │
|
|
171
|
+
│ • Formats tool results into a single turn message (Law 2 Invariant) │
|
|
172
|
+
│ • Records exact tokens, cache read hits, and USD billing per turn │
|
|
173
|
+
└─────────────────────────────────────────────────────────────────────────────┘
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## 📂 Understanding the `.axon` Directories
|
|
179
|
+
|
|
180
|
+
```
|
|
181
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
182
|
+
│ 1. GLOBAL PROFILE: ~/.axon/ (Across Your Entire Computer) │
|
|
183
|
+
├─────────────────────────────────────────────────────────────────────────────┤
|
|
184
|
+
│ • Path: ~/.axon/ │
|
|
185
|
+
│ • Purpose: Universal configuration and credentials applied everywhere. │
|
|
186
|
+
│ • Contents: │
|
|
187
|
+
│ ├── config.toml -> Global default model, reasoning tier, token caps │
|
|
188
|
+
│ ├── .env -> Universal API keys and provider endpoints │
|
|
189
|
+
│ ├── skills/ -> User-wide custom skills & slash commands │
|
|
190
|
+
│ └── memory/ -> Global knowledge & developer preferences │
|
|
191
|
+
└─────────────────────────────────────────────────────────────────────────────┘
|
|
192
|
+
|
|
193
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
194
|
+
│ 2. WORKSPACE DIRECTORY: <project-root>/.axon/ (This Specific Repository) │
|
|
195
|
+
├─────────────────────────────────────────────────────────────────────────────┤
|
|
196
|
+
│ • Path: ./my-project/.axon/ │
|
|
197
|
+
│ • Purpose: Local, project-scoped state isolated to the current repo. │
|
|
198
|
+
│ • Contents: │
|
|
199
|
+
│ ├── sessions/ -> Append-only JSONL transcripts & subagent charts │
|
|
200
|
+
│ ├── memory/ -> Learned project rules and AGENTS.md conventions │
|
|
201
|
+
│ ├── outputs/ -> Full un-truncated command logs (latest_output.log)│
|
|
202
|
+
│ └── research/ -> Cached deep-research trees and scraped tables │
|
|
203
|
+
└─────────────────────────────────────────────────────────────────────────────┘
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
## 🛠️ 24 Built-In Native Tools
|
|
209
|
+
|
|
210
|
+
Axon comes pre-equipped with 24 native tools designed for terminal-first development:
|
|
211
|
+
|
|
212
|
+
| Category | Tools | Description |
|
|
213
|
+
| :--- | :--- | :--- |
|
|
214
|
+
| **File I/O** | `Read`, `Write`, `Edit`, `MultiEdit`, `Patch`, `Diff` | Surgical edits with `(mtime, sha256)` staleness detection and read-before-edit enforcement. |
|
|
215
|
+
| **Navigation** | `Ls`, `FileTree`, `Glob`, `Grep`, `CodeSymbols` | AST-aware code symbol extraction and fast regex workspace searching. |
|
|
216
|
+
| **Execution** | `Bash`, `Process`, `Env`, `Git`, `Doctor` | Direct shell execution, process monitoring, proxy diagnostics, and git status analysis. |
|
|
217
|
+
| **Research & Web** | `DeepResearch`, `TableSearch`, `WebSearch`, `WebFetch`, `Http` | Multi-round technical research, table querying, and web exploration. |
|
|
218
|
+
| **Planning & Tasks** | `Task`, `TodoWrite`, `ExitPlanMode` | Concurrent subagent workers, multi-step checklists, and plan-mode control. |
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
|
|
222
|
+
## ⌨️ Useful Commands & Shortcuts
|
|
223
|
+
|
|
224
|
+
Inside the Axon prompt, you can use these shortcuts:
|
|
225
|
+
|
|
226
|
+
- **`Tab`**: Cycle permission modes (`manual` → `auto-accept edits` → `plan mode` → `bypass permissions`).
|
|
227
|
+
- **`←` (Left Arrow)**: Open the interactive **Previous Chats / Session Switcher** dashboard.
|
|
228
|
+
- **`!` (Exclamation)**: Execute direct shell commands (e.g. `!pytest`, `!git status`, `!npm test`).
|
|
229
|
+
- **`@` (At symbol)**: Fuzzy search and link project files directly into your prompt context.
|
|
230
|
+
- **`/cost`**: View detailed token breakdown, prompt cache hits, subagent costs, and workspace lifetime billing.
|
|
231
|
+
- **`/subagents`**: Open the subagent monitor to inspect isolated subagent transcripts and costs.
|
|
232
|
+
- **`/main`**: Return to the main chat session from any subagent view.
|
|
233
|
+
- **`/model`**: Switch active LLM on the fly (`deepseek-v4-flash`, `claude-opus-5`, `gpt-5.6-sol`, `glm-5.3`).
|
|
234
|
+
- **`/effort`**: Adjust reasoning effort level (`reflex`, `balanced`, `synapse`, `quantum`).
|
|
235
|
+
- **`/clear`**: Reset the conversation and start a clean session.
|
|
236
|
+
- **`?` or `/help`**: Show the categorized interactive commands cheat sheet.
|
|
237
|
+
|
|
238
|
+
---
|
|
239
|
+
|
|
240
|
+
## 🧪 Running Unit Tests (519 Tests)
|
|
241
|
+
|
|
242
|
+
To run the automated test suite covering all tools, invariants, sessions, and edge cases:
|
|
243
|
+
|
|
244
|
+
```bash
|
|
245
|
+
# Run the complete test suite
|
|
246
|
+
pytest tests -v
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
```
|
|
250
|
+
============================= 519 passed in 4.5s ==============================
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
---
|
|
254
|
+
|
|
255
|
+
## 📄 License
|
|
256
|
+
|
|
257
|
+
MIT License. Designed and built for seamless terminal-native AI engineering.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "axon-gpr"
|
|
3
|
+
version = "0.27.0"
|
|
4
|
+
description = "A terminal-native agentic coding assistant."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.11"
|
|
7
|
+
dependencies = [
|
|
8
|
+
"anthropic>=0.40.0",
|
|
9
|
+
"httpx>=0.27.0",
|
|
10
|
+
"pydantic>=2.9.0",
|
|
11
|
+
"pydantic-settings>=2.6.0",
|
|
12
|
+
"tomli-w>=1.0.0",
|
|
13
|
+
"beautifulsoup4>=4.12.0",
|
|
14
|
+
]
|
|
15
|
+
|
|
16
|
+
[project.optional-dependencies]
|
|
17
|
+
dev = ["pytest", "pytest-cov", "ruff", "mypy"]
|
|
18
|
+
|
|
19
|
+
[project.scripts]
|
|
20
|
+
axon = "axon.cli:main"
|
|
21
|
+
|
|
22
|
+
[build-system]
|
|
23
|
+
requires = ["setuptools>=61.0"]
|
|
24
|
+
build-backend = "setuptools.build_meta"
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Axon package root.
|
|
3
|
+
"""
|
|
4
|
+
from axon.agent.loop import Agent, TurnResult
|
|
5
|
+
from axon.config import Settings
|
|
6
|
+
from axon.errors import AxonError, ToolError, PermissionDenied
|
|
7
|
+
|
|
8
|
+
__version__ = "GPR_27"
|
|
9
|
+
|
|
10
|
+
__all__ = [
|
|
11
|
+
"Agent",
|
|
12
|
+
"TurnResult",
|
|
13
|
+
"Settings",
|
|
14
|
+
"AxonError",
|
|
15
|
+
"ToolError",
|
|
16
|
+
"PermissionDenied",
|
|
17
|
+
]
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Agent package exports.
|
|
3
|
+
"""
|
|
4
|
+
from axon.agent.state import Conversation, FileState, TodoState, Todo
|
|
5
|
+
from axon.agent.prompt import build_system, discover_project_context
|
|
6
|
+
from axon.agent.context import ContextManager
|
|
7
|
+
from axon.agent.subagent import run_subagent
|
|
8
|
+
from axon.agent.loop import Agent, TurnResult
|
|
9
|
+
|
|
10
|
+
__all__ = [
|
|
11
|
+
"Conversation",
|
|
12
|
+
"FileState",
|
|
13
|
+
"TodoState",
|
|
14
|
+
"Todo",
|
|
15
|
+
"build_system",
|
|
16
|
+
"discover_project_context",
|
|
17
|
+
"ContextManager",
|
|
18
|
+
"run_subagent",
|
|
19
|
+
"Agent",
|
|
20
|
+
"TurnResult",
|
|
21
|
+
]
|