Ao Desktop Dev

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.

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.

Preview multiple PRs locally

When the user wants to see multiple unmerged PRs together:

1. Require a clean worktree and fetch each PR head.
2. Create a clearly named local-only integration branch using the session/repository branch convention.
3. Merge or cherry-pick the requested PR heads without rewriting or pushing either source branch.
4. Resolve overlaps according to the requested combined behavior and run focused typechecks/tests.
5. Let renderer changes hot reload; restart Electron if either PR changes main/preload/IPC code.
6. State that the integration branch is local-only. Do not push it unless the user explicitly requests a combined PR.

Once one PR merges, prefer rebasing the remaining PR onto current main; the normal PR branch then contains both views without a local integration merge.

Stop without collateral damage

1. Send Ctrl+C to the foreground dev process and wait briefly for Electron and its managed daemon to exit.
2. Re-run the checkout-scoped process query. If the exact process group remains, identify the group created by this launch before sending TERM to that group.
3. On Windows, terminate the verified parent tree only. Never use a broad Electron, Node, Go, or port-based kill.
4. Confirm the captured Electron PID and dev daemon listener are gone. Leave installed AO and other worktrees untouched.

Common mistakes

• ao preview controls the AO Browser panel; it does not launch the desktop shell.

• npm run dev:web is useful for browser-only renderer work but does not provide Electron APIs or native chrome.

• Renderer URLs can move from 5173 when a port is occupied. Trust Forge's printed URL rather than assuming one.

• Multiple dev instances share ~/.ao/dev/electron by default, and Chromium's singleton lock lives in the profile, so a second checkout's npm run dev loses requestSingleInstanceLock() and exits immediately with code 0. To run two worktrees at once, give each its own profile, run file, and data dir:

  env -u AO_PORT \
    AO_DEV_ELECTRON_DIR="$HOME/.ao/dev/<name>/electron" \
    AO_RUN_FILE="$HOME/.ao/dev/<name>/running.json" \
    AO_DATA_DIR="$HOME/.ao/dev/<name>/data" \
    npm run dev
  

  Without all three the instances still collide, on the profile lock, the run file, or the daemon's SQLite data.

• An inherited AO_DATA_DIR changes dev mode from isolated data to real data. Always choose and report the mode instead of inheriting it accidentally.

• Repeated /healthz/ 404 entries from external probes can be noisy; readiness is determined by Electron's daemon status and successful API traffic, not by log volume.

Completion report

Report:

• checkout and branch being displayed;
• isolated or real-data mode and the non-sensitive data/run-file paths;
• renderer and daemon addresses actually reported;
• whether Electron was restarted for main/preload changes;
• user flows exercised in the native window;
• any remaining stale process, port, or visual-verification limitation.