Chronos Code

A YAML-native AI coding agent harness, shipped as a single Go binary.

Define agents, skills, guardrails, and routing in YAML. Run them from the terminal, a headless CLI, or an HTTP API, backed by a multi-language code graph, persistent memory, and a security floor that project config can't weaken.

Documentation · Install · Quick start · Architecture · Releases

Chronos Code is an AI coding agent built on the Chronos agentic framework. You talk to one primary agent, chronos-code. It spawns specialists (coder, reviewer, debugger, and others) when needed, or when you @mention one.

Everything you'd normally tune in code lives in YAML: agents, skills, guardrails, security policy, model routing, and MCP servers. It works on first run with embedded defaults. chronos-code init exports those defaults into your project so you can edit them.

Prebuilt binaries for Linux, macOS, and Windows (amd64 and arm64) come with every tagged release.

macOS / Linux

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

Windows (PowerShell)

irm https://raw.githubusercontent.com/spawn08/chronos-code/main/scripts/install.ps1 | iex

The installers detect your OS and architecture, download the matching archive, check it against the release's SHA256SUMS, and install chronos-code to ~/.local/bin.

On Windows, use $env:VERSION / $env:INSTALL_DIR. If the script warns that the install directory isn't on PATH, add it.

git clone https://github.com/spawn08/chronos.git
git clone https://github.com/spawn08/chronos-code.git
cd chronos-code
make build          # → bin/chronos-code
make install        # → $GOPATH/bin

chronos-code login           # configure a provider (Anthropic, OpenAI, Azure, …)
chronos-code                 # launch the interactive TUI

A few more common starting points:

chronos-code run "add table-driven tests for internal/router"   # one-shot, then exit
chronos-code run --json "summarize this repo"                    # machine-readable output
chronos-code init                                                # export editable YAML to .chronos-code/
chronos-code serve                                               # HTTP API on :8430

In the TUI, mention a specialist to skip the router:

@reviewer check my last commit
@debugger why is TestAuth failing
@security-auditor threat-model the HTTP handlers
/ppd migrate the config loader to the new schema

/ppd <task> (or mentioning "PPD" in a request) runs the task as a rolling plan: planner proposes the next few steps with a verification command each, the primary agent tracks them with update_plan, completes each only after its check passes, and re-plans until the request is verified. The checklist is saved with the session, so /resume picks it back up.

cmd/chronos-code is a thin main, and internal/cli dispatches commands. The REPL, headless run, and serve each build a single Orchestrator. The orchestrator resolves configuration, indexes the workspace graph, wires up Chronos agents, and executes turns. The TUI and HTTP server are front ends to that runtime; they never call Chronos directly.

Chronos (github.com/spawn08/chronos) is used as a library: agent SDK, harness, tool runtime, streaming, and storage adapters. Chronos Code builds on its agent loop instead of reimplementing it.

1. Surface. The CLI starts a REPL, a one-shot run, or serve.
2. Orchestrator. Loads config, agents, skills, security policy, routing, graph, session, and memory stores.
3. Router. Classifies the message with YAML regexes (T0), optionally checked by a cheap model (T1). It picks a model tier and an implementation path (low / medium / high). chronos-code keeps the conversation unless you @mention a specialist.
4. Chronos agent loop. Order of escalation: graph tools (T0), then ranged file reads (T1), then shell and writes (T2). Guardrails and the security policy wrap every tool call. If an MCP server fails, healthy servers and chat keep working.
5. Post-turn. The session is persisted, explicit memory intents are written, and learning may emit a pending suggestion for review.

