axe-cli 1.7.5

axe, yerrrr

axe

The AI agent built for real codebases.

While other AI coding tools burn tokens on bloat to charge you more, axe gives you surgical precision. Built for large-scale projects, battle-tested internally for 6 months, and powered by the world's most advanced code retrieval engine.

---

What is axe?

axe is an AI agent that runs in your terminal, helping you complete software development tasks and terminal operations. It can read and edit code, execute shell commands, search and fetch web pages, and autonomously plan and adjust actions during execution.

axe is suited for:

• Writing and modifying code: Implementing new features, fixing bugs, refactoring code
• Understanding projects: Exploring unfamiliar codebases, answering architecture and implementation questions
• Automating tasks: Batch processing files, running builds and tests, executing scripts
• Research and data analysis: Web research, log analysis, data processing

axe provides a shell-like interactive experience in the terminal. You can describe your needs in natural language or press Ctrl+X to switch to shell mode and execute commands directly.

---

Why axe exists

The problem: Claude Code and OpenAI Codex dump your entire codebase into context, charging you for irrelevant noise. They're built for vibe coding—one-shot weekend projects where "good enough" is the goal.

The reality: Real engineering happens in 100K+ line codebases where precision matters. You need to understand execution flow, trace bugs through call graphs, profile memory bottlenecks, and refactor without breaking half your tests.

The solution: axe combines AI agents with axe-dig, our 5-layer code intelligence engine that extracts meaning instead of dumping text. The result:

• 95% fewer tokens while preserving everything needed to understand code
• Semantic search that finds code by behavior, not just keywords
• Execution tracing (coming soon) that shows you what values flowed through functions
• Flame graphs & memory profiling (coming soon) to debug performance, not just logic
• Call graph analysis to refactor safely and understand impact

This isn't a toy for side projects. This is the tool our internal team has used for 6 months to ship production code faster.

---

Common Use Cases

axe can help you complete various software development and general tasks. Here are some typical scenarios.

Implementing new features

When you need to add new features to your project, simply describe your requirements in natural language. axe will automatically read relevant code, understand the project structure, and then make modifications.

Add pagination to the user list page, showing 20 records per page

axe typically works through a "Read → Edit → Verify" workflow:

1. Read: Search and read relevant code, understand existing implementation
2. Edit: Write or modify code, following the project's coding style
3. Verify: Run tests or builds to ensure changes don't introduce issues

If you're not satisfied with the changes, you can tell axe to adjust:

The pagination component style doesn't match the rest of the project, reference the Button component's style

Fixing bugs

Describe the problem you're encountering, and axe will help you locate the cause and fix it:

After user login, when redirecting to the home page, it occasionally shows logged out status. Help me investigate

For problems with clear error messages, you can paste the error log directly:

When running npm test, I get this error:

TypeError: Cannot read property 'map' of undefined
    at UserList.render (src/components/UserList.jsx:15:23)

Please fix it

You can also have axe run commands to reproduce and verify the issue:

Run the tests, and if there are any failing cases, fix them

Understanding projects

axe can help you explore and understand unfamiliar codebases:

What's the overall architecture of this project? Where is the entry file?

How is the user authentication flow implemented? What files are involved?

Explain what the src/core/scheduler.py file does

If you encounter parts you don't understand while reading code, you can ask anytime:

What's the difference between useCallback and useMemo? Why use useCallback here?

Automating small tasks

axe can perform various repetitive small tasks:

Change all var declarations to const or let in .js files under the src directory

Add documentation comments to all public functions without docstrings

Generate unit tests for this API module

Update all dependencies in package.json to the latest version, then run tests to make sure there are no issues

Automating general tasks

Beyond code-related tasks, axe can also handle general scenarios.

Research tasks:

Research Python async web frameworks for me, compare the pros and cons of FastAPI, Starlette, and Sanic

Data analysis:

Analyze the access logs in the logs directory, count the call frequency and average response time for each endpoint

Batch file processing:

Convert all PNG images in the images directory to JPEG format, save to the output directory

---

Quick start

Install

pip install axe-cli axe-dig

Index your codebase

cd /path/to/your/project
axe

On first run, axe-dig automatically indexes your codebase (30-60 seconds for typical projects). After that, queries are instant.

Start using

# Find code by behavior
/skill:code-search "database connection pooling"

# Understand a function without reading the whole file
/skill:code-context get_user_by_id

# See who calls a function before refactoring
/skill:code-impact authenticate_request

# Make surgical edits
StrReplaceFile src/auth.py "old code" "new code"

