Hub-based multi-agent orchestration for OpenCode
- 31 specialized agents for different task types
- 105 workflow skills for development tasks
- 30 TypeScript tools for session management and file editing
- 154 hub subcommand specs across 6 hub directories
- Hook system plugin for mode detection, state persistence, and context injection
- Multi-tier cache system — tool, file, session, vector search caching
- Durable context storage — knowledge compounds across sessions
Every turn, every subagent invocation, every verification round costs an API request. Minimize them.
When making multiple independent tool calls, batch them in a single message. Reading 3 files? 3 Read calls in one message. Dispatching 2 subagents? 2 Task calls in one message. Never serialize independent operations across multiple turns.
Think, then act in the same turn. Do not send a message that only contains analysis, planning, or narration without taking action. Internal reasoning happens before the tool call, not as a separate message. The user sees results, not process.
Handle tasks directly by default. For natural-language requests, assess whether you can do the work yourself with good results. Only propose delegation when it would be meaningfully faster or more effective. When the user explicitly selects an orchestration pattern from the hub menu or names a subagent, use that pattern — no proposal needed.
Give subagents everything they need in one prompt. Include full file contents, relevant rules, expected output format, and verification commands. A subagent that completes in 1 turn saves 2+ API requests over one that needs follow-up.
Verify your own work before handing off. Run the test/lint command, check the output, confirm it works. Only escalate to @verifier when self-verification fails or the task explicitly requires independent review. Skip verification entirely if no files were modified.
After completing work, report results and stop. Do not ask "Would you like me to..." or "Shall I proceed with..." — the user already gave the command. Only ask follow-up questions when genuinely blocked (missing credentials, ambiguous requirements, conflicting instructions).
Cache Context7 documentation results. Before calling Context7 MCP, check .opencode/context/research/ for existing cached docs matching the library and query. After fetching, save results to .opencode/context/research/{library-slug}/ for future reuse. Library docs rarely change — cache with a 7-day TTL.
Cache file reads within a session. When reading a file that was already read earlier in the same session, use the cached content instead of re-reading. The file cache namespace (24h TTL, memory-only) is available for this. Invalidate on write to the same file.
Classify subagent errors before retrying. Provider errors (connection refused, model unavailable, 502/503/504, timeout, rate limit) → retry with fallback. Task errors (incorrect output, wrong implementation) → fix the task prompt, don't retry. Tool errors (file not found, permission denied) → fix the root cause, don't retry. Never retry more than 3 times total.
| Rule | Purpose |
|---|---|
shell_strategy.md |
Non-interactive shell — CI-safe commands, banned patterns |
context-strategy.md |
Durable memory — state vs context, manual-only load/save |
karpathy-guidelines.md |
Think before coding, simplicity first, surgical changes |
file-operations.md |
No standalone scripts at project root; use file-editing tools, not inline scripts |
hub-description-directive.md |
Hub subcommand description conventions |
security.md |
Security rules — mandatory checks, secret management |
completion-guardrail.md |
MANDATORY STOP after planning/analysis — no auto-implementation |
On-demand rules (load via tool when needed): hub-routing.md, resource-tags.md, global-reference.md, hub-state.md
| Type | Location | Git | Lifecycle |
|---|---|---|---|
| State | .opencode/state/ |
Gitignored | Ephemeral session data |
| Context | .opencode/context/ |
Committed | Durable knowledge |
| Secrets | .opencode/state/sessions/ |
Gitignored | Session lifetime only |
All context operations are MANUAL ONLY. No auto-harvest, auto-commit, auto-chain, or auto-submit.
Magic keywords (ralph, autopilot, ultrawork, build me, create me, etc.) do NOT auto-activate modes. The plugin detects them and injects a context message, but the agent must propose the mode to the user and get explicit confirmation before activating.
Each tier has a failover chain: Primary → F1 → F2 → (F3). Stop on first success. Model key: o=ollama, og=opencode-go, oc=opencode (free).
| Tier | Primary | F1 | F2 | F3 | Agents |
|---|---|---|---|---|---|
| Pro | o/dsv4-pro:cloud |
og/dsv4-pro |
oc/dsv4-flash-free |
(NVIDIA) | architect, planner, security-reviewer, requirements-analyzer, tracer, analyst, critic |
| Default | oc/dsv4-flash-free |
o/dsv4-flash:cloud |
og/dsv4-flash |
(NVIDIA) | hubs, executor, debugger, test-engineer, designer, frontend-design, git-master, config-orchestrator, skill-creator, refactoring, code-simplifier, qa-tester, code-reviewer, scientist, deep-thinker |
| Fast | oc/dsv4-flash-free |
o/glm-5.2:cloud |
og/glm-5.2 |
— | writer, verifier, document-specialist, effort-estimator, explore, commit-drafter, prompt-simplifier, convention-extractor |
Routing: Pro → complex reasoning. Default → implementation/testing/debugging/design. Fast → docs/verification/search.
Session model: o/dsv4-flash:cloud (set in agents/hubs.md frontmatter).
Failover: Provider errors advance chain after 60s. Task errors → fix prompt, don't advance. Chain exhausted → escalate via question tool.
Max turns per subagent, configurable by agent type:
| Agent Type | Max Turns | Rationale |
|---|---|---|
| writer, verifier, document-specialist, effort-estimator, explore, commit-drafter, prompt-simplifier, convention-extractor | 3 | Simple or narrowly-scoped tasks — rarely need more |
| executor, debugger, test-engineer, designer, frontend-design, git-master, config-orchestrator, skill-creator, refactoring, code-simplifier, qa-tester, code-reviewer, scientist, deep-thinker | 5 | Standard dev tasks — may need iteration |
| architect, planner, security-reviewer, requirements-analyzer, tracer, analyst, critic | 7 | Complex reasoning tasks — may need deep analysis |
If no output after the max turns, terminate and escalate. Looping/hanging subagents waste API requests — needs a better prompt or different approach.
| Command | Purpose | Subcommands |
|---|---|---|
/init-project |
Project init | setup, detect, recommend, docs, context, verify, refresh, status, map-codebase, doctor, reset, provision, tag, find-skills, find-agents, find-tools, find-rules |
/ideation |
Planning/research | plan, brainstorm, decomposition, refine, overhaul, deep, graph, research, ralplan, ddd, event-storming, double-diamond, jtbd, impact-mapping, spiral, top-down, bottom-up, adversarial-debate, cleanroom, pwf, rpikit, hive, story-mapping, lean-canvas, constitution, quality, architecture, redesign, grill, modularity, arch-prep, web-research, tech-eval, competitive-analysis, tree-of-thoughts, opro, analyze-patterns |
/orchestrate |
Execution | ralph, team, deep, ccg, ultrawork, autopilot, sciomc, swarm, state-machine, consensus, evolutionary, spec-driven, react, plan-execute, hive, tdd, pair, pipeline, gsd, self-assess, remediate, devin, maestro, metaswarm, cc10x, gastown, ruflo, harden, subagent-driven, brownfield, vibe-code |
/harvest-context |
Context mgmt | session, codebase, skill, agent, rule, command, memory, docs, web-research, compare, decompose, context, consume, compress, secondbrain, journal, search, prune, export, diff, sweep |
/project |
Project ops | create-tests, commit, git-stage-thread, pr, gh, optimize, refactor, simplify, cleanup, modernize, icon, organize, changelog, converge, scan, sandbox, retrospect, purge, release, review, audit, archive, git-cleanup, workspace, readme |
/skills |
Skill management | list, add, create, remove, edit, search, info, update, package, validate, sync, setup, scan |
Each of the 155 hub subcommands has a dedicated spec file in tools/hubs/<hub>/<subcommand>.ts containing the full HubSubcommandSpec — detailedDescription, tools, rules, relatedSkills, examples, warnings.
Direct selection (/orchestrate ralph): hubMenu route returns the full spec in one response (detailedDescription + inlined rules + related skill pointers + examples). No follow-up loadSkill or rule-read calls needed.
Routing required (bare /orchestrate + NL task, or pure NL): hubMenu menu returns the slim identity slice (label + short description + reminder) for the model to pick from. Then route loads the full spec for the chosen subcommand.
See rules/hub-routing.md for the complete delegation table and architecture details.
| Keyword | Injects Mode Context |
|---|---|
"ralph", "don't stop", "must complete" |
Ralph |
"autopilot", "build me", "create me" |
Autopilot |
"ultrawork", "ulw", "uw" |
Ultrawork |
"deep interview" |
Deep-interview |
"cancel", "stop" |
Cancel modes |
~/.config/opencode/
├── opencode.jsonc # Main configuration
├── AGENTS.md # This file (core instructions)
├── agents/ # 31 agent definitions
├── skills/ # 105 workflow skills
├── commands/ # (empty — all subcommands live in hub menus)
├── archetypes/ # Project archetype templates (bare-bones, cli-tool, go, nextjs, etc.)
├── tools/ # TypeScript tools
│ ├── hubMenu.ts # Hub menu router (route returns full spec, menu returns slim slice)
│ ├── hub-data.ts # Hub types, subcommand spec loader, state helpers
│ ├── hub-<name>.ts # Thin hub manifests (10 lines each, identity slice only)
│ ├── hubs/ # Per-subcommand spec files (155 files across 6 directories)
│ └── ... # File editing, cache, session, skill tools
├── plugins/ # Hook system + TUI plugin
├── rules/ # Shared rules (loaded as instructions)
├── templates/ # File templates
├── rule-templates/ # Rule generation templates
├── tool-templates/ # Tool generation templates
└── .opencode/ # Project state, context, docs, cache
├── state/ # Session state (gitignored)
├── context/ # Durable knowledge (committed)
│ ├── research/ # Cached Context7 documentation
│ ├── index.md # LLM Wiki catalog
│ ├── log.md # LLM Wiki operation chronicle
│ └── wiki-schema.md # LLM Wiki schema
├── cache/ # Multi-tier prompt cache (gitignored)
├── docs/ # Generated documentation
└── CHANGELOG.md # Auto-commit log
Use Context7 MCP to fetch current documentation when the user asks about a library, framework, SDK, API, CLI tool, or cloud service. Always start with resolve-library-id, then query-docs. Do not use for: refactoring, debugging business logic, code review, or general programming concepts.
Before fetching: Check .opencode/context/research/{library-slug}/ for cached results. If a cached result exists and is less than 7 days old, use it instead of making a new API call. After fetching: Save results to .opencode/context/research/{library-slug}/{query-hash}.md for future reuse.