Architecture

The components of the ChooChoo platform

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

Planned Integrations

ChooChoo is designed to integrate with where engineering work happens.

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.