AGENTS.md · jrswab/axe

Sections

1. What This Is
2. Design Philosophy
3. Non-Obvious Constraints
4. What Good Contributions Look Like
5. Directory Structure
6. Key Entry Points
7. Configuration
8. Repo-Specific Patterns
9. CI/CD
10. Docker
11. Project Docs
12. Custom Instructions

First lines (shown under the repo's Apache-2.0 license)

# Axe — AGENTS.md

## What This Is

A lightweight CLI for running single-purpose LLM agents. Think `make` for AI — define agents in TOML, give them focused context via SKILL.md files, and trigger them from anywhere (cron, git hooks, pipes, file watchers).

## Design Philosophy

- **Small context windows by design.** Each agent gets only what it needs. Sub-agents return results, not conversations. This is the core value prop — fight context bloat at every level.
- **Unix citizen.** Stdout is clean and pipeable. Debug goes to stderr. Exit codes are meaningful. Stdin is always accepted. Axe composes with existing tools, it doesn't replace them.
- **Executor, not scheduler.** Axe runs agents. Triggering is the user's job (cron, entr, git hooks, webhooks). No built-in daemon, no watch mode, no event loop.
- **Single binary, zero runtime.** Go. No interpreters, no node_modules, no Docker required. `go build` and ship.
- **Config over code.** Agent definitions are TOML, not Go. Users should never touch source to define or modify agents.

## Non-Obvious Constraints

- **SKILL.md is a community format** — not invented here. Treat it as an external standard. Don't add axe-specific extensions to the format itself; put axe-specific config in TOML.
- **models.dev format for model strings** — always `provider/model-name`. Don't invent a custom format.
- **XDG Base Directory spec** — config, data, and cache go where XDG says. No dotfiles in $HOME.
- **Sub-agents are opaque to parents.** A parent never sees a sub-agent's internal turns, tool calls, or files. Only the final text result crosses the boundary. This is intentional — don't leak internals upward.
- **Depth limits are safety rails, not features.** Default 3, hard max 5. If someone needs more depth, the design is wrong, not the limit.

## What Good Contributions Look Like

- Tests for every new package (table-driven, no mocks when avoidable — use the real thing or `testutil` helpers)
- Errors that help the user fix the problem, not just describe it
- No global state — pass dependencies explicitly
- Flags override TOML overrides defaults. Resolution order matters everywhere.
- When in doubt, print nothing. Axe output MUST be safe to pipe.

## Directory Structure

```text
axe/
├── cmd/                    # CLI commands (run, agents, config, gc, version)
├── internal/
│   ├── agent/             # Agent TOML loading and validation
│   ├── config/            # Global config.toml handling
│   ├── envinterp/         # ${VAR} expansion for MCP headers
│   ├── mcpclient/         # Model Context Protocol client
│   ├── memory/            # Persistent memory system
│   ├── provider/          # LLM provider implementations (Anthropic, OpenAI, Ollama, OpenCode, Bedrock)
│   ├── refusal/           # LLM refusal detection
│   ├── resolve/           # Context resolution (workdir, skill, files, stdin)
│   ├── testutil/          # Test helpers and mock servers
│   ├── tool/              # Built-in tools (file ops, shell, web)
│   ├── toolname/          # Tool name constants
│   └── xdg/               # XDG Base Directory support
├── docs/
│   ├── design/            # Architecture docs
│   └── plans/             # Implementation specs
├── examples/              # Example agents (code-reviewer, commit-msg, summarizer)
└── main.go
```

## Key Entry Points

### CLI Commands (`cmd/`)

- **run.go** - Main execution: loads agent, resolves context, calls provider, handles conversation loop (`max_turns`, default 50), executes tools (parallel by default), manages memory
- **agents.go** - Agent management: list, show, init (scaffold), edit (opens $EDITOR)
- **config.go** - Config init (creates XDG dirs, embeds sample skill), path display
- **gc.go** - Memory garbage collection with LLM-assisted pattern detection or fallback to max_entries
- **root.go** - Root command, exit code mapping (0=success, 1=runtime error, 2=config error)

### Core Packages

- **internal/agent** - `Load()` parses TOML, `Validate()` checks required fields and constraints, `Scaffold()` generates template
- **internal/provider** - `Provider` interface with `Send(ctx, Request) (Response, error)`. Implementations: Anthropic (messages API), OpenAI (chat completions), Ollama (local), OpenCode (multi-route: Claude/messages, GPT/responses, others/chat/completions), Bedrock (AWS Converse API)
- **internal/tool** - Registry pattern. Built-in tools: list_directory, read_file (with pagination), write_file, edit_file (find/replace), run_command (via sh -c), url_fetch (HTML stripping), web_search, call_agent (sub-agent delegation). All file tools sandboxed to workdir.
- **internal/resolve** - Resolution order: flags > TOML > env vars > defaults. Handles tilde/env var expansion, glob patterns (simple and **), binary file detection, symlink escape prevention.
- **internal/memory** - Timestamped markdown entries. `AppendEntry()` adds task/result, `LoadEntries()` loads last N, `TrimEntries()` keeps last N, `CountEntries()` returns total.
- **internal/mcpclient** - MCP client for stdio/HTTP transports. `Connect()`, `ListTools()`, `CallTool()`. Router manages multiple servers, namespaces tools by server name.

## Configuration

### Agent TOML (`$XDG_CONFIG_HOME/axe/agents/*.toml`)

```toml
name = "agent-name"              # Required
model = "provider/model-name"    # Required (e.g., anthropic/claude-sonnet-4-20250514)
description = "..."              # Optional
system_prompt = "..."            # Optional
skill = "path/to/SKILL.md"       # Optional (absolute, relative to config dir, or bare name)
files = ["**/*.go", "README.md"] # Optional (glob patterns)
workdir = "/path/to/dir"         # Optional (default: cwd, supports ~ and $VAR)
max_turns = 75                # Optional (default: 50 when unset)
tools = ["read_file", "write_file"] # Optional (valid: list_directory, read_file, write_file, edit_file, run_command, url_fetch, web_search)
sub_agents = ["agent1", "agent2"] # Optional (allowed sub-agent names)

[sub_agents_config]
max_depth = 3    # Default: 3, Max: 5
parallel = true  # Default: true (run sub-agents concurrently)
timeout = 120    # Default: 120 seconds

[memory]
enabled = true       # Default: false
last_n = 10          # Default: 10 (load last N entries into context)
max_entries = 100    # Default: 100 (warn when exceeded)
path = "/custom/path" # Optional (default: $XDG_DATA_HOME/axe/memory/{agent-name}.md)

[params]
temperature = 0.7  # Optional (OpenAI/Atlas Cloud send explicit 0)
reasoning_effort = "low" # Optional (OpenAI/Atlas Cloud only, no value validation)
max_tokens = 4096  # Default: 0 (provider default)

[artifacts]
enabled = true
dir = "output"
default_write = true  # When true, write_file without explicit artifact arg writes to artifact dir

[[mcp_servers]]
name = "server-name"
transport = "stdio"  # or "http", "https"
command = "/path/to/server"
args = ["--flag"]
env = {"KEY" = "value"}

[[mcp_servers]]
name = "http-server"
transport = "https"
url = "https://example.com/mcp"
headers = {"Authorization" = "Bearer ${API_KEY}"}  # ${VAR} expanded from env
```

### Global Config (`$XDG_CONFIG_HOME/axe/config.toml`)

```toml
[providers.anthropic]
api_key = "sk-ant-..."
base_url = "https://api.anthropic.com"

[providers.openai]
api_key = "sk-..."
base_url = "https://api.openai.com"

[providers.ollama]
base_url = "http://localhost:11434"

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

**Env vars override config file:**
- `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`
- `AXE_ANTHROPIC_BASE_URL`, `AXE_OPENAI_BASE_URL`, `AXE_OLLAMA_BASE_URL`, `AXE_OPENCODE_BASE_URL`
- `AWS_REGION`, `AWS_DEFAULT_REGION` (for Bedrock)
- `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` (for Bedrock)
- `TAVILY_API_KEY` (overrides config for web search API key), `AXE_WEB_SEARCH_BASE_URL`

## Repo-Specific Patterns

### Testing

- **Table-driven tests** - See any `*_test.go` for examples. Use `[]struct{name, input, want}` pattern.
- **Mock servers** - `internal/testutil/mockserver.go` provides `NewMockLLMServer()` for Anthropic/OpenAI responses. Use in integration tests.
- **Golden files** - `cmd/golden_test.go` and `cmd/testdata/golden/` for CLI output testing. Update with `UPDATE_GOLDEN=1 go test`.
- **Fixtures** - `cmd/testdata/agents/` and `cmd/testdata/skills/` for test data. Use `testutil.SeedFixtureAgents()` and `testutil.SeedFixtureSkills()`.
- **Integration tests** - `cmd/run_integration_test.go` and `cmd/run_mcp_integration_test.go` compile binary and run end-to-end tests.
- **Smoke tests** - `cmd/smoke_test.go` runs actual binary with real config (requires API keys in CI).