Getting Started & Local Setup
Relevant source files
The following files were used as context for generating this wiki page:
Omi is a multi-platform ecosystem designed for real-time conversation capture, transcription, and AI-driven insights. It consists of a macOS desktop application, a Flutter-based mobile application, a Python backend, and specialized firmware for wearable hardware. The project supports various setups ranging from a "YOLO" quick start (connecting to cloud services) to full-stack local development environments.
Sources: README.md:1-12, README.md:105-115
Quick Start (macOS)
For users who want to run the application immediately without configuring local backends or credentials, the project provides a "YOLO" script. This builds the macOS application and connects it directly to the Omi cloud backend.
git clone https://github.com/BasedHardware/omi.git && cd omi/desktop && ./run.sh --yolo
System Requirements
- OS: macOS 14+
- Tools: Xcode (includes Swift & code signing), Node.js, Rustup/Rust (for the desktop backend)
Sources: README.md:19-30, README.md:38-42
Component-Specific Setup
The Omi ecosystem is divided into several primary modules, each requiring specific setup steps.
macOS Desktop Application
The desktop app is a Swift Package Manager project that incorporates a Rust-based backend. Development requires initializing a worktree and setting up Git hooks to ensure proper formatting and linting.
# In the repository root
make setup
# To build and run the development version
cd desktop/macos && ./run.sh
Sources: README.md:32-34, AGENTS.md:14-16, desktop/macos/AGENTS.md:95-103
Flutter Mobile Application
The mobile application supports both iOS and Android. It uses a bootstrap script to handle dependencies, flavor configuration, and code generation.
cd app
bash setup.sh ios # or: bash setup.sh android
Sources: README.md:58-60, app/AGENTS.md:21-26
Firmware (nRF5340)
Building firmware for the Omi wearable requires the nRF Connect SDK (NCS) v2.9.0. The build process utilizes the west tool and generates an OTA-compatible ZIP file for flashing via the nRF Connect mobile app.
Sources: omi/firmware/BUILD_AND_OTA_FLASH.md:23-35, omi/firmware/BUILD_AND_OTA_FLASH.md:112-120
Local Development Architecture
The following diagram illustrates the relationship between local development components and the data flow during a standard execution of the desktop application.
This diagram shows the local desktop development stack and its interaction with cloud services.
Sources: README.md:111-125, AGENTS.md:14-20, desktop/macos/AGENTS.md:115-125
Development Guidelines & Automation
The project enforces strict coding and safety rules through its AGENTS.md and CLAUDE.md files to maintain consistency across the monorepo.
Safety and Process Rules
- Production Isolation: Never kill or restart production apps (
/Applications/Omi.app) during development. - Git Strategy: Never push directly to
main. Use PRs. - Worktree Isolation: Use
scripts/dev-instance.shfor parallel worktrees; each instance gets unique ports (Rust 10201+, Python 8080+) and bundle names. - Formatting: Pre-commit hooks automatically format Python (Black), Dart (dart format), and Rust (rustfmt).
Sources: AGENTS.md:25-35, AGENTS.md:130-145, AGENTS.md:245-255
Configuration Summary
| Component | Port (Dev) | Environment/Config File | Technology |
|---|---|---|---|
| Desktop Backend | 10201+ | desktop/macos/Backend-Rust/.env | Rust |
| Python Backend | 8080+ | .env | Python/FastAPI |
| Mobile App (Dev) | N/A | .dev.env | Flutter |
| Automation | 47777+ | N/A | agent-swift/agent-flutter |
Sources: AGENTS.md:130-145, app/AGENTS.md:7-10, plugins/omi-github-app/QUICKSTART.md:41-48
Plugin/App Development Setup
Developers can create integrations (e.g., GitHub, Linear, Notion) that utilize the Omi webhook and chat tools system.
Example: GitHub Plugin Setup
- Dependencies: Install via
pip install -r requirements.txt. - OAuth: Register a New OAuth App on GitHub.
- Environment: Configure
.envwithGITHUB_CLIENT_ID,GITHUB_CLIENT_SECRET, andOPENAI_API_KEY. - Tunneling: Use
ngrokto expose the local server for Omi webhook delivery.
Sources: plugins/omi-github-app/QUICKSTART.md:7-39, plugins/omi-github-app/SETUP_COMPLETE.md:10-25
Sequence of events for a voice-triggered GitHub issue creation.
Sources: plugins/omi-github-app/QUICKSTART.md:120-130, plugins/omi-github-app/SETUP_COMPLETE.md:85-105
Troubleshooting Local Setup
Common issues encountered during setup and their resolutions:
- Port Conflict: If port 8000 (GitHub plugin) or 8080 (Backend) is in use, use
lsof -ti:<port> | xargs kill -9or change theAPP_PORTin the.envfile. - Xcode Version Mismatch: Always use
xcrun swift buildto ensure the SDK matches the installed Xcode version. - Mobile Gen Errors: If
flutter pub run build_runnerfails, use the--delete-conflicting-outputsflag.
Sources: plugins/omi-github-app/QUICKSTART.md:65-72, desktop/macos/AGENTS.md:105-110, app/AGENTS.md:118-120
The local setup is designed to be modular. Developers can contribute to the hardware firmware, mobile UI, or AI backend logic independently, provided they follow the established safety protocols and toolchain requirements.