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.
Files changed (82) hide show
  1. axon_gpr-0.27.0/PKG-INFO +275 -0
  2. axon_gpr-0.27.0/README.md +257 -0
  3. axon_gpr-0.27.0/pyproject.toml +24 -0
  4. axon_gpr-0.27.0/setup.cfg +4 -0
  5. axon_gpr-0.27.0/src/axon/__init__.py +17 -0
  6. axon_gpr-0.27.0/src/axon/__main__.py +8 -0
  7. axon_gpr-0.27.0/src/axon/agent/__init__.py +21 -0
  8. axon_gpr-0.27.0/src/axon/agent/context.py +70 -0
  9. axon_gpr-0.27.0/src/axon/agent/images.py +372 -0
  10. axon_gpr-0.27.0/src/axon/agent/loop.py +515 -0
  11. axon_gpr-0.27.0/src/axon/agent/memory.py +238 -0
  12. axon_gpr-0.27.0/src/axon/agent/prompt.py +131 -0
  13. axon_gpr-0.27.0/src/axon/agent/state.py +299 -0
  14. axon_gpr-0.27.0/src/axon/agent/subagent.py +397 -0
  15. axon_gpr-0.27.0/src/axon/cli.py +393 -0
  16. axon_gpr-0.27.0/src/axon/commands/__init__.py +6 -0
  17. axon_gpr-0.27.0/src/axon/commands/builtin.py +1435 -0
  18. axon_gpr-0.27.0/src/axon/config.py +157 -0
  19. axon_gpr-0.27.0/src/axon/errors.py +47 -0
  20. axon_gpr-0.27.0/src/axon/hooks/__init__.py +6 -0
  21. axon_gpr-0.27.0/src/axon/hooks/runner.py +41 -0
  22. axon_gpr-0.27.0/src/axon/permissions/__init__.py +15 -0
  23. axon_gpr-0.27.0/src/axon/permissions/engine.py +105 -0
  24. axon_gpr-0.27.0/src/axon/permissions/paths.py +56 -0
  25. axon_gpr-0.27.0/src/axon/permissions/rules.py +48 -0
  26. axon_gpr-0.27.0/src/axon/providers/__init__.py +48 -0
  27. axon_gpr-0.27.0/src/axon/providers/anthropic.py +174 -0
  28. axon_gpr-0.27.0/src/axon/providers/base.py +166 -0
  29. axon_gpr-0.27.0/src/axon/providers/openai_compat.py +401 -0
  30. axon_gpr-0.27.0/src/axon/providers/registry.py +53 -0
  31. axon_gpr-0.27.0/src/axon/session/__init__.py +11 -0
  32. axon_gpr-0.27.0/src/axon/session/checkpoint.py +76 -0
  33. axon_gpr-0.27.0/src/axon/session/interactive.py +228 -0
  34. axon_gpr-0.27.0/src/axon/session/ledger.py +92 -0
  35. axon_gpr-0.27.0/src/axon/session/store.py +286 -0
  36. axon_gpr-0.27.0/src/axon/skills/__init__.py +6 -0
  37. axon_gpr-0.27.0/src/axon/skills/importer.py +118 -0
  38. axon_gpr-0.27.0/src/axon/skills/interactive.py +257 -0
  39. axon_gpr-0.27.0/src/axon/skills/manager.py +269 -0
  40. axon_gpr-0.27.0/src/axon/tools/__init__.py +82 -0
  41. axon_gpr-0.27.0/src/axon/tools/base.py +42 -0
  42. axon_gpr-0.27.0/src/axon/tools/code_symbols.py +123 -0
  43. axon_gpr-0.27.0/src/axon/tools/deep_research.py +186 -0
  44. axon_gpr-0.27.0/src/axon/tools/diff_tool.py +55 -0
  45. axon_gpr-0.27.0/src/axon/tools/doctor.py +34 -0
  46. axon_gpr-0.27.0/src/axon/tools/env_tool.py +68 -0
  47. axon_gpr-0.27.0/src/axon/tools/file_tree.py +91 -0
  48. axon_gpr-0.27.0/src/axon/tools/fs_read.py +74 -0
  49. axon_gpr-0.27.0/src/axon/tools/fs_write.py +187 -0
  50. axon_gpr-0.27.0/src/axon/tools/git.py +103 -0
  51. axon_gpr-0.27.0/src/axon/tools/http_tool.py +77 -0
  52. axon_gpr-0.27.0/src/axon/tools/patch.py +97 -0
  53. axon_gpr-0.27.0/src/axon/tools/process_tool.py +77 -0
  54. axon_gpr-0.27.0/src/axon/tools/registry.py +67 -0
  55. axon_gpr-0.27.0/src/axon/tools/search.py +201 -0
  56. axon_gpr-0.27.0/src/axon/tools/shell.py +106 -0
  57. axon_gpr-0.27.0/src/axon/tools/table_search.py +166 -0
  58. axon_gpr-0.27.0/src/axon/tools/task.py +58 -0
  59. axon_gpr-0.27.0/src/axon/tools/todo.py +45 -0
  60. axon_gpr-0.27.0/src/axon/tools/web.py +49 -0
  61. axon_gpr-0.27.0/src/axon/tools/web_search.py +113 -0
  62. axon_gpr-0.27.0/src/axon/ui/__init__.py +44 -0
  63. axon_gpr-0.27.0/src/axon/ui/approve.py +45 -0
  64. axon_gpr-0.27.0/src/axon/ui/input.py +794 -0
  65. axon_gpr-0.27.0/src/axon/ui/live_turn.py +11 -0
  66. axon_gpr-0.27.0/src/axon/ui/markdown.py +574 -0
  67. axon_gpr-0.27.0/src/axon/ui/picker.py +63 -0
  68. axon_gpr-0.27.0/src/axon/ui/render.py +1313 -0
  69. axon_gpr-0.27.0/src/axon/ui/subagent_monitor.py +308 -0
  70. axon_gpr-0.27.0/src/axon/ui/switcher.py +465 -0
  71. axon_gpr-0.27.0/src/axon/ui/theme.py +45 -0
  72. axon_gpr-0.27.0/src/axon_gpr.egg-info/PKG-INFO +275 -0
  73. axon_gpr-0.27.0/src/axon_gpr.egg-info/SOURCES.txt +80 -0
  74. axon_gpr-0.27.0/src/axon_gpr.egg-info/dependency_links.txt +1 -0
  75. axon_gpr-0.27.0/src/axon_gpr.egg-info/entry_points.txt +2 -0
  76. axon_gpr-0.27.0/src/axon_gpr.egg-info/requires.txt +12 -0
  77. axon_gpr-0.27.0/src/axon_gpr.egg-info/top_level.txt +1 -0
  78. axon_gpr-0.27.0/tests/test_invariants.py +355 -0
  79. axon_gpr-0.27.0/tests/test_permissions.py +47 -0
  80. axon_gpr-0.27.0/tests/test_session.py +492 -0
  81. axon_gpr-0.27.0/tests/test_tools.py +296 -0
  82. axon_gpr-0.27.0/tests/test_ui_markdown.py +250 -0
@@ -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](https://img.shields.io/badge/tests-519%20passed-brightgreen.svg)](tests/)
29
+ [![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue.svg)](pyproject.toml)
30
+ [![Architecture](https://img.shields.io/badge/architecture-ReAct%20Loop%20%2B%20Subagents-orange.svg)](docs/01-ARCHITECTURE.md)
31
+ [![License](https://img.shields.io/badge/license-MIT-purple.svg)](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](https://img.shields.io/badge/tests-519%20passed-brightgreen.svg)](tests/)
11
+ [![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue.svg)](pyproject.toml)
12
+ [![Architecture](https://img.shields.io/badge/architecture-ReAct%20Loop%20%2B%20Subagents-orange.svg)](docs/01-ARCHITECTURE.md)
13
+ [![License](https://img.shields.io/badge/license-MIT-purple.svg)](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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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,8 @@
1
+ """
2
+ Entrypoint for `python3 -m axon`.
3
+ """
4
+ import sys
5
+ from axon.cli import main
6
+
7
+ if __name__ == "__main__":
8
+ sys.exit(main())
@@ -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
+ ]