AO Desktop App Launcher

AO Desktop Dev

Run the Electron application from the current checkout and verify it in the native window. Keep the dev daemon, renderer, Electron preload, and selected data mode explicit so the user never reviews a mock or stale build by accident.

Choose the data mode

Ask only when the request does not make the desired data source clear.

• Use isolated mode by default for implementation and destructive testing. Electron uses port 3002, ~/.ao/dev/running.json, ~/.ao/dev/data, and ~/.ao/dev/electron.
• Use real-data mode only when the user explicitly asks to see this machine's actual AO projects or sessions. Start the checkout's dev daemon on the isolated dev port/run file while pointing AO_DATA_DIR at the real AO data directory. This is a separate daemon process using real data; do not describe it as the installed app's daemon.
• Never try to attach an unpackaged Electron app directly to a packaged daemon from another checkout. The supervisor intentionally rejects daemon identity mismatches.
• Warn before actions in real-data mode that create, terminate, rename, or otherwise mutate sessions. Merely opening and inspecting the UI is expected.
• Real-data mode reads the same database as the installed app, so both windows show the same projects and sessions. Quit the packaged app first where possible: two daemons sharing one SQLite database can cross-talk, and acting on the wrong window runs unmerged code against real sessions. The dev window is marked with an Agent Orchestrator (dev) title, the default Electron dock icon, and an in-app dev badge — verify those markers before acting.

Preflight

1. Work from the repository root and inspect git status --short --branch.
2. Read frontend/package.json, frontend/src/main.ts, and frontend/forge.config.ts when the launch behavior may have changed. Treat source as authoritative over this skill.
3. Confirm Node/npm and the Go version required by backend/go.mod are available. Run npm ci in frontend/ only when dependencies are absent or inconsistent; do not reinstall on every launch.
4. Check for an existing dev instance from this exact checkout before starting another. Do not kill by process name alone, and never terminate every Electron process.

On macOS/Linux, inspect checkout-scoped processes and listeners with finite commands:

ps -axo pid=,ppid=,pgid=,lstart=,command= | rg 'frontend/(node_modules/.bin/electron-forge|node_modules/electron/dist/Electron)'
lsof -nP -iTCP:3002 -sTCP:LISTEN

Use the full command paths and start times to distinguish this checkout from other AO worktrees. On Windows, use Get-CimInstance Win32_Process and Get-NetTCPConnection; preserve the same exact-target rule.

Launch the app

Run Electron Forge in a foreground interactive process so its output and restart input remain available. Do not append &, use a detached shell, or start a browser preview instead.

Isolated mode

On macOS/Linux:

cd frontend
env -u AO_DATA_DIR -u AO_RUN_FILE -u AO_PORT npm run dev

On PowerShell:

Set-Location frontend
Remove-Item Env:AO_DATA_DIR, Env:AO_RUN_FILE, Env:AO_PORT -ErrorAction SilentlyContinue
npm run dev

Real-data mode

First resolve and report the actual data directory. In an AO worker session, AO_DATA_DIR normally already identifies it. Otherwise the repository default is the absolute path corresponding to ~/.ao/data.

Keep the real data directory but remove inherited port/run-file overrides so the dev app retains its own daemon handshake and port:

cd frontend
env -u AO_RUN_FILE -u AO_PORT AO_DATA_DIR="${AO_DATA_DIR:-$HOME/.ao/data}" npm run dev

PowerShell equivalent:

Set-Location frontend
$realAoData = if ($env:AO_DATA_DIR) { $env:AO_DATA_DIR } else { Join-Path $HOME ".ao/data" }
Remove-Item Env:AO_RUN_FILE, Env:AO_PORT -ErrorAction SilentlyContinue
$env:AO_DATA_DIR = $realAoData
npm run dev

Do not print unrelated environment variables: AO sessions may carry credentials. It is safe to report only AO_DATA_DIR, AO_RUN_FILE, and AO_PORT.

Confirm the correct app is ready

Wait for all of these signals:

• Electron Forge reports Launched Electron app.
• The daemon reports daemon listening, normally on 127.0.0.1:3002 unless it explicitly reports another bound port.
• The renderer makes successful requests such as /api/v1/projects and /api/v1/sessions.
• The native Electron window shows the checkout's UI. A Vite URL opened in a normal browser is not equivalent because it lacks the Electron preload bridge.

If several AO windows exist, identify the newest Electron main process belonging to this checkout. On macOS, foreground that exact PID only when needed:

osascript -e 'tell application "System Events" to set frontmost of first process whose unix id is <verified-pid> to true'

Do not claim real data from appearance alone. Verify the selected data directory and successful API responses. Do not claim visual success from compilation alone; interact with the requested flow in Electron or ask the user for a screenshot when screen capture is unavailable.

Reload changes correctly

• Renderer-only React/CSS changes normally hot reload.
• Changes to frontend/src/main.ts, preload files, Forge configuration, shared bridge types, or IPC registration require an Electron main-process restart. Type rs into the active Forge terminal or fully stop and relaunch the dev process.
• A renderer error such as aoBridge.<method> is not a function almost always means the renderer hot-reloaded against a stale preload. Restart Electron before changing code to add guards around a bridge method that should exist.
• Backend changes require restarting the managed dev daemon or the Electron process; renderer hot reload cannot apply Go changes.

After a restart, confirm the new Electron PID/start time and re-check the logs for the original error.