code

README

axon-code

axon-code is a Go library that implements a coding agent. It drives an LLM conversation loop to implement plan steps against a project directory, using file-system and shell tools sandboxed to that directory.

Import

import code "github.com/benaskins/axon-code"

Usage

package main

import (
    "fmt"
    "os"

    code "github.com/benaskins/axon-code"
    "github.com/benaskins/axon-code/plan"
    talk "github.com/benaskins/axon-talk"
)

func main() {
    client := talk.NewAnthropicClient(os.Getenv("ANTHROPIC_API_KEY"))

    coder := code.New(client,
        code.WithMaxIterations(30),
        code.WithVerbose(os.Stdout),
    )

    step := plan.Step{
        Title:       "Add greeting handler",
        Description: "Add a /hello endpoint that returns 'Hello, world!' with status 200.",
    }

    summary, err := coder.Implement("/path/to/project", step, "")
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
    fmt.Println(summary)
}

Options

Option	Default	Description
WithMaxIterations(n)	50	Maximum LLM turns per Implement call
WithTimeout(d)	15m	Wall-clock timeout per Implement call
WithSystemPromptPrefix(s)	""	Prepended to the system prompt
WithVerbose(w)	nil	Writer for tool-use trace output

Prerequisites

• Go 1.24+
• just

Development

just build   # go build ./...
just test    # go test ./...
just lint    # go vet ./...

Documentation

Overview

Package code implements a coding agent that drives an LLM conversation loop to implement plan steps against a sandboxed project directory using file-system and shell tools.

Class: platform UseWhen: Building a coding agent (code-hand). Implements Implement(projectDir, step, feedback). Not for orchestrators or non-coding workers.

Index

• type Agent
• type Coder
  • func New(client talk.LLMClient, opts ...Option) *Coder
  • func (c *Coder) Config() Config
  • func (c *Coder) Implement(projectDir string, step plan.Step, feedback string) (*ImplementResult, error)
• type Config
• type DoneSignal
  • func BuildTools(projectDir string) (map[string]tool.ToolDef, *DoneSignal, error)
• type ImplementResult
• type Option
  • func WithMaxIterations(n int) Option
  • func WithModel(m string) Option
  • func WithSessionID(id string) Option
  • func WithSystemPromptPrefix(s string) Option
  • func WithTimeout(d time.Duration) Option
  • func WithVerbose(w io.Writer) Option

Types

type Agent

type Agent interface {
	Implement(projectDir string, step plan.Step, feedback string) (*ImplementResult, error)
}

Agent implements a plan step in a given project directory.

type Coder

type Coder struct {
	// contains filtered or unexported fields
}

Coder implements the Agent interface using axon-loop, axon-talk, and axon-tool.

func New

func New(client talk.LLMClient, opts ...Option) *Coder

New constructs a Coder with the given LLM client and options. Default: MaxIterations=50, Timeout=15min.

func (*Coder) Config

func (c *Coder) Config() Config

Config returns the current configuration.

func (*Coder) Implement

func (c *Coder) Implement(projectDir string, step plan.Step, feedback string) (*ImplementResult, error)

Implement runs the coding agent loop for the given plan step. It builds the tool registry, assembles the system prompt, runs axon-loop, and returns the done summary on success.

type Config

type Config struct {
	Model              string
	MaxIterations      int
	Timeout            time.Duration
	SystemPromptPrefix string
	SessionID          string
	Verbose            io.Writer
}

Config holds runtime configuration for a Coder.

type DoneSignal

type DoneSignal = internaltools.DoneSignal

DoneSignal is populated by the done tool when the agent signals completion.

func BuildTools

func BuildTools(projectDir string) (map[string]tool.ToolDef, *DoneSignal, error)

BuildTools returns the standard coding tool set bound to projectDir, plus a DoneSignal the caller can inspect after the loop exits. Tools are returned as a map keyed by tool name.

type ImplementResult

type ImplementResult struct {
	Summary string      // what the agent accomplished
	Files   []string    // paths modified (relative to project dir)
	Usage   *talk.Usage // token usage for this step; nil if provider doesn't report
}

ImplementResult captures the outcome of implementing a plan step.

type Option

type Option func(*Config)

Option applies a configuration change to a Config.

func WithMaxIterations

func WithMaxIterations(n int) Option

WithMaxIterations sets the maximum number of loop iterations.

func WithModel

func WithModel(m string) Option

WithModel sets the model name for the LLM request.

func WithSessionID

func WithSessionID(id string) Option

WithSessionID sets the OpenRouter session ID for request grouping.

func WithSystemPromptPrefix

func WithSystemPromptPrefix(s string) Option

WithSystemPromptPrefix prepends a custom string to the system prompt.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the timeout for a single Implement call.

func WithVerbose

func WithVerbose(w io.Writer) Option

WithVerbose sets the writer for verbose tool-use logging.