chronos

module
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 15, 2026 License: MIT

README

Chronos

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

Install · Quickstart · Docs · Examples · Roadmap

Features

Layer What it does
SDK Agent builder, teams (sequential/parallel/router/coordinator), memory, knowledge (RAG), inter-agent protocol bus
Engine StateGraph runtime with checkpointing and interrupt nodes, 14+ LLM providers, tool registry, guardrails, hooks, SSE streaming
ChronosOS HTTP control plane — auth, RBAC, tracing, audit logs, approval API
Storage SQLite, PostgreSQL, Redis, MongoDB, DynamoDB, Qdrant, Pinecone, Weaviate, Milvus
CLI Interactive REPL, headless batch mode, session/memory management, YAML-first config

Install

CLI Binary (Linux / macOS / Windows)

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 Module

go get github.com/spawn08/chronos

Build from Source

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

Quickstart

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"})

Examples

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

Example Description Needs Keys?
quickstart Minimal agent with SQLite and 3-node graph No
tools_and_guardrails Tool permissions + input/output guardrails No
hooks_observability Metrics, cost tracking, caching, retry, rate limiting No
graph_patterns Conditional edges, interrupt nodes, checkpoints No
memory_and_sessions Short/long-term memory, multi-turn sessions No
streaming_sse Pub/sub broker, graph events, SSE HTTP server No
chat_with_tools Agent chat with calculator and lookup tools No
fallback_provider Provider chain with automatic failover No
sandbox_execution Process sandbox with timeouts and I/O capture No
durable_queue Durable work queue: leased workers, durable sleep, park/signal HITL, orphan recovery No
durable_hitl Human-in-the-loop approval with checkpoint + resume No
multi_round_tools Multi-round sequential tool calls retaining full context No
multitenant_memory Per-user long-term memory isolation on one agent No
cli_agent Build, inspect, and run an agent from YAML via the CLI No
cli_ops Operate Chronos from the CLI: serve, monitor, db, sessions, pipe, deploy No
multi_agent All 4 team strategies, bus delegation Optional
multi_provider OpenAI, Anthropic, Gemini, Mistral, Ollama Yes
mcp_agent Agent using MCP tools over stdio transport Yes

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

Supported Providers

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

Documentation

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

Roadmap

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

Priority Area Status
P0 Bug fixes, CLI wiring, test foundation 5/16 done
P1 MCP support, subgraphs, time travel, advanced HITL Planned
P2 A2A protocol, cron triggers, multi-modal, graph visualization Planned
P3 Workflow DSL, plugin marketplace, distributed execution Planned

What's Next (P1 highlights)

  • 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

CI/CD

Workflow Trigger What it does
CI Push/PR to main Lint, build, test (Ubuntu + macOS), example smoke tests, Docker build
Release Tag v*.*.* Test gate, build 6 platform binaries, create GitHub Release with checksums, publish Go module, push Docker image to GHCR

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

Contributing

  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

License

MIT

Directories

Path Synopsis
cli
Chronos CLI entry point.
 Chronos CLI entry point.
cmd
Package cmd provides the Chronos CLI command tree.
 Package cmd provides the Chronos CLI command tree.
repl
Package repl provides an interactive REPL for the Chronos CLI.
 Package repl provides an interactive REPL for the Chronos CLI.
engine
graph
Package graph provides the StateGraph durable execution runtime.
 Package graph provides the StateGraph durable execution runtime.
guardrails
Package guardrails provides input/output validation for agent execution.
 Package guardrails provides input/output validation for agent execution.
hooks
Package hooks provides a middleware system for intercepting agent execution events.
 Package hooks provides a middleware system for intercepting agent execution events.
mcp
Package mcp implements the Model Context Protocol (MCP) client.
 Package mcp implements the Model Context Protocol (MCP) client.
model
Package model defines pluggable LLM provider interfaces.
 Package model defines pluggable LLM provider interfaces.
queue
Package queue provides a durable, distributed work queue for Chronos graph runs.
 Package queue provides a durable, distributed work queue for Chronos graph runs.
stream
Package stream provides event streaming for real-time observability.
 Package stream provides event streaming for real-time observability.
tool
Package tool provides the tool registry with permissions and approval hooks.
 Package tool provides the tool registry with permissions and approval hooks.
tool/builtins
Package builtins provides ready-to-use tool implementations.
 Package builtins provides ready-to-use tool implementations.
Package evals provides an evaluation framework for testing agent quality.
 Package evals provides an evaluation framework for testing agent quality.
examples
azure command
Azure OpenAI example for Chronos.
 Azure OpenAI example for Chronos.
chat_with_tools command
Example: chat_with_tools demonstrates an agent that uses tools during chat.
 Example: chat_with_tools demonstrates an agent that uses tools during chat.
