An RTS-style operator interface for supervising fleets of autonomous
coding agents, delivered as a VS Code extension. V1 forks
vscode-jupyter subtractively, wires LLMKernel as the sole kernel,
and uses bidirectional MCP as the structured communication channel
between operator and agent.
The repo started life as a 1.1 MB design conversation
(_ingest/chat-export-2026-04-26T04-22-39.md)
— that conversation is the historical source of truth for the original architectural choices.
The current normative reference is the doc tree under docs/,
with docs/atoms/ holding canonical definitions,
docs/notebook/ + docs/rfcs/
holding behavioral and wire-format specs, and
docs/kernel/ holding substrate-level documentation
for the embeddable LLMKernel (capture invariants, identity model,
deployment surfaces, per-slice implementation plans).
V1 is shipped — tagged v1.0.0 on 2026-06-30. Every row of the PLAN-v1-roadmap §5 ship-ready checklist is ✅ green. Rows 1-11 (operator-visible UX) shipped 2026-05-02 → 2026-05-19; the last two rows closed this cycle:
- Row 13 (substrate gaps) — all 9 gaps closed 2026-06-30 via PLAN-substrate-gap-closure. Kernel test suite: 908/908 green.
- Row 14 (atom drift) — full PLAN-atom-hygiene sweep landed 2026-06-30. All 3 verification checks (orphan / drift / Status-line consistency) return empty.
Operator-visible V1 UX (feature-complete since 2026-05-19): S5.5 sections (full collapse via native markdown fold), S7 sidebar trees (zones / agents / activity), S10 reduced V1 (streaming/artifact badges + bulk-collapse / find wrappers), S10 follow-on (sidebar Find-in-cells WebviewView with the full FSP-002 §2.1 search UX). S5.0.6 (nvim driver) deferred to whenever the nvim operator's dogfooding pressure justifies the per-cell affordance — the headless llmnb execute --connect CLI (df95ad4) covers file-level operation for nvim users in the interim.
V2 lane opened 2026-05-20: branch-switching UX (sidebar Branches subnode under each agent that has forked descendants — lineage recovered from metadata.rts.zone.event_log[*] fork_agent envelopes) and output-kind lens UI (5th sidebar view grouping every tagged span across the active notebook). Both are pure read-side — no kernel changes, no wire changes. See docs/06 - Roadmaps/ROADMAP.md for the V2 short/long-horizon queue.
Genuinely blocked on VS Code API: per-cell gutter color decoration (notebookCellDecoration is not even a Microsoft API proposal, per a probe against the vendored vscode-jupyter's enabledApiProposals). The literal "floating search bar above the editor" is the same ceiling — no overlay-above-editor API. Both surface UX is now in the sidebar instead.
V1 cell-side substrate is shipped end-to-end. Operator @@spawn /
@@agent / @<flag> cell-magic dispatches; agent processes spawn and
persist via --resume; multi-turn cells, cross-agent context handoff,
and the headless executor all work. The cell schema collapsed in S5.0
to {text, outputs, bound_agent_id} with kind/flags parse-derived from
text via the @@ cell-magic + @ line-magic vocabulary
(magic atom).
V1.6+ shipped since 2026-05-02 (most recent first):
-
PLAN-S5.0.5 — cell-magic file encode/decode (commits
ce214baPhase 1 /1c9e81fPhase 2; submodule7139a3f→02fb2d3).@@importextended to accept.magicand.ipynbin addition to native.llmnb; new@@export path:"…" [format:…] [overwrite:…]cell-magic serializes the current notebook to disk. Kernel-speaks-magic throughout — no operator-action envelope round-trip, no RFC-006 bump, no extension changes. Three new K-classes (K3M path-outside-workspace, K3N overwrite-refused, K3O bundled I/O failure withcausesub-code). The cell↔file matrix is now symmetric in all four quadrants. (PLAN-S5.0.5) -
PLAN-S5.0.4 — privileged magic emission (extension
838aa85; kernel2306aef/bc24720/987b7ef).emit_magic_cellMCP toolmagic_emit_privileges[]store +promote_stream_magicoperator action. Privileged agents can produce cells via the structural channel; unprivileged stream emissions stay sanitized.
-
Tier-2
llmnb execute --connect(commitdf95ad4, 2026-05-14). The CLI can now attach to a long-livedllmnb servekernel instead of spawning a fresh PTY-loopback each invocation. Token from--auth-token-env(defaultLLMNB_AUTH_TOKEN); never on argv. Unblocks per-cell execution against a shared kernel from any non-VS Code driver. -
BSP-007 overlay graph — operator-side, git-style commits over the agent turn DAG.
apply_commit/revert_to_commit/diff/branchprimitives; 17 V1 op kinds; §6 cell-merge correctness validators; K90-K95 failure modes. (commit3a430cb) -
BSP-008 RunFrames + ContextPacker integration — every agent turn now persists a
record_context_manifest+ start/terminalrecord_run_frametrail through the BSP-003 intent path. (commit3a430cb) -
PLAN-S6.0 in-tree event log + hydrate-replay safety — the event log lives in
metadata.rts.event_log[];EventLogReplayerassertsdispatcher.is_writable() == Falseat the boundary to prevent double-emission on reopen. (commit03de446) -
Inspect mode V1 (read-only) — per-cell status bar item shows latest RunFrame + ContextManifest summary; click opens manifest detail QuickPick rendering the inclusion/exclusion trace per BSP-008 §11. (commit
92c7412) -
Standalone TCP server —
python -m llm_kernel servewith bearer-token auth lets external drivers (CLI, future Rust/Go orchestrators) attach over TCP. Validation task filed atdocs/ops/validate-serve-mode.md. -
Tier-3 live OAuth+mitm smoke green — 6 Anthropic API calls intercepted; notify + report_completion emitted by the agent. Three latent harness bugs surfaced and fixed in
28c3658(LogRecordnamecollision, missingsend_user_turnafter spawn, missing stdin close). -
Engineering Guide §11.9 — new anti-pattern entry on
logger.*(..., extra={...})keys colliding with reservedLogRecordattribute names; codifies the rule from the magic-injection-defense atom on the path of anyone editing logging. -
Repo hygiene — legacy
vendor/LLMKernel/vscode-llm-kernel-extension/removed (74 files); platforms expanded towin-64+linux-64+osx-arm64; ESLint 9 flat config landed for the active extension.
Test surface: 857 kernel tests + 374+ stub contract tests + 109
outer driver tests all green at last verified run (kernel + driver:
2026-05-16; stub: 2026-05-29 pre-output-kind-lens). The stub tier
grew ~50 tests during the V1-UX-feature-complete sweep and V2 lane
opening; the final V2 output-kind-lens slice (85bd5e4) added 20
more whose verification is pending a Windows VS Code installer
mutex release. Full kernel suite runs in ~20s under xdist.
Shipped slices (per BSP-005 §6.5):
| Slice | Commit | |
|---|---|---|
| ✅ | S0.5 cell-kinds typed enum | 14873a1 |
| ✅ | S1 cell-as-agent badges | 26ac581 |
| ✅ | S2 persistent Claude --resume |
26ac581 |
| ✅ | S3 multi-turn @<agent> continuation |
ac2bb4d + b4cb550 |
| ✅ | S3.5 ContextPacker walker | 64a34d4 |
| ✅ | S4 cross-agent context handoff | fe2121a |
| ✅ | S5.0 cell-magic vocabulary + S5.0.1 injection defenses | 336a6c7 + 88ffb15 |
| ✅ | S5.0.3.x headless executor (TCP + handshake + live mode) | ae7b1a6 → 27c0fcc |
| ✅ | S5a / S8 partial / S9 interrupt | 5b5533e / 8d9bd39 / 5de3401+64a34d4 |
| ✅ | S5c stop | wip/s5c-stop merged |
| ✅ | S6.0 in-tree event log + hydrate-replay safety | 264b69c + 03de446 |
| ✅ | BSP-007 overlay applier + BSP-008 RunFrames | 3a430cb |
| ✅ | Inspect mode V1 (read-only per-cell + manifest detail) | 92c7412 |
| ✅ | Tier-2 llmnb execute --connect (attach to running kernel) |
df95ad4 |
| ✅ | S5.0.4 privileged magic emission (emit_magic_cell + promotion chip) |
838aa85 + submodule 987b7ef |
| ✅ | S5.0.5 Phase 1 — multi-format @@import (.magic / .ipynb) + notebook_format public module |
ce214ba + submodule 7139a3f |
| ✅ | S5.0.5 Phase 2 — @@export cell-magic + K3M/K3N/K3O |
1c9e81f + submodule 02fb2d3 |
| ✅ | S5.5 sections — overlay-based section CRUD; cell kind: "section"; Phase 5 ships native markdown-fold collapse |
645e23a + 8251a5a |
| ✅ | S7 sidebar trees — onLastAcceptedVersion event + 3-view activity-bar (zones / agents / activity) |
03976c7 + 8aaa3e3 + 2260ce0 |
| ✅ | S10 reduced V1 — streaming + artifact cell badges + llmnb.collapseAll* / llmnb.expandAll* / llmnb.findInCells wrappers fanning out to engine builtins |
b07e6f9 |
| ✅ | S10 follow-on — sidebar Find in cells WebviewView with full FSP-002 §2.1 search UX (scope filter / case / whole-word / regex / M-of-N / click-to-reveal) |
426051f |
| ⏸ | PLAN-S5.0.6 Nvim driver V1 — design locked, implementation deferred 2026-05-19 (llmnb execute --connect covers file-level in interim) |
8639949 (PLAN doc) + b7e50cc (deferral) |
| 🚫 | Per-cell gutter color decoration (the "three-pane" colored gutter) — notebookCellDecoration API not exposed and not a Microsoft proposal |
blocked |
| 🚫 | Floating search bar literally above the notebook editor — no overlay API on v1.92 | blocked |
V2 lane (shipped this session, both pure read-side):
| Slice | Commit | |
|---|---|---|
| ✅ | V2 branch-switching UX — sidebar Branches subnode under each agent with forked descendants; lineage recovered from metadata.rts.zone.event_log[*] fork_agent envelopes |
667dd68 |
| ✅ | V2 output-kind lens UI — 5th sidebar view grouping every span tagged with llmnb.output.kind by kind; high-attention kinds first; forward-compat <other> bucket |
85bd5e4 |
| 🔵 | V2 output-kind lens — per-cell decoration (dim non-matching cells) | queued (same notebookCellDecoration ceiling) |
| 🔵 | FSP-002 collapse state promotion (option B: metadata.rts.cells[<id>].metadata.rts.cell.collapsed) |
queued |
| 🔵 | Inspect mode session lineage (which claude_session_id produced each turn across /branch / /revert) |
queued |
| 🔵 | FSP-001 OpenUI button (cells as clickable UI affordances) | queued |
| 🔵 | Multi-provider campaign (gpt-cli / gemini / ollama) |
design doc not yet authored |
Observed velocity is roughly 10× the BSP-005 "working day" budget (which was sized for one mega-round agent in series); see BSP-005 §6.5.
The doc tree has three normative layers:
docs/atoms/— canonical definitions for every reusable noun, verb, rule, decision, and anti-pattern. ~91 atoms across 7 subdirectories (concepts,operations,discipline,decisions,anti-patterns,protocols,contracts). When an atom and a longer spec disagree on what a thing IS, the atom wins.docs/rfcs/— public boundary contracts (wire format, file format, transport, failure surface). Normative for behavior + wire shape.docs/notebook/— BSPs (build sequence proposals), FSPs (feature spec proposals), PLAN-S* slice plans. Normative for substrate behavior + slice sequencing.
docs/decisions/ holds the original 16 design ADRs
(MADR-lite format, design-conversation provenance). The newer
docs/atoms/decisions/ holds the V1/V2 implementation
decisions (PLAN-§4 row IDs like D1-D8 / S1-S6 / etc.) — distinct namespace.
| # | Title | Status |
|---|---|---|
| 001 | V1 MCP tool taxonomy | Draft; implemented (13 tools) |
| 002 | Claude Code provisioning procedure | Draft v1.0.1; implemented |
| 003 | Custom Jupyter message format | Superseded by RFC-006 |
| 004 | Failure-mode analysis + fault-injection harness | Draft; implemented |
| 005 | .llmnb file format |
Draft v1.0.2; implemented |
| 006 | Kernel↔extension wire format | Draft v2.1.0; implemented |
| 007 | .tape files (OTLP/JSON Logs) |
Queued; stub spec |
| 008 | Kernel host integration (PTY + socket + TCP) | Draft v1.0.1; implemented |
| 009 | Zone control + config precedence | Draft; implemented |
docs/notebook/ holds:
- BSP-002 — conversation graph (turns + agents-as-refs)
- BSP-003 — writer / intent registry (canonical mutation path)
- BSP-004 — kernel runtime (legacy
main()dispatch path) - BSP-005 — cell roadmap (the current slice ladder)
- BSP-006 — embedded ASGI sketch (deferred V2)
- BSP-007 — overlay git semantics (commits, refs, merge correctness)
- BSP-008 — ContextPacker + RunFrames module spec
- FSP-001 / 002 / 003 — cells → OpenUI, in-cell search + collapse, test campaign
- PLAN-S* series — per-slice execution plans (S0.5 through S10, plus the S5.0.x cell-magic + executor + injection-defense substreams)
- KB-notebook-target.md — the target architecture; §0 pins V1 amendments
- PLAN-atom-refactor.md — the executed plan for the atom-layer refactor
llmb_rts_notebook/
├── README.md ← you are here
├── LICENSE ← MIT
├── CLAUDE.md ← Claude Code project guidance
├── pixi_guide.md ← Pixi CLI quick reference
├── pyproject.toml / pixi.lock ← Pixi workspace
├── Engineering_Guide.md ← project-level engineering practices
├── Testing.md ← test architecture reference
├── docs/ ← normative documentation
│ ├── README.md
│ ├── atoms/ ← canonical definitions (~91 atoms, 7 subdirs)
│ ├── rfcs/ ← public boundary contracts (RFCs 001-009)
│ ├── notebook/ ← BSPs / FSPs / PLAN-S* / KB-target
│ ├── decisions/ ← 16 original design ADRs (MADR-lite)
│ └── dev-guide/ ← 8 chapters from the design conversation
├── extension/ ← VS Code extension (subtractive fork output)
├── llm_client/ ← Python CLI + executor + transport (`llmnb`)
├── tests/ ← Python driver/CLI test suite
├── tools/ ← one-off maintenance scripts
├── vendor/
│ ├── LLMKernel/ ← submodule, our kernel fork
│ └── vscode-jupyter/ ← submodule, microsoft/vscode-jupyter (read-only baseline)
└── _ingest/ ← decomposition pipeline (frozen)
# Build the extension
pixi run -e kernel npm --prefix extension install
pixi run -e kernel npm --prefix extension run build
pixi run -e kernel npm --prefix extension run package
# Run extension contract tests
pixi run -e kernel npm --prefix extension run test:contract
# Run kernel tests (LLMKernel submodule)
pixi run pytest vendor/LLMKernel/tests/
# Open VS Code on a .llmnb file → cells dispatch via @@spawn / @@agent / @See extension/README.md for extension-specific build
- test detail, and pixi_guide.md for the Pixi env setup.
MIT — see LICENSE.