Contributing to the main repo

You contribute code and documentation to the main OrcAI repository through a branch, local checks and a pull request.

Before you startCopy Anchor Link

• Use Bun >=1.3.10.
• Start the per-worktree stack as described under Recommended workflow.
• Create a branch from the latest main branch.

Typical contribution flowCopy Anchor Link

1. Update main and create a feature or fix branch.
2. Implement your changes.
3. Run the relevant checks locally.
4. Commit using Conventional Commit format.
5. Open a pull request with clear scope and validation notes.

Branch namingCopy Anchor Link

Use short, descriptive branch names, for example:

• feat/chat-branch-switcher-fixes
• fix/repository-playground-empty-state
• docs/self-hosting-config-update

Commit message formatCopy Anchor Link

commitlint (@commitlint/config-conventional) checks every commit message.

Use Conventional Commits, for example:

• feat(chat): add branch filter to chat list
• fix(workers): handle missing qdrant payload field
• docs(self-hosting): clarify spicedb security modes

Local validationCopy Anchor Link

While iterating, run Biome, the TypeScript check, the migration check and the unit tests. None of them needs the stack.

bun run verify

Before you open a pull request, run what the validate job in CI runs. It adds ESLint, the docs type check and the production build.

bun run ci

If your change touches user-facing flows, run the end-to-end suite as well. It needs the stack running and resets the stack's data, see End-to-end tests.

bun run stack e2e

Git hooks and CICopy Anchor Link

• pre-commit runs lint-staged, which applies Biome's safe fixes and formatting to the staged files and fails on remaining errors. Biome lints Markdown but does not format it, because it pads table columns.
• commit-msg runs commitlint.
• pre-push runs bun run prepush, which is bun run lint-full.

GitHub Actions runs bun run ci and the end-to-end suite as two blocking checks, validate and e2e, for pushes to main and for pull requests. Pull requests that only touch docs content or Markdown skip the end-to-end suite. Pull request runs check the branch merged into main, so rebase onto main when CI fails on something a local run passes.

Pull request expectationsCopy Anchor Link

Include the following in your PR description:

• What changed and why.
• Risk level and impacted areas (apps/app, apps/workers, apps/web, packages/*).
• Validation performed (commands run and outcomes).
• Screenshots for user-facing UI changes.
• Any TODOs or follow-up work.

Documentation contributionsCopy Anchor Link

If your change modifies user flow, operations, or configuration behaviour, update the relevant docs in apps/web/content/docs and README.md in the same change.

A docs page is an MDX file in a section folder under apps/web/content/docs. List it in that folder's meta.json, which sets the sidebar order, and give it a title and a description in its frontmatter. Check the page and its links with bun run --filter @orcai/web build.

The OrcAI Assistant answers from these pages. The docs site serves an index at /llms.txt with each page's title, URL and description, every page as Markdown at /docs/<page>.md, and all pages in one file at /llms-full.txt. The Assistant reads the index first and picks pages by their description, so the description names what the page covers. It fetches from WEB_INTERNAL_URL, or WEB_URL when that is unset, see Configuration.

Any change to UI strings, emails or docs pages uses the terms in the Glossary, in English and German, and follows the writing skill in .agents/skills/writing/. Coding agents load the skill on their own.

Model-facing textCopy Anchor Link

System prompts, tool and parameter descriptions, structured-output instructions and the text tools return to the model follow the prompting skill in .agents/skills/prompting/. Coding agents load it on their own.

Run the prompt evals before and after such a change and put the comparison in the pull request:

bun run prompt-evals                                   # on the unchanged code
bun run prompt-evals --compare <results file>          # on the change

The evals call real models through OpenRouter with the key in OPENROUTER_API_KEY or ~/.config/orcai/openrouter.env, and a full run costs about $0.30. PROMPT_EVALS_ENDPOINT points them at another OpenAI-compatible endpoint. .agents/skills/prompting/EVALS.md describes the flags, the cases and how to add one.

Generated and derived filesCopy Anchor Link

After adding, moving or deleting a route file, run the app or docs site once and commit the updated route tree.

Security reportsCopy Anchor Link

Do not open a public issue for a suspected vulnerability. Follow the private reporting process in the repository's SECURITY.md.

Contribution licenceCopy Anchor Link

OrcAI is licensed under the GNU Affero General Public License, version 3 only (AGPL-3.0-only). By submitting a contribution, you agree to license it under the same terms and confirm that you have the right to do so. Do not submit code or assets whose licence is incompatible with the AGPL.