Start Local Development Environment

Start the backend server, macOS app, or Flutter mobile app for local development.

Usage

Run /local-dev to start both the backend and macOS 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
/local-dev mobile - run Flutter app in iOS simulator (dev flavor, dev backend)
/local-dev mobile --prod - run Flutter app in iOS simulator (prod flavor, prod backend)

Commands

Backend

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'])"

macOS App

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

Flutter Mobile (iOS Simulator)

Find or boot a simulator:

xcrun simctl list devices | grep Booted  # check for running simulator
# If none booted:
xcrun simctl list devices available | grep -i "iphone" | tail -5
xcrun simctl boot <device-id>
open -a Simulator

Run the app:

cd app && flutter run -d <device-id> --flavor dev
# Or for prod backend:
cd app && flutter run -d <device-id> --flavor prod

Logs stream to /tmp/flutter-run.log.

Flavor & Env Files

Flavor	Env file	Backend	Agent proxy
`dev`	`app/.dev.env`	`api.omiapi.com`	`agent.omiapi.com`
`prod`	`app/.env`	`api.omi.me`	`agent.omi.me`

Dev flavor has USE_WEB_AUTH=false (native sign in). Prod has USE_WEB_AUTH=true (Safari OAuth). The simulator works best with native sign in — use dev flavor for simulator testing.

After changing any .env file, regenerate the compiled env:

cd app && rm -rf .dart_tool/build lib/env/prod_env.g.dart lib/env/dev_env.g.dart
dart run build_runner build --delete-conflicting-outputs

Simulator Notes

iOS Keychain persists across app uninstalls in the simulator, so Firebase Auth sessions survive reinstalls
claudeAgentEnabled defaults to false on fresh install — toggle it on in Settings → Developer Mode
The Flutter debug connection frequently dies ("Lost connection to device") when the app goes to background — the app itself keeps running, just relaunch flutter run
Logs: grep -E "\[AgentChat\]|\[HomePage\]" /tmp/flutter-run.log | tail -20
Hot restart: kill -SIGUSR2 $(pgrep -f "flutter run" | head -1)

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 "mobile", run Flutter app in iOS simulator with dev flavor. When $ARGUMENTS is "mobile --prod", run Flutter app in iOS simulator with prod flavor. When $ARGUMENTS is empty or "all", start both backend and macOS app.