home / skills / basedhardware / omi / local-dev

local-dev skill

safe

This skill starts the backend server and macOS app for local development, speeding up setup and testing across components.

npx playbooks add skill basedhardware/omi --skill local-dev

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.4 KB

---
name: local-dev
description: Start local development environment with backend and macOS app
allowed-tools: Bash
---

# Start Local Development Environment

Start the backend server and macOS app for local development.

## Usage

Run `/local-dev` to start both the backend and app, or:
- `/local-dev backend` - start backend only
- `/local-dev app` - build and run the macOS app (debug mode)
- `/local-dev app --clean` - clean build and run (forces Swift recompilation)
- `/local-dev app --release` - build and run in release mode

## Commands

### Backend
```bash
cd backend
lsof -ti:8000 | xargs kill -9 2>/dev/null || true
python3 -c "from dotenv import load_dotenv; load_dotenv(); import subprocess; subprocess.run(['python3', '-m', 'uvicorn', 'main:app', '--host', '0.0.0.0', '--port', '8000', '--reload'])"
```

### App
```bash
app/scripts/dev-macos.sh $EXTRA_ARGS
```

Where `$EXTRA_ARGS` can be:
- `--clean` - force clean build (removes build cache, ensures Swift recompilation)
- `--release` - build in release mode instead of debug
- `--no-run` - build only, don't launch the app

## Argument Handling

When `$ARGUMENTS` is "backend", only start the backend.
When `$ARGUMENTS` is "app", build and run the macOS app.
When `$ARGUMENTS` starts with "app ", pass remaining args to the script (e.g., "app --clean").
When `$ARGUMENTS` is empty or "all", start both backend and app.

Overview

This skill starts the local development environment for the AI wearables project by launching the backend server and the macOS app. It provides targeted commands to run the backend alone, the macOS app alone, or both together, with options for clean and release builds. The tool streamlines iterative development by handling port cleanup and build flags automatically.

How this skill works

The skill runs a small script that kills any process on the backend port, loads environment variables, and starts the FastAPI/uvicorn server on port 8000 with reload enabled. For the macOS app it invokes the provided app/scripts/dev-macos.sh wrapper, passing through flags like --clean, --release, and --no-run to control build behavior. Argument parsing supports explicit modes: backend, app, app with extra flags, or both when no argument is given.

When to use it

During local feature development that changes backend APIs or app UI/logic
When you need a quick local integration loop between the mobile/macOS app and the backend
To force Swift recompilation after native code changes using --clean
To test production-like builds locally using --release
When automating local test runs or developer onboarding scripts

Best practices

Run the command from the repository root to ensure correct relative paths
Use --clean after native dependency or Swift toolchain updates to avoid stale builds
Use --no-run to build artifacts for CI or inspection without launching the UI
Keep port 8000 free or change the backend script if you need a different port
Monitor the terminal output for uvicorn reloads and macOS build logs to catch issues early

Example use cases

Start both backend and macOS app for full end-to-end testing of speech-to-transcript flows
Quickly iterate on backend API changes and see them reflected in the running app via uvicorn --reload
Rebuild the macOS app in release mode to profile performance or test signed builds
Perform a clean build after upgrading Swift or changing native libraries to avoid linker/build cache errors
Build only (--no-run) to produce an app binary for distribution or CI packaging

FAQ

What happens if port 8000 is already in use?

The script attempts to kill any process listening on port 8000 before starting the backend. If it cannot, you must free the port or change the backend port in the startup command.

How do I pass extra flags to the macOS build?

Use the app argument followed by flags, for example: /local-dev "app --clean --no-run". The script forwards extra args to app/scripts/dev-macos.sh.