Skip to main content

Will this be accepted?

Before you write code, check product fit:
  • Read PRODUCT.md: memory-first loop, one shared chat mind, trust over cleverness, integrations harness, taste floor.
  • Check the product invariant registry. Locked invariants (for example one shared transcript across notch and main chat) are binding; PRs that touch their paths must name the invariant ID.
  • Large or ambiguous features should start as a GitHub issue so maintainers can align on scope and direction before major implementation work begins.
When maintainers decline a PR for direction or taste, they cite an invariant ID or open a proposed invariant the same week. Project direction stays written down.

How to contribute

1

Fork the Repository

Go to github.com/BasedHardware/Omi and click Fork.
2

Make Your Changes

Clone your fork, create a branch, and implement your changes.
3

Test Your Changes

Add focused tests. Record the commands or manual steps you used to verify the change.Before you push, run make preflight. Then draft the PR body and run scripts/pr-preflight --pr-body-file /path/to/draft-pr-body.md to check invariant citations and any required failure-class declaration. Run scripts/pr-preflight --suggest before you draft the body to get the paste-ready invariant section and failure-class guidance. The manifest-backed checks are identical locally and in CI.
4

Create a Pull Request

Submit a PR and specify which issue it relates to. Name any product invariants your change affects.

What we want most

  • Bug reports with reproductions. An issue with logs, steps, or a failing test is often more valuable than a rushed fix.
  • Apps and integrations built on the platform. See Apps and open-sourcing your app.
  • Community ports. Windows/Linux clients, new device integrations, firmware variants.
  • Core PRs remain welcome under the quality bar below.
Core work is occasionally posted as a paid bounty with a public proof spec.

Recognition

Contributors who land significant work get the Contributor role in Discord, and the team occasionally sends hardware or credits to standout contributors. Contributors who consistently ship strong work may be invited to work more closely with the team.

Pull request quality bar

Good PRs are easy to review and come with evidence that the change works.
  • Bug fixes include the regression test that would have caught the bug.
  • Small features can go straight to a PR when well scoped: test the core path and the main error path.
  • Large or ambiguous features start as an issue so maintainers can agree on scope first.
  • Show your verification. List the commands you ran and what they showed. “It compiles” is not evidence; exercising the real user-facing path is.
  • Tests in CI are hermetic: no live services, no network. Live validation is welcome as extra evidence, never as the only proof.
  • Name product invariants you touch (for example INV-CHAT-1) in the PR body.
  • Run make preflight before pushing, then scripts/pr-preflight --pr-body-file <draft> to validate the PR body.
