An IDE for directing code instead of typing it. You see each project as diagrams generated from its code, and steer it by chatting with Claude Code. The agent does the work; you watch where in the system it happens and approve what it wants to run.
It is a personal, single-user tool: it runs on your own machine, loopback only, and drives the
unmodified claude CLI with your own Claude subscription login — never API keys (see
PLAN.md §5 for the terms this relies on). Built for macOS as Flightdeck.app; the server
itself is plain Node and also runs from a checkout on Linux.
Status (2026-10-14): chat, maps, plans and the requirements workspace built and in daily use by its author. Expect rough edges; it is shared as-is.
- macOS for Flightdeck.app (the Xcode command line tools provide
swiftc:xcode-select --install). Any OS with Node for the server alone. - Node 22+ and git.
- Claude Code installed and logged in to a Claude subscription: run
claudeonce and/login. Flightdeck finds it at~/.local/bin/claudeor onPATH(CLAUDE_BINoverrides). - Optional: Cursor CLI, logged in with
cursor-agent login, to run chats or generate maps on Cursor. - Your projects as git repositories under one folder,
~/devby default (FLIGHTDECK_BROWSE_ROOT).
git clone https://github.com/VLO-Labs/flightdeck.git && cd flightdeck
cp .env.example .env # optional: port, host name, project folders, default model …
scripts/mac/install.shOpening Flightdeck.app starts the server and opens the browser at http://flightdeck.localhost:8100; quitting it stops the server. The Dock icon reopens the page.
- Update:
git pull, thenscripts/mac/install.shagain. It copies this repo to~/Library/Application Support/Flightdeck/app, runsnpm ciand the build there, and (re)builds/Applications/Flightdeck.app. It refuses while a chat turn or map refresh is running, and quits and reopens the app if it was open. The app runs that copy, never the checkout, so a chat editing this repo can't change the running server. - Data:
~/Library/Application Support/Flightdeck/data(SQLite + chat feeds); untouched by updates, new tables and columns are added on start. Log:~/Library/Logs/Flightdeck.log. - Stop: quit the app, or
scripts/mac/stop.sh. - Port-less address (optional): set
FLIGHTDECK_BARE_HOST=flightdeck.test(any name) in.env, runsudo scripts/mac/port80.shonce, thenscripts/mac/install.shagain. The name gets its own loopback IP and port 80 forwards to the server. Loopback only either way: nothing on the network can reach Flightdeck.
Everything is set through environment variables, read from a .env file next to the code (the
install script copies the repo's .env beside the app) or from the environment, which wins.
.env.example lists them all with their defaults; the ones most people touch:
| Variable | Default | What |
|---|---|---|
FLIGHTDECK_PORT, FLIGHTDECK_HOST_NAME |
8100, flightdeck.localhost |
The address the page opens at |
FLIGHTDECK_BROWSE_ROOT |
~/dev |
Projects must live inside this folder |
FLIGHTDECK_PROJECTS_DIR |
the browse root | Where + New project creates projects |
FLIGHTDECK_MODEL |
claude-opus-5-5 |
Model new projects start with (haiku to spare the plan) |
CLAUDE_BIN |
~/.local/bin/claude or claude on PATH |
The Claude Code binary |
CURSOR_BIN, FLIGHTDECK_CURSOR_MODEL |
~/.local/bin/cursor-agent or on PATH, auto |
The Cursor CLI, and the model its chats start with |
FLIGHTDECK_DATA |
app data folder / ./data |
Database and chat feeds |
Change one of the address variables or CLAUDE_BIN and re-run scripts/mac/install.sh; the app
bakes those in. The rest take effect on the next start.
npm ci && npx vite build
FLIGHTDECK_DATA=./data FLIGHTDECK_PORT=8199 npm startA separate port and data folder, so it never touches the installed app's. Checks: npm test,
npm run typecheck. Contributors: see CLAUDE.md for how changes go live.
- Loopback only. The server binds 127.0.0.1 and refuses requests whose
Hostisn't a name of this machine (blocks DNS rebinding) or whoseOriginis another site; state changes must be JSON. No login, because nothing else can reach it. - Approval cards. Claude Code's tool calls go through an HTTP hook that holds them until you click Allow or Deny, under per-project rules you set. Discuss chats can't change files at all; one Build chat at a time holds a project's edit lock.
- Subscription, not keys.
ANTHROPIC_API_KEYis stripped from the agent's environment, and a run aborts if the CLI reports any auth other than the subscription login.
Each chat runs on one or the other. Project settings choose what new chats use; a chat can change it
until its first message, then stays on it. Approval cards, rules (written in Claude Code's syntax, so
Bash(git status:*) covers Cursor's shell too), Discuss and Build, and the edit lock work the same on
both. Cursor chats have no slash commands, and Discuss refuses any Cursor tool not known to only read.
They use your own cursor-agent login, never CURSOR_API_KEY.
Project settings also choose what generates the maps (and plan checks), Claude Code by default. Claude Code is held to the map's schema as it runs; Cursor's reply is checked afterwards and asked once to fix a bad one, so its runs can fail more often. Maps on Cursor use their own model, Composer 2.5 by default.
| Read | For |
|---|---|
PLAN.md |
What it is, the decisions and why, how the chat works, the build phases |
Each project can keep a PRD and feature specs in its own repository, as plain Markdown that works anywhere (VS Code, GitHub, Claude Code):
docs/requirements/PRD.md overview, users, scope, business rules (BR-001 …)
docs/requirements/features/<name>.md one per feature: scenarios, edge cases, acceptance criteria (AC-001 …)
In a multi-repo folder they live in the repository that keeps the maps. CLAUDE.md stays the
engineering instructions; the PRD says what the software must do.
- Start one: for a new project, + New project → Start with: Requirements (the default): it creates the repository and opens a Discuss chat — no code — that asks what you need and proposes the PRD from your conversation, leaving what you haven't decided under Open questions; scaffold later in Build. For any project, a Discuss chat can be asked to write or revise it, or use the PRD tab → Start the PRD (a template with headings and guidance, no rules) and edit it yourself. + Feature spec adds a spec. Files written by hand show up too.
- Ids start a heading or list item (
### BR-001 · …,- **AC-001** …). A draft's ids can change until they are approved; after that they never change and are never reused, and a rule that no longer applies is marked(retired). Saves that break this are refused. - Approve freezes exactly the text you see as vN (kept in Flightdeck's database); later edits are a draft until approved. Nothing is committed for you — commit the files like any others.
- In chat: + chat on any rule or section attaches it to your message. In Discuss the agent can propose edits, which you accept or reject as a diff; it can't write the files. In Build, attached requirements, and any ids the message or the approved plan names, go as their approved text, and each run records which versions it used.
- Links in the documents:
[name](src/file.ts#L10)opens the file,[name](map:architecture/<node-id>)shows the node on its map.
MIT.
- 2026-10-10 — idea scoped in a Claude Code session: IDE replacement for an architecture-first / vibe-coding workflow. Named Flightdeck. Phase 1 = projects, diagrams, chats. Docs-verified the headless CLI mechanics and the subscription terms the plan relies on.
- 2026-10-10 — Step 0 spike run on the box: hook-held approvals, SIGINT stop, resume and the subscription tripwire all confirmed. Corrected the plan: a timed-out approval falls back to Claude Code's normal rules (read-only runs, writes refused), not a blanket deny.
- 2026-10-10 — TypeScript locked; per-project approval rules designed. Phase 1a built:
projects, chats on headless
claude -p, approval cards (http PreToolUse hook), per-project rules, edit lock, stop, replay, model per chat (default Opus 5.5). Verified end to end on the box: Opus 5.5 on the subscription (apiKeySource: none), card → allow + "always allow" rule, deny with reason, edit lock refusing a second chat's writes, stop with a card open. - 2026-10-10 — Discuss / Build modes per chat, with a model per mode (project defaults Opus 5.5 for both, chat overrides). Verified: Discuss refused the edit and proposed it; switching to Build in the same session made it from "go ahead". Confirmed chats share Claude Code's per-project memory.
- 2026-10-10 — Phase 1b built: maps (architecture / data model / flows) generated from code by
a read-only agent with structured output, validated, stored in
.flightdeck/, drawn with React Flow + ELK, drill-down, change detection, read-only file viewer. Flightdeck's own maps are committed in.flightdeck/. Hardened the rules engine on the way: output redirection is never covered by an allow rule. - 2026-10-10 — Phase 1c built: map pane in chats, nodes as message context (resolved server-side), live read/edit highlighting, "Discuss in a new chat". First look at the real UI in a browser found and fixed: double-click zoomed instead of opening a node, a double-click also toggled context twice, the canvas fitted to the previous level, and a crowded chat header. Phase 1 is complete.
- 2026-10-11 — Permanent: systemd service, tunnel route and SSO via the shared gateway
(
flightdeck.vlolabsdev.com). The gateway reaches the native listener over docker0 with a secret header; UFW needed an allow from the docker subnets (Docker-published services never hit UFW, a native one does). - 2026-10-11 — Requirements workspace (PLAN.md §11): chat beside a tabbed workspace (PRD, maps, code); PRD and feature specs as Markdown in the repo with stable ids, approved revisions kept by Flightdeck, requirements attached to messages, agent-proposed edits reviewed as diffs, Build given the approved text.