Each agent is a YAML file. Run chronos-code init and edit .chronos-code/agents/*.yaml to change them or add your own.

.chronos-code/
├── config.yaml      # model, storage, memory, learning, verification
├── routing.yaml     # intents, models, complexity paths, PPD
├── security.yaml    # path allowlists, shell restrictions, MCP trust
├── agents/          # chronos-code.yaml, coder.yaml, …
├── skills/
├── guardrails/
├── memory/          # project.yaml, user.yaml, feedback.yaml
└── learned/         # pending learning suggestions
.mcp.json            # project MCP servers (repo root)

Runtime databases live under ~/.chronos-code/projects/<name>-<id>/ (override the root with CHRONOS_CODE_DATA_HOME). Existing project databases are imported from verified SQLite snapshots, and the originals are kept. A shared, partitioned ~/.chronos-code/memory.db provides user and organization recall across projects. See Harness reliability, layered memory, and hooks.

Highest to lowest:

1. CLI flags
2. Provider and server environment variables (CHRONOS_CODE_PROVIDER, CHRONOS_CODE_MODEL, …)
3. .chronos-code/config.yaml (project)
4. ~/.chronos-code/config.yaml (user)
5. Embedded defaults

verification:
  mode: report          # report | enforce: enforce refuses "done" without current evidence

defaults:
  reasoning:
    strategy: cot
    native: true        # Anthropic extended thinking / OpenAI reasoning effort (off by default)
    effort: medium      # low | medium | high
    budget_tokens: 4096
    summary: true       # stream thinking summaries in the TUI

session:
  recall_prior_summaries: false
  context_report: false
learning:
  pattern_injection: false
mcp:
  discovery_enabled: false

Session resume: The TUI prints the full session ID and chronos-code --resume <id> at startup, after changing sessions, and after returning to your shell. The header shows the current ID, shortened when space is limited. /session shows the full details at any time.

Working status: The footer shows an animated indicator, the current activity or tool, and elapsed time throughout a run. Question and permission dialogs show a waiting state. Tool details reuse cached rendering, and long inline plans show a bounded preview with the full content available through /inspect. A scoped-instruction deferral appears as loading project instructions while the harness prepares the next model call and retry.

Scrolling and selection: The mouse wheel scrolls the transcript by default. Shift-drag selects text, which you copy with your terminal's shortcut. Streaming doesn't repaint the pane while you're scrolled away from the live tail, so your selection stays put until Ctrl+End.

Clarification dialogs: Agents are guided to resolve routine choices themselves and ask a small number of high-information questions for essential user decisions. When a decision needs your input, the agent can call ask_user_question to show up to four questions. Use arrow keys or Tab to move, Space to toggle multi-select choices, and Enter to answer and advance. Select Other to type a custom answer. Recommended options are marked. Escape cancels the questions; Ctrl+C interrupts the running task. Answers return to the agent in the same run. Headless run and HTTP serve return an input_required tool result so the agent can explain the missing decision and wait for a follow-up.

Memory intents: Only explicit forms persist: remember <category>: <fact>, forget: <mem_ID>, recall-past: <query>. Casual use of "remember", "always", or "never" does not.

• Security floor. The embedded floor can't be weakened by project policy or --yolo. --yolo auto-approves tools that policy already allows; it never overrides deny rules or destructive-action confirmations.
• Cost caps. --budget <usd> sets a USD cap. If pricing for the model is unknown, a positive cap fails closed before any provider call.
• Consuming MCP. Manage .mcp.json with chronos-code mcp add | list | test | remove. Only stdio and HTTPS SSE transports are accepted. Arguments or query values that look like credentials must be ${ENV_VAR} references, and they are redacted in output. MCP tools are namespaced, require approval by default, and are closed on cleanup. Servers that are denied, untrusted, malformed, or unavailable don't block anything else.
• Serving MCP. chronos-code indexer mcp exposes the read-only code graph tools to other MCP hosts over stdio. Repositories listed in workspace.indexer.federation (or passed via --repo [name=]dir) are indexed separately. Symbol lookup, search, and callers follow imports and API contracts across them. See docs/chronos-indexer.md.

chronos-code                           Start the interactive REPL
chronos-code run <message>             Run one task, then exit
chronos-code init                      Export .chronos-code/ into the project
chronos-code login | logout | whoami   Manage provider credentials
chronos-code providers                 List resolvable providers
chronos-code models [provider]         Query live models (labeled static fallback)
chronos-code agents list               List resolved agents
chronos-code config show | validate    Inspect resolved config
chronos-code session list | delete | export
chronos-code memory list | search | forget
chronos-code mcp add | list | test | remove
chronos-code indexer mcp [--repo DIR]  Serve code graph tools over MCP stdio
chronos-code learn suggest | list | show | accept | reject
chronos-code skills list | show
chronos-code team list | run
chronos-code eval run | ppd
chronos-code serve                     Start the HTTP API server
chronos-code version

Global flags: -c/--config, --provider <name>, --model <id>, --debug, --stream / --no-stream, --permission-mode, --yolo, --dangerously-skip-permissions (approve everything that would ask; policy blocks still apply — sandboxes/CI only), --plan-mode, --budget <usd>, --resume <session-id>, --json (headless).

make build        # bin/chronos-code
make test         # go test -race
make lint
make eval         # token-efficiency eval against benchmark/eval/baseline.json
make size-check   # release binary size gate (56 MiB)
make fmt vet tidy

Every push and pull request to main runs CI: build, lint, go test -race, the release-binary size gate, and the token-efficiency eval.

Chronos Code follows semantic versioning. Pushing a v* tag triggers the release workflow, which:

1. Runs the test suite against the pinned Chronos revision (release/chronos.version)
2. Builds linux, darwin, and windows binaries for amd64 and arm64
3. Generates an SPDX SBOM for each binary
4. Writes a SHA256SUMS manifest, attests build provenance, and signs the manifest with Sigstore cosign (keyless)
5. Publishes everything to a GitHub Release

Local builds get their version from git describe; untagged commits report a dev version with a commit suffix. Check yours with chronos-code version.

Full user documentation, covering getting started, everyday use, plan mode, headless automation, configuration, agents and skills, permissions, and best practices, is at spawn08.github.io/chronos-code. The source is in docs/.

Released under the same license as Chronos.