We welcome contributions! ChooChoo is open source and we appreciate help from the community. Before contributing, familiarize yourself with the Architecture and Core Concepts to understand the platform.

Getting started

1. Fork the repository on GitHub.
2. Clone your fork.
3. Install dependencies: bun install.
4. Run tests: bun test.

For details on setting up a local ChooChoo project for testing, see the Installation and Quickstart guides.

Code standards

• We use oxlint + oxfmt for linting/formatting (packages), Biome for the docs app.
• All PRs must pass the CI pipeline — see CI/CD Integration.
• New features require tests (collocated *.test.ts files).
• Commit messages follow: feat:, fix:, chore:, docs:, refactor:, test:.

Areas of contribution

• Documentation: Improve or expand these docs.
• Standards: Help improve the open standards ChooChoo builds on.
• Schema validation: Improve validation rules and schema coverage.
• CLI features: Extend the CLI with new commands.
• Trace hooks: Add support for more coding agents in trace hooks.
• Bug reports: File issues with clear reproduction steps and error messages.

Reporting issues

When filing a bug report, please include:

• The choochoo --version output
• The relevant error code and the exit code from your shell (echo $?)
• Steps to reproduce the issue

Related

• Roadmap — See what's planned and where contributions are most impactful.
• Architecture — Understand the platform architecture before diving in.
• CLI Reference — Full command reference for the CLI.
• Standards Reference — The open standards ChooChoo implements.