Axe

https://docs.getaxe.dev
Admin
Axe is a Unix-like CLI tool that orchestrates LLM-powered agents defined via TOML configuration,...
Tokens:14,814
Snippets:142
Trust Score:1.9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Use Example Axe Agents

Source: https://docs.getaxe.dev/getting-started/quick-start.html

Shows how to copy and use pre-built example agents from the examples directory. This includes setting API keys and running agents like a code reviewer.

```bash
# Copy an example agent into your config
cp examples/code-reviewer/code-reviewer.toml "$(axe config path)/agents/"
cp -r examples/code-reviewer/skills/ "$(axe config path)/skills/"

# Set your API key and run
export ANTHROPIC_API_KEY="your-key-here"
git diff | axe run code-reviewer
```

--------------------------------

### Install Axe CLI using Go

Source: https://docs.getaxe.dev/getting-started/installation.html

Installs the latest version of the Axe CLI using the Go package manager. Ensure Go 1.25+ is installed.

```bash
go install github.com/jrswab/axe@latest
```

--------------------------------

### Start Ollama and Axe Agent Services

Source: https://docs.getaxe.dev/docker/compose.html

Starts the Ollama service using a specific profile and subsequently runs the Axe agent. This is the recommended approach for local model execution.

```bash
docker compose --profile ollama up -d ollama
docker compose --profile cli run --rm axe run my-agent
```

--------------------------------

### Enable Axe Agent Tools

Source: https://docs.getaxe.dev/tools/built-in.html

This snippet shows how to enable specific tools for an Axe agent. Tools are added to the agent's 'tools' field to allow the LLM to interact with the environment through these functionalities. The example lists 'read_file', 'list_directory', and 'run_command' as available tools.

```python
tools = ["read_file", "list_directory", "run_command"]
```

--------------------------------

### Configure provider credentials in config.toml

Source: https://docs.getaxe.dev/providers.html

Example configuration for setting API keys and base URLs for various AI providers within the Axe config.toml file. This file is located at $XDG_CONFIG_HOME/axe/config.toml and allows for centralized management of provider settings.

```toml
[providers.anthropic]
api_key = "sk-ant-..."

[providers.google]
api_key = "AIza..."

[providers.minimax]
api_key = "..."

[providers.openai]
api_key = "sk-..."
base_url = "https://your-openai-proxy.example.com"

[providers.bedrock]
region = "us-east-1"
```

--------------------------------

### Configure Agent Retry Settings in TOML

Source: https://docs.getaxe.dev/configuration/retry.html

Example configuration for enabling and customizing retry behavior in an Axe agent. This snippet demonstrates setting the maximum number of retries, the backoff strategy, and the timing delays for transient error recovery.

```toml
[retry]
max_retries = 3
backoff = "exponential"
initial_delay_ms = 500
max_delay_ms = 30000
```

--------------------------------

### Initialize Axe Configuration Directory

Source: https://docs.getaxe.dev/getting-started/installation.html

Initializes the Axe configuration directory structure and creates a sample skill and default config.toml. The directory is created at `$XDG_CONFIG_HOME/axe/`.

```bash
axe config init
```

--------------------------------

### Configure Token Budget via TOML and CLI

Source: https://docs.getaxe.dev/configuration/token-budget.html

Demonstrates how to define a maximum token limit in a TOML configuration file and how to override it using the command-line interface. The CLI flag takes precedence over the configuration file value.

```toml
[budget]
max_tokens = 50000   # 0 = unlimited (default)
```

```bash
axe run my-agent --max-tokens 10000
```

--------------------------------

### Execute Agent with Inline Prompt

Source: https://docs.getaxe.dev/print.html

Demonstrates how to run an agent using the --prompt flag to provide an inline instruction. This command takes precedence over piped stdin.

```bash
axe run my-agent -p "Summarize the README"
```

--------------------------------

### Initialize a New Axe Agent

