axe

Axe provides several capabilities for managing and executing LLM agents:

• Multi-provider support: Anthropic, OpenAI, Ollama (local), OpenCode, and AWS Bedrock.
• Agent Configuration: Declarative, version-controllable definitions using TOML.
• Sub-agent delegation: Agents can call other agents via LLM tool use (supports depth limiting and parallel execution).
• Persistent memory: Uses timestamped markdown logs to carry context across runs, with LLM-assisted garbage collection.
• Skill system: Reusable instruction sets shared across agents.
• Unix-style integration: Supports stdin piping (e.g., git diff | axe run reviewer) and provides structured JSON output for scripting.
• Tooling: Built-in sandboxed file operations, shell execution, URL fetching, and web search (with SSRF protection via output allowlists).
• MCP support: Connects to external Model Context Protocol (MCP) servers via SSE or streamable-HTTP.
• Execution controls: Token budgets via [budget] config or --max-tokens flag, and configurable retry logic for transient provider errors.

When an agent run exceeds the configured max_tokens budget, the following behavior occurs:

1. Enforcement Timing: The budget is checked before each LLM call. If a call pushes the total usage over the limit, that call is allowed to complete, its tokens are recorded, and then the execution stops. Consequently, actual usage may slightly exceed the limit by the amount of the final response.
2. Partial Results: The agent will return the last successful LLM response generated before the limit was hit, preserving any work completed so far.
3. Warnings: A budget-exceeded warning is printed to stderr.
4. Exit Code: The process exits with exit code 4, which specifically indicates that the budget was exhausted. This is distinct from other error codes:
   • 0: Success
   • 1: Runtime error
   • 2: Config error
   • 3: Transient provider error
   • 4: Budget exceeded

Agents in Axe are configured using TOML files located in the <config_dir>/agents/ directory. Each file must be named <name>.toml and corresponds to an agent identifier.

Required Fields

• name: The agent identifier (must match the filename).
• model: A provider/model string following the models.dev format (e.g., anthropic/claude-sonnet-4-20250514).

Optional Fields

• description: A human-readable description.
• system_prompt: The agent's persona or instructions.
• skill: A relative path to a SKILL.md file.
• files: A list of glob patterns for context files.
• workdir: The working directory used for glob resolution.
• sub_agents: A list of names of other agents this agent can invoke.
• [memory]: Sub-configuration for persistent memory:
  • enabled: Boolean to enable memory.
  • path: Custom directory for memory storage.
• [params]: Model parameter overrides:
  • temperature: Float (0 means provider default).
  • max_tokens: Integer (0 means provider default).

name = "my-agent"
description = "A helpful assistant"
model = "anthropic/claude-sonnet-4-20250514"
system_prompt = "You are a helpful assistant."

# Context files - glob patterns resolved from workdir or cwd
files = ["src/**/*.go", "README.md"]

[memory]
enabled = true
path = "~/.axe/memory/my-agent"

[params]
temperature = 0.3
max_tokens = 4096

The OpenAI provider maps Server-Sent Events (SSE) from the /chat/completions endpoint into a sequence of StreamEvent types. The mapping logic handles text deltas, tool calls, and usage data.

When using sub-agents, the allowed_hosts configuration follows an inheritance with explicit override model. This allows you to control the security boundaries of your agent hierarchy recursively.

Inheritance Rules:

1. Explicit Override: If a sub-agent's TOML defines its own allowed_hosts list, that list is used exclusively for that sub-agent. It does not merge with the parent's list.
2. Inheritance: If a sub-agent's TOML does not define allowed_hosts (or it is empty), it inherits the effective allowlist from its parent.
3. Recursive Propagation: This rule applies at every level of the tree. A sub-agent's effective list (whether inherited or explicit) becomes the fallback for any sub-sub-agents it invokes.

Security Implications:

• A sub-agent can be more restrictive than its parent by defining a subset of hosts.
• A sub-agent can be less restrictive than its parent by defining a different or wider set of hosts (this is treated as an explicit operator decision).