Custom OpenCode Harness
OpenCode · OpenRouter · Langfuse · MCP · AgentMemory · CodeGraph
Multi-agent platform with phase-routed roles, cost-aware model routing, and a four-plane context stack.
Context
Single-model coding agents thrash on real work. They use an expensive model for mechanical edits, a cheap model for architecture, or one overloaded chat for planning, implementation, and debugging—so context collapses, cost spikes, and the same mistake gets retried with more tokens instead of a better process.
I wanted a harness that treats agent work like an engineering org: different roles for different phases, a default that is cheap enough to run all day, a deliberate path to escalate only when stuck, and durable context so the next session does not re-discover the repo from zero.
What I built
The custom OpenCode harness is a multi-agent platform layered on OpenCode + OpenRouter:
Phase-routed primary agents — planner, build (default executor), debug, and an optional orchestrator for large parallelizable jobs.
Subagents for specialized work — exploration, general implementation, code review on a different model family, and a multi-model consult panel when one model is stuck or stakes are high.
Cost-aware routing — open-weight executors pinned to cache-friendly providers where possible; frontier models reserved for plan, systematic debug, and review.
Four-plane AI context layer — agentmemory (session/decision memory), codegraph (live symbol graph), Understand Anything (architecture / domain maps), Graphify (broader corpus including non-code). Each plane answers a different question class so agents do not grep the world by default.
Observability — Langfuse / OpenRouter generation metadata and broadcast-style tagging so cost and routing are inspectable, not folklore.
Config is the product: global tooling stays lean; product MCPs and stack skills live in the repo that needs them.
How it works
Work enters with a phase. Planning is not the same loop as implementing a two-file fix, and neither is systematic debugging.
Planner owns design and implementation plans (and is gated away from casually editing production source while the plan is still being written). Build is the default executor: high agentic throughput at controlled cost. Debug is a Tab-away primary for root-cause work when the cheap loop is spinning. Orchestrator is optional: it coordinates, verifies, and delegates rather than absorbing the whole codebase into one context window.
Escalation is explicit. The build loop has a retry cap. Repeated gate failures, malformed tool use, unverifiable “success,” or oversized diffs promote the subtask to a stronger model—or to the multi-model panel when bias or stuckness is the risk. Planner-tagged hard work (type-level, concurrency, schema migration, auth) can skip the cheap tier entirely.
Context is consulted by intent. Memory for “what did we decide?” Codegraph for “where is this symbol / who calls it?” Architecture maps for onboarding and flow. Corpus graphs for specs and non-code. The rule of thumb: reach for the cheapest plane that answers the question; do not re-read the tree when a graph already holds the edge.
Skills encode process (brainstorming, TDD, subagent-driven development, finishing a branch) so the harness improves with every workflow, not only every prompt tweak.
Decisions
Profile B routing. Frontier models on plan and debug; a strong cheap model on the execute loop. Planning is the leverage point—economizing there is false thrift. Executing with a cache-sticky mid-tier model is how long sessions stay affordable.
Retry cap = 2 before escalate. Infinite cheap retries burn money and hide process bugs. Two failed gates, then a better model or a panel, forces either a fix or an honest escalation.
Isolation of product tooling. Global OpenCode config holds universal MCPs (memory, codegraph, routing). Product integrations (Render, Sentry, Clerk, …) stay project-local so a personal site session does not load a mobile app’s entire stack.
Graph before grep. Codegraph and memory are the primary lookup planes; raw file crawls are the fallback. That is both a cost control and a correctness control—call graphs beat string search for “what breaks if I change this.”
Different model families for review. Code review is dispatched on a model that did not write the patch, on purpose, to catch class-of-bug blindness.
Skills over vibes. Superpowers-style skills force brainstorming before features, verification before “done,” and structured finishes. The harness is only as good as the process it refuses to skip.
Results
Agent work has durable roles instead of one infinite chat persona.
Cost intent is structural: cheap by default, frontier when the phase or the failure mode demands it, with provider pins aimed at cache hits rather than silent hop-shopping.
Sessions stay grounded. Decisions land in memory; structure lives in graphs; architecture and corpus planes cover the questions code search cannot.
The harness is how I ship—including this site. The case study is not theoretical: it is the operating system under the work.