Source: https://docs.getaxe.dev/getting-started/quick-start.html

Creates a new agent configuration for Axe. This command is used to set up a new agent with a specified name.

```bash
axe agents init my-agent
```

--------------------------------

### Clone and Build Axe CLI from Source

Source: https://docs.getaxe.dev/getting-started/installation.html

Clones the Axe repository from GitHub and builds the executable locally. This method requires Git and Go 1.25+.

```bash
git clone https://github.com/jrswab/axe.git
cd axe
go build .
```

--------------------------------

### Agent Tool Execution

Source: https://docs.getaxe.dev/tools/built-in.html

Overview of how to enable and interact with the Axe agent's toolset.

```APIDOC
## POST /agent/tools

### Description
Enables specific tools for the agent to use during its conversation loop. Tools allow the agent to perform file operations, execute commands, or search the web.

### Method
POST

### Endpoint
/agent/tools

### Parameters
#### Request Body
- **tools** (array) - Required - A list of tool names to enable (e.g., ["read_file", "run_command", "web_search"])
- **parallel** (boolean) - Optional - Set to false to disable concurrent tool execution

### Request Example
{
  "tools": ["read_file", "write_file", "run_command"],
  "parallel": true
}

### Response
#### Success Response (200)
- **status** (string) - Confirmation of tool initialization

#### Response Example
{
  "status": "success",
  "enabled_tools": ["read_file", "write_file", "run_command"]
}
```

--------------------------------

### Pipe Input to Axe Agents

Source: https://docs.getaxe.dev/getting-started/quick-start.html

Demonstrates piping output from other command-line tools into Axe agents. This allows for flexible data processing workflows.

```bash
git diff --cached | axe run pr-reviewer
cat error.log | axe run log-analyzer
```

--------------------------------

### Axe CLI Commands

Source: https://docs.getaxe.dev/print.html

Lists common Axe command-line interface commands and their descriptions. These commands cover agent management, configuration, and execution.

```bash
Command| Description  
---|---
`axe run <agent>`| Run an agent  
`axe agents list`| List all configured agents  
`axe agents show <agent>`| Display an agent’s full configuration  
`axe agents init <agent>`| Scaffold a new agent TOML file  
`axe agents edit <agent>`| Open an agent TOML in `$EDITOR`  
`axe config path`| Print the configuration directory path  
`axe config init`| Initialize the config directory with defaults  
`axe gc <agent>`| Run memory garbage collection for an agent  
`axe gc --all`| Run GC on all memory-enabled agents  
`axe version`| Print the current version  
```

--------------------------------

### Correct vs. Incorrect Script Path Usage in SKILL.md

Source: https://docs.getaxe.dev/print.html

Demonstrates the correct and incorrect ways to specify script paths within a `SKILL.md` file. Absolute paths are required for helper scripts executed by `run_command` because the execution context is the agent's working directory, not the skill directory.

```shell
# Correct — absolute path
/home/user/.config/axe/skills/my-skill/scripts/fetch.sh <args>

# Wrong — relative path won't resolve from the agent's workdir
scripts/fetch.sh <args>
```

--------------------------------

### File System Operations

Source: https://docs.getaxe.dev/tools/built-in.html

Details on sandboxed file system tools including reading, writing, and editing files.

```APIDOC
## POST /tools/file/{operation}

### Description
Perform sandboxed file system operations. All operations are restricted to the agent's working directory.

### Method
POST

### Endpoint
/tools/file/{operation}

### Parameters
#### Path Parameters
- **operation** (string) - Required - One of: list_directory, read_file, write_file, edit_file

#### Request Body
- **path** (string) - Required - Relative path to the target file or directory
- **content** (string) - Optional - Required for write_file/edit_file

### Response
#### Success Response (200)
- **output** (string) - The result of the file operation (truncated to 1024 bytes if necessary)

#### Response Example
{
  "output": "file content or directory listing..."
}
```

--------------------------------

