Claude implementation harness scaffolding, the five layers, file by file

Why the harness matters more than the model

A wrapper sends a prompt and prints a reply. A harness gives the model an environment to act inside, with a filesystem, a tool surface, a permission gate, a memory layer, and a feedback loop that closes when the work is verified. Anthropic's own engineering post on this estimates that roughly 98% of an agent's observed behavior comes from what surrounds the model, not from the model itself. The corollary is unsettling: the choice of GPT versus Claude versus the next thing matters less than the harness you put around whichever one you picked.

That puts a lot of weight on the scaffolding. So this page does something the existing writing on harnesses does not: walks through one real harness, top to bottom, with every layer anchored to a file you can open and grep.

The five layers, in boot order

These layers boot bottom-up: process boot starts the daemons the bridge needs, the bridge connects the agent the MCP toolbelt extends, the MCP toolbelt makes the tools the layered context tells the agent how to use, and the event-capture instrumentation sits at the top so the client UI can finally see what the agent is doing.

Layer 1 in code, the boot script

The whole boot is 71 lines. Trimmed for readability, the shape looks like this. Every later layer assumes these ports are open and these daemons are alive.

# docker/e2b/files/opt/startup.sh  (71 lines total)

# Layer 1: the virtual display so the agent has a screen
Xvfb :99 -screen 0 1600x1600x24 -ac &
export DISPLAY=:99

# Layer 1: the residential proxy daemon (dormant until configured)
node /opt/brd-proxy.js &

# Layer 1: Chromium with CDP open on 9222
chromium --no-sandbox --disable-gpu \
  --user-data-dir=/root/.chromium-profile \
  --proxy-server=http://127.0.0.1:3003 \
  --remote-debugging-port=9222 about:blank &

# Layer 1: VNC and WebSocket bridge (the user watches here)
x11vnc -display :99 -nopw -forever -shared -rfbport 5900 -q &
websockify 0.0.0.0:5901 localhost:5900 &

# Layer 3 of the harness: Playwright MCP wired to CDP
npx @playwright/mcp --cdp-endpoint http://127.0.0.1:9222 \
  --port 3001 --host 0.0.0.0 --allowed-hosts '*' &

# Layer 2: the agent protocol bridge
node /opt/acp-bridge.js &

# Vite dev server for the app the agent is about to write
cd /app && npx vite --host 0.0.0.0 --port 5173 &

# The single foreground process, the public proxy
exec node /opt/proxy.js

The deliberate omission of set -e at the top of the script is the part most people get wrong on the first pass. A failing VNC daemon must not tear down the agent. The single foreground process, the public proxy on port 3000, is the only thing whose death should end the container.

Layer 3 in code, the MCP toolbelt

One block, three servers. The shape of this block is identical to what Claude Code reads from ~/.claude/settings.json, which means any MCP server you build elsewhere drops in here unchanged.

// src/core/e2b.ts  (lines 175-213)

export function buildMcpServersConfig(): Array<Record<string, unknown>> {
  return [
    {
      name: "playwright",
      command: "npx",
      args: [
        "@playwright/mcp",
        "--cdp-endpoint",
        "http://127.0.0.1:9222",
      ],
      env: [
        {
          name: "PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH",
          value: "/usr/bin/chromium",
        },
      ],
    },
    {
      // Reads /run/mk0r-session.json at tool-call time so pool reuse
      // and reconnect-after-pause both work without restarting.
      name: "scheduler",
      command: "node",
      args: ["/opt/scheduler-mcp.js"],
      env: [],
    },
    {
      // Lazy on-demand provisioning of Resend + Neon Postgres.
      name: "mk0r-provisioning",
      command: "node",
      args: ["/opt/provisioning-mcp.js"],
      env: [],
    },
  ];
}

The two custom servers, scheduler and mk0r-provisioning, both read /run/mk0r-session.json at tool-call time rather than at startup. That tiny detail matters: when a sandbox is paused and later resumed, or when a pool sandbox is reassigned to a new project, the session credentials change, but the MCP subprocesses are already running. Reading at call time, not startup time, is what makes the pool work.

