omi Documentation

File: README.md Copy Chapter

Quick Start Copy Chapter

macOS Copy Section

git clone https://github.com/BasedHardware/omi.git && cd omi/desktop/macos && ./run.sh --yolo

Builds the macOS app, connects to the cloud backend, and launches. No env files, no credentials, no local backend.

Requirements: macOS 14+, Xcode (includes Swift & code signing), Node.js

Windows Copy Section

git clone https://github.com/BasedHardware/omi.git
cd omi\desktop\windows
npm install
copy .env.example .env
npm run dev

Starts the Windows desktop app from source using the public config in .env.example.

Requirements: Node.js

For development worktrees, run the baseline local setup once. It installs the Git hooks and syncs the pinned backend Python environment used by selected pre-push checks; mobile and desktop runtime environments remain opt-in.

make setup

Full Installation

For local development with the full backend stack:

1. Install prerequisites

xcode-select --install
uv --version

2. Clone and configure

git clone https://github.com/BasedHardware/omi.git
cd omi/desktop/macos
cp ../../backend/.env.example ../../backend/.env

3. Build and run

./run.sh

See desktop/macos/README.md for environment variables and credential setup.

Mobile App Copy Section

cd app && bash setup.sh ios    # or: bash setup.sh android

How it works

┌─────────────────────────────────────────────────────────┐
│                      Your Devices                       │
│                                                         │
│  ┌──────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │ Omi      │  │ macOS App    │  │ Mobile App        │  │
│  │ Wearable │  │ (Swift/Python) │  │ (Flutter)         │  │
│  └────┬─────┘  └──────┬───────┘  └────────┬──────────┘  │
│       │    BLE         │   HTTPS/WS        │             │
└───────┼────────────────┼───────────────────┼─────────────┘
        │                │                   │
        ▼                ▼                   ▼
┌─────────────────────────────────────────────────────────┐
│                    Omi Backend (Python)                  │
│                                                         │
│  ┌─────────┐  ┌──────────┐  ┌─────────┐  ┌──────────┐  │
│  │ Listen  │  │ Pusher   │  │ VAD     │  │ Diarizer │  │
│  │ (REST)  │  │ (WS)     │  │ (GPU)   │  │ (GPU)    │  │
│  └─────────┘  └──────────┘  └─────────┘  └──────────┘  │
│                                                         │
│  ┌─────────┐  ┌──────────┐  ┌─────────┐  ┌──────────┐  │
│  │ Deepgram│  │ Firestore│  │ Redis   │  │ LLMs     │  │
│  │ (STT)   │  │ (DB)     │  │ (Cache) │  │ (AI)     │  │
│  └─────────┘  └──────────┘  └─────────┘  └──────────┘  │
└─────────────────────────────────────────────────────────┘

Documentation Copy Chapter

Getting Started Copy Section

• Introduction
• Quick Start Guide
• macOS App Development
• Mobile App Setup
• Backend Setup
• Contributing — also CONTRIBUTING.md and PRODUCT.md

Building Apps Copy Section

• App Development Guide
• Example Apps — GitHub, Slack, OmiMentor
• Audio Streaming Apps
• Custom Chat Tools
• Submit to App Store

API & SDKs Copy Section

• API Reference — REST endpoints for memories, conversations, action items
• Device multi-lang protocol SDKs — shared BLE UUIDs/packet framing for TS/Go/Rust/C++/Dart
• Python device SDK — full BLE + Opus + Deepgram
• Swift device SDK
• React Native device SDK
• MCP Server — Model Context Protocol integration

Architecture Copy Section

• Backend Deep Dive
• Transcription Pipeline
• Chat System
• Audio Streaming Pipeline
• BLE Protocol

Omi Hardware Copy Chapter

Open-source AI wearables that pair with the mobile app for 24h+ continuous capture.

• Buy Omi
• Buy Omi Glass Dev Kit — ESP32-S3, camera + audio
• Open Source Hardware Designs
• Buying Guide
• Build the Device
• Flash Firmware
• Integrate Your Wearable
• Hardware Specs

License Copy Chapter

MIT — see LICENSE

File: docs/README.md Copy Chapter

Mintlify Starter Kit

Click on Use this template to copy the Mintlify starter kit. The starter kit contains examples including

• Guide pages
• Navigation
• Customizations
• API Reference pages
• Use of popular components

/Development Copy Section

Install the Mintlify CLI to preview the documentation changes locally. To install, use the following command

npm i mintlify

Run the following command at the root of your documentation (where docs.json is)

mintlify dev

Publishing Changes Copy Section

Install our Github App to auto propagate changes from your repo to your deployment. Changes will be deployed to production automatically after pushing to the default branch. Find the link to install on your dashboard.

Troubleshooting

• Mintlify dev isn't running - Run mintlify install it'll re-install dependencies.
• Page loads as a 404 - Make sure you are running in a folder with docs.json