ChooChoo uses a minimal configuration approach. Most behavior is controlled by CLI flags rather than config files.

Project data

.choochoo/ directory

The .choochoo/ directory in your project root stores local data:

File	Purpose
traces.jsonl	Agent trace records (newline-delimited JSON)

This directory is created automatically when you run choochoo trace record or when trace hooks fire.

Content directory

The content directory (default: ./choochoo/docs) holds your documentation and spec files. It is created by choochoo init and used by choochoo tui, choochoo web, and choochoo validate.

User data

~/.choochoo/

Authentication credentials from choochoo auth login are stored in your home directory. Tokens expire after 90 days.

Environment variables

Variable	Purpose	Default
CHOOCHOO_CONTENT_DIR	Content directory for tui and web commands	./choochoo/docs

choochoo.toml — Project Configuration

choochoo.toml in your project root is the single source of truth for governance policies, context compilation settings, and validation behavior. It is versioned alongside your code.

Annotated example

# ── Context compilation ───────────────────────────────────────────────────────
[context]
# Automatically regenerate AGENTS.md after every commit.
auto_regenerate = true

[context.skills]
# Glob patterns pointing to skill files ChooChoo injects into agent context.
sources = ["skills/**/*.md"]

# ── Governance ────────────────────────────────────────────────────────────────
[governance]
# Paths that always require human review, regardless of risk score.
require_review = ["contracts/**", "auth/**", "pii-tagged-schemas/**"]

[governance.risk]
# Changes below this score are auto-approved.
auto_approve_threshold = 3.0
# Changes above this score are blocked until a human approves.
require_approval_above = 7.0

[governance.approval]
# Where to send approval notifications (Slack channel or email).
notify_channel = "slack:#ai-governance"
# If true, CI holds (exit code 10) until the approval is granted.
blocking = true
# Auto-reject if no response within this many minutes.
timeout_minutes = 60

# ── Validation ────────────────────────────────────────────────────────────────
[validate]
# Pin schema versions to prevent unexpected breaking changes.
[validate.schema_versions]
odcs = "3.1.0"
openapi = "3.1"

Known keys

Key path	Type	Default	Description	Status
context.auto_regenerate	bool	false	Regenerate AGENTS.md after each commit	Live
context.skills.sources	string[]	[]	Glob patterns for skill files	Live
governance.require_review	string[]	[]	Paths that always require approval	Live
governance.risk.auto_approve_threshold	float	3.0	Risk scores below this are auto-approved	Preview
governance.risk.require_approval_above	float	7.0	Risk scores above this block until approved	Preview
governance.approval.notify_channel	string	—	Slack/email destination for approval requests	Preview
governance.approval.blocking	bool	true	If true, CI exits with code 10 until approved	Preview
governance.approval.timeout_minutes	int	60	Minutes before an unanswered request is auto-rejected	Preview
validate.schema_versions.*	string	latest	Pin a schema type to a specific version	Live

"Live" keys are enforced by the current CLI release. "Preview" keys are parsed and validated but governance features require The Station (Phase 2).

Related

• CLI Reference — Full command reference with all available flags.
• Error Messages — Exit codes and validation error reference.
• Context Compilation — How AGENTS.md is generated using context.* settings.