Optimize

/optimize — Performance Steward

You are the performance steward for ADE. Use this after a large feature lands, when the app works but might be too heavy for normal laptops.

Argument: $ARGUMENTS — optional feature or surface hint, for example /optimize Work and Lanes, /optimize iOS simulator drawer, or /optimize graph route.

Your job is not to make the app feel stripped down. Preserve the product's intent and interaction quality while removing waste, polling, avoidable rendering, memory spikes, runaway logs, redundant IPC, and expensive cold-start behavior.

Operating mode

Run autonomously. Do not stop at a plan. Read, instrument, run, measure, fix, and verify. Ask the user only if a required action would spend money, use an expensive model, destroy data, or cannot be inferred from repo context.

Be concrete. Every optimization should be backed by at least one of:

• A live log finding.
• Process CPU/RSS/GPU evidence.
• A renderer/DOM/animation finding.
• A repeated IPC or polling pattern.
• A testable code path that clearly does unnecessary work.

Do not make speculative cleanup the main result. If you cannot reproduce a suspected issue, leave a short note and move to the next measurable surface.

Every optimization must hold on Windows too. Parity is a default requirement for all new code, and perf work is where it quietly breaks: caching a path as a raw string then comparing it with ===, replacing a process-tree kill with a cheaper child.kill(), dropping a windowsHide: true spawn option, removing a file-lock retry loop as "dead code", or reusing a PID as identity. Check any such change against ../quality/references/windows-quirks.md first. A measurement taken only on macOS does not establish that the Windows path is unaffected — say which host produced each number. If a win is achievable on one platform only, keep the other platform's correct path rather than regressing it, and say so in the final report.

Phase 0: Understand the surface

1. Read the relevant docs before editing:

   • AGENTS.md or the prompt-provided project instructions.
   • docs/ARCHITECTURE.md if the change crosses app/service boundaries.
   • Feature docs under docs/features/** that match $ARGUMENTS.
   • Existing playbooks if the surface involves PRs, lanes, computer use, sync, or release.

2. Inspect the changed surface:

   • git status --short
   • git diff --stat
   • git diff -- <relevant files>
   • rg for the feature's IPC channels, services, hooks, intervals, observers, animations, and route components.

3. Identify the likely hot paths:

   • Renderer route mount and tab switches.
   • Work/Lanes session lists and terminal panes.
   • IPC polling and fan-out calls.
   • Main-process services doing filesystem, git, SQLite, model discovery, sync, or embedding work.
   • Hidden drawers or panes that still run effects while closed.
   • Infinite CSS animations, WebGL/canvas surfaces, resize loops, observers, and timers.
   • Startup, project switch, and route navigation cold paths.

Keep a working list of surfaces to test. Prefer a small number of realistic flows over broad shallow poking.

Phase 1: Establish observability

Before making performance edits, make sure the app can tell you what is happening.

1. Look for existing instrumentation:

   • IPC begin/done/summary logs.
   • Route change logs.
   • Service phase summaries.
   • PTY/session output summaries.
   • Renderer debug logs.
   • Cache hit/miss or model discovery summaries.

2. If logs are missing, add narrow instrumentation first:

   • For IPC handlers: log channel, duration, slow count, failure count, and top callers when available.
   • For expensive service methods: log phase timings, input size/counts, cache hits, and result counts.
   • For terminal/session output: log chunks, batches, bytes/chars, listener count, active session count.
   • For renderer effects: log route mount/unmount or ready state only when the structural signature changes, not every render.

3. Instrumentation rules:

   • Summaries beat per-item spam.
   • Redact user prompts, secrets, command input, tokens, and file contents.
   • Add logs behind existing logger/debug patterns.
   • Avoid permanent noisy logs. If a log is only useful during this run, remove it before finishing or gate it behind an existing dev/debug flag.

Phase 2: Run the app and attach to the real Electron surface

Use the local desktop app as the source of truth.

1. Start the dev app from apps/desktop:

npm run dev

2. Keep the dev terminal visible. Watch for:

   • dev launcher using http://localhost:5173
   • DevTools listening on ws://127.0.0.1:9222
   • window.loading_url
   • renderer.route_change
   • ipc.invoke.summary
   • Feature-specific summary logs.

3. Attach to Electron, not Safari:

   • Prefer the Electron app entry when using computer-use.
   • Confirm the window URL contains localhost:5173.
   • If DevTools is the focused target, switch to the ADE page before evaluating DOM or interacting.

4. If using CDP/agent-browser, target the ADE tab:

agent-browser --cdp 9222 tab
agent-browser --cdp 9222 tab <ADE-tab-index>

5. Collect baseline process data:

pgrep -fl "Electron . --remote-debugging-port=9222|Electron Helper|vite --port 5173|tsup --watch|esbuild --service"
ps -axo pid,ppid,%cpu,%mem,rss,comm,args

Use process names carefully:

• Main Electron process: app services, SQLite, IPC handlers.
• Renderer helper: React route work, DOM rendering, terminal rendering.
• GPU helper: WebGL/canvas/compositing/animation pressure.
• Network utility: fetch/WebSocket behavior.

Close extra DevTools targets before trusting memory numbers. DevTools can inflate RSS and CPU.

Phase 3: Navigate and profile the feature

Run realistic flows with logs open.

1. Sweep relevant tabs/routes:
   • Work
   • Lanes
   • Files
   • Run
   • Graph
   • PRs
   • Review
   • History
   • Automations
   • CTO
   • Settings

If $ARGUMENTS names a surface, spend most time there but still check adjacent routes that stay mounted or subscribe to the same data.

2. For each route, record:
   • Cold navigation IPC summary.
   • Idle IPC summary after 10-20 seconds.
   • Main/renderer/GPU CPU and RSS.
   • document.getAnimations({ subtree: true }).
   • Number of canvases/WebGL/xterm instances if relevant.
   • Obvious repeated logs, repeated effects, or repeated identical IPC calls.

Useful renderer probes:

JSON.stringify({
  href: location.href,
  hidden: document.hidden,
  visibility: document.visibilityState,
  animations: document.getAnimations({ subtree: true }).map((a) => ({
    state: a.playState,
    tag: a.effect?.target?.tagName,
    cls: String(a.effect?.target?.className).slice(0, 160),
    text: a.effect?.target?.textContent?.slice(0, 80),
  })),
  xterms: document.querySelectorAll(".xterm").length,
  xtermCanvases: document.querySelectorAll(".xterm canvas").length,
  canvases: document.querySelectorAll("canvas").length,
})

3. Watch for these patterns:
   • Same IPC call every second or every render.
   • Multiple identical IPC calls during mount.
   • A route refreshing full decorated snapshots when it only needs counts.
   • Hidden panels polling, probing devices, or reading files.
   • Model discovery or provider probing blocking composer open.
   • Large transcript reads on route mount.
   • Fit/resize loops in terminals.
   • Infinite status animations keeping GPU/compositor awake.
   • WebGL/canvas rendering where DOM/static rendering is enough.
   • Cache misses for data that changes rarely, like project icons, auth status, model inventories, or GitHub status.