A Go framework for building durable, scalable AI agents.
Define agents. Connect any LLM. Let them collaborate.

Install · Quickstart · Docs · Examples · Roadmap

curl -fsSL https://raw.githubusercontent.com/spawn08/chronos/main/install.sh | bash

Pre-built binaries for linux/amd64, linux/arm64, darwin/amd64 (Intel), darwin/arm64 (Apple Silicon), windows/amd64, and windows/arm64 are published to GitHub Releases.

go get github.com/spawn08/chronos

git clone https://github.com/spawn08/chronos.git && cd chronos
make build    # outputs bin/chronos

YAML config — create .chronos/agents.yaml:

defaults:
  model:
    provider: openai
    api_key: ${OPENAI_API_KEY}
  storage:
    backend: sqlite
    dsn: chronos.db

agents:
  - id: dev
    name: Dev Agent
    model:
      model: gpt-4o
    system_prompt: You are a senior software engineer.

chronos repl                            # interactive chat
chronos run "explain Go interfaces"     # headless one-shot

Go builder API:

a, _ := agent.New("chat", "Chat Agent").
    WithModel(model.NewOpenAI(os.Getenv("OPENAI_API_KEY"))).
    WithSystemPrompt("You are a helpful assistant.").
    Build()

resp, _ := a.Chat(ctx, "What is the capital of France?")
fmt.Println(resp.Content)

Graph-based agent:

g := graph.New("pipeline").
    AddNode("greet", func(_ context.Context, s graph.State) (graph.State, error) {
        s["message"] = fmt.Sprintf("Hello, %s!", s["user"])
        return s, nil
    }).
    SetEntryPoint("greet").
    SetFinishPoint("greet")

a, _ := agent.New("hello", "Hello Agent").WithGraph(g).Build()
result, _ := a.Run(ctx, map[string]any{"user": "World"})

All examples with No API keys run with mock providers — no external calls.

Run any example: go run ./examples/<name>/

OpenAI, Anthropic, Google Gemini, Mistral, Ollama, Azure OpenAI, and any OpenAI-compatible endpoint (Together, Groq, DeepSeek, OpenRouter, Fireworks, Perplexity, Anyscale, vLLM, LiteLLM).

Full docs at spawn08.github.io/chronos:

• Installation — CLI binary, Go module, build from source
• CLI Install — curl install for all platforms
• Quickstart — First agent in 5 minutes
• Agents — Agent builder, YAML config, capabilities
• Teams — Multi-agent orchestration strategies
• StateGraph — Durable execution with checkpointing
• Tools — Function calling and permissions
• Hooks — Middleware: retry, cache, cost, rate limit
• Storage — All 10 storage and vector adapters

Active development tracked in ROADMAP.md. Key upcoming work:

• MCP (Model Context Protocol) — Connect to MCP servers, use MCP tools natively
• Subgraphs — Compose graphs as nodes, parallel fan-out/fan-in with state reducers
• Time Travel — Replay from any checkpoint, fork execution with modified state
• Advanced Streaming — Multiple stream modes (values, updates, debug), custom event emission
• Structured Output — Response models with automatic validation and retry
• Agentic Loops — ReAct, iterative refinement, self-correcting tool call patterns

Cut a release: git tag v0.2.0 && git push origin v0.2.0

1. Fork and create a feature branch from main
2. Follow Go conventions — go vet, gofmt, wrap errors with %w
3. No init() functions, no global state, context.Context first on I/O methods
4. Table-driven tests in *_test.go files

MIT