Get up and running with ChooChoo in four steps. Make sure you have installed the CLI first.

1. Initialize a project

Run choochoo init inside any repository. It scaffolds a choochoo/ directory with example agent configs, schema files, and a starter AGENTS.md.

choochoo init

You can pass --dir ./path/to/docs to change the output location, or --yes to skip prompts.

Project structure: choochoo init creates the following layout:

choochoo/
├── agents/
│   └── AGENTS.md          # Agent context document (auto-generated)
├── system-cards/
│   └── example.yaml       # Example System Card
└── schemas/               # Your schema files (ODCS, OpenAPI, Arazzo, etc.)

2. Validate

Run the validator against the scaffolded examples. ChooChoo auto-detects file types (ODCS, ODPS, OpenAPI, Arazzo, GraphQL, AsyncAPI, AI System Card) from file content.

choochoo validate ./choochoo

You should see a summary of files checked and their validation status. If any files have errors, the CLI prints the file path, field path, and what went wrong. See Error Messages for details.

You can also validate individual files or use --schema to force a specific schema type:

choochoo validate openapi.yaml --schema openapi
choochoo validate contract.yaml --schema odcs

3. Generate agent context

Compile startup context for your agents from the repo:

choochoo context generate

This produces AGENTS.md — a document your AI agent reads at session start to understand what's in scope, what's off-limits, and what schemas apply. See Context Compilation for details.

4. Connect your coding agent

ChooChoo can auto-detect coding agents (Claude Code, Cursor, OpenCode, Gemini CLI, Codex) on your machine and install trace hooks so every AI-assisted change gets recorded.

# See what agents are installed
choochoo trace hooks scan

# Install trace hooks into their config files
choochoo trace hooks install

Use --dry-run to preview changes before writing. See Agent Trace for more on how tracing works.

Next steps

• CLI Reference — Full reference for all available commands and flags.
• Agent Trace — Understand how ChooChoo records who changed what and why.
• CI/CD Integration — Add choochoo validate to your Git pipeline.
• Context Compilation — How AGENTS.md is generated and kept up to date.