jrswab/axe

Axe – A Unix‑style CLI for LLM‑powered agents

What it is – Axe is a command‑line program (written in Go) that lets you define agents – small, single‑purpose LLM workflows – in declarative TOML files and run them from the terminal or inside scripts. Think of each agent as a tiny Unix utility that talks to an LLM, can call built‑in tools (read/write files, run shell commands, fetch URLs, web‑search) and even delegate work to other agents.

Why it matters – Most existing LLM wrappers assume you want a long‑running chatbot with a huge context window. Axe flips that model: agents are focused, composable, and stateless unless you explicitly enable persistent memory. Because it works like any other CLI, you can pipe data into an agent (git diff | axe run pr‑reviewer), schedule it with cron, trigger it from CI, or chain several agents together with standard Unix pipelines.

---

Core concepts

Concept	What it does
Agent definition	A TOML file ($XDG_CONFIG_HOME/axe/agents/*.toml) that specifies the model, system prompt, a skill (a Markdown instruction file), optional tools, sub‑agents, memory settings, token budget, retry policy, etc.
Skill	Reusable SKILL.md instruction set that tells the LLM how to perform the task. Skills are looked up relative to the Axe config directory or via an absolute path.
Persistent memory	Optional markdown logs that are automatically loaded into the LLM context on each run. Axe can also run LLM‑assisted garbage‑collection to trim old entries.
Tool use	Built‑in sandboxed tools (read_file, write_file, run_command, url_fetch, web_search, etc.) and optional external MCP tools. The LLM can request a tool call, Axe executes it, returns the result, and the conversation continues.
Sub‑agent delegation	An agent can invoke other agents (call_agent) with depth and parallelism limits, enabling hierarchical workflows.

---

Highlighted features (as described in the README)

• Multi‑provider support – Anthropic, OpenAI, Ollama (local), OpenCode, AWS Bedrock.
• TOML‑based, version‑controllable configs – easy to store in Git.
• Standard‑input piping – treat an agent like any other filter.
• Dry‑run mode – preview the resolved context without hitting the LLM.
• JSON envelope – structured output for downstream automation.
• Token‑budget enforcement – stop a run when a cumulative token limit is hit (exit code 4).
• Memory garbage collection – LLM‑assisted trimming of old logs.
• Retry logic – configurable exponential/linear/fixed back‑off for transient provider errors.
• Security – sandboxed file tools, host allow‑list for web fetches, SSRF protection, and hardened Docker images (non‑root user, read‑only root FS, capabilities dropped).

---

Installation

Method	Command
Pre‑built binary (Linux/macOS/Windows)	Download from the GitHub Releases page.
Go install (requires Go 1.25+)	go install github.com/jrswab/axe@latest
Build from source	bash\n git clone https://github.com/jrswab/axe.git\n cd axe\n go build .\n

---

Quick‑start workflow

# Initialise a config directory (~/.config/axe)
axe config init

# Scaffold a new agent called "my‑agent"
axe agents init my-agent

# Edit the generated TOML to set model, skill, etc.
axe agents edit my-agent

# Run it – you can pipe data or use -p to supply a prompt
git diff --cached | axe run my-agent
# or
axe run my-agent -p "Summarise the latest changelog"

The README also ships an examples/ folder with ready‑to‑copy agents such as a code reviewer, commit‑message generator, and text summariser.

Docker support

• A minimal Dockerfile builds a hardened image (UID 10001, read‑only root, all caps dropped).
• Run an agent by mounting your Axe config directory and passing API keys via environment variables.
• Multi‑arch builds (linux/amd64, linux/arm64) are supported via docker buildx.
• A docker‑compose.yml is provided for running Axe alongside a local Ollama instance; you can also use the image with a cloud‑only provider by omitting the Ollama service.

---

Typical use cases

• Automated code review – pipe git diff into a code‑reviewer agent that can read files, run linters, and suggest changes.
• Commit‑message generation – feed commit logs to an agent that outputs a concise message.
• Log analysis – stream error logs into a log‑analyzer agent that can search the web for known issues.
• CI/CD gating – run an agent as a step in a GitHub Actions workflow to enforce style or security checks.
• Ad‑hoc data extraction – use read_file/run_command tools to fetch data from a repo, then ask the LLM to transform it.

---

Where to look next

• examples/README.md – detailed walkthrough of the bundled agents.
• CLI reference – axe --help or the table in the README for all commands and flags.
• Agent TOML schema – the README’s “Agent Configuration” section lists every optional field (memory, budget, retry, MCP servers, etc.).
• MCP integration – if you have external tool servers that speak the Model Context Protocol, declare them under [[mcp_servers]] to extend the toolset.

---

Bottom line

Axe provides a lightweight, Unix‑philosophy‑aligned way to treat LLMs as programmable command‑line tools. By keeping each agent small, version‑controlled, and composable, it fits naturally into existing shell pipelines, CI systems, and Docker workflows while still offering advanced features like sub‑agent delegation, persistent memory, and multi‑provider support.