Skip to content
Series
20 posts

Looplane Architecture Notes

Follow one coding-agent task through Looplane: from the TUI, disposable workspace, prompt, and two runtime lanes through tool authority, the state/event lifecycle, MCP, subagents, SDK/IDE integrations, and finally Cloudflare remote execution. Each article traces one data flow, failure boundary, and test surface.

Series guide

Looplane's TUI and CLI: how a run becomes visible in the terminal

Looplane's TUI and plain CLI are two interfaces over the same runtime paths. The CLI selects a presentation mode from TTY state and flags, runners emit events, and the TUI projects those events into thinking, tool, approval, verification, and terminal states. The screen distinguishes native and external runtimes without treating UI entry points as proof of backend maturity.

Looplane prompts, instruction precedence, and explicit memory: what the model actually sees

Looplane resolves user and root-to-leaf project instructions before rendering named prompt sections for runtime, skills, workspace state, and the latest 20 explicit memories. The pipeline is traceable and reloadable, but it is not semantic memory and repository text does not become system authority.

Looplane's provider-neutral native loop: from one model turn to a verified terminal state

Looplane's native lane is controlled by AgentRunner: prepare a workspace, request a model turn, execute tool calls, append observations, and enter verification only when the model stops calling tools. Step, wall-time, repetition, token, and cancellation guards can terminate the run independently of the model. Protocol translation belongs to the next article.

Looplane's ModelProvider multi-gateway: multiple protocols, one canonical contract

Looplane collapses OpenAI-compatible, Responses, Anthropic, Gemini, Workers AI, scripted, and experimental Codex OAuth adapters into one `ModelProvider` contract. The Codex OAuth transport reads SSE but still reduces it inside the adapter into one canonical `ModelTurn`; AgentRunner does not consume token deltas.

Looplane's ExternalCodingRunner: why Codex and Claude Code CLI are external runtimes, not ModelProviders

`ExternalCodingRunner` is Looplane's second runtime lane. The external coding CLI owns its model loop and credentials; Looplane hands off a task and disposable clone, then treats the returned patch as untrusted input and reruns path audit, verification, and the source invariant. This is a capability-bounded handoff, not another `ModelProvider`.

Looplane's tool isolation: path allowlists, strict argv, process groups, and credential-free subprocesses

This article follows one Looplane tool call through its mechanical execution boundary: `SafePathPolicy` for paths and symlink escape, fixed argv with `shell=False`, a sanitized subprocess environment, read-version hashes plus atomic replace for writes, and process-group cleanup at timeout. Permission policy, OS containment, and tool programs are reserved for later articles.

Looplane's state-first event journaling: recovering between manifest commits and JSONL appends

Looplane maintains append-only `events.jsonl` and atomically replaced `session.json`, reconciling sequences before crash recovery. The same event contract now supports deterministic replay, canonical JSON replay, fork seeds at a selected sequence, and new workspaces without replaying old side effects; ambiguous `tool.started` or `verification.started` states still hard-fail.

Looplane remote execution on Cloudflare: Worker, Sandbox, Capability DO, and durable RunSession

Looplane's old synchronous M6 path completed one real deployed coding run. It has since grown into an asynchronous control plane with RunSession, SSE, approvals, cancellation, and artifacts, but that newer path has not been live-revalidated. Audience-separated HMAC capabilities enter the Sandbox while provider credentials stay in the Worker; this is not production-traffic or SLO proof.