OpenSource.mdx

title	Open Source Your App
icon	code-branch
description	Contribute your Omi app to the open-source repo. Share your code with the community, get visibility, and help other developers learn from your work.

Overview

Beyond publishing to the Omi app store, you can open-source your app by contributing it to the BasedHardware/omi repository. This gives your app maximum visibility, lets other developers learn from and build on your work, and contributes to the Omi ecosystem.

flowchart LR
    B[Build Your App] --> T[Test Locally]
    T --> F[Fork the Repo]
    F --> A[Add Your App]
    A --> PR[Open a PR]
    PR --> R[Review & Merge]
    R --> C[🎉 Community Access]

Loading

Your app is discoverable by thousands of Omi developers Significant contributions earn free DevKit hardware

---

Repository Structure

Open-source apps live in the plugins/ directory:

omi/
├── plugins/
│   ├── your-app-name/
│   │   ├── README.md          # Required: documentation
│   │   ├── requirements.txt   # Python dependencies
│   │   ├── main.py            # Entry point
│   │   ├── .env.example       # Environment variable template
│   │   └── ...                # Your app code

Each app should be a self-contained directory with everything needed to run it independently.

---

Step-by-Step Guide

Go to [github.com/BasedHardware/omi](https://github.com/BasedHardware/omi) and click **Fork** to create your own copy.

```bash
git clone https://github.com/YOUR_USERNAME/omi.git
cd omi
```

Create a new folder under `plugins/` with a descriptive name:

```bash
mkdir plugins/your-app-name
cd plugins/your-app-name
```

Use lowercase, hyphens for spaces (e.g., `meeting-summarizer`, `crm-sync`, `daily-journal`).

Structure your app with these files at minimum:

| File | Required | Description |
|------|----------|-------------|
| `README.md` | ✅ | Documentation (see template below) |
| `main.py` | ✅ | App entry point |
| `requirements.txt` | ✅ | Python dependencies |
| `.env.example` | ✅ | Environment variable template (no secrets!) |
| `.gitignore` | Recommended | Ignore `.env`, `__pycache__/`, etc. |

<Warning>
**Never commit secrets, API keys, or credentials.** Use `.env.example` with placeholder values and add `.env` to `.gitignore`.
</Warning>

Your README is the first thing developers see. Include:

```markdown
# Your App Name

Brief description of what your app does.

## Features
- Feature 1
- Feature 2

## How It Works
Explain the architecture and how it integrates with Omi.

## Setup

### Prerequisites
- Python 3.8+
- Any external service accounts needed

### Installation
1. Clone the repo
2. `pip install -r requirements.txt`
3. Copy `.env.example` to `.env` and fill in your values
4. Run `python main.py` or `fastapi run`

### Environment Variables
| Variable | Description |
|----------|-------------|
| `API_KEY` | Your API key for X service |

## Registering with Omi
Explain how to register the app (webhook URLs, etc.)

## Usage
How users interact with the app once it's running.

## License
MIT
```

Before submitting, make sure:

- [ ] App runs from a clean install following your README
- [ ] All environment variables are documented in `.env.example`
- [ ] No hardcoded secrets or API keys in the code
- [ ] Webhooks handle errors gracefully
- [ ] Code is clean and reasonably commented

```bash git checkout -b add-your-app-name git add plugins/your-app-name/ git commit -m "feat: add your-app-name plugin" ``` Push your branch and open a PR against `main`:

```bash
git push origin add-your-app-name
```

Then go to GitHub and create a Pull Request with:
- **Title:** `feat: add [your-app-name] plugin`
- **Description:** What the app does, how to use it, and any relevant context
- **Screenshots/demo** (if applicable)

---

PR Review Checklist

Our team will review your PR against these criteria:

- Clean, readable code - No unnecessary dependencies - Proper error handling - No hardcoded secrets or credentials - Complete README with setup instructions - `.env.example` with all required variables - Clear explanation of what the app does - App runs independently from its directory - All dependencies listed in `requirements.txt` - No modifications to core Omi code - Respects user privacy - No harmful or inappropriate content - Provides genuine value to users

---

Tips for a Successful Contribution

A well-documented simple app is better than a complex, undocumented one Include screenshots, GIFs, or a demo video in your README Respond to review feedback quickly to get your PR merged faster Look at existing apps in `plugins/` for style and structure inspiration

---

Contribution Rewards

Significant open-source contributions earn rewards:

Contributions	Reward
1 merged PR	Free DevKit device (necklace or glasses)
2+ merged PRs	Additional DevKit + community recognition

See the full [Contribution Guide](/doc/developer/Contribution) for details on rewards and bounties.

---

Related Documentation

Submit your app to the Omi app store (no code required) Learn how to build Omi apps from scratch General contribution guidelines and rewards Build webhook-based integrations