Architecture overview

Chronos is an orchestration and governance layer on top of the AI model. It turns a spec or an issue into verified, review-ready code by running agents in parallel, each in its own isolated environment (a git worktree), integrated with the organization’s version control and governed from an enterprise panel.

One pattern unifies the platform: catalog in the panel → global→team→workspace→session cascade → per-session materialization → enforcement via managed settings → audit. Both MCPs and context/memory follow it.

Components

The local client is a Rust workspace; all orchestration logic lives in the daemon.

Component	Crate	Role
Daemon	chronosd	Owner of state: workspaces, sessions, agent processes, sequence queues, event bus, audit log. All logic lives here.
CLI	chronos-cli	Thin client. Talks to the daemon over a Unix socket (macOS) or named pipe (Windows). Depends only on the IPC contract, never on daemon internals.
Broker	chronos-broker	Loopback MCP proxy. Validates the per-session bearer, injects credentials provided by the panel, and forwards to the real remote endpoints.
Adapters	chronos-adapters	Agent runners (Claude Code, Codex, OpenCode, …) behind the AgentRunner trait. Model/provider agnosticism lives here.
Git	chronos-git	Worktree, branch and PR management.
Sandbox	chronos-sandbox	Per-OS isolation: seatbelt on macOS, job objects on Windows.
Domain & contract	chronos-core, chronos-contract	Domain types plus the panel↔daemon contract types — the source of the generated TS types (see Contract). Neither depends on anything else in the workspace.
Cloud	cloud/api, cloud/dashboard	The enterprise panel: catalogs, credentials, teams/scopes, SSO, audit, insights.

Stack: Rust + tokio + SQLite on the client; Tauri for the desktop app; web for the dashboard. Cross-platform macOS + Windows from day one. Agent CLIs run as child processes orchestrated via spawn + stdio — Chronos does not reimplement them.

Session model

• Workspace — a directory opened with chronos .; holds .chronos/settings.toml (base branch, remote, managed worktree path).
• Session — a git worktree on branch chronos/<id>, created in a managed path outside the main repo — by default ~/Chronos/workspaces/<repo-name>/<session-id>/, visible in your file browser. Not a copy: it shares the object store and never touches the base branch.
• Sequence — a per-session FIFO queue of prompts (enqueue, reorder, cancel).

On close, the daemon runs git worktree remove and deletes the branch; PRs follow the client’s configured Gitflow.

Session state machine

Each session moves through a finite state machine owned by the daemon:

created → setup → ready → running
        → awaiting_input / awaiting_approval
        → verifying → ready_for_review
        → merged / discarded → cleaned

error is a side state reachable from running and verifying. The user-facing subset of these states maps to visual signals in the design system.

Event flow

• Adapters map each agent’s native output stream to a common AgentEvent model.
• The daemon’s event bus fans events out to clients (CLI, dashboard, desktop app); agent stdout/events are streamed incrementally — never buffered whole before display.
• The sequence queue and the event bus apply backpressure; a scheduler caps simultaneous agents by available cores/RAM and queues the rest, so there is no unbounded process spawning and the daemon stays responsive under load.
• Heavy filesystem and git work runs in spawn_blocking, off the async path.

SQLite store

The daemon persists state and the append-only audit log in SQLite:

• WAL mode with proper indices on workspace/session/audit keys.
• Writes are kept off the async request path (dedicated writer task / spawn_blocking); audit writes are batched.
• Session memory — transcript, sequence, tool calls — lives here per session, enabling attach/restore and feeding the audit log. It stays local.

Performance budgets

Performance is a product requirement, not a nice-to-have: every hot path has a budget and a benchmark, and a regression is a bug. Budgets are targets on a typical dev laptop against a mid-size repo, verified by a perf suite (criterion benchmarks + integration timing) that runs in CI and fails if a budget regresses.

Key targets:

Path	Budget
Daemon cold start	< 100 ms
CLI round-trip (ping/list)	< 50 ms
Session create (worktree add + register)	< 1 s on a repo up to ~1 GB / ~50k files
Chronos overhead on the agent’s first surfaced token	< 50 ms
Navigator tree/diff/status	< 200 ms, incremental via file-watching
Broker per-call overhead	< 5 ms over a direct call; SSE/streaming passed through
Daemon responsiveness under N parallel agents	CLI/UI < 100 ms

The strategies behind the numbers: worktrees instead of clones (shared object store, near-instant creation), incremental streaming, file-watching instead of repeated full git status, connection reuse and in-memory short-lived token caching in the broker, and virtualized/chunked rendering in the UI.