Agents Flightdeck

Human-in-the-loop orchestration for AI coding agents. Scope exactly what the agent touches, gate it between every step, and watch every change in real time.

Flightdeck wraps Claude Code agents in a structured pipeline: codebase search → method curation → plan review → gated execution → git diff per step. You stay in control at every decision boundary. The agent does the work between them.

Supports three context backends: JIDRA MCP (method-level AST search + call graphs), CodeGraph MCP (blast-radius graph explorer), and fallback grep (no MCP required). Auto mode picks the best available backend for the repo.

---

The Problem

AI coding agents are powerful but dangerous without oversight. Give an agent a vague goal and it will hallucinate scope, modify files you never intended, burn through budget on the wrong task, and leave you with a diff you can't reason about.

Existing options are bad on both ends:

• Fully autonomous — agent decides what to touch, you find out at the end. No ability to course-correct mid-run.
• Fully manual — you write every instruction, paste every file. Defeats the point of having an agent.

There's no middle ground where a human stays in control at the moments that actually matter: what is in scope, what will the agent do, and what did it change.

---

What Agents Flightdeck Does

Flightdeck is a human-in-the-loop orchestration layer for AI coding agents. You define the goal, curate exactly which code is in scope, review and approve the generated plan, then watch agents execute — with a gate between every step and a git diff after each one.

You stay in control at every decision boundary. The agent does the work between them.

---

Features

Jidra — Codebase Intelligence

Flightdeck is backed by Jidra, a language-aware MCP server that indexes Java, Go, and TypeScript codebases using AST parsing and BM25 search. It surfaces methods, their signatures, source, and call graphs — not just file paths.

When you launch a mission, Jidra searches the repo using your goal as the query and returns a graph of relevant methods with their callee chains. You can override the search query to target a specific class or method precisely.

Context Curation

Before planning, you see every method Jidra surfaced as a selectable node graph. You check exactly which methods are in scope. The planner sees only the source of checked methods — nothing else in the codebase is visible to it. This eliminates hallucinated scope and forces surgical instructions.

You can expand any node to read its source before including it.

Surgical Planning

A Claude Sonnet planner reads the curated source and generates a task graph: one node per independent concern, one test/verify node at the end. Each node gets:

• A precise title and step-by-step instructions referencing exact file paths, class names, line numbers
• A model assignment (default: claude-haiku-4-5)
• A per-node USD budget enforced at the SDK level — the agent is stopped mid-run if it exceeds it

If the goal is ambiguous given the source shown, the planner asks clarifying questions before generating rather than guessing.

Human Approval Gate

Before any agent runs, you review the full plan. Edit any node's instructions inline, adjust budgets, delete nodes, or set a mission-level cap. Nothing executes until you click approve.

Execution Gate

Between every two nodes, execution pauses. Flightdeck captures a git snapshot of what the previous agent changed — changed files are listed in the terminal and shown in a modal. You review the diff, then approve to continue or halt the mission. Nothing proceeds until you decide.

Live Terminal Streaming

Each node's Claude Code agent streams output in real time to an embedded xterm.js terminal — tool calls (Read, Edit, Write, Bash), output previews, budget progress, and final cost summary. A per-node budget bar fills as the agent spends.

Git Diff Viewer

After every node completes (including budget-exceeded failures), Flightdeck captures a git snapshot and renders a side-by-side diff with file tabs, line numbers, and added/removed highlighting. The diff is persisted as an artifact so you can revisit it at any time.

Audit Trail

Every action — stage transitions, tool calls, budget warnings, gate decisions, agent completions — is written to an append-only SQLite audit log. Full cost and token accounting per node and per mission.

Mission History

All past missions are listed with stage, status, and total cost. Resume a halted mission, inspect any prior run's terminal output and diffs, or delete it.

---

Architecture

flowchart LR
    U(["👤 Human"])

    subgraph WEB["Web UI · React / Vite · :5173"]
        W["Node graph\nDiff viewer\nxterm.js terminal"]
    end

    subgraph SRV["Server · Node.js / Express · :3000"]
        direction TB
        SM["Stage machine\ncontext → plan → approve → execute"]
        GH["⏸ Gate\nfires between every node"]
        DB[("SQLite\nmissions · nodes · gates · audit")]
        WS["WebSocket\nreal-time stream"]
        SM --> GH
    end

    subgraph MCP["Context Backends"]
        J["JIDRA MCP\nAST · BM25 · call graph\n(stdio subprocess)"]
        CG["CodeGraph MCP\nblast-radius graph\n(stdio subprocess)"]
        GR["grep fallback\nfile paths · no MCP"]
    end

    subgraph AI["Claude Agent SDK · Anthropic API"]
        PL["claude-sonnet-4-6\nPlanner"]
        EX["claude-haiku-4-5\nExecutor · per node · budget-capped"]
    end

    REPO[("📁 Target Repo\ngit-tracked codebase")]

    U -- "REST / WS" --> WEB
    WEB -- "REST / WS" --> SRV
    SRV -- "stdio" --> MCP
    SRV -- "HTTPS" --> AI
    AI -- "Read · Edit · Write · Bash" --> REPO
    MCP -- "node graph" --> SRV
    REPO -- "git snapshot\n(diff per node)" --> SRV