### Configure Host-based Ollama Connectivity

Source: https://docs.getaxe.dev/docker/compose.html

Environment variables and Docker flags required to connect the Axe container to an Ollama instance running directly on the host machine.

```bash
# Linux
--add-host=host.docker.internal:host-gateway -e AXE_OLLAMA_BASE_URL=http://host.docker.internal:11434

# macOS / Windows (Docker Desktop)
-e AXE_OLLAMA_BASE_URL=http://host.docker.internal:11434
```

--------------------------------

### Directory Structure for Axe Skills

Source: https://docs.getaxe.dev/print.html

Provides a visual representation of the expected directory structure for organizing Axe configuration files, agents, and skills. This includes the main configuration file, agent definitions, and skill components like `SKILL.md` and helper scripts.

```tree
$XDG_CONFIG_HOME/axe/
├── config.toml
├── agents/
│   └── my-agent.toml
└── skills/
    └── my-skill/
        ├── SKILL.md
        └── scripts/
            └── fetch.sh
```

--------------------------------

### Run an Axe Agent

Source: https://docs.getaxe.dev/getting-started/quick-start.html

Executes a specified Axe agent. This command can take input from standard input (stdin) for processing.

```bash
axe run my-agent
```

--------------------------------

### Project-Local Agent Directory Structure

Source: https://docs.getaxe.dev/local-agents.html

Illustrates the expected file structure for project-local Axe agent configurations. Axe automatically discovers agents in the 'axe/agents/' subdirectory of the current working directory.

```file structure
my-project/
└── axe/
    └── agents/
        └── my-agent.toml   ← found automatically
```

--------------------------------

### Configure Stdio MCP Server in TOML

Source: https://docs.getaxe.dev/tools/mcp.html

Defines a local MCP server using the stdio transport protocol. This requires specifying the command path and any necessary arguments for the local process.

```toml
[[mcp_servers]]
name = "filesystem"
transport = "stdio"
command = "/usr/local/bin/mcp-server-filesystem"
args = ["--root", "/home/user/projects"]
```

--------------------------------

### Refusal Detection

Source: https://docs.getaxe.dev/print.html

Explains how Axe detects LLM refusals to complete tasks, the patterns it looks for, and the limitations of this heuristic detection, which is active only with the `--json` flag.

```APIDOC
## Refusal Detection

### Description
Details the heuristic mechanism Axe uses to detect when an LLM declines to complete a task, indicated by the `refused` field in the JSON output.

### Detection Mechanism
Refusal detection is heuristic and scans the response content for phrases indicating refusal, such as:
  * "I cannot", "I can't"
  * "I’m unable to", "I am unable to"
  * "I’m not able to", "I am not able to"
  * "I must decline"
  * "I don’t have the ability", "I do not have the ability"
  * "as an AI" combined with limiting language

### Activation
Refusal detection is only active when the `--json` output flag is used.

### Example Usage
```bash
axe run my-agent --json | jq '.refused'
```

### Limitations
This detection is a lightweight signal for scripting and observability and is not exhaustive. Unusual phrasing of refusal may not be detected. It does not guarantee detection of all refusals.
```

--------------------------------

### Run Axe Agent with Docker Compose

Source: https://docs.getaxe.dev/docker/compose.html

Executes the Axe agent using a predefined Docker Compose service. This command assumes the environment is already configured for the agent.

```bash
docker compose run --rm axe run my-agent
```

--------------------------------

### Using --agents-dir Flag with Axe CLI

Source: https://docs.getaxe.dev/local-agents.html

Demonstrates how to specify a custom directory for Axe agents using the --agents-dir flag. This flag can be used with various Axe commands to override the default agent loading paths.

```bash
axe run my-agent --agents-dir ./custom/agents
```

--------------------------------

### Check Refusal Status via CLI

Source: https://docs.getaxe.dev/print.html

Demonstrates how to pipe the JSON output of an Axe command into jq to extract the refusal status for automated monitoring.

