Flightdeck
A Claude Code mod that puts a live agent dashboard in your terminal: context and cost, an advisor timeline, every permission check, and your subagents as cards or swimlanes. Every number comes from a real session event, and nothing leaves your machine.
Install · What you see · What it can reach · Configure · Troubleshooting · What's new
Install
Inside Claude Code (2.1.287 or later):
/plugin marketplace add scasella/claude-flightdeck
/plugin install flightdeck@claude-flightdeck
/reload-plugins
/flightdeck
From the terminal, or from a clone
claude plugin marketplace add scasella/claude-flightdeck claude plugin install flightdeck@claude-flightdeck
Or load it straight from a clone, for one session:
git clone https://github.com/scasella/claude-flightdeck claude --plugin-dir ./claude-flightdeck
The installer may say config options aren't set; the defaults are fine, and /config changes them.
Mods are an early-access Claude Code feature and their API can change between releases. If something breaks, see Troubleshooting.
What you see
flightdeck-clip.mp4
| Docked beside the transcript | Inline above the prompt |
|---|---|
 |
 On the main screen, without fullscreen, the pane is a summary of at most 8 rows; up to 3 agents join it when the session has subagents. |
| Panel | Shows | From |
|---|---|---|
| main | model, effort, permission mode, request count; a context gauge with compactions (⟲); cost and the first two rate-limit windows when your plan reports them, with the time to each reset (↻) from 56 columns; the last main-loop request's time to first token and output tokens per second | turn.step, session.measure, session.compact, $.session.usage() |
| architect | consults on a timeline, whether one is running, how long the last took; optionally the moment of each consult; the first line of a subagent architect's advice | a spawn of a matching agent type, or a matching server tool in the assistant's rows |
| gate | one cell per permission check: green allowed without asking, blue decided by the auto-mode classifier or you and then run, amber pending, red ✗ denied, dim if made inside a subagent. Totals, and a drill-down per tool family with credentials masked | tool.check, settled by the tool.call around it |
| agents | cards side by side while they fit: the task, type, live context and output tokens, steps, a running clock, max_tokens in red. Beyond that, swimlanes on one time axis |
agent.spawn, turn.step, tool.call, turn.complete |
| loops | model loops that match no card: workflow agents, compactions, memory forks | turn.step ids no card claims |
| receipt | the running turn, or the last one: duration, agents, edits, errors, cost added | turn.start, turn.complete |
| log | prompts, spawns, completions, consults, edits, errors and denials; filtered to one agent while you view its transcript | all of the above |
Connectors animate only while work flows: a turn is running, an agent is running, or a consult is open. Panels with nothing to show take no room, so a session without subagents shows just the main box and the log.
Use
| Command | Does |
|---|---|
/flightdeck |
open the pane |
/flightdeck close |
close it |
/flightdeck reset |
clear agents, checks, consults, log and the turn (cost, rate limits and compactions stay) |
/flightdeck layout auto|compact|wide|mini |
override the layout for this session |
Focus the pane with ctrl+x tab, then:
| Key | Does |
|---|---|
1, 2, … |
expand an agent card or lane: its full task, last 3 tool calls, start of its answer |
f s o |
open the gate's file / shell / other drill-down: the last 5 checks and their verdicts |
/clear resets the pane along with the conversation.
Where it runs
- Fullscreen terminal: docked beside the transcript; two columns from 110 columns wide.
- Main-screen terminal: inline above the prompt, as the 8-row summary.
- Desktop app, VS Code, mobile: the same panels, plus the agents drawn as an SVG time axis. VS Code and mobile can't animate, so connectors and clocks are static there.
With openOnStart, the pane opens by itself when a session starts, in terminals at least 144 columns wide; below that, /flightdeck opens it. Colours come from your Claude Code theme, so light, dark and colour-blind themes all read.
What it can reach
Flightdeck only watches. Every hook passes its event on unchanged: it never denies, rewrites or delays a tool call, a prompt or a subagent.
| It sees | Through |
|---|---|
| every tool call's name and input, and whether it failed | tool.call |
| every permission verdict | tool.check |
| subagent spawns, their model requests and token usage, and their final answers | agent.spawn, turn.step, turn.complete |
| your prompts' first 70 characters, for the log | turn.start |
| context, cost and rate-limit readings | session.measure, $.session.usage() |
| advisor tool calls in the assistant's responses (their content is encrypted) | session.append |
What it keeps: short summaries (a tool name plus a path or command, with credentials masked) in session state, which ends with the session. It makes no network requests, runs no processes, reads and writes no files, stores nothing across sessions, and calls no model. claude plugin validate . prints exactly what it hooks and calls.
What is inferred, not measured
- Architect moments. "Before a plan" means no edits yet this turn, "error repeats" means 2+ main-loop errors in a row, "before done" means edits were made. They are labelled
(inferred); turn them off withmoments: false. - Server-side advice is encrypted. For a server tool such as Claude Code's
advisor, the pane counts and times the consult but cannot show what it said. - Per-agent context is the latest request's whole input (uncached + cache read + cache write). It is labelled
ctx, not cost: the API has no per-agent cost. - Other loops can't tell a workflow agent from a compaction fork; both are model loops no card claims.
- A background agent's first step can arrive before its card exists, so its usage may show one step late.
- Request speed.
ttftandtok/sare timed at Flightdeck's ownturn.stephook, so they include everything beneath it: other plugins' hooks, the engine, the network and any retry.tok/sdivides the reportedoutput_tokens(thinking included) by the time from the first piece of response to the stop. Measured, not inferred, but not the API's own figures.
Configure
In /config, or under pluginConfigs["flightdeck"].options in settings.json:
| Option | Default | Meaning |
|---|---|---|
architectPattern |
advisor|architect |
case-insensitive regex for agent types and server tools that count as the architect |
matchDescriptions |
false |
also match agent descriptions, not just type names |
architectLabel |
ARCHITECT |
the architect's name in the pane |
gateLabel |
GATE |
the permission panel's name |
panels |
main,architect,gate,agents,loops,receipt,log |
which panels show, in order |
layout |
auto |
mini, compact, wide, or auto (mini inline, wide from 110 columns docked) |
maxCards |
3 |
cards side by side before swimlanes (1–6); fewer if the pane is too narrow |
motion |
while-active |
off keeps connectors still |
moments |
true |
show the inferred consult moments |
palette |
theme |
pastel uses fixed colours tuned for dark terminals |
openOnStart |
true |
ask to open the pane when a session starts |
statusLine |
true |
context, running agents, consults and denials in the status line |
Troubleshooting
The pane doesn't appear.
- Check
claude --versionis 2.1.287 or later, then run/reload-pluginsand/flightdeck. - Below 144 columns, Claude Code won't seat a pane nobody asked for;
/flightdeckopens it at any width. - Look in the transcript for a dim line starting
flightdeck:. It names the hook that failed or the reason the pane was refused. Please open an issue with it.
Colours look wrong. Set palette to pastel in /config.
It's too much motion. Set motion to off.
Counters look stale after an update. Run /flightdeck reset.
How it works
| File | Holds |
|---|---|
hooks/register.tsx |
the event hooks, state access, and one function per panel |
hooks/core.ts |
every reducer, formatter and layout rule as pure functions, so behaviour is testable directly |
hooks/rail.tsx, hooks/elapsed.tsx |
surface modules: animated connectors and live clocks that redraw only themselves, on the surface's own frame clock |
types/index.d.ts |
the state contract |
tests/ |
24 tests: pure behaviour, plus drawings mounted on every surface at 40–120 columns |
State lives in $.state atoms. Every read is merged over defaults, so a missing or older field never breaks the pane; an update that changes the state's shape may still reset its counters once. New to mods? Start with Claude Code mods and Getting started with Claude Code mods.
Related projects
Flightdeck works alongside these, and owes ideas to them:
- claude-hud: context, limits, tools and agents in your status line. Use both: that's the status line, this is the pane.
- zoetrope: a Claude Code or Codex session as a live flow graph.
- ccusage: cost reports from your session logs.
- awesome-claude-code-mods: the index of Claude Code mods.
Develop
claude --plugin-dir . # load it; edits hot-reload claude plugin validate . claude plugin test . npx -p typescript tsc -p . # after the first load, which writes .claude-plugin/types/
See CONTRIBUTING.md. Changes are listed in CHANGELOG.md.