Build your coding orchestrator from scratch part 1

A developer has built SpurCode, a terminal-UI coding agent orchestrator that pairs a "brain" coding agent with single-shot worker coding agents, letting one agent family delegate tasks to another (for example, Claude Code handing work to Codex). The design borrows Apache Spark's driver–worker model, keeps a human in the loop through the TUI, and is built on the open Agent Client Protocol (ACP) used by editors such as Zed and JetBrains. The author says the setup addresses weaker same-model code reviews, quota-driven interruptions, and poor context management across multiple agents.

Six months ago, I made up my mind to build SpurCode , a TUI coding agent orchestrator, from scratch. At the time, the pain points I was facing on a daily basis mostly came from depending on a single coding agent. It was affecting code quality, productivity, and my ability to stay in a flow state because: - Using the same model family to generate and review code seemed to result in lower-quality code reviews. - Five-hour and weekly quotas kept breaking my flow state. - Context management across multiple coding agents wasn’t effective at the time. Orchestrator The idea behind an orchestrator is simple: you have a team of agents, and you can plan and assign specific tasks to different agents based on their profiles. For example, you might have an engineer agent, a product owner agent, and a sales agent. For each scope of work, you assign the task to a predefined agent. For each agent profile, you can refine: - The prompt the agent’s profile prompt and the specific agent. - The model and the reasoning effort assigned to that agent. - The tools the agent is allowed to use. And yes, many coding agents already support agent orchestration, like Kiro, Claude Code, and Codex, where the main active agent can proactively delegate work to sub-agents. But the coding agent orchestrator I’m trying to build works at a higher level than that. Instead of following the usual main agent → multiple sub-agents model, what I want is: Main coding agent → multiple worker coding agents. So, for example, a Claude Code brain/driver agent could delegate a task to a Codex worker agent. You can see the difference here: - On the left, the brain coding agent is the main interface with the user. It provides the feedback loop between the user and the brain agent. - On the right, the worker coding agent runs a single-shot, task-based session. It receives a task from the brain and asynchronously returns the outcome and artifacts to the brain for review and approval. In my mental modal: - The user me works directly with the brain agent on solutions, task planning, and problem-solving. - The user interacts through the TUI as a chat interface, similar to the chat-based interfaces we use today. - The brain agent provides the interface needed to spin up worker agents based on tasks agreed on by the user and the brain agent. - A worker coding agent should — and must — run a single-task session . - That means there’s no back-and-forth interaction between the brain and the worker while the worker is executing its task receipt. - Once the worker session is done, it reports back to the brain agent for review. - There is an internal feedback loop between brain ↔ worker . And of course, the user can interrupt and take control of that loop through HITL in the TUI: - user ↔ brain agent . This model enables a more autonomous SDLC while still keeping control. Every task should be reviewed by the brain, and HITL stays in charge of critical decisions. The idea comes from Apache Spark , with its driver–worker model. Hint: Spark’s Adaptive Query Execution AQE also gave me a lot of hints for building SpurCode’s planning mode. I’ll cover that in Part 2: the task planner for long-running tasks, planning, and execution. Now that we have a basic understanding of what SpurCode is — a TUI coding agent orchestrator — we can move on to the more technical stuff. ACP Protocol - Build on top of the giant shoulder ACP Agent Client Protocol is an open standard that connects AI coding agents to code editors and IDEs, such as Zed and JetBrains. To me, it looks like a USB protocol that allows an IDE or application to communicate with different coding agents. Why ACP ? At the beginning, I was aware of my own resources and knowledge, and I kept asking myself: - Could I build an entire coding agent from scratch? : - I felt it would be pretty foolish to believe I could build something better than existing, well-known coding agents like Claude Code and Codex. They have far more resources and are already widely adopted. - Could I fork an open-source coding agent like Codex CLI or OpenCode and build on top of it? Maybe. But that would lead to another problem: keeping my fork in sync with the upstream version. At the time, ACP was still at version 0.x.x. It wasn’t stable yet, but it looked very promising because many coding agents were starting to support it. And now, the list is much longer. With ACP, I could immediately have a working coding agent running in the background. Since there were already multiple ACP-compatible agents, the main things I needed to handle were rendering and working with the ACP protocol. The protocol was defined, and existing libraries https://github.com/agentclientprotocol/ could help with it. At the beginning, the architecture was very simple: a TUI to render and display messages from an ACP coding agent. SpurCode would also have a built-in MCP server to provide tools for the brain coding agent to delegate tasks to worker coding agents. Initially, delegation was synchronous. It looked similar to the existing sub-agent model: the brain waited for the worker coding agent to finish Rust - Rataui for TUI The TUI is the main interface between the user and the brain ACP coding agent. Rust had been on my radar for a long time. When I started this project, I barely knew Rust. But I really wanted to learn it and experiment with the beauty of the language. That’s the main reason I chose Rust. Ratatui was also a well-known choice for building TUIs. Why do we need a middle layer after Spur-ACP? Why we need midle layer after Spur-ACP for standardizing to create de-coupling layer Spur-Core to harmonize and standardize The ACP could give out unified about protocol level , but the protocol itself have downside of version pragment and each vender have some change . So, Base on my experience , the down stream the TUI should isolate from the up stream protocol versin deviation , that why we need standardizing layer through the spur-core then after spur-core , you can have standard approach for render to display the ACP messages in TUI with Rataui spur-core is more than just and de-couple layer in context of SpurCode system, but for part 1 , let tactical it as is. At begining , my intending is cover many coding agent as much as possible , that why we have native , json stream or cli wrapper , but eventually , now we most active develop on native acp Because there are many of coding agent overther and each agents have slight different implement, the adjust will go through adapters/ .rs for standardize 1. connection/native.rs — the native path: spec-shaped by construction For a spec-compliant agent, the native connection does no shaping at all — that’s the point. It parses the official JSON-RPC frame directly into the official schema types and forwards: // native.rs essence session notif tx: broadcast::Sender<SessionNotification , // L1036 — connection-scoped // wire frame → serde → typed SessionNotification agent client protocol schema // → pass through only two guards , then broadcast: fn cache session notification mode update ... // L1355: side-cache CurrentModeUpdate fn should forward session notification ... // L1372: drop notifs for closed sessions Key idea: shaping = deserialization into spec types + filtering. The message is already the right shape the moment serde succeeds — nothing is rewritten, no vendor fields invented. The guards only side-cache state and suppress stale sessions; they never mutate the payload. adapter/pi.rs — the adapter path: re-shaping a deviant vendor Pi streams terminal output inside a non-standard meta tunnel and never sets spec raw output. The standardizer repairs it in place, in stream order: // pi.rs — the whole contract in ~30 lines pub fn standardize &mut self, mut notification: SessionNotification - SessionNotification { if let SessionUpdate::ToolCallUpdate ref mut update = notification.update { self.standardize tool call update update ; // serial, per-stream = order-safe } notification // same object, now spec-shaped } fn standardize tool call update &mut self, update: &mut ToolCallUpdate { if let Some data = update.meta.get "terminal output" .and then |v| v.get "data" .and then Value::as str { let entry = self.terminal output.entry tool call id .or default ; append capped entry, data, ACCUMULATOR CAP BYTES ; // bounded accumulator update.fields.raw output = Some json entry.clone ; // CUMULATIVE — TUI // replaces act text // meta kept untouched: vendor diagnostic; consumers MUST NOT depend on it } if let Some exit = meta.get "terminal exit" { // vendor terminal signal → let status, raw output = match exit code { // spec ToolCallStatus Some 0 | None = ToolCallStatus::Completed, accumulated , ... - native.rs: “if the vendor speaks spec, pass the typed frame through untouched” — shaping costs zero. adapter/pi.rs: “if the vendor tunnels, keep a per-tool accumulator and rewrite the update so it looks exactly like a spec agent would have” — so downstream, Pi and a spec-perfect agent are indistinguishable. spur-core : the core/heart of entire SpurCode. is transfer the language of acp to the SpurCode internal behavior system The wrap silver → gold, verbatim : notification pump.rs:232 Every standardized ACP notification crosses into SPUR’s language like this — nested whole, not flattened: // notification pump.rs the pump drains the drain-loop’s callback funnel.emit SpurEventBody::AgentNotification { session: spur session id.clone , // SPUR’s own session identity notification: Box::new notification , // ← the ENTIRE spec ACP update, } ; // untouched, boxed inside snapshot.emitted = snapshot.emitted.saturating add 1 ; fn emit lag funnel, session, skipped { ... } // and when the pipe lagged, SPUR // says so in its own language Note the shape: SPUR adds who session and keeps what Box<SessionNotification — no field-mapping, no data loss, and the TUI/brain still gets the full spec event for rendering. Now try to look into the architecture from other perspective. what is the difference between the brain coding agent and worker coding agent . - Either brain or worker coding agent , if there are communicate through acp and the spur message/event traversal through spur-acp and spur-core before consume by whatever consumer app , then we trick it as the same , the same render engine or acp event through spur event envelop Message/event ordering the ordering of message is supper critical here because of : what happen if there are wrong order : the TUI could not correct display the acp streaming message . what happen if there are end tune event come before the acp streaming message chunk. the render should stop the render/missing content spur-acp → spur-core boundary: subscribe-before-prompt + single-callback drain crates/spur-core/src/notification drain.rs drives every agent’s stream // Subscribe BEFORE calling prompt so we don't miss notifications // emitted during the async setup inside prompt . let mut notif rx = connection.subscribe session notifications ; ... loop { tokio::select { biased; // stream frames one at a time → serial callback = per-agent FIFO Some notif = ... = on notification notif , // ONE at a time None = ... // stream closed → grace deadline = Some now + TRAILING NOTIFICATION GRACE , // 100ms for stragglers } } Guarantee: an agent’s own events are processed strictly one-by-one, in arrival order, and late frames still get numbered before the turn’s later events. spur-core → down stream // Emitters brain, workers, executors all just enqueue: pub fn emit &self, body: SpurEventBody { let = self.tx.send FunnelCommand::Event body ; // unbounded mpsc } // ONE funnel task owns seq + publish: FunnelCommand::Event body = { let s = seq.fetch add 1, Ordering::Relaxed ; // ① next ticket number let event = SpurEvent { occurred at: SystemTime::now , seq: s, body }; lineage.lock .apply &event ; // ② in-memory projection let = broadcast tx.send event ; // ③ publish — same task, } All senders serialize onto a single mpsc queue; the single funnel task does number → project → broadcast as consecutive statements, so every consumer sees identical order. Cross-agent ordering exists only here. orchestrator.rs:392-399 documents it: “Monotonic sequence counter for the S2 funnel. The funnel task drains onto event tx , stamping monotonic seq…”, bus created at :486 broadcast::channel 4096 . The beauti of it is about : for TUI , you can easy to subscribe to the bus, the same logic to handle every acp message per coding agent . The same language SpurEvent from the Spur-Core Summary For Part 1: we target the high level architecture , the the fundamental about why ACP, the main backbone event driven/streaming processing architecture , standardizing and dedouplication between each layer where - Spur-ACP best effort to give out shape-spec driven ACP message from different coding agent - Spur-core the heart of the entire SpurCode try to translate the acp message , orchestrate, translate things into internal SpurEvent message/event bus for downstream - Spur-TUI which is the main interface, subscribe to the 4096 bus SpurEvent for rendering and act as the main interface between user and the brain-agent , also observe the flow of the worker coding agent