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_ARGSWhere $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 prodLogs 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-outputsSimulator Notes
- iOS Keychain persists across app uninstalls in the simulator, so Firebase Auth sessions survive reinstalls
claudeAgentEnableddefaults tofalseon 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.