> ## Documentation Index
> Fetch the complete documentation index at: https://omi-codex-issue-9443-memory-v3-package.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Contribution Guide

> Contribute to Omi and earn rewards! Some tasks have paid bounties.

## Will this be accepted?

Before you write code, check product fit:

* Read [`PRODUCT.md`](https://github.com/BasedHardware/Omi/blob/main/PRODUCT.md) — memory-first loop, one shared chat mind, trust over cleverness, integrations harness, taste floor.
* Check the [product invariant registry](https://github.com/BasedHardware/Omi/tree/main/docs/product/invariants). 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.

Maintainers declining a PR for direction or taste will cite an invariant ID or open a proposed invariant the same week — so “project direction” stays written down, not tribal.

***

## How to Contribute

<Steps>
  <Step title="Fork the Repository">
    Go to [github.com/BasedHardware/Omi](https://github.com/BasedHardware/Omi) and click **Fork**.
  </Step>

  <Step title="Make Your Changes">
    Clone your fork, create a branch, and implement your changes.
  </Step>

  <Step title="Test Your Changes">
    Add focused tests and include the commands or manual steps you used to verify the change. Before pushing, draft the PR body and run
    `scripts/pr-preflight --pr-body-file /path/to/draft-pr-body.md` (use `scripts/pr-preflight --suggest` to get the paste-ready invariant ID block). Pre-push runs the same cheap contracts.
  </Step>

  <Step title="Create a Pull Request">
    Submit a PR and specify which issue it relates to. Name any product invariants your change affects.
  </Step>
</Steps>

***

## Pull Request Quality

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.
* **Close the failure class.** For a bug fix, describe the violated contract and
  the durable guard. If recent history contains the same cause, fix the shared
  boundary, state model, harness, compatibility check, or static contract rather
  than adding another call-site exception.
* **Small features** can go straight to PR when they are well scoped: test the core path and the main error path, and describe any manual verification you did.
* **Large or ambiguous features** should start as a GitHub issue so maintainers can align on scope and direction before major implementation work begins.
* **Show your verification.** List the commands you ran and what they showed in the PR description. "It compiles" is not evidence — exercising the real user-facing path is.
* **Tests that run in CI must be hermetic** — no live services, no network. Validation against a live service is welcome as extra evidence, but it can never be the only proof a PR works.
* **Behavioral tests execute production behavior.** Source-string assertions are
  static tripwires only; they do not prove lifecycle, concurrency, or integration
  behavior.
* **Product invariants** — if you touch paths listed on a locked invariant, name the ID (for example `INV-CHAT-1`) in the PR body.
* **Fast local PR 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 cheap contracts.

### 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`](https://github.com/BasedHardware/Omi/blob/main/AGENTS.md) at the repo root (plus per-component guides in `backend/`, `app/`, and `desktop/macos/`). The engineering standards there — especially the **Definition of Done** checklist — apply to your PR. Rules in that file about maintainer machines and landing on `main` directly don't apply to fork-based contributions.

***

## Documentation Contributions

Docs contributions are just as important as code contributions! Our docs are located in the [GitHub docs folder](https://github.com/BasedHardware/Omi/tree/main/docs) and sync in real-time with [docs.omi.me](https://docs.omi.me).

<Tip>
  You can edit docs directly from GitHub: Fork the repo → [click the edit icon](https://share.cleanshot.com/dkBSffGr) → click "Preview" → create a pull request.
</Tip>

***

## Contribution Rewards

Get rewarded for approved PRs with significant contributions:

<CardGroup cols={2}>
  <Card title="1 PR" icon="gift">
    Free DevKit device (necklace or glasses, depending on contribution area)
  </Card>

  <Card title="2 PRs" icon="coins">
    \$100 of transcription credits
  </Card>

  <Card title="5 PRs" icon="star">
    \$500 of transcription credits + special Contributor role in Discord
  </Card>

  <Card title="10 PRs" icon="plane">
    Trip to hang out with the Based Hardware team
  </Card>
</CardGroup>

### What Qualifies as a Significant Contribution?

<AccordionGroup>
  <Accordion title="Time Investment" icon="clock">
    Something you spent 5+ hours on. Can be multiple smaller contributions that add up.
  </Accordion>

  <Accordion title="Impact" icon="bolt">
    Either a new feature or a major bug fix.
  </Accordion>

  <Accordion title="Quality" icon="check">
    Quality code with clear explanations, focused tests, and verification notes.
  </Accordion>
</AccordionGroup>

<Info>
  To claim your reward, email [team@basedhardware.com](mailto:team@basedhardware.com) with:

  * List of your contributions
  * Your address
  * Email and phone number
</Info>

***

## Paid Bounties

Get paid to improve AI wearables!

<Card title="View Paid Bounties" icon="money-bill" href="https://github.com/BasedHardware/Omi/issues?q=is:open+is:issue+label:%22Paid+Bounty+%F0%9F%92%B0%22">
  Browse open issues with the "Paid Bounty" label
</Card>

### Bounty Rules

| Rule                | Description                                                                                     |
| ------------------- | ----------------------------------------------------------------------------------------------- |
| Code must be merged | Your code must be merged into the master branch                                                 |
| Eligibility         | Bounty eligibility is solely at our discretion                                                  |
| Locking a task      | You can "lock" a bounty task, but only after your first PR is merged                            |
| Claiming payment    | Email [team@basedhardware.com](mailto:team@basedhardware.com) with bounty link + PayPal account |

### No Bounties Available?

If there are no paid bounties available, you can suggest your own:

<Steps>
  <Step title="Browse Open Issues">
    Filter by [open issues](https://github.com/BasedHardware/Omi/issues?q=is:open+is:issue) without the "bounty" label.
  </Step>

  <Step title="Suggest a Bounty">
    Comment on the issue and ping @josancamon19 or @kodjima33 with your bounty suggestion.
  </Step>
</Steps>

***

## Get Started

<CardGroup cols={2}>
  <Card title="GitHub Issues" icon="github" href="https://github.com/BasedHardware/Omi/issues">
    Browse all open issues
  </Card>

  <Card title="Paid Bounties" icon="money-bill" href="https://github.com/BasedHardware/Omi/issues?q=is:open+is:issue+label:%22Paid+Bounty+%F0%9F%92%B0%22">
    View issues with bounties
  </Card>

  <Card title="Discord" icon="discord" href="http://discord.omi.me">
    Join the community
  </Card>

  <Card title="Documentation" icon="book" href="https://github.com/BasedHardware/Omi/tree/main/docs">
    Contribute to docs
  </Card>
</CardGroup>