The repository has more specific rules for some kinds of change. Your agent or make preflight will point you to the relevant one; the details are below.
Classify reactive fixes. A fix: commit responds to a triggering defect and must declare exactly one of Failure-Class: FC-<slug>, Failure-Class: new or Failure-Class: none in its PR body. Every class belongs to one contract family (.github/failure-class-families.json); reuse a class in the family before declaring new. A harden: commit strengthens a boundary or contract without a triggering incident; it may cite a class but needs no declaration. The validator is offline and required; its report command is advisory and only identifies classes eligible for a maintainer to mark dormant.Keep instance fixes compact. An existing-class declaration replaces the root-cause and durable-guard narrative. Provide that extended narrative only when declaring new, changing a class’s canonical prevention primitive or owner, or making a registry-only lifecycle transition. An instance-fix PR never edits registry data. To mark a class dormant, a separate registry-only PR sets status to dormant with a UTC ISO-8601 dormant_since. When report flags a recurrence after that timestamp, merge a separate registry-only reopen PR that sets status to open and removes dormant_since, then classify the instance fix. IDs use stable semantic lower-kebab slugs such as FC-malformed-doc-read; use scripts/failure-class prepare or explain for the exact field and relevant context.Temporary Git fixtures must clear the variables reported by git rev-parse --local-env-vars, plus GIT_NAMESPACE, before running Git or checks that invoke Git. scripts/pr-preflight resolves and enters the selected worktree before clearing this environment for its child checks; standalone Python script fixtures can use scripts/git_test_env.py.Prefer primitives to guards. Before adding a check or ratchet, answer in the PR body: “Why isn’t this a shared primitive instead?” A new guard must cite the real merged PR or incident it would have caught; no real instance means the check does not land.
CI on fork PRs: fork PRs run the cheap checks (Hygiene, Formatting, metadata, affected backend/Python units, Static Contracts, and OpenAPI). App PRs also run Dart Analyze & Tests (the analyzer ratchet and regular Flutter tests), including forks without ci:full. Mobile Release Eligibility fails if selected Flutter coverage did not run and pass. Once maintainers require that status on main, app PRs cannot merge without passing Flutter coverage. Generated-file checks, iOS compile, Android compile and JVM tests, emulator acceptance, seeded journeys, slow backend guardrails, and the Windows Python ACL check still wait for full CI on fork PRs. When a contribution is ready for full review, ask a maintainer to add the ci:full label, then use Re-run all jobs on the PR’s latest commit. CI reads the current labels on rerun; adding a label alone does not start new workflows or cancel an in-flight run. The label persists across new commits, which then get full CI automatically. Heavy aggregate checks name this flow when coverage is deferred.Backend hermetic gate: every PR reports Backend Hermetic Merge Gate. Affected full-tier PRs run the backend E2E harness; emulator gauntlets run for their integration inputs, main, and nightly. A cheap-tier fork reports deferral instead of a green heavy-check verdict.Behavioral tests execute production behavior. Source-string assertions are static tripwires only; they do not prove lifecycle, concurrency, or integration behavior.
Fast local deterministic checks: run make preflight. Selection includes staged, unstaged, and untracked files; commit-based checks still need a final run after committing. New deterministic diff-scoped checks belong in .github/checks-manifest.yaml, never directly in workflow YAML.PR metadata contract check: draft the body, then run scripts/pr-preflight --pr-body-file /path/to/draft-pr-body.md. Use scripts/pr-preflight --suggest when you need the paste-ready invariant section. Once the branch has a PR, scripts/pr-preflight reads its current body automatically with gh (or set OMI_PR_BODY_FILE). Pre-push runs these same contracts. When editing only the PR body, use scripts/pr-preflight --metadata-only --pr-body-file /path/to/draft-pr-body.md. This runs every applicable metadata-dependent check and reports all failures together. CI uses this mode for title, body, and label edits; code updates still run the full preflight. Metadata success validates the PR description and does not replace the source-code verdict.CI budget: when adding or changing a workflow or job, run python3 .github/scripts/check_ci_budget.py --refresh, then review .github/ci-budget.yaml. Set a p50 runtime budget, expected PR runs per day, owner, and rationale for new jobs. A wider trigger, larger matrix, runner change, or raised budget needs an explicit budget and rationale edit in the same PR. After CI diet changes merge, re-seed measured fields with --refresh --reseed --seed-dayruns <dayruns.tsv> --seed-dayjobs <dayjobs.tsv> and review the diff. The checked-in caps cover PR Linux and macOS runner minutes per day and internal time-to-signal. The weekly audit samples completed PR runs with GITHUB_TOKEN, publishes a report artifact, and updates one tracking issue on overrun or insufficient samples.
The capture ownership contract defines constructor seams, session generations and staged recovery/foreground ownership handoffs. Declare completed file/rule adoption in app/contracts/capture/boundary-baseline.json. Only adopted files and new files are constrained; ordinary legacy-file growth stays unblocked. Diagnostics name the request interface to use. Run TZ=UTC bash app/test.sh for the protected contracts. Pending tests execute and fail on unexpected success; builders remove only their pending marker.For native BLE changes, distinguish a connected radio from device audio setup. The device lifecycle architecture describes late readiness after a launch timeout and the Limitless regression path.
Backend compatibility checks cover adopted released-client shapes in contracts/client-compat/. Preserve fields and request forms those clients use; new unused endpoints stay unrestricted. A failure identifies the release and field: restore compatibility or version the endpoint, rather than editing a historical fixture. Replay uses synthetic records in the existing backend E2E suite; a successful build tag alone is not proof of store distribution.
For typed mobile analytics, add events and executable consumer references to contracts/analytics/events.json, then run python3 scripts/check_event_registry.py --write and commit the generated Dart API and tracking plan. Preserve emitted names and properties during migration. The raw-call check covers adopted files; new and existing unadopted files stay unrestricted. See app/lib/utils/analytics/registry/REGISTRY.md for batch tests.

Contributing with an AI agent

Omi is built to be agent-friendly. If you use an AI coding agent, it will automatically pick up AGENTS.md at the repo root (plus per-component guides in backend/, app/, and desktop/macos/). The root guide routes to component instructions and repository conventions. The PR quality requirements above apply to all contributions; maintainer-machine instructions apply only when using those machines.

Documentation contributions

Docs live in the GitHub docs folder and sync with docs.omi.me. The docs have a style guide and deterministic checks (broken links, navigation, generated pages). See docs/AGENTS.md before writing.

Get started

Development setup

Run the app, backend, and firmware locally

Bounties

Team-posted paid tasks with a proof spec

Community & code of conduct

Discord, conduct, and contacts

GitHub Issues

Browse open issues