Layer 5 in code, the patched ACP entry

This is the file that earns its own section. The stock @agentclientprotocol/claude-agent-acp@0.25.0 entry point ships, runs, and on its surface looks fine. The problem is that several session-update event types come out of the Claude Code SDK and never make it to the client. Without them, your UI lies about progress during long tool calls, disappears during context compaction, and silently freezes during rate limits.

mk0r ships a patched entry, around 200 lines, that wraps ClaudeAcpAgent.prototype.createSession and replaces session.query.next() with a function that forwards six specific event types the stock SDK drops: api_retry, rate_limit_event, compact_boundary, task_notification, tool_progress, and tool_use_summary. It also captures per-turn cost (session._lastCostUsd) and the typed last error (session._lastApiError) so the bridge can attach a _meta block to the prompt response.

// docker/e2b/files/opt/patched-acp-entry.mjs

// Patch query.next() so events the stock SDK drops still reach the client.
const originalNext = session.query.next.bind(session.query);
session.query.next = async function (...args) {
  const item = await originalNext(...args);

  if (item.value?.type === "system") {
    const subtype = item.value.subtype;
    if (subtype === "compact_boundary") { /* forward */ }
    else if (subtype === "task_notification") { /* forward */ }
    else if (subtype === "api_retry") { /* forward + record */ }
  }

  if (item.value?.type === "rate_limit_event") {
    // includes resetsAt, utilization, overageStatus, isUsingOverage
    /* forward */
  }

  if (item.value?.type === "tool_progress")    { /* forward */ }
  if (item.value?.type === "tool_use_summary") { /* forward */ }

  return item;
};

If you write a harness and your "agent is working" spinner stops moving for 30 seconds at a time, this is almost certainly why. The agent did not freeze. The event that says it's still working never made it through.

Harness versus wrapper, side by side

A useful way to feel the gap is to put a harness next to the shape most people start with, a thin HTTP wrapper that POSTs to the API. The wrapper is fine for a chatbot. It falls apart the moment you want the agent to ship working code.

Where Anthropic and the open reference harnesses sit

For context: Anthropic's engineering post on effective harnesses for long-running agents is the canonical theory. Chachamaru's claude-code-harness on GitHub is a worker / reviewer / scaffolder layout. cc-mini is roughly 1,000 lines of Python that show you what the minimum looks like. None of them ship as a product to non-technical users, so none of them have to solve the boring parts: paused sandboxes that resume cleanly, rotated refresh tokens that survive a host restart, MCP servers that read session creds at call time instead of startup, and a patched entry point that forwards the events the stock SDK drops.

None of those problems are interesting in isolation. All of them are the difference between a harness you can demo and a harness you can run.

What to copy if you're building your own

Three patterns are worth lifting whole, regardless of what your harness is for:

1. Pin every harness dependency, including transitive ones. A floating @playwright/mcp version is the same kind of mistake as a floating database driver version. The harness is a contract; treat it like one.
2. Buffer the agent subprocess's stderr. The first time it dies, you will want the last 200 lines, not the bare error message. mk0r keeps a rolling buffer at the bridge level and attaches it to the rejection.
3. Patch the agent SDK if you have to. Forking a dependency feels heavy, but if the cost is 200 lines of instrumentation and the benefit is a UI that does not lie about progress, fork it.

The honest limits

mk0r's harness is shaped for one job: take a one-sentence app idea from a non-technical user, ship a working Vite + React app inside 30 seconds for static apps and a few minutes for ones that need a database. It is not a general-purpose Claude Code replacement. If you need parallel agents in a multi-process workflow, look at Anthropic's C-compiler post. If you need something small enough to read end-to-end, cc-mini is honest. What mk0r offers is a working answer to one specific question: what does a Claude harness look like when the user is not a developer?

Frequently asked