cli_agent command
Command custom_tool shows how to give a Chronos agent a CUSTOM tool with a real Go handler.
 Command custom_tool shows how to give a Chronos agent a CUSTOM tool with a real Go handler.
coding_agent command
Example: coding_agent — A full-featured autonomous coding agent.
 Example: coding_agent — A full-featured autonomous coding agent.
durable_hitl command
Example: durable_hitl demonstrates a durable, human-in-the-loop (HITL) StateGraph.
 Example: durable_hitl demonstrates a durable, human-in-the-loop (HITL) StateGraph.
durable_queue command
Command durable_queue demonstrates the Chronos durable, distributed execution plane (engine/queue) delivered in Phase P1.
 Command durable_queue demonstrates the Chronos durable, distributed execution plane (engine/queue) delivered in Phase P1.
fallback_provider command
Example: fallback_provider demonstrates automatic failover between model providers.
 Example: fallback_provider demonstrates automatic failover between model providers.
graph_patterns command
Example: graph_patterns demonstrates the StateGraph durable execution engine.
 Example: graph_patterns demonstrates the StateGraph durable execution engine.
graph_with_llm command
Example: graph_with_llm — StateGraph with real LLM calls inside nodes.
 Example: graph_with_llm — StateGraph with real LLM calls inside nodes.
hooks_observability command
Example: hooks_observability demonstrates all Chronos hooks for production observability.
 Example: hooks_observability demonstrates all Chronos hooks for production observability.
internal/exampletest
Package exampletest provides helpers for tests under examples/.
 Package exampletest provides helpers for tests under examples/.
mcp_agent command
Example: mcp_agent demonstrates connecting an agent to a Model Context Protocol (MCP) server and importing its tools into the agent's registry.
 Example: mcp_agent demonstrates connecting an agent to a Model Context Protocol (MCP) server and importing its tools into the agent's registry.
memory_and_sessions command
Example: memory_and_sessions demonstrates persistent multi-turn sessions and the memory system (short-term + long-term).
 Example: memory_and_sessions demonstrates persistent multi-turn sessions and the memory system (short-term + long-term).
multi_agent command
Example: multi_agent demonstrates all four team strategies and agent communication.
 Example: multi_agent demonstrates all four team strategies and agent communication.
multi_provider command
Example: multi_provider demonstrates connecting agents to different LLM providers.
 Example: multi_provider demonstrates connecting agents to different LLM providers.
multi_round_tools command
Example: multi_round_tools demonstrates an agent performing MULTIPLE sequential tool-calling rounds, where the result of tool A feeds the arguments of tool B.
 Example: multi_round_tools demonstrates an agent performing MULTIPLE sequential tool-calling rounds, where the result of tool A feeds the arguments of tool B.
multitenant_memory command
Example: multitenant_memory demonstrates per-user long-term memory isolation — two different users served by one logical agent, whose memories never leak across tenants.
 Example: multitenant_memory demonstrates per-user long-term memory isolation — two different users served by one logical agent, whose memories never leak across tenants.
quickstart command
Chronos Quickstart — a minimal agent with SQLite storage and a durable StateGraph.
 Chronos Quickstart — a minimal agent with SQLite storage and a durable StateGraph.
sandbox_execution command
Example: sandbox_execution demonstrates the process sandbox for running untrusted commands with timeouts and output capture.
 Example: sandbox_execution demonstrates the process sandbox for running untrusted commands with timeouts and output capture.
streaming_sse command
Example: streaming_sse demonstrates the event streaming broker for real-time observability.
 Example: streaming_sse demonstrates the event streaming broker for real-time observability.
team_deploy command
Example: team_deploy — Deploy multi-agent teams from YAML with sandbox isolation.
 Example: team_deploy — Deploy multi-agent teams from YAML with sandbox isolation.
tools_and_guardrails command
Example: tools_and_guardrails demonstrates the tool registry with permission levels and guardrail engine for input/output validation.
 Example: tools_and_guardrails demonstrates the tool registry with permission levels and guardrail engine for input/output validation.
os
Package chronosos provides the ChronosOS control plane server.
 Package chronosos provides the ChronosOS control plane server.
approval
Package approval provides human-in-the-loop approval workflows for the ChronosOS control plane.
 Package approval provides human-in-the-loop approval workflows for the ChronosOS control plane.
auth
Package auth provides authentication and RBAC for ChronosOS.
 Package auth provides authentication and RBAC for ChronosOS.
interfaces/discord
Package discord provides a Discord bot interface for Chronos agents.
 Package discord provides a Discord bot interface for Chronos agents.
interfaces/slack
Package slack provides a Slack bot interface for Chronos agents.
 Package slack provides a Slack bot interface for Chronos agents.
interfaces/telegram
Package telegram provides a Telegram bot interface for Chronos agents.
 Package telegram provides a Telegram bot interface for Chronos agents.
logging
Package logging provides structured JSON-line logging with correlation and tenant identifiers carried through context.
 Package logging provides structured JSON-line logging with correlation and tenant identifiers carried through context.
