An agent harness is a wrapper around an AI coding tool (Claude Code, Gemini CLI, OpenCode, Codex) that provides it with structured startup context, enforces behavioral boundaries, and records every decision as a trace.

ChooChoo treats agents as first-class registered entities. Every agent operating in a governed repository is declared in AGENTS.md, which the LLM reads at session start to understand what it can and cannot do.

AGENTS.md — Agent Context Document

AGENTS.md is not just a registry — it is a context document that the LLM reads every time it starts. It tells the agent:

• What files and directories are in scope
• What tools it is permitted to use
• What actions require human approval
• What schemas and standards apply
• What the codebase's conventions are

ChooChoo generates and maintains AGENTS.md automatically via choochoo context generate. You can also author it manually.

Example AGENTS.md

# Registered Agents

## Claude Code

**ID:** `claude-code`
**System Card:** `system-cards/claude-code.yaml`
**Status:** `active`

### Capabilities

- Read codebase
- Propose and apply code changes
- Run tests via `mise run test`
- Validate schemas via `choochoo validate`

### Boundaries

- Cannot modify `contracts/` without human review
- Cannot push to `main` directly
- Cannot read fields tagged `pii`
- No access to production environment variables

Supported Harnesses

ChooChoo hooks into coding agents via their native hook/event systems:

Harness	Hook Mechanism	Auto-install
Claude Code	.claude/settings.json hooks	choochoo trace hooks install
Cursor	.cursor/hooks.json	choochoo trace hooks install
Gemini CLI	~/.gemini/settings.json	choochoo trace hooks install
OpenCode	opencode.json	choochoo trace hooks install
Codex	~/.codex/config.yaml	choochoo trace hooks install

Run choochoo trace hooks scan to detect which agents are installed on your machine, then choochoo trace hooks install to wire them up automatically.

Using ChooChoo with multiple agents (BYOA)

ChooChoo is Bring Your Own Agent. The same AGENTS.md, choochoo.toml, and skills/ directory apply to every agent in your repository — you choose the agents, and ChooChoo provides uniform governance across all of them.

Wiring up multiple agents

# Step 1: Detect all supported agents installed on this machine
choochoo trace hooks scan

# Step 2: Install trace hooks for each detected agent
choochoo trace hooks install

# Step 3: Verify — after your next session with each agent,
# confirm that traces show different tool.name values
choochoo trace list --since 1d --format json | jq '.[].tool.name' | sort -u

You should see output like:

"claude_code"
"cursor"
"gemini_cli"

What "uniform governance" means in practice

What you configure	Where it lives	Applies to
Agent boundaries	AGENTS.md	All agents
Governance policies	choochoo.toml	All agents
Skill files	skills/**/*.md	All agents
System Cards	system-cards/*.yaml	Per-agent identity

Each agent gets its own System Card (declaring its unique capabilities and limitations), but operates within the shared AGENTS.md boundary declarations and choochoo.toml policy. The trace log captures tool.name on every record so you can filter by agent when reviewing fleet activity.

Agent Capabilities

When you register an agent, you declare its capabilities explicitly. These declarations are used by the validation engine to enforce boundaries and by Context Compilation to build accurate startup context:

systemCardSpecification: "1.0.0"
info:
  id: claude-code
  name: Claude Code
  version: "1.x"
  owner: [email protected]
  description: AI coding agent integrated with Claude Code CLI

intendedUse:
  - Code generation and refactoring
  - Test writing
  - Schema validation

limitations:
  - No access to production environments
  - Cannot modify financial data without approval

Agent Rails (Boundaries)

Boundaries defined in AGENTS.md are enforced by the ChooChoo Engine. An agent that attempts a boundary-violating action receives error E007.

Boundary Type	Description
read-only	Agent cannot modify artifacts of specific types.
no-pii	Agent receives redacted values for PII fields.
requires-approval	Agent actions require human review before proceeding.
env-restricted	Agent cannot operate in specific environments (e.g., production).
scope-limited	Agent is restricted to specific file paths.

Writing AGENTS.md manually

ChooChoo generates AGENTS.md automatically via choochoo context generate, but you can also hand-author or edit it directly.

Required sections

A valid AGENTS.md must contain at minimum:

1. Registered Agents — one ## section per agent, with ID, System Card, and Status fields
2. Capabilities — a bullet list of what the agent is permitted to do
3. Boundaries — a bullet list of what the agent is not permitted to do (these are enforced)

# Registered Agents

## My Agent

**ID:** `my-agent`
**System Card:** `system-cards/my-agent.yaml`
**Status:** `active`

### Capabilities

- Read all source files
- Propose code changes

### Boundaries

- requires-approval: contracts/**
- read-only: src/auth/**
- scope-limited: src/

Boundary syntax

The following keywords in boundary bullet points trigger enforcement:

Keyword	Effect
requires-approval	Actions on matching paths require human sign-off
read-only	Agent may read but not modify matching artifacts
scope-limited	Agent is restricted to the listed paths
no-pii	Agent receives redacted values for PII-tagged fields

What happens at a boundary

When an agent attempts an action that violates a declared boundary, ChooChoo raises error E007. The action is blocked; the trace record is written with outcome: blocked.

To debug boundary violations: choochoo trace list --outcome blocked --agent <id>.

Choosing the right boundary type:

• Use requires-approval for sensitive paths where the agent can act but needs sign-off (contracts, auth, financial schemas).
• Use read-only when the agent should be able to use a file for context but must never modify it.
• Use scope-limited to contain an agent to a subsystem entirely.

AGENTS.md in CI

AGENTS.md is consumed in two places:

1. Locally at session start — the agent reads it to understand scope and boundaries before taking any action.
2. In CI via choochoo validate — the validation command checks that boundary declarations in AGENTS.md are consistent with actual agent permissions and that all referenced System Cards exist.

# .github/workflows/choochoo.yml (excerpt)
- name: Validate AGENTS.md and specs
  run: choochoo validate . --quiet

This keeps declared scope and actual permissions in sync: if an agent's capabilities expand (e.g. a new tool is registered), CI flags the discrepancy until AGENTS.md is updated to reflect it.

Evaluation

Every action an agent takes is recorded as an Agent Trace. Traces accumulate in .choochoo/traces.jsonl and can be used to:

• Benchmark agent quality against task suites (SWE-Bench, ITBench, custom)
• Surface quality scores in The Station dashboard
• Provide signal for prompt optimization and fine-tuning

CLI Commands

Dedicated agent-management commands (choochoo agent list|register|audit) are scheduled for the next CLI release — see the Planned commands section for status.

Today, list configured agent harnesses by inspecting AGENTS.md directly, and filter the trace log by agent name:

choochoo trace list --json | jq '.[] | select(.tool.name == "claude_code")'

See the CLI Reference for full documentation.

Related

• Agent Trace — How AI decisions are recorded and persisted.
• Context Compilation — How AGENTS.md is generated from your codebase.
• Governance (Preview) — Audit trail, risk scoring, and approval workflows.
• Supported Schemas — Schema types ChooChoo validates.