```bash
axe run my-agent --json | jq '.refused'
```

--------------------------------

### Axe CLI Flags

Source: https://docs.getaxe.dev/print.html

This section details the various command-line flags available for the Axe CLI, allowing users to customize model, skill, working directory, timeout, token usage, verbosity, and prompt handling.

```APIDOC
## CLI Flags

### Description
Flags to customize the behavior of the `axe run` command.

### Parameters
#### Query Parameters
- **`--model`** (string) - Optional - Override the model provider and name (e.g., `anthropic/claude-sonnet-4-20250514`). Defaults to the value specified in the TOML configuration.
- **`--skill`** (path) - Optional - Override the skill file path. Defaults to the value specified in the TOML configuration.
- **`--workdir`** (path) - Optional - Override the working directory. Defaults to the current working directory or the value specified in the TOML configuration.
- **`--timeout`** (seconds) - Optional - Set the request timeout in seconds. Defaults to `120`.
- **`--max-tokens`** (int) - Optional - Cap the cumulative token usage for the run. If exceeded, the command exits with code 4. Defaults to `0` (unlimited).
- **`--dry-run`** - Optional - If set, shows the resolved context without actually calling the LLM.
- **`--verbose`** / **`-v`** - Optional - If set, prints debug information (model, timing, tokens, retries) to stderr. Defaults to `false`.
- **`--json`** - Optional - If set, wraps the output in a JSON envelope with metadata. Defaults to `false`.
- **`-p`** / **`--prompt`** (string) - Optional - An inline prompt to be used as the user message. This flag takes precedence over piped stdin. If absent or empty/whitespace-only, piped stdin is used, falling back to a default message if neither is available.
```

--------------------------------

### Axe Tool Call Details Schema

Source: https://docs.getaxe.dev/cli/json-output.html

This schema details the structure of each entry within the `tool_call_details` array in the JSON output. It provides information about individual tool invocations, including their name, input arguments, output, and whether an error occurred.

```json
{
  "name": "read_file",
  "input": { "path": "main.go" },
  "output": "package main\n...",
  "is_error": false
}
```

--------------------------------

### Configure SSE MCP Server in TOML

Source: https://docs.getaxe.dev/tools/mcp.html

Defines an MCP server using the Server-Sent Events (SSE) transport protocol. It includes authentication headers with environment variable interpolation.

```toml
[[mcp_servers]]
name = "my-tools"
url = "https://my-mcp-server.example.com/sse"
transport = "sse"
headers = { Authorization = "Bearer ${MY_TOKEN}" }
```

--------------------------------

### Skill Path Resolution in Agent TOML

Source: https://docs.getaxe.dev/print.html

Explains the order in which Axe resolves skill paths specified in an agent's TOML configuration. It prioritizes absolute paths, then paths relative to the config directory, and finally bare skill names.

```toml
# Example of a skill path in agent TOML
skill = "skills/code-review/SKILL.md"
```

--------------------------------

### Set Agent Token Budget

Source: https://docs.getaxe.dev/print.html

Configuration for limiting total token usage for an agent run. This can be set in the TOML file or overridden via command-line flags.

```toml
[budget]
max_tokens = 50000
```

```bash
axe run my-agent --max-tokens 10000
```

--------------------------------

### Edit an Existing Axe Agent

Source: https://docs.getaxe.dev/getting-started/quick-start.html

Opens the configuration file for an existing Axe agent in the default editor, allowing for modifications. Use this to update agent settings.

```bash
axe agents edit my-agent
```

--------------------------------

### User Message Resolution

Source: https://docs.getaxe.dev/print.html

Explains the order in which the user message is determined when using the Axe CLI, prioritizing the `--prompt` flag, then piped stdin, and finally a default message.