metrics
Package metrics provides Prometheus-format metrics collection and export.
 Package metrics provides Prometheus-format metrics collection and export.
middleware
Package middleware provides HTTP middleware for ChronosOS.
 Package middleware provides HTTP middleware for ChronosOS.
scheduler
Package scheduler provides cron-based scheduling for agent runs.
 Package scheduler provides cron-based scheduling for agent runs.
trace
Package trace provides execution tracing and audit logging.
 Package trace provides execution tracing and audit logging.
webhook
Package webhook provides a generic webhook interface for receiving external events.
 Package webhook provides a generic webhook interface for receiving external events.
Package sandbox provides isolation for untrusted tool/skill execution.
 Package sandbox provides isolation for untrusted tool/skill execution.
sdk
agent
Package agent provides the agent definition and builder API.
 Package agent provides the agent definition and builder API.
knowledge
Package knowledge provides a RAG knowledge base abstraction inspired by Agno's Knowledge protocol.
 Package knowledge provides a RAG knowledge base abstraction inspired by Agno's Knowledge protocol.
knowledge/loaders
Package loaders provides document loaders for different file formats.
 Package loaders provides document loaders for different file formats.
memory
Package memory — manager.go provides an LLM-powered memory manager inspired by Agno's MemoryManager.
 Package memory — manager.go provides an LLM-powered memory manager inspired by Agno's MemoryManager.
protocol
Package protocol defines the agent-to-agent communication protocol.
 Package protocol defines the agent-to-agent communication protocol.
protocol/a2a
Package a2a implements the Agent-to-Agent (A2A) protocol for cross-framework agent communication.
 Package a2a implements the Agent-to-Agent (A2A) protocol for cross-framework agent communication.
skill
Package skill provides the skill/plugin system for Chronos agents.
 Package skill provides the skill/plugin system for Chronos agents.
team
Package team provides multi-agent orchestration with inter-agent communication.
 Package team provides multi-agent orchestration with inter-agent communication.
skills
examples
Package examples provides example skill definitions.
 Package examples provides example skill definitions.
Package storage defines the core persistence interfaces for Chronos.
 Package storage defines the core persistence interfaces for Chronos.
adapters/chromadb
Package chromadb provides a ChromaDB-backed VectorStore adapter for Chronos.
 Package chromadb provides a ChromaDB-backed VectorStore adapter for Chronos.
adapters/dynamo
Package dynamo provides a DynamoDB-backed Storage adapter for Chronos.
 Package dynamo provides a DynamoDB-backed Storage adapter for Chronos.
adapters/lancedb
Package lancedb provides a LanceDB-backed VectorStore adapter for Chronos.
 Package lancedb provides a LanceDB-backed VectorStore adapter for Chronos.
adapters/memory
Package memory provides an in-memory Storage adapter for Chronos.
 Package memory provides an in-memory Storage adapter for Chronos.
adapters/milvus
Package milvus provides a Milvus-backed VectorStore adapter for Chronos.
 Package milvus provides a Milvus-backed VectorStore adapter for Chronos.
adapters/mongo
Package mongo provides a MongoDB-backed Storage adapter for Chronos.
 Package mongo provides a MongoDB-backed Storage adapter for Chronos.
adapters/pgvector
Package pgvector provides a PostgreSQL+pgvector-backed VectorStore adapter for Chronos.
 Package pgvector provides a PostgreSQL+pgvector-backed VectorStore adapter for Chronos.
adapters/pinecone
Package pinecone provides a Pinecone-backed VectorStore adapter for Chronos.
 Package pinecone provides a Pinecone-backed VectorStore adapter for Chronos.
adapters/postgres
Package postgres provides a PostgreSQL-backed Storage adapter for Chronos.
 Package postgres provides a PostgreSQL-backed Storage adapter for Chronos.
adapters/qdrant
Package qdrant provides a Qdrant-backed VectorStore adapter for Chronos.
 Package qdrant provides a Qdrant-backed VectorStore adapter for Chronos.
adapters/redis
Package redis provides a Redis-backed Storage adapter for Chronos.
 Package redis provides a Redis-backed Storage adapter for Chronos.
adapters/redisvector
Package redisvector provides a Redis-backed VectorStore adapter using RediSearch.
 Package redisvector provides a Redis-backed VectorStore adapter using RediSearch.
adapters/sqlite
Package sqlite provides a SQLite-backed Storage adapter for Chronos.
 Package sqlite provides a SQLite-backed Storage adapter for Chronos.
adapters/weaviate
Package weaviate provides a Weaviate-backed VectorStore adapter for Chronos.
 Package weaviate provides a Weaviate-backed VectorStore adapter for Chronos.
migrate
Package migrate provides versioned database migrations for SQL backends.
 Package migrate provides versioned database migrations for SQL backends.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.