claude-agent-go

Build, run, debug and test Claude Code agents from one typed Go API: locally, in containers, or across a fleet of machines.

claude-agent-go drives the claude binary as a subprocess. It does not reimplement the agent loop, so you get the upstream models and tools for free. On top of the CLI it adds:

• Core client. One-shot and interactive runs, in-process Go tools, permission and hook callbacks, inline subagents, streaming, retries with cost accounting.
• Execution graphs. Plan, code, review and fix loops, parallel fan-out, human review, and durable runs that survive a crash (Recover, Fork).
• A debugger. graphweb, a live and replay web UI for graph runs, plus recordings you can replay offline and free.
• Evals and a test kit. Trajectory matching, ROUGE, LLM judges, pass@k, user simulation, fake CLI binaries, stream invariants, golden replays.
• Remote execution. Local, docker exec, docker run and ssh transports that really stop the remote agent on cancel, with a preflight check.
• Safety. A rule-based permission policy, a bearer-token MCP server, spend caps, fuzz-tested parsers.

// one line moves the agent off your laptop:
r := runner.New(runner.WithTransport(transport.SSH{Host: "gpu-box"}))
res, _ := r.RunJSON(ctx, runner.Input{Prompt: "Run the test suite and summarize failures."})

• Zero external runtime dependencies beyond the official MCP Go SDK (used only by tools). testify is test-only. Heavy integrations live in separate modules (otel/, temporal/).
• Behaviorally verified against the real claude binary: integration tests assert effects (a denied tool that does not write, a subagent whose prompt reaches the answer, an ssh/docker run that actually reaches the binary).
• >90% unit coverage across every substantive package; 22 fuzz targets.

Contents: Install · Quick start · Core · Graphs · Debugging · Evals · Testing your agents · Transports · Observability · Examples

Install

As a library (Go 1.27+):

go get github.com/tggo/claude-agent-go@latest

Or the cag CLI, to run agents and inspect runs without writing Go:

go install github.com/tggo/claude-agent-go/cmd/cag@latest

cag run --transport ssh --host gpu-box "run the test suite and summarize failures"
cag fleet examples/cag/fleet.yaml        # a batch across a worker pool, from YAML
cag trace runs/ --open                   # HTML view of recorded runs
cag web --replay runs/journal.jsonl      # graph debugger on a recorded run
cag runs ./checkpoints                   # durable graph runs: running/crashed/paused/done

Both need the claude CLI on PATH (2.1.196 or newer) and valid credentials.

Quick start

r := runner.New(runner.WithModel("sonnet"))
res, err := r.RunJSON(ctx, runner.Input{Prompt: "Summarize this repo in one line."})
if err != nil {
    log.Fatal(err)
}
fmt.Println(res.ResultText, res.TotalCostUSD, res.SessionID)

Try the examples: go run ./examples/basic -prompt "Say hi".

Package	What it does
runner	One-shot runs: Run, RunJSON, RunStream (+ ProgressFunc), retries, plugins, preflight.
client	Interactive multi-turn session and the control protocol (permissions, hooks, agents, skills).
tools	Expose Go functions to the agent as MCP tools, in-process; untyped or typed with schema inference.
permissions	Ordered allow/deny/ask rules for can_use_tool, in Claude Code's pattern syntax.
graph	Execution graphs: loops, fan-out, interrupt/resume, human review, durable runs, observers.
graphweb	Live and replay web UI for graph runs.
eval	Agent evals: trajectories, ROUGE, judges, pass@k, user simulation, go test integration.
recording	JSONL run recordings and ReplayTransport for offline replay.
clitest	Fake claude binaries for your own tests.
claudecli	Output types and parsers; CheckInvariants for stream sanity.
transport	How the binary is launched: local, docker exec, docker run, ssh; teardown and preflight.
fleet, budget	A worker pool over git worktrees; cross-run spend tracking.
mcp, workspace, signal	MCP config files, project/worktree dirs, marker-agnostic outcome detection.
otel/ (own module)	OpenTelemetry adapters for runner and graph observers.

Core

Runner: one-shot runs

Run returns text, RunJSON adds metadata (cost, tokens, session, turns), and RunStream calls you back for every event. A stream that ends without a result event comes back as *runner.TruncatedStreamError with the session ID and the partial text, and RunStreamWithRetry with RetryPolicy{Resume: true} continues that session via --resume instead of starting over.

Transient failures (rate limits, overloaded, 5xx, timeouts) are retried with exponential backoff that honors retry-after. The cost of every attempt is accumulated into Result.TotalCostUSD, and MaxSpendUSD stops retrying once the cumulative spend hits the cap. Each attempt also runs with --max-budget-usd lowered to what the cap has left, so one attempt cannot spend past it:

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