```APIDOC
## User Message Resolution

### Description
Determines the user message sent to the LLM based on the presence of the `--prompt` flag and piped stdin.

### Order of Precedence
1. **`-p`/`--prompt` flag**: If provided with a non-empty, non-whitespace value, it is used as the user message.
2. **Piped stdin**: If `-p` is absent or empty/whitespace-only, piped stdin is used.
3. **Built-in default**: If neither `-p` nor stdin provides content, the default message `"Execute the task described in your instructions."` is used.

**Note**: When `-p` is provided alongside piped stdin, the piped stdin is silently ignored. An empty or whitespace-only `-p` value is treated as absent and falls through to stdin, then the default.
```

--------------------------------

### Run Axe Agent with JSON Output

Source: https://docs.getaxe.dev/cli/json-output.html

The `--json` flag enables the agent's output to be wrapped in a JSON envelope. This is useful for scripting and observability, providing structured data about the agent's execution.

```bash
axe run my-agent --json
```

--------------------------------

### Retry Configuration for Transient Errors

Source: https://docs.getaxe.dev/configuration/retry.html

This section details how to configure the retry mechanism for agents to handle transient errors from LLM providers, such as rate limits (429), server errors (5xx), and timeouts. Retries are opt-in and disabled by default.

```APIDOC
## Retry Configuration for Transient Errors

### Description
Agents can retry on transient LLM provider errors — rate limits (429), server errors (5xx), and timeouts. Retry is opt-in and disabled by default.

### Method
N/A (Configuration settings)

### Endpoint
N/A (Configuration settings)

### Parameters
#### Configuration Fields
- **`max_retries`** (integer) - Optional - Number of retry attempts after the initial request. 0 disables retry.
- **`backoff`** (string) - Optional - Strategy: `"exponential"` (with jitter), `"linear"`, or `"fixed"`. Defaults to `"exponential"`.
- **`initial_delay_ms`** (integer) - Optional - Base delay in milliseconds before the first retry. Defaults to 500.
- **`max_delay_ms`** (integer) - Optional - Maximum delay cap in milliseconds. Defaults to 30000.

**Note:** Only transient errors are retried. Authentication errors (401/403) and bad requests (400) are never retried.

When `--verbose` is enabled, each retry attempt is logged to stderr. The `--json` envelope includes a `retry_attempts` field for observability.

### Configuration Example (TOML format)
```toml
[retry]
max_retries = 3
backoff = "exponential"
initial_delay_ms = 500
max_delay_ms = 30000
```

### Response
N/A (Configuration settings)
```

--------------------------------

### Axe JSON Output Schema

Source: https://docs.getaxe.dev/cli/json-output.html

This schema describes the structure of the JSON output when using the `--json` flag. It includes the agent's text response, token usage, tool call statistics, and refusal detection status.

```json
{
  "output": "Here is the summary...",
  "output_tokens": 312,
  "tool_calls": 2,
  "tool_call_details": [
    {
      "name": "read_file",
      "input": { "path": "main.go" },
      "output": "package main\n...",
      "is_error": false
    },
    {
      "name": "run_command",
      "input": { "command": "go test ./..." },
      "output": "ok  \tgithub.com/jrswab/axe\t0.42s",
      "is_error": false
    }
  ],
  "refused": false,
  "retry_attempts": 0
}
```

--------------------------------

### JSON Output Structure

Source: https://docs.getaxe.dev/print.html

Details the structure of the JSON output envelope generated when the `--json` flag is used, including fields for output, token usage, tool calls, and refusal detection.

