Contributing

The One Rule

You must understand your code. If you cannot explain what your changes do, a maintainer will ask for clarification before merging.

Using AI to write code is fine. Submitting AI-generated code without understanding it isn't.

Contribution Gate

First-time contributors start with an Issue or Discussion, not a PR. Maintainers reply lgtmi (issues) or lgtm (issues + PRs) to approve. Once approved, you can submit PRs directly.

Setup

Prerequisites: Bun ≥ 1.0, uv (macOS MLX only).

git clone https://github.com/<your-username>/Brain.git
cd Brain
git remote add upstream https://github.com/the-brain-dev/The-Brain.git
./install.sh

Workflow

Fork → feature branch → PR against main. Direct pushes are blocked.

git fetch upstream
git checkout -b feat/your-feature upstream/main

# Write code, following AGENTS.md conventions

bun test --coverage && bun run lint    # must pass
cd apps/docs && bun run build          # docs compile clean

git add <specific-files>               # targeted add only
git commit -m "type(scope): description"
git push origin feat/your-feature

Branch prefixes: feat/, fix/, refactor/, docs/, chore/. Lowercase, hyphen-separated.

Create a changeset to document your changes:

bunx changeset

Before Submitting

bun test --coverage — >80% line coverage for new code
bun run lint — zero errors
cd apps/docs && bun run build — docs compile clean

Philosophy

Core is minimal. New features should be plugins. PRs that bloat the core will likely be rejected. Read PHILOSOPHY.md for the full vision.