Flightdeck

A personal cockpit for parallel development work.

You run many work items at once — drafting an issue, an agent working a worktree, a dev server on some port, a PR awaiting review — and lose track of which is where. Flightdeck is one glanceable board that shows every work item's stage and what needs your attention, by observing reality (gh, git, local dev servers, claude agents) rather than relying on you or your agents to keep a status doc current.

Status: v1 (read-only board) implemented. Observes GitHub PRs/issues, git worktrees, local MMGIS deployments, and claude agents sessions, and renders a glanceable kanban + "needs my attention" lane. The embedded launch/resume terminal is the next milestone. Name is a placeholder — rename freely.

Run it

npm install
npm run dev

• Board: http://localhost:4316
• API: http://localhost:4317/api/state

Prereqs: gh authenticated, claude on PATH, MMGIS checked out at ~/github/MMGIS. See docs/RUNBOOK.md for details and a no-browser API smoke test.

What it tracks

Each work item, across its lifecycle: drafting → posted to GitHub → in progress (worktree + agent) → deployed locally (clickable port) → PR out → reviews awaiting my response → merged. Plus the agent layer: which Claude Code session is on which worktree, whether it's busy / idle / blocked, and (stretch) talking to it from the dashboard.

How it works (in brief)

• Observe reality, every poll. The backend re-derives all state on an 8s loop by shelling out to gh (PRs/issues), git (worktrees, merged branches), the MMGIS deployment skill's list.sh (deployments), and claude agents --json (live sessions) — plus reading Claude transcripts and issue .md drafts. The core board never depends on agent self-report, so it can't rot.
• Sessions are attributed by what they touch. A session is filed under the worktree whose files it actually edits (from its transcript), not the directory it launched in.
• Local SPA + thin backend, loopback-only. A modern web UI over a small local server bound to 127.0.0.1.
• No tmux. The embedded terminal launches/resumes Claude via native primitives (claude --resume, node-pty, xterm.js) — see the spike doc.

Liveness today is poll-based: a session shows running/resumable from claude agents --json, not from pushed events. Hook-based push status (SessionStart/Stop/Notification) and a staleness watchdog are planned — see ROADMAP.md. The full architecture lives in docs/architecture/.

Docs

• docs/design.md — consolidated design / spec (start here)
• docs/problem-and-features.md — problem + prioritized feature catalog
• docs/implementation-approaches.md — the key decisions and their tradeoffs
• docs/agent-interaction-spike.md — verified agent-layer spike (observe / status / talk)
• docs/research-landscape.md — survey of existing multi-agent orchestrators and what they lack
• docs/research-notes-raw.md — raw research notes