```APIDOC
## JSON Output Structure

### Description
The `--json` flag wraps the agent’s output in a JSON envelope with metadata for scripting and observability.

### Fields
- **`output`** (string) - The agent’s text response.
- **`output_tokens`** (int) - Total output tokens across all turns.
- **`tool_calls`** (int) - Total number of tool calls made.
- **`tool_call_details`** (array) - Per-call details for each tool invocation.
  - **`name`** (string) - Tool name (e.g., `read_file`, `run_command`).
  - **`input`** (object) - Arguments passed to the tool.
  - **`output`** (string) - Tool output, truncated to 1024 bytes.
  - **`is_error`** (bool) - Whether the tool call resulted in an error.
- **`refused`** (bool) - Whether refusal was detected in the response.
- **`retry_attempts`** (int) - Number of retries that occurred.
- **`budget_max_tokens`** (int) - Token budget cap (only present when a budget is set).
- **`budget_used_tokens`** (int) - Cumulative tokens used (only present when a budget is set).
- **`budget_exceeded`** (bool) - Whether the budget was exceeded (only present when a budget is set).

### Example Response
```json
{
  "output": "Here is the summary...",
  "output_tokens": 312,
  "tool_calls": 2,
  "tool_call_details": [
    {
      "name": "read_file",
      "input": { "path": "main.go" },
      "output": "package main\n...",
      "is_error": false
    },
    {
      "name": "run_command",
      "input": { "command": "go test ./..." },
      "output": "ok  \tgithub.com/jrswab/axe\t0.42s",
      "is_error": false
    }
  ],
  "refused": false,
  "retry_attempts": 0
}
```
```

--------------------------------

### Pull Ollama Models

Source: https://docs.getaxe.dev/docker/compose.html

Uses the Docker Compose exec command to pull a specific model (e.g., llama3) into the running Ollama container.

```bash
docker compose --profile ollama exec ollama ollama pull llama3
```

--------------------------------

### Define Axe Agent Configuration in TOML

Source: https://docs.getaxe.dev/configuration/agent-config.html

This TOML configuration defines an agent's identity, operational parameters, and tool integrations. It supports advanced features like sub-agent orchestration, memory management, and MCP server connections.

```toml
name = "pr-reviewer"
description = "Reviews pull requests for issues and improvements"
model = "anthropic/claude-sonnet-4-20250514"
system_prompt = "You are a senior code reviewer. Be concise and actionable."
skill = "skills/code-review/SKILL.md"
files = ["src/**/*.go", "CONTRIBUTING.md"]
workdir = "/home/user/projects/myapp"
tools = ["read_file", "list_directory", "run_command"]
sub_agents = ["test-runner", "lint-checker"]
allowed_hosts = ["api.example.com", "docs.example.com"]

[sub_agents_config]
max_depth = 3
parallel = true
timeout = 120

[memory]
enabled = true
last_n = 10
max_entries = 100

[[mcp_servers]]
name = "my-tools"
url = "https://my-mcp-server.example.com/sse"
transport = "sse"
headers = { Authorization = "Bearer ${MY_TOKEN}" }

[params]
temperature = 0.3
max_tokens = 4096

[budget]
max_tokens = 50000

[retry]
max_retries = 3
backoff = "exponential"
initial_delay_ms = 500
max_delay_ms = 30000

[[mcp_servers]]
name = "filesystem"
transport = "stdio"
command = "/usr/local/bin/mcp-server-filesystem"
args = ["--root", "/home/user/projects"]
```

--------------------------------

### Axe Exit Codes

Source: https://docs.getaxe.dev/print.html

Lists and explains the meaning of the different exit codes returned by the Axe CLI, indicating success or various types of errors.

```APIDOC
## Exit Codes

### Description
Meaning of the exit codes returned by the Axe CLI.

### Codes
- **`0`**: Success
- **`1`**: Runtime error
- **`2`**: Configuration error
- **`3`**: Provider/network error
- **`4`**: Token budget exceeded
```

--------------------------------

### Configure allowed_hosts for Axe Agents

Source: https://docs.getaxe.dev/configuration/output-allowlist.html

Defines the allowed_hosts configuration variable to restrict agent network requests to a specific list of domains. This setting ensures that agents only interact with trusted hostnames, while automatically blocking private IP addresses and validating redirect targets.

```toml
allowed_hosts = ["api.example.com", "docs.example.com"]
```
Tokens:
Raw