# Toggle to shell mode
[Ctrl+X]
pytest tests/
[Ctrl+X]

---

What makes axe different

1. Precision over bloat

Other tools: "Here's your entire 50-file module. Claude, figure it out."
axe: "Here are the 6 lines that affect your bug, the call graph showing who uses this function, and the data flow proving where the null came from."

How? axe-dig builds 5 analysis layers:

┌─────────────────────────────────────────────────────────────┐
│ Layer 5: Program Dependence  → "What affects line 42?"      │
│ Layer 4: Data Flow           → "Where does this value go?"  │
│ Layer 3: Control Flow        → "How complex is this?"       │
│ Layer 2: Call Graph          → "Who calls this function?"   │
│ Layer 1: AST                 → "What functions exist?"      │
└─────────────────────────────────────────────────────────────┘

Different tasks need different depth. Browsing? Layer 1. Refactoring? Layer 2. Debugging a null pointer? Layer 5 shows only the relevant lines.

2. Semantic code search

Find code by what it does, not what it's named.

# Traditional grep: finds literal text matches
grep "jwt" src/  # Misses verify_access_token()

# axe semantic search: understands behavior
/skill:code-search "validate JWT tokens and check expiration"
# Finds verify_access_token() because the call graph and 
# data flow reveal it's doing JWT validation

3. Built for debugging (coming soon)

Debugging isn't just about bad code—it's about bad logic, performance bottlenecks, and understanding what actually happened at runtime.

Coming features:

• Execution tracing: See exact values that flowed through each function call
• Flame graphs: Visualize where your code spends time
• Memory profiling: Find leaks and allocation hotspots
• Call stack reconstruction: Understand how you got to that error state

4. Token cost transparency

We don't make money by wasting your tokens. Every query shows exactly how many tokens were used:

✓ Context extracted: 175 tokens (was 21,000 raw)
✓ Savings: 99.2%

5. Shell mode integration

Hit Ctrl+X to switch to normal shell. Run your tests, check git status, install packages. Hit Ctrl+X again to toggle back to axe.

No more juggling terminal windows. No more context switching.

---

Core capabilities

Code intelligence tools

Powered by axe-dig's 5-layer analysis:

Tool	What it does	Use case
CodeSearch	Semantic search by behavior	"Find JWT validation logic"
CodeContext	LLM-ready function summaries (95% token savings)	Understand unfamiliar code
CodeStructure	Navigate functions/classes in files/dirs	Explore new codebases
CodeImpact	Reverse call graph (who calls this?)	Safe refactoring

File operations

• ReadFile / WriteFile / StrReplaceFile - Standard file I/O
• Grep - Exact file locations + line numbers (use after CodeSearch)
• Glob - Pattern matching
• ReadMediaFile - Images, PDFs, videos

Multi-agent workflows

• Task - Spawn subagents for parallel work
• CreateSubagent - Custom agent specs
• SetTodoList - Track multi-step tasks

Shell integration

• Shell - Execute commands
• Ctrl+X - Toggle between axe and normal shell mode

---

Real example: Debug a null pointer

Without axe:

1. Read the 150-line function top to bottom
2. Trace every variable assignment manually
3. Miss the bug because it's hidden in control flow
4. Spend 30 minutes and burn 21,000 tokens

With axe:

# Ask axe to debug
"Why is user null on line 42 in src/auth.py?"

# axe uses CodeImpact + data flow analysis internally
# Shows you only the 6 lines that matter:

3:   user = db.get_user(username)
7:   if user is None:
12:      raise NotFound
28:  token = create_token(user)  # ← BUG: skipped null check
35:  session.token = token
42:  return session

✓ 175 tokens used (was 21,000)
✓ Bug found in 30 seconds

The bug is obvious: line 28 uses user without going through the null check path.

---

Powered by SRSWTI Inc.

Building the world's fastest retrieval and inference engines.

Bodega's Own

Exclusive models trained/optimized for Bodega Inference Engine. Note: Our models are also available on Hugging Face.

Raptor Series

Ultra-compact reasoning models designed for efficiency and edge deployment.

• bodega-raptor-0.9b - 900M params. Runs on mobile/Pi with 100+ tok/s. Handles document classification, query reformulation, and lightweight reasoning at the edge.
• bodega-raptor-90m - Extreme edge variant. Sub-100M params for amazing tool calling support and reasoning.
• bodega-raptor-1b-reasoning-opus4.5-distill - Distilled from Claude Opus 4.5 reasoning patterns. Enhanced logical deduction chains.
• bodega-raptor-8b-mxfp4 - Balanced power/performance for laptops.
• bodega-raptor-15b-6bit - Better raptor.

