Axon

---

Quickstart

go get github.com/atakang7/axon/v2

Axon uses gopkg.in/yaml.v3 for configuration and golang.org/x/sys/windows for native Windows process jobs.

On Windows, shell tools use Git for Windows Bash when installed, with a PowerShell fallback. Background commands and foreground cancellation use Windows Job Objects to terminate the whole process tree. Windows does not provide POSIX SIGTERM, so job termination is immediate. Linux and macOS continue to use POSIX process groups.

Point it at any OpenAI-compatible endpoint and drive a turn:

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/atakang7/axon/v2"
)

func main() {
    model, err := axon.OpenAI(axon.ClientConfig{
        Provider: axon.Provider{
            BaseURL: "https://openrouter.ai/api",
            Model:   "deepseek/deepseek-v3.2",
            APIKey:  os.Getenv("OPENROUTER_API_KEY"),
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    agent, err := axon.New(axon.Config{
        Model:        model,
        SystemPrompt: "You are a careful coding agent.",
    })
    if err != nil {
        log.Fatal(err)
    }
    defer agent.Close() // kills background shells, closes MCP

    result, err := agent.Step(context.Background(), "List the files in this directory.")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Assistant)
}

Set an API key and run:

export OPENROUTER_API_KEY=sk-...
go run .

Example

The snippet above is the full agent loop — one client, one agent, one Step. Axon layers the rest on top when you need it:

• Tools — file I/O, search, shell exec, background processes, all built in
• Sessions — persistent, resumable; the deciding model checkpoints what stays in context, and an optional read-only explorer answers broad questions with verified quotes (see WORKING_CONTEXT.md)
• MCP — connect external tool servers over stdio or HTTP
• Events — a structured stream you can render into any UI

---

Documentation

Full documentation lives at atakang7.github.io/axon:

Getting Started

• What is Axon? — What Axon is and why it exists.
• Quickstart — Get an agent running in under a minute.

Core Concepts

• The Turn Loop — How Step() drives the agent through model calls and tool execution.
• Context Management — How Axon keeps the model's context window bounded.
• Sessions & Memory — Persistence, listing, switching, and undo.
• Events & UI — The structured event stream for building UIs.

Tools

• Built-in Tools — The seven tools that ship with every agent.
• Custom Tools — How to add your own tools to an agent.
• MCP Servers — Integrate Model Context Protocol tool servers.

Configuration

• Agent Setup — The two configuration surfaces and why they are separate.
• Runtime Policies — Every field in the configuration file.
• File Locations — Where Axon reads and writes files.

Under the Hood

• Architecture — Internal design reference for contributors.
• Security Boundaries — How Axon protects credentials and configuration from tools.
• Retry Logic — How Axon handles transient failures.

---

License

MIT