ChooChoo is composed of three layers that work together to give AI agents persistent context, validated schemas, and a feedback loop for continuous improvement. For the motivations behind this design, see Why ChooChoo?.

1. The Engine (CLI & Validation)

The Engine is the developer-facing interface — a CLI tool (@choochoo-works/cli) that runs on developer machines and in CI/CD pipelines.

Responsibilities:

• Parse and enforce choochoo.toml — the single source of truth for a repository's AI governance policies. Policy definitions ("breaking changes to Data Contracts are forbidden"), role definitions ("Security Reviewer agents cannot modify auth logic without approval"), and context configuration all live here.
• Validate agent configs, trace files, and schema files (ODCS, ODPS, OpenAPI, Arazzo, GraphQL, AsyncAPI, AI System Card) against their respective schemas.
• Compile startup context for agents via choochoo context generate — producing AGENTS.md and injecting relevant SKILL.md files.
• Enforce agent rails and boundaries at validation time, before changes land.

See the CLI Reference and Quickstart.

2. The Map (Context Graph)

The Map is the accumulated storage of Agent Traces. It links every AI-assisted change to the conversation that produced it, the model that ran it, and the files it affected.

Entities:

• Traces: Decision records from every agent session.
• Actors: Human developers, AI agents (Claude Code, Gemini CLI, OpenCode, Codex), CI systems.
• Artifacts: Agent configs (AGENTS.md), schema files, trace files.

What it enables:

• Agents retrieve past decisions (context across sessions).
• Semantic search over historical agent work (choochoo qmd vsearch).
• Historical quality scoring for benchmark and fine-tuning workflows.

See Agent Trace and Context Compilation.

3. The Station (Evaluation Dashboard)

The Station is the evaluation and observability dashboard — currently in preview.

Capabilities (preview):

• Visualize the Context Graph and agent activity.
• View quality scores from benchmark runs.
• Track context compilation history.
• Manage access control and agent governance policies.

See Governance (Preview).

Architecture Diagram

graph TD
    subgraph "Developer Environment"
        Dev[Developer]
        Agent[AI Agent]
        CLI[ChooChoo CLI]
    end

    subgraph "CI/CD Pipeline"
        CI[CI Runner]
        Validate[choochoo validate]
    end

    subgraph "ChooChoo Platform"
        Graph[Context Graph / The Map]
        Station[The Station]
    end

    Dev -->|Edits| CLI
    Agent -->|Hooks into| CLI
    CLI -->|Compiles context| Agent
    CLI -->|Local Validation| Dev

    Dev -->|Push| CI
    CI -->|Run| Validate
    Validate -->|Submit Trace| Graph

    Station -->|Read/Query| Graph
    Station -->|Quality scores| Graph

Planned Integrations

ChooChoo is designed to integrate with where engineering work happens.

Integration	What it does	Status
GitHub App	Review bot that checks PRs specifically for policy compliance — not just syntax. Blocks merge on policy violations.	Roadmap
Harbor	Sandboxed containerized evaluation — runs agents against benchmark tasks before they can touch live branches.	Roadmap
Linear	Syncs Linear issues with AGENTS.md context; posts validation results and agentic progress back to the ticket.	Roadmap

See the Roadmap for timeline.

Next Steps

• Getting Started — Install ChooChoo and initialize your first project.
• Core Concepts — Deep dive into Agents, Agent Traces, and Context Compilation.
• Glossary — Key terms used throughout the documentation.