contribute

Contribute

No CLA. No sponsor lockouts. One maintainer who reads everything. Small, focused PRs with real test coverage land fastest.

find a thread to pull

Pick an issue

Browse open issues. good first issue means the path is clear. Anything ambiguous, ask first in Discussions.

Open issues →

fork and branch

Branch with intent

Fork, then git checkout -b feat/short-name. Conventional commits: feat:, fix:, docs:, refactor:, test:, chore:.

Repo on GitHub →

match the checks

Run the tests

Install dev extras and run the pytest suite before you push: pip install -e .[dev] then python -m pytest tests/ -v.

Contributing guide →

open the PR

Explain the why

The diff covers what changed; your description should cover why. Link the issue. Small, focused PRs with real test coverage land fastest.

Pull requests →

Section 01 · house rules

Build the thing, don't polish the meta.

Yes

Bug reports with reproductions, and refactors that explain the trade-off.
Tests that demonstrate a bug — even better than the fix.
Hard questions in Discussions, especially with data.

No

Drive-by AI-generated patches with no understanding of the diff.
Adding telemetry, hosted dependencies, or referral links.
Renaming things across the repo to match a personal preference.

Section 02 · the dev loop

From clone to merged.

The full sequence, copy-pasteable.

dev loop

$ # fork on github, then:
$ git clone git@github.com:YOU/clawcodex
$ cd clawcodex
$ git checkout -b feat/your-thing
$ 
$ # set up + run locally
$ python3 -m venv .venv && source .venv/bin/activate
$ pip install -e .[dev]
$ clawcodex
$ 
$ # checks
$ python -m pytest tests/ -v
$ 
$ # commit + push + PR
$ git commit -m "feat: short subject in conventional-commit form"
$ git push -u origin feat/your-thing
$ gh pr create --fill

CONTRIBUTING.md → Open issues →