A multi-agent architecture for OpenCode with cost-aware model routing, parallel specialist execution, and an agent-maintained project wiki.
OpenCode has powerful features — subagents, custom tools, per-agent permissions, skill files, model variants — that I haven't seen used much in practice. Most setups are a single agent with one model. That works, but it leaves a lot on the table.
I built this to use OpenCode seriously without assigning the most expensive model to every task. Subscription models can handle routing, planning, review, and code generation; usage-based or local models can be mixed in where they provide better quality or economics. The template uses role-based placeholders so it is not coupled to the providers or models I happened to use when it was created.
This is my configuration as a starting point. Python and Go are two of my preferred languages, so both are first-class global specialists: python-pro for modern Python and go-pro for idiomatic Go. For other stacks, add the matching specialists from examples/specialists/ for frontend, backend, database, and DevOps work. Fork it, adjust it, make it yours.
An orchestrator delegates implementation to focused specialists based on the domain of each task. Fast, economical models can handle routing and analysis while stronger models handle code generation, regardless of whether they are subscription, usage-based, or local. Inspired by Anthropic's multi-agent research and Karpathy's LLM wiki concept. Includes code-navigation tools, an agent-maintained project wiki conforming to Open Knowledge Format v0.2, and parallel review with read-only domain reviewers.
Tab cycle (primary agents — user switches between these):
plan orchestrator
(read-only, SUB model) (router, SUB model)
| |
|-- reads code |-- delegates to subagents:
|-- produces plans |
|-- traces impact +-- python-pro (CODE model)
|-- never modifies files +-- go-pro (CODE model)
+-- ops-specialist (SUB model)
+-- wiki-curator (SUB model)
+-- explore/scout (built-in, read-only)
+-- [your specialists]
Project-level agents:
orchestrator override review-lead your-project-dev
(primary, project routes) (SUB model, read-only) (CODE, edit-capable)
| | |
+-- project task allow list +-- routes diffs only to +-- knows your project's
read-only reviewers architecture & conventions
Primary agents appear in the Tab cycle -- the user switches between them directly. The plan agent investigates and plans; the orchestrator executes by delegating to specialists.
Subagents are hidden from the Tab cycle and invoked by primary agents via the Task tool. They do the actual work: writing code, reviewing diffs, maintaining the wiki.
Smart routing: The orchestrator reads the request, determines which specialist(s) are needed, and fans out in parallel. A Python refactor goes to python-pro, Go services and CLIs go to go-pro, and deployment work goes to ops-specialist. A cross-cutting feature fans out to multiple specialists simultaneously.
Prerequisites: OpenCode installed, at least one LLM provider configured.
Open OpenCode in this repository:
cd /path/to/opencode-hive
opencodeThen say:
Set this up for my project at /path/to/my-project
OpenCode reads the AGENTS.md file, discovers your available models, detects your project stack, and installs everything with the right model assignments. See AGENTS.md for the full setup protocol.
# 1. Copy global files
mkdir -p ~/.config/opencode/{agents,tools,scripts,rules,skills}
cp -R global/agents/. ~/.config/opencode/agents/
cp -R global/tools/. ~/.config/opencode/tools/
cp -R global/scripts/. ~/.config/opencode/scripts/
cp -R global/rules/. ~/.config/opencode/rules/
cp -R global/skills/. ~/.config/opencode/skills/
# 2. Copy project files into your target project
TARGET=/path/to/my-project
mkdir -p "$TARGET/.opencode"/{agents,rules,wiki}
cp project/agents/orchestrator.md "$TARGET/.opencode/agents/"
cp project/agents/review-lead.md "$TARGET/.opencode/agents/"
cp project/agents/_project-dev-template.md \
"$TARGET/.opencode/agents/your-project-dev.md"
cp -R project/rules/. "$TARGET/.opencode/rules/"
cp -R project/wiki/. "$TARGET/.opencode/wiki/"
# 3. Merge global/opencode.json into ~/.config/opencode/opencode.json
# Do not overwrite an existing file: preserve its providers, MCP servers,
# plugins, LSP configuration, and other user settings.
if [ ! -e ~/.config/opencode/opencode.json ]; then
cp global/opencode.json ~/.config/opencode/opencode.json
else
echo "Existing opencode.json found; merge the template keys manually."
fi
# 4. Replace all four model placeholders in the copied agent files and
# ~/.config/opencode/opencode.json. See "Model Selection" below.
# 5. Add stack-specific implementation/reviewer pairs, then edit the
# project-local orchestrator.md and review-lead.md allow lists. Replace every
# TODO in your-project-dev.md and review-lead.md before using them.
# 6. From this repository, verify the source template and real installation
python3 scripts/validate-template.py
python3 scripts/validate-template.py --target "$TARGET"If ~/.config/opencode/opencode.json does not exist, copying
global/opencode.json is safe. Otherwise merge its small_model,
default_agent, snapshot, compaction, watcher, and instructions keys
into your existing file. OpenCode merges separate configuration sources, but a
shell copy would still destroy the existing file.
Run opencode models to see every model available from your configured providers. The placeholders describe roles; the tier is only a suggested cost strategy:
| Suggested tier | Cost | Used By | Example Assignment |
|---|---|---|---|
| SUB | Subscription, no per-token cost | orchestrator, plan, review-lead, reviewers, ops-specialist, wiki-curator | Models included with your provider subscription |
| MID | Subscription or pay-per-token | python-pro, go-pro, project-dev, frontend-dev | Your strongest coding model |
| PREMIUM | Frontier pricing | Manual override only | Best available models, used sparingly |
Replace these placeholders in agent files and opencode.json:
| Placeholder | Suggested tier | Role |
|---|---|---|
YOUR_ROUTING_MODEL |
SUB | Orchestrator routing decisions |
YOUR_ANALYSIS_MODEL |
SUB | Planning, review, wiki curation |
YOUR_FAST_MODEL |
SUB | Titles and other lightweight tasks |
YOUR_CODE_MODEL |
MID | Code generation and editing |
Reasoning controls are provider-specific model options, not part of these model IDs. Add reasoningEffort, thinking, or a built-in variant only after selecting a model that supports it. See docs/model-selection.md for details.
The config includes conservative compaction settings (reserved: 24000). Treat them as starting points and tune them for the context window of the models you select. Provider-specific timeout examples are covered in docs/model-selection.md.
| Agent | Model Tier | Role |
|---|---|---|
| plan | SUB | Read-only investigation and structured planning. Never modifies files. |
| orchestrator | SUB | Routes tasks to specialists. Reads code but delegates all implementation. |
| Agent | Model Tier | Role |
|---|---|---|
| python-pro | MID | Expert Python 3.12+ developer. Types, tests, modern patterns. |
| python-reviewer | SUB | Read-only Python correctness and test review. |
| go-pro | MID | Expert Go developer. Services, CLIs, concurrency, tests, and profiling. |
| ops-specialist | SUB | Linux systems, systemd, deployment, logs, infrastructure. |
| ops-reviewer | SUB | Read-only operational and deployment review. |
| wiki-curator | SUB | Maintains the project wiki. Bootstrap, ingest, query, lint. |
| Agent | Model Tier | Role |
|---|---|---|
| review-lead | SUB | Multi-lens code review coordinator. Routes diffs only to read-only reviewers. |
| orchestrator | SUB | Project-local router override and task allow list. |
| [project]-dev | MID | Your project specialist. Created from _project-dev-template.md. |
| Domain | Implementation agent | Read-only reviewer |
|---|---|---|
| Frontend | frontend-dev |
frontend-reviewer |
| Backend | backend-dev |
backend-reviewer |
| Database | database-dev |
database-reviewer |
| DevOps | devops-engineer |
devops-reviewer |
Copy both files for each domain you use. Add implementation agents to the
project-local orchestrator's permission.task allow list and reviewer agents
to review-lead's allow list. Review workflows never delegate to edit-capable
implementation agents.
The orchestrator can also use OpenCode's built-in explore agent for fast,
read-only code discovery and scout for external documentation or dependency
source research.
Tools appear as native LLM tools in OpenCode—typed parameters, descriptions, and auto-discovery from ~/.config/opencode/tools/. Most wrap a trusted script installed in ~/.config/opencode/scripts/; check wraps a shell script and wiki_search is implemented directly in TypeScript.
| Tool | Script | Purpose |
|---|---|---|
skeleton |
skeleton.py |
Strip method bodies from Python files to produce a smaller structural view. |
impact |
impact.py |
Find likely definitions and usages of a Python symbol. Run before renaming or refactoring. |
seek |
seek.py |
Jump to the exact definition of a class or function project-wide. |
which_test |
which_test.py |
Find tests that textually reference a given module. |
ghost |
ghost.py |
Identify dead-code candidates for manual confirmation. |
check |
check.sh |
Run Ruff lint, Ruff format checking, and—when unscoped—pytest; returns failure if any check fails. |
wiki_search |
-- | Search wiki pages by content (no backing script, implemented in TypeScript). |
The Python code has standard-library fallbacks and works with Python 3.10+.
seek and impact use Jedi when available for better resolution; scanning
tools may call git or grep; check requires Ruff and pytest.
The project wiki is an agent-maintained knowledge base that lives at .opencode/wiki/ inside your project. The wiki bundle conforms to the Open Knowledge Format v0.2 specification — every concept is a markdown file with YAML frontmatter (type, title, description, plus optional trust/lifecycle families), the body is free-form prose, and provenance is recorded with keyed footnotes to sources. Inspired by Karpathy's proposal, it accumulates understanding when you explicitly ask the wiki curator or a wiki skill to bootstrap, ingest, or lint project knowledge.
Spec conformance: the wiki is an OKF v0.2 bundle. Concepts carry
type:(required) and the optional trust (generated,verified) and lifecycle (status,stale_after) families. Provenance lives insources, attributed with markdown footnotes keyed tosources[].id. Consumers that speak OKF — human readers, agents, static site generators, the bundled visualizer — can consume the bundle without bespoke tooling.
- Bootstrap: On first use, the wiki-curator scans your project and creates initial concept files covering architecture, major modules, and conventions — each with OKF frontmatter.
- Ingest: After significant changes (PRs, new features, refactors), feed the source material to the wiki-curator. It extracts knowledge, writes OKF frontmatter (updating
generated.atandsourcesas needed), and updates relevant pages. - Query: Any agent can read the wiki before diving into source code. The
wiki_searchtool matches frontmatter (title,description,type,tags) plus body text. This saves tokens — the wiki provides pre-distilled understanding with provenance. - Lint: Periodic health checks catch OKF conformance failures, stale pages past
stale_after, broken cross-references, and gaps in coverage.
.opencode/wiki/
index.md # Table of contents with links to all pages
log.md # Changelog of wiki updates
WIKI_SCHEMA.md # OKF v0.2 frontmatter schema and conventions
entities/ # Module and service concepts
concepts/ # Patterns, domain terms, glossary
architecture/ # System design and decisions
references/ # First-class copies of external or run material
sessions/ # Valuable query results filed as knowledge
Two skills provide convenient entry points:
- wiki-ingest: "Add this PR to the wiki" — delegates to wiki-curator's ingest operation
- wiki-lint: "Check the wiki health" — delegates to wiki-curator's lint operation
See docs/wiki-system.md for the full guide.
- Copy a template from
examples/specialists/or create a new.mdfile - Set the frontmatter: description, mode (
subagent), model, and permissions. The filename is the agent name; usepermissionrather than the deprecated booleantoolsconfig. - Place it in
~/.config/opencode/agents/when it should exist in every project, or.opencode/agents/when it is project-specific - Add a global specialist to the global orchestrator; add a project specialist to
.opencode/agents/orchestrator.md - Create or copy a separate read-only reviewer and add only that reviewer to
review-lead.md
See docs/adding-specialists.md for a detailed walkthrough.
- Copy
project/agents/_project-dev-template.md - Fill in: project name, layout, conventions, dev commands, key files
- Save as
.opencode/agents/<project-name>-dev.mdin your target project - Add it to the project-local orchestrator. If it needs review coverage, create a separate read-only reviewer for
review-lead.
Create .opencode/rules/my-rule.md in your project. Rules are loaded into every session via the instructions config. Keep each rule file under 50 lines.
Change the model field in any agent's frontmatter using the format provider/model-id. For supported reasoning models, set the provider option separately (for example, reasoningEffort: high).
Switch to the plan agent (Tab cycle). Describe the feature. The plan agent investigates the codebase -- reading files, tracing call chains, checking tests -- and produces a structured implementation plan with specific file paths, risks, and specialist routing.
Switch to the orchestrator. Paste the plan or describe the task. The orchestrator routes to the appropriate specialist(s), providing them with specific file paths and success criteria. For cross-cutting changes, multiple specialists run in parallel.
Invoke the review-lead (via @review-lead or through the orchestrator). It analyzes the diff, categorizes changed files by domain, and dispatches read-only reviewers in parallel. Results are synthesized into one report with severity levels and a verdict; implementation agents are never used for review.
On first use: "Bootstrap the wiki for this project." The wiki-curator scans the project and creates initial concept files with OKF v0.2 frontmatter. After PRs or major changes: "Ingest this PR into the wiki." Periodically: "Lint the wiki" to catch staleness, conformance failures, and broken references.
Agent not in Tab cycle -- Check that the agent's frontmatter has mode: primary. Subagents (mode: subagent) are hidden and invoked via the Task tool.
Subagent can't be invoked -- Check the calling agent's permission.task section. Agent names must match exactly. The orchestrator's task permissions are the most common place to add new specialists.
Project agent unavailable -- Add project-only agents to .opencode/agents/orchestrator.md, not the global orchestrator. OpenCode merges the project-local definition for that project.
Model not found -- Run opencode models to verify the model ID exists and is available from your configured providers. Check for typos in the model field.
Wiki not bootstrapping -- Check whether .opencode/wiki/index.md exists. Its absence is the bootstrap signal; a fresh installation may already contain WIKI_SCHEMA.md.
Tools not appearing -- Tool .ts files must be in ~/.config/opencode/tools/. Verify with ls ~/.config/opencode/tools/. OpenCode auto-discovers tools on startup.
Scripts not found by tools -- Global tools execute their trusted implementations from ~/.config/opencode/scripts/. Ensure that directory was copied during installation and its scripts are readable.
Template validation fails -- Run python3 scripts/validate-template.py to validate the source template, or add --target /path/to/project to inspect the real installed configuration. Installed-target validation also rejects unresolved model placeholders.
- OpenCode Documentation
- OpenCode Agents
- OpenCode Custom Tools
- OpenCode Models & Variants
- OpenCode Configuration
- Open Knowledge Format v0.2 Specification — the spec the project wiki conforms to
- Anthropic Multi-Agent Research
- Karpathy's LLM Wiki
MIT -- see LICENSE.