Q-02: LangGraph Fit
Status: ANSWERED Agent: opencode/ext-agent Timestamp UTC: 2026-05-11T02:15:00Z Claim: CLAIM | opencode/ext-agent | 2026-05-11T01:54:47Z
Prior Answers Checked
- Q-01 (pi-teams-fit): Confirms pi-teams is sufficient for MVP. LangGraph evaluated as supplement/replacement.
Short Answer
No. LangGraph is not worth adding to this workcell for MVP. It would introduce a second runtime (Python), a second orchestration layer, and significant pre-staging complexity — all to solve a problem (deterministic task lifecycle) that prompt discipline + pi-teams plan approval mode can handle adequately at this stage. Keep LangGraph as a future upgrade path, not the first build.
Evidence
1. What LangGraph Provides (from docs.langchain.com)
| Feature | How It Works | Relevant to d3-tui-triad? |
|---|---|---|
| StateGraph | Directed graph of nodes (computation steps) connected by edges (transitions) | Maps to T0→T1→...→T7 lifecycle. Strong fit. |
| Durable execution | Checkpointer saves state after each node; resume from failure or pause | Would survive container restarts. Useful but not critical for MVP. |
| Human-in-the-loop | interrupt() function pauses graph, waits for Command(resume=...) |
Maps to "wait for lead approval before T4." Clean pattern. |
| Persistence (MemorySaver, SqliteSaver) | Saves graph state to memory/DB; thread_id acts as cursor | Would make task state durable. pi-teams task board is ephemeral. |
| Streaming | Real-time chunk delivery via astream() |
Nice for observability, not critical. |
| Graceful shutdown | RunControl.request_drain() stops at next superstep with checkpoint |
Useful for Pi resource management. |
| Retry/recover | Auto-resume from last checkpoint after failure | Would handle LLM provider outages gracefully. |
2. T0-T7 Lifecycle Could Be Modeled as a StateGraph
# Conceptual mapping — not implemented
graph = StateGraph(TaskState)
graph.add_node("t0_intake", t0_node)
graph.add_node("t1_research", t1_node)
graph.add_node("t2_plan", t2_node)
graph.add_node("t3_dispatch", t3_node)
graph.add_node("t4_implement", t4_node) # Gated: requires interrupt approval
graph.add_node("t5_validate", t5_node)
graph.add_node("t6_review", t6_node)
graph.add_node("t7_close", t7_node)
graph.add_edge("t0", "t1")
graph.add_edge("t1", "t2")
# ...
graph.add_conditional_edges("t3", approval_check, {"approved": "t4", "blocked": END})
The interrupt() at T3→T4 would enforce "no implementation without plan approval." This is the strongest argument for LangGraph — it would mechanically enforce what prompts currently request politely.
3. The Real Costs
A. Second Runtime on Raspberry Pi
- pi-teams: Bun (JavaScript/TypeScript), already running
- LangGraph: Python 3.10+, pip install langgraph langgraph-checkpoint-sqlite
- The Pi 4 would need both runtimes, both memory footprints, both process trees
- The container already has cgroup/memory-limit issues (see Q-06). Adding Python+LangGraph compounds this.
B. Orchestration Collision Two options, both bad: 1. LangGraph wraps pi-teams: LangGraph nodes invoke pi-teams tools — doubles the orchestration surface, creates a Python→Bun bridge 2. LangGraph replaces pi-teams: Lose tmux pane GUI, autonomous polling, shared task board, and agent messaging. Need to rebuild all of those in Python.
C. Pre-Staging Burden To use LangGraph, the team must: - Design the state graph (nodes, edges, state schema) - Choose and configure a checkpointer (SQLite on Pi? InMemory and lose durability?) - Write interrupt points and resume logic - Integrate with the existing agent prompts and LLM-wiki - Debug graph execution without LangSmith (requires cloud account) - Test all failure/retry/resume paths
This is a separate project — it could easily consume 2-3 sessions before touching D3-TUI. The config-research-pivot.md correction explicitly warned about this: "Would LangGraph need thorough pre-staging to avoid becoming the main project?" — Yes.
D. Loss of pi-teams Strengths The running d3-tui-triad container proves pi-teams works now: - tmux panes with live-labeled agents: visible, debuggable - Autonomous polling: agents find work without manual dispatch - Shared task board: all agents see the same queue - Agent messaging: lead coordinates via inbox
LangGraph provides none of these. Each would need to be rebuilt as LangGraph nodes or replaced with LangSmith (cloud dependency).
4. What pi-teams Plan Approval Mode Provides Instead
pi-teams has a requirePlanApproval flag (not yet configured for d3-tui-triad). When enabled:
- Builder-reviewer must submit a plan before editing code
- Lead receives the plan as an inbox message
- Lead approves or rejects with feedback
- Builder-reviewer only proceeds after approval
This is the T0-T3 gate, implemented with zero new infrastructure. It's manual, not mechanical — but for a three-agent team working on one issue at a time, that's sufficient.
Fit For This Pi Workcell
| Concern | pi-teams Only | pi-teams + LangGraph |
|---|---|---|
| T0-T3 gate before T4 | Plan approval mode (manual) | interrupt() at T3→T4 edge (mechanical) |
| State persistence across restarts | LLM-wiki files (durable) | Checkpointer SQLite + LLM-wiki (dual) |
| Agent coordination | Lead inbox + task board | Graph edges + state transitions |
| Failure recovery | Manual (re-read wiki, re-check board) | Auto-resume from checkpoint |
| Resource usage | 1 runtime (Bun) | 2 runtimes (Bun + Python) |
| Observability | tmux panes (direct) | tmux panes + graph traces |
| Setup time | Already running | 2-3 sessions minimum |
Risks / Failure Modes
- Becomes the main project: LangGraph state graph design, checkpointing config, interrupt logic, and failure handling easily balloon into a multi-week orchestration project. D3-TUI work stops.
- Pi resource starvation: Python 3.10+ with langgraph + langgraph-checkpoint-sqlite + sqlite3 on top of Bun + pi-teams + 4 agent panes. The Pi 4 has 4-8 GB RAM but the container already shows memory pressure.
- LangSmith dependency: LangSmith is "recommended" for debugging interrupts. Without it, you debug graph execution blind. LangSmith requires a LangChain cloud account — a new dependency in the chain.
- Subgraph replay pitfalls: LangGraph re-runs entire nodes on interrupt resume, not single lines. Any file writes or mutations before
interrupt()are duplicated. This is a subtle bug class that bites even experienced LangGraph users. - Two sources of task truth: LangGraph state vs. LLM-wiki claim board vs. Forgejo issues. Three ledgers, one of which (LangGraph state) is opaque to external agents working through the claim board.
Decision Needed From Mehdi
- Defer LangGraph? (Recommended: yes, defer. Use plan approval mode first. Revisit LangGraph only if prompt-discipline coordination consistently fails.)
- Enable plan approval mode now? (Recommended: yes. This gives the T0-T3 gate without LangGraph complexity. One config change in d3-tui-triad.)
- If LangGraph is eventually added: Should it wrap pi-teams (state graph calls pi-teams tools) or replace pi-teams (pure LangGraph with new agent nodes)? This choice determines whether Bun+pi-teams stays.
Next Probe
Enable plan approval mode on the builder-reviewer teammate in the running container and verify the lead can approve/reject plans. This is the direct alternative to LangGraph's interrupt() — test it before evaluating orchestration frameworks further.