Skip to main content
Bug fixes, features, docs and tests are all welcome. AI-assisted pull requests are fine: just say so. For a large change, open an issue or discussion first, so we agree on the approach.
1

Fork and clone

Fork the repository on GitHub, then clone your fork and add the original as upstream:
Then follow Set up for development from step 2.
2

Create a branch from master

master is the only long-lived branch.
3

Make the change, with a test

Follow the CLAUDE.md in the folder you change (see Project tour). New behavior ships with a test. A bug fix ships with a test that fails without the fix. See Testing.
4

Run the checks

Add the tests for what you changed. mise run lint:fix and mise run lint:py:fix fix most lint findings.
5

Commit

Use a conventional commit message.
With the hooks installed (mise run pre-commit:install), commits run the linters, and pushes run the CI checks your change affects. That can take a few minutes.
6

Merge master if it moved

Use a merge, not a rebase:
7

Push and open the pull request

Open the pull request against master. Its title uses the same format as a commit, and CI rejects any other. See the allowed types.
8

Fill in the template

Write the description for someone who has never seen your branch. Delete sections that don’t apply.
  • Summary and Why: what changes for the user, and why.
  • What changed, grouped by area.
  • The bug, for fixes: root cause and how the fix addresses it.
  • Screenshots for anything visual.
  • How to verify: steps a reviewer can follow.

​
What happens next

  1. CI runs on every push. Open a failed check to read its log.
  2. A maintainer reviews and may comment.
  3. Push more commits to the same branch to answer. The pull request updates itself.
  4. A maintainer merges it once it’s approved and green.
Contributors are credited in the README, and in the release notes for significant changes.

​
Common problems

Read the log. Most failures name the file and line. The table in the repository’s CLAUDE.md maps each kind of change to its command. Run it locally, fix, commit and push.
Merge master into your branch, resolve the conflicts git reports, then commit and push.
Edit the title so it starts with an allowed type, like fix: or feat(web):. The check reruns on its own.
Need help? Ask in Discord, GitHub Discussions or on the issue.

​
Next

Architecture

How the processes, databases and AI agents fit together.