docs/doc/developer/apps/OpenSource.mdx
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]
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
```bash
git clone https://github.com/YOUR_USERNAME/omi.git
cd omi
```
```bash
mkdir plugins/your-app-name
cd plugins/your-app-name
```
Use lowercase, hyphens for spaces (e.g., `meeting-summarizer`, `crm-sync`, `daily-journal`).
| 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>
```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
```
- [ ] 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 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)
Our team will review your PR against these criteria:
<AccordionGroup> <Accordion title="Code Quality" icon="code"> - Clean, readable code - No unnecessary dependencies - Proper error handling - No hardcoded secrets or credentials </Accordion> <Accordion title="Documentation" icon="book"> - Complete README with setup instructions - `.env.example` with all required variables - Clear explanation of what the app does </Accordion> <Accordion title="Self-Contained" icon="box"> - App runs independently from its directory - All dependencies listed in `requirements.txt` - No modifications to core Omi code </Accordion> <Accordion title="Community Guidelines" icon="heart"> - Respects user privacy - No harmful or inappropriate content - Provides genuine value to users </Accordion> </AccordionGroup>Significant open-source contributions earn rewards:
| Contributions | Reward |
|---|---|
| 1 merged PR | Free DevKit device (necklace or glasses) |
| 2+ merged PRs | Additional DevKit + community recognition |