Flagship Models

Frontier intelligence, distilled and optimized.

• deepseek-v3.2-speciale-distilled-raptor-32b-4bit - DeepSeek V3.2 distilled to 32B with Raptor reasoning. Exceptional math/code generation in 5-7GB footprint. 120 tok/s on M1 Max.
• bodega-centenario-21b-mxfp4 - Production workhorse. 21B params optimized for sustained inference workloads. Behemoth in all categories.
• bodega-solomon-9b - Multimodal and best for agentic coding.

Axe-Turbo Series

Agentic Coding Models.

• axe-turbo-1b - 1B params, 150 tok/s, sub-50ms first token. Edge-first architecture.
• axe-turbo-31b - for High-capacity workloads. Baller coding model, exceptional agentic capabilities.

Specialized Models

Task-specific optimization.

• bodega-vertex-4b - 4B params. Optimized for structured data.
• blackbird-she-doesnt-refuse-21b - Uncensored 21B variant for unrestricted generation.

---

Sessions and Context Management

axe automatically saves your conversation history, allowing you to continue previous work at any time.

Session resuming

Each time you start axe, a new session is created. If you want to continue a previous conversation, there are several ways:

Continue the most recent session:

Use the --continue flag to continue the most recent session in the current working directory:

axe --continue

Switch to a specific session:

Use the --session flag to switch to a session with a specific ID:

axe --session abc123

Switch sessions during runtime:

Enter /sessions (or /resume) to view all sessions in the current working directory, and use arrow keys to select the session you want to switch to:

/sessions

The list shows each session's title and last update time, helping you find the conversation you want to continue.

Startup replay

When you continue an existing session, axe will replay the previous conversation history so you can quickly understand the context. During replay, previous messages and AI responses will be displayed.

Clear and compact

As the conversation progresses, the context grows longer. axe will automatically compress the context when needed to ensure the conversation can continue.

You can also manually manage the context using slash commands:

Clear context:

Enter /clear to clear all context in the current session and start a fresh conversation:

/clear

After clearing, the AI will forget all previous conversation content. You usually don't need to use this command; for new tasks, starting a new session is a better choice.

Compact context:

Enter /compact to have the AI summarize the current conversation and replace the original context with the summary:

/compact

Compacting preserves key information while reducing token consumption. This is useful when the conversation is long but you still want to retain some context.

---

Agent Skills

Agent Skills is an open format for adding specialized knowledge and workflows to AI agents. axe supports loading Agent Skills to extend AI capabilities.

What are Agent Skills?

A skill is a directory containing a SKILL.md file. When axe starts, it discovers all skills and injects their names, paths, and descriptions into the system prompt. The AI will decide on its own whether to read the specific SKILL.md file to get detailed guidance based on the current task's needs.

For example, you can create a "code style" skill to tell the AI your project's naming conventions, comment styles, etc.; or create a "security audit" skill to have the AI focus on specific security issues when reviewing code.

Skill discovery

axe uses a layered loading mechanism to discover skills, loading in the following priority order (later ones override skills with the same name):

Built-in skills

Skills shipped with the package, providing basic capabilities.

User-level skills

Stored in the user's home directory, effective across all projects. axe checks the following directories in priority order and uses the first one that exists:

• ~/.config/agents/skills/ (recommended)
• ~/.agents/skills/
• ~/.axe/skills/
• ~/.claude/skills/
• ~/.codex/skills/

Project-level skills

Stored in the project directory, only effective within that project's working directory. axe checks the following directories in priority order and uses the first one that exists:

• .agents/skills/ (recommended)
• .axe/skills/
• .claude/skills/
• .codex/skills/

You can also specify other directories with the --skills-dir flag, which skips user-level and project-level skill discovery:

axe --skills-dir /path/to/my-skills

Built-in skills

axe includes the following built-in skills:

• axe-cli-help: axe CLI help. Answers questions about axe installation, configuration, slash commands, keyboard shortcuts, MCP integration, providers, environment variables, and more.
• skill-creator: Guide for creating skills. When you need to create a new skill (or update an existing skill) to extend axe's capabilities, you can use this skill to get detailed creation guidance and best practices.

Creating a skill

Creating a skill only requires two steps:

1. Create a subdirectory in the skills directory
2. Create a SKILL.md file in the subdirectory

Directory structure:

A skill directory needs at least a SKILL.md file, and can also include auxiliary directories to organize more complex content:

~/.config/agents/skills/
└── my-skill/
    ├── SKILL.md          # Required: main file
    ├── scripts/          # Optional: script files
    ├── references/       # Optional: reference documents
    └── assets/           # Optional: other resources

SKILL.md format:

SKILL.md uses YAML frontmatter to define metadata, followed by prompt content in Markdown format:

---
name: code-style
description: My project's code style guidelines
---

## Code Style

In this project, please follow these conventions:

- Use 4-space indentation
- Variable names use camelCase
- Function names use snake_case
- Every function needs a docstring
- Lines should not exceed 100 characters

Frontmatter fields:

Field	Description	Required
name	Skill name, 1-64 characters, only lowercase letters, numbers, and hyphens allowed; defaults to directory name if omitted	No
description	Skill description, 1-1024 characters, explaining the skill's purpose and use cases; shows "No description provided." if omitted	No
license	License name or file reference	No
compatibility	Environment requirements, up to 500 characters	No
metadata	Additional key-value attributes	No

Best practices:

• Keep SKILL.md under 500 lines, move detailed content to scripts/, references/, or assets/ directories
• Use relative paths in SKILL.md to reference other files
• Provide clear step-by-step instructions, input/output examples, and edge case explanations

Example skills

PowerPoint creation:

---
name: pptx
description: Create and edit PowerPoint presentations
---

## PPT Creation Workflow

When creating presentations, follow these steps:

1. Analyze content structure, plan slide outline
2. Choose appropriate color scheme and fonts
3. Use python-pptx library to generate .pptx files

## Design Principles

- Each slide focuses on one topic
- Keep text concise, use bullet points instead of long paragraphs
- Maintain clear visual hierarchy with distinct titles, body, and notes
- Use consistent colors, avoid more than 3 main colors

Python project standards:

---
name: python-project
description: Python project development standards, including code style, testing, and dependency management
---

## Python Development Standards

- Use Python 3.14+
- Use ruff for code formatting and linting
- Use pyright for type checking
- Use pytest for testing
- Use uv for dependency management

Code style:
- Line length limit 100 characters
- Use type annotations
- Public functions need docstrings

Git commit conventions:

---
name: git-commits
description: Git commit message conventions using Conventional Commits format
---

## Git Commit Conventions

Use Conventional Commits format:

type(scope): description

Allowed types: feat, fix, docs, style, refactor, test, chore

Examples:
- feat(auth): add OAuth login support
- fix(api): fix user query returning null
- docs(readme): update installation instructions

Using slash commands to load a skill

The /skill:<name> slash command lets you save commonly used prompt templates as skills and quickly invoke them when needed. When you enter the command, axe reads the corresponding SKILL.md file content and sends it to the Agent as a prompt.

For example:

• /skill:code-style - Load code style guidelines
• /skill:pptx - Load PPT creation workflow
• /skill:git-commits fix user login issue - Load Git commit conventions with an additional task description

You can append additional text after the slash command, which will be added to the skill prompt as the user's specific request.

TIP: For regular conversations, the Agent will automatically decide whether to read skill content based on context, so you don't need to invoke it manually.

Skills allow you to codify your team's best practices and project standards, ensuring the AI always follows consistent standards.

Flow skills

Flow skills are a special skill type that embed an Agent Flow diagram in SKILL.md, used to define multi-step automated workflows. Unlike standard skills, flow skills are invoked via /flow:<name> commands and automatically execute multiple conversation turns following the flow diagram.

Creating a flow skill:

To create a flow skill, set type: flow in the frontmatter and include a Mermaid or D2 code block in the content:

---
name: code-review
description: Code review workflow
type: flow
---

```mermaid
flowchart TD
A([BEGIN]) --> B[Analyze code changes, list all modified files and features]
B --> C{Is code quality acceptable?}
C -->|Yes| D[Generate code review report]
C -->|No| E[List issues and propose improvements]
E --> B
D --> F([END])

**Flow diagram format:**

Both Mermaid and D2 formats are supported:

- **Mermaid**: Use ` ```mermaid ` code block, [Mermaid Playground](https://mermaid.live) can be used for editing and preview
- **D2**: Use ` ```d2 ` code block, [D2 Playground](https://play.d2lang.com) can be used for editing and preview

Flow diagrams must contain one BEGIN node and one END node. Regular node text is sent to the Agent as a prompt; decision nodes require the Agent to output `<choice>branch name</choice>` in the output to select the next step.

**Executing a flow skill:**

Flow skills can be invoked in two ways:

- `/flow:<name>` - Execute the flow. The Agent will start from the BEGIN node and process each node according to the flow diagram definition until reaching the END node
- `/skill:<name>` - Like a standard skill, sends the SKILL.md content to the Agent as a prompt (does not automatically execute the flow)

```bash
# Execute the flow
/flow:code-review

# Load as a standard skill
/skill:code-review

---

Agents and Subagents

An agent defines the AI's behavior, including system prompts, available tools, and subagents. You can use built-in agents or create custom agents.

Built-in agents

axe provides two built-in agents. You can select one at startup with the --agent flag:

axe --agent default

default

The default agent, suitable for general use. Enabled tools:

• Task, SetTodoList, Shell, ReadFile, ReadMediaFile, Glob, Grep, WriteFile, StrReplaceFile
• CodeSearch, CodeContext, CodeStructure, CodeImpact (axe-dig tools)

okabe

An experimental agent for testing new prompts and tools. Adds SendDMail on top of default.

Custom agent files

Agents are defined in YAML format. Load a custom agent with the --agent-file flag:

axe --agent-file /path/to/my-agent.yaml

Basic structure:

version: 1
agent:
  name: my-agent
  system_prompt_path: ./system.md
  tools:
    - "axe_cli.tools.shell:Shell"
    - "axe_cli.tools.file:ReadFile"
    - "axe_cli.tools.file:WriteFile"

Inheritance and overrides:

Use extend to inherit another agent's configuration and only override what you need to change:

version: 1
agent:
  extend: default  # Inherit from default agent
  system_prompt_path: ./my-prompt.md  # Override system prompt
  exclude_tools:  # Exclude certain tools
    - "axe_cli.tools.web:SearchWeb"
    - "axe_cli.tools.web:FetchURL"

extend: default inherits from the built-in default agent. You can also specify a relative path to inherit from another agent file.

Configuration fields:

Field	Description	Required
extend	Agent to inherit from, can be default or a relative path	No
name	Agent name	Yes (optional when inheriting)
system_prompt_path	System prompt file path, relative to agent file	Yes (optional when inheriting)
system_prompt_args	Custom arguments passed to system prompt, merged when inheriting	No
tools	Tool list, format is module:ClassName	Yes (optional when inheriting)
exclude_tools	Tools to exclude	No
subagents	Subagent definitions	No

System prompt built-in parameters

The system prompt file is a Markdown template that can use ${VAR} syntax to reference variables. Built-in variables include:

Variable	Description
${AXE_NOW}	Current time (ISO format)
${AXE_WORK_DIR}	Working directory path
${AXE_WORK_DIR_LS}	Working directory file list
${AXE_AGENTS_MD}	AGENTS.md file content (if exists)
${AXE_SKILLS}	Loaded skills list

You can also define custom parameters via system_prompt_args:

agent:
  system_prompt_args:
    MY_VAR: "custom value"

Then use ${MY_VAR} in the prompt.

System prompt example:

# My Agent

You are a helpful assistant. Current time: ${AXE_NOW}.

Working directory: ${AXE_WORK_DIR}

${MY_VAR}

Defining subagents in agent files

Subagents can handle specific types of tasks. After defining subagents in an agent file, the main agent can launch them via the Task tool:

version: 1
agent:
  extend: default
  subagents:
    coder:
      path: ./coder-sub.yaml
      description: "Handle coding tasks"
    reviewer:
      path: ./reviewer-sub.yaml
      description: "Code review expert"

Subagent files are also standard agent format, typically inheriting from the main agent and excluding certain tools:

# coder-sub.yaml
version: 1
agent:
  extend: ./agent.yaml  # Inherit from main agent
  system_prompt_args:
    ROLE_ADDITIONAL: |
      You are now running as a subagent...
  exclude_tools:
    - "axe_cli.tools.multiagent:Task"  # Exclude Task tool to avoid nesting

How subagents run

Subagents launched via the Task tool run in an isolated context and return results to the main agent when complete. Advantages of this approach:

• Isolated context, avoiding pollution of main agent's conversation history
• Multiple independent tasks can be processed in parallel
• Subagents can have targeted system prompts

Dynamic subagent creation

CreateSubagent is an advanced tool that allows AI to dynamically define new subagent types at runtime (not enabled by default). To use it, add to your agent file:

agent:
  tools:
    - "axe_cli.tools.multiagent:CreateSubagent"

---

Built-in Tools

The following are all built-in tools in axe.

Task

Path: axe_cli.tools.multiagent:Task
Description: Dispatch a subagent to execute a task. Subagents cannot access the main agent's context; all necessary information must be provided in the prompt.

Parameter	Type	Description
description	string	Short task description (3-5 words)
subagent_name	string	Subagent name
prompt	string	Detailed task description

SetTodoList

Path: axe_cli.tools.todo:SetTodoList
Description: Manage todo list, track task progress

Parameter	Type	Description
todos	array	Todo list items
todos[].title	string	Todo item title
todos[].status	string	Status: pending, in_progress, done

Shell

Path: axe_cli.tools.shell:Shell
Description: Execute shell commands. Requires user approval. Uses the appropriate shell for the OS (bash/zsh on Unix, PowerShell on Windows).

Parameter	Type	Description
command	string	Command to execute
timeout	int	Timeout in seconds, default 60, max 300

ReadFile

Path: axe_cli.tools.file:ReadFile
Description: Read text file content. Max 1000 lines per read, max 2000 characters per line. Files outside working directory require absolute paths.

Parameter	Type	Description
path	string	File path
line_offset	int	Starting line number, default 1
n_lines	int	Number of lines to read, default/max 1000

ReadMediaFile

Path: axe_cli.tools.file:ReadMediaFile
Description: Read image or video files. Max file size 100MB. Only available when the model supports image/video input. Files outside working directory require absolute paths.

Parameter	Type	Description
path	string	File path

Glob

Path: axe_cli.tools.file:Glob
Description: Match files and directories by pattern. Returns max 1000 matches, patterns starting with ** not allowed.

Parameter	Type	Description
pattern	string	Glob pattern (e.g., .py, src/**/.ts)
directory	string	Search directory, defaults to working directory
include_dirs	bool	Include directories, default true

Grep

Path: axe_cli.tools.file:Grep
Description: Search file content with regular expressions, based on ripgrep

Parameter	Type	Description
pattern	string	Regular expression pattern
path	string	Search path, defaults to current directory
glob	string	File filter (e.g., *.js)
type	string	File type (e.g., py, js, go)
output_mode	string	Output mode: files_with_matches (default), content, count_matches
-B	int	Show N lines before match
-A	int	Show N lines after match
-C	int	Show N lines before and after match
-n	bool	Show line numbers
-i	bool	Case insensitive
multiline	bool	Enable multiline matching
head_limit	int	Limit output lines

WriteFile

Path: axe_cli.tools.file:WriteFile
Description: Write files. Requires user approval. Absolute paths are required when writing files outside the working directory.

Parameter	Type	Description
path	string	Absolute path
content	string	File content
mode	string	overwrite (default) or append

StrReplaceFile

Path: axe_cli.tools.file:StrReplaceFile
Description: Edit files using string replacement. Requires user approval. Absolute paths are required when editing files outside the working directory.

Parameter	Type	Description
path	string	Absolute path
edit	object/array	Single edit or list of edits
edit.old	string	Original string to replace
edit.new	string	Replacement string
edit.replace_all	bool	Replace all matches, default false

CodeSearch

Path: axe_cli.tools.axe:CodeSearch
Description: Semantic code search powered by axe-dig. Finds code by behavior, not just text matches.

CodeContext

Path: axe_cli.tools.axe:CodeContext
Description: Get LLM-ready function summaries with 95% token savings.

CodeStructure

Path: axe_cli.tools.axe:CodeStructure
Description: Navigate functions and classes in files or directories.

CodeImpact

Path: axe_cli.tools.axe:CodeImpact
Description: Reverse call graph analysis - see who calls a function before refactoring.

Tool security boundaries

Working directory restrictions:

• File reading and writing are typically done within the working directory
• Absolute paths are required when reading files outside the working directory
• Write and edit operations require user approval; absolute paths are required when operating on files outside the working directory

Approval mechanism:

The following operations require user approval:

Operation	Approval required
Shell command execution	Each execution
File write/edit	Each operation
MCP tool calls	Each call

---

Configuration

axe uses configuration files to manage API providers, models, services, and runtime parameters, supporting both TOML and JSON formats.

Config file location

The default configuration file is located at ~/.axe/config.toml. On first run, if the configuration file doesn't exist, axe will automatically create a default configuration file.

You can specify a different configuration file (TOML or JSON format) with the --config-file flag:

axe --config-file /path/to/config.toml

When calling axe programmatically, you can also pass the complete configuration content directly via the --config flag:

axe --config '{"default_model": "claude-sonnet-4", "providers": {...}, "models": {...}}'

Config items

The configuration file contains the following top-level configuration items:

Item	Type	Description
default_model	string	Default model name, must be a model defined in models
default_thinking	boolean	Whether to enable thinking mode by default (defaults to false)
providers	table	API provider configuration
models	table	Model configuration
loop_control	table	Agent loop control parameters
services	table	External service configuration (search, fetch)
mcp	table	MCP client configuration

Complete configuration example:

default_model = "claude-sonnet-4"
default_thinking = false

[providers.anthropic]
type = "anthropic"
base_url = "https://api.anthropic.com/v1"
api_key = "sk-ant-xxx"

[models.claude-sonnet-4]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
max_context_size = 200000

[loop_control]
max_steps_per_turn = 100
max_retries_per_step = 3
max_ralph_iterations = 0
reserved_context_size = 50000

[services.search]
base_url = "https://api.example.com/search"
api_key = "sk-xxx"

[services.fetch]
base_url = "https://api.example.com/fetch"
api_key = "sk-xxx"

[mcp.client]
tool_call_timeout_ms = 60000

providers

providers defines API provider connection information. Each provider uses a unique name as key.

Field	Type	Required	Description
type	string	Yes	Provider type (e.g., anthropic, openai)
base_url	string	Yes	API base URL
api_key	string	Yes	API key
env	table	No	Environment variables to set before creating provider instance
custom_headers	table	No	Custom HTTP headers to attach to requests

Example:

[providers.anthropic]
type = "anthropic"
base_url = "https://api.anthropic.com/v1"
api_key = "sk-ant-xxx"
custom_headers = { "X-Custom-Header" = "value" }

models

models defines available models. Each model uses a unique name as key.

Field	Type	Required	Description
provider	string	Yes	Provider name to use, must be defined in providers
model	string	Yes	Model identifier (model name used in API)
max_context_size	integer	Yes	Maximum context length (in tokens)
capabilities	array	No	Model capability list

Example:

[models.claude-sonnet-4]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
max_context_size = 200000
capabilities = ["thinking", "image_in", "video_in"]

loop_control

loop_control controls agent execution loop behavior.

Field	Type	Default	Description
max_steps_per_turn	integer	100	Maximum steps per turn
max_retries_per_step	integer	3	Maximum retries per step
max_ralph_iterations	integer	0	Extra iterations after each user message; 0 disables; -1 is unlimited
reserved_context_size	integer	50000	Reserved token count for LLM response generation; auto-compaction triggers when context_tokens + reserved_context_size >= max_context_size

services

services configures external services used by axe.

search service:

Configures web search service. When enabled, the SearchWeb tool becomes available.

Field	Type	Required	Description
base_url	string	Yes	Search service API URL
api_key	string	Yes	API key
custom_headers	table	No	Custom HTTP headers to attach to requests

fetch service:

Configures web fetch service. When enabled, the FetchURL tool prioritizes using this service to fetch webpage content.

Field	Type	Required	Description
base_url	string	Yes	Fetch service API URL
api_key	string	Yes	API key
custom_headers	table	No	Custom HTTP headers to attach to requests

mcp

mcp configures MCP client behavior.

Field	Type	Default	Description
client.tool_call_timeout_ms	integer	60000	MCP tool call timeout (milliseconds)

---

Architecture

┌──────────────────────────────────────────────────────────────┐
│                     YOUR CODEBASE                            │
│  100K lines across 500 files                                 │
└───────────────────────┬──────────────────────────────────────┘
                        │
                        ▼
┌──────────────────────────────────────────────────────────────┐
│                    AXE-DIG ENGINE                            │
│  5-layer analysis + semantic embeddings                      │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────┐ │
│  │   AST   │→│  Calls  │→│   CFG   │→│   DFG   │→│  PDG   │ │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └────────┘ │
│                                                              │
│  In-memory daemon: 100ms queries instead of 30s CLI spawns  │
└───────────────────────┬──────────────────────────────────────┘
                        │
                        ▼
┌──────────────────────────────────────────────────────────────┐
│                      AXE AGENT                               │
│  • Understands code semantically (not just text)            │
│  • Extracts minimal context (95% token savings)             │
│  • Executes tools (file ops, shell, multi-agent)            │
│  • Interactive shell UI with Ctrl+X toggle                  │
└──────────────────────────────────────────────────────────────┘

The difference:

• Other tools: Dump 100K lines → Claude figures it out → Burn tokens
• axe: Extract 5K tokens of pure signal → Surgical edits → Save money

---

Workflow examples

Understanding unfamiliar code

# See the structure first
/skill:code-structure src/auth/

# Find specific functionality
/skill:code-search "user session management"

# Get function context
/skill:code-context create_session

Safe refactoring

# Before changing a function, see who calls it
/skill:code-impact validate_token

# Shows:
# - 12 direct callers
# - 3 indirect callers through middleware
# - 8 test files that exercise this function

# Now you know what might break

Debugging

# Find code related to the error
/skill:code-search "handle database connection errors"

# Read the implementation
ReadFile src/db/connection.py

# Make a fix
StrReplaceFile src/db/connection.py "retry_count = 3" "retry_count = 5"

# Toggle to shell and test
[Ctrl+X]
pytest tests/test_db.py
[Ctrl+X]

---

Advanced features

Multi-agent workflows

Spawn subagents for parallel tasks:

# Main agent delegates to specialists
Task "refactor auth module" --agent refactor-specialist
Task "update tests" --agent test-specialist
Task "update docs" --agent docs-specialist

Skills system

Reusable workflows and domain expertise:

# Available skills auto-detected from project
/skill:docker-deploy
/skill:api-design
/skill:performance-optimization

Context management

axe maintains conversation history and can checkpoint/restore:

# Save current context
/checkpoint "before-refactor"

# Restore if things go wrong
/restore "before-refactor"

---

What's coming

Our internal team has been using features that will change the game:

1. Execution tracing

See what actually happened at runtime:

# Trace a failing test
/trace pytest tests/test_auth.py::test_login

# Shows exact values that flowed through each function:
# authenticate(username="alice", password="wrong")
#   → validate_credentials(user=User(id=123), password="wrong")
#     → check_password_hash(hash="$2b$...", password="wrong")
#       → bcrypt.verify() returned False
#       → raised AuthenticationError

2. Performance debugging

# Generate flame graph
/flamegraph run_server.py

# Find memory leaks
/memory-profile background_worker.py

# Both integrated directly in the chat interface

3. Visual debugging

Interactive call graphs, data flow visualizations, and dependency maps—all generated on demand and viewable in your browser.

4. Smart test selection

# Only run tests affected by your changes
/test-impact src/auth/session.py

# Shows: 8 tests need to run (not all 1,247)

---

Why we built this

We're building the world's best retrieval and inference engine. We started with coding because it's the hardest problem: understanding large codebases, tracing execution, debugging logic errors, optimizing performance.

If we can nail code understanding, we can nail anything.

Other tools optimize for demo videos and charging per token. We optimize for engineers shipping production code.

---

Installation

# Install both axe and axe-dig
pip install axe-cli axe-dig

# Or from source
git clone https://github.com/yourusername/axe
cd axe
make prepare
make build

# Run
axe

---

Supported languages

Python, TypeScript, JavaScript, Go, Rust, Java, C, C++, Ruby, PHP, C#, Kotlin, Scala, Swift, Lua, Elixir

Language auto-detected. Specify with --lang if needed.

---

MCP Integration

For AI tools integration, axe supports Model Context Protocol (MCP).

Add to your MCP-compatible tool's configuration:

{
  "mcpServers": {
    "axe-dig": {
      "command": "dig-mcp",
      "args": ["--project", "/path/to/your/project"]
    }
  }
}

---

Community

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Docs: Full documentation

---

License

AGPL-3.0 - See LICENSE file.

---

Comparison

Feature	Claude Code	OpenAI Codex	axe
Built for	Weekend projects	Demos	Production codebases
Context strategy	Dump everything	Dump everything	Extract signal (95% savings)
Code search	Text/regex	Text/regex	Semantic (behavior-based)
Call graph analysis	❌	❌	✅ 5-layer analysis
Token optimization	❌ (incentivized to waste)	❌ (incentivized to waste)	✅ Show savings per query
Execution tracing	❌	❌	✅ Coming soon
Flame graphs	❌	❌	✅ Coming soon
Memory profiling	❌	❌	✅ Coming soon
Shell integration	❌	❌	✅ Ctrl+X toggle
Session management	Limited	Limited	✅ Full history + replay
Skills system	❌	❌	✅ Modular, extensible
Subagents	❌	❌	✅ Parallel task execution
Battle-tested	Public beta	Public API	6 months internal use

---

The bottom line: If you're building real software in large codebases, you need precision tools. Not vibe coding toys.

Welcome to axe.