Loading

---

Prerequisites

• Node.js 20+
• pnpm 9+
• Python 3.10+
• Claude Code CLI — npm install -g @anthropic-ai/claude-code

---

Setup

1. Copy the env file and fill it in:

cp .env.example .env

Open .env and set:

ANTHROPIC_API_KEY=sk-ant-...        # required — your Anthropic API key

JIDRA_PYTHON=/path/to/python3       # required for JIDRA backend
                                    # python binary from the external Jidra project's venv
                                    # e.g. /home/you/jidra/.venv/bin/python3.14
                                    # skip if you only use CodeGraph or No tools backend

2. Install dependencies:

pnpm setup

Runs pnpm install across all workspaces.

---

Start

pnpm dev

Starts server and web concurrently. UI at http://localhost:5173.

---

Flow

1. Launch a mission

Set the repository path, enter your goal, and choose a context backend from the dropdown. Auto mode probes for JIDRA → CodeGraph → fallback and picks the best available backend.

---

2. Build context

Flightdeck searches the codebase and returns a node graph. Each node is a method or file — depending on backend. Check the nodes you want in scope. The planner sees only the source of checked nodes; nothing else in the repo is visible to it. Expand any node to read its source before including it.

JIDRA MCP — method-level graph, seed nodes from BM25 search:

JIDRA — manually add a method by name to expand scope:

CodeGraph MCP — file-level blast-radius graph:

CodeGraph MCP — manually add a method by name to expand scope:

No tools — file path nodes from grep, no MCP required:

---

3. Plan

Curate which nodes are in scope, then generate the plan. The planner sees only the source of checked methods. Toggle between Graph and Raw view — Raw shows the full step-by-step instructions per node.

JIDRA — plan graph with model and budget per node:

JIDRA — raw view with precise method anchors, file paths, line numbers:

CodeGraph — plan graph:

CodeGraph — raw view:

No tools — plan graph, file-level only:

No tools — raw plan, file-level only:

---

4. Approve

Review the full plan before anything runs. Edit node instructions inline, adjust per-node budgets and models, delete nodes, or set a mission-level spend cap. Click Execute when ready.

JIDRA:

CodeGraph:

No tools:

---

5. Execute

Agents run with live terminal streaming. After each node completes, execution pauses — changed files are shown in the terminal and a gate modal appears. Review the Git diff tab, then approve to continue or halt.

JIDRA — node 1 running, live terminal output:

Gate fires — node 2 waiting for approval before it starts:

Node 2 running after approval:

JIDRA — Git diff tab (side-by-side, per node):

CodeGraph — Git diff tab:

No tools — Git diff tab (4 files changed):

Budget exceeded — node stopped by SDK, diff still captured:

---

Backend Comparison

Two tasks run against the same TypeScript codebase with the same goal.

Test 1 — Remove a variant from an enum-dispatched service class

Goal: remove EVENT from typesWithRights, its switch case, the getEventLineups method it gates, and dead imports.

Backend	Plan $	Exec $	Total	Result
JIDRA	$0.0197	$0.0546	$0.074	✅ Complete
CodeGraph	$0.0878	$0.0665	$0.154	✅ Complete
No tools	—	$0.1016	$0.102	✅ Complete

JIDRA tip: selecting 2+ methods from the same file sends the full file — planner sees class-level fields and constants. Selecting a single method sends method source only — may miss fields like typesWithRights.

Test 2 — Swap a deprecated constant across all call sites

3 occurrences, pure method-body change, no class-level side effects.

Backend	Exec $	Result
JIDRA	$0.0608	✅ All 3 replaced
CodeGraph	$0.1010	✅ All 3 replaced
No tools	$0.1016	✅ All 3 replaced

All backends produced identical output. JIDRA cheapest — method-level context sufficient, no file bloat needed.

When to use which

Situation	Backend
Change touches class fields, constants, or multiple methods in same file	CodeGraph or JIDRA (select 2+ methods)
Change scoped to specific method bodies	JIDRA
No MCP server available	No tools
Unknown / let system decide	Auto