OpenCode plugin for Agent Hive - from vibe coding to hive coding
npm install opencode-hive
From Vibe Coding to Hive Coding — The OpenCode plugin that brings structure to AI-assisted development.
Stop losing context. Stop repeating decisions. Start shipping with confidence.
``
Vibe: "Just make it work"
Hive: Plan → Review → Approve → Execute → Ship
`bash`
npm install opencode-hive
1. Create .opencode/mcp-servers.json using the template:packages/opencode-hive/templates/mcp-servers.json
- From this repo:
- Or from npm:
2. Set to enable websearch_exa (optional).
3. Restart OpenCode.
This enables tools like grep_app_searchGitHub, context7_query-docs, websearch_web_search_exa, and ast_grep_search.
1. Create Feature — hive_feature_create("dark-mode")
2. Write Plan — AI generates structured plan
3. Review — You review in VS Code, add comments
4. Approve —
5. Execute — Tasks run in isolated git worktrees
6. Ship — Clean commits, full audit trail
During planning, "don't execute" means "don't implement" (no code edits, no worktrees). Read-only exploration is explicitly allowed and encouraged, both via local tools and by delegating to Scout.
#### Canonical Delegation Threshold
- Delegate to Scout when you cannot name the file path upfront, expect to inspect 2+ files, or the question is open-ended ("how/where does X work?").
- Local read/grep/glob is acceptable only for a single known file and a bounded question.
| Create a new feature |
| hive_feature_complete | Mark feature as complete |$3
| Tool | Description |
|------|-------------|
| hive_plan_write | Write plan.md |
| hive_plan_read | Read plan and comments |
| hive_plan_approve | Approve plan for execution |$3
| Tool | Description |
|------|-------------|
| hive_tasks_sync | Generate tasks from plan |
| hive_task_create | Create manual task |
| hive_task_update | Update task status/summary |$3
| Tool | Description |
|------|-------------|
| hive_worktree_create | Start work on task (creates worktree) |
| hive_worktree_commit | Complete task (applies changes) |
| hive_worktree_discard | Abort task (discard changes) |Prompt Budgeting & Observability
Hive automatically bounds worker prompt sizes to prevent context overflow and tool output truncation.
$3
| Limit | Default | Description |
|-------|---------|-------------|
|
maxTasks | 10 | Number of previous tasks included |
| maxSummaryChars | 2,000 | Max chars per task summary |
| maxContextChars | 20,000 | Max chars per context file |
| maxTotalContextChars | 60,000 | Total context budget |When limits are exceeded, content is truncated with
...[truncated] markers and file path hints are provided so workers can read the full content.$3
hive_worktree_create output includes metadata fields:-
promptMeta: Character counts for plan, context, previousTasks, spec, workerPrompt
- payloadMeta: JSON payload size, whether prompt is inlined or referenced by file
- budgetApplied: Budget limits, tasks included/dropped, path hints for dropped content
- warnings: Array of threshold exceedances with severity levels (info/warning/critical)$3
Large prompts are written to
.hive/features/ and passed by file reference (workerPromptPath) rather than inlined in tool output. This prevents truncation of large prompts.Plan Format
`markdown
Feature Name
Overview
What we're building and why.Tasks
$3
Description of what to do.$3
Description.
`Configuration
Hive uses a config file at
. You can customize agent models, variants, disable skills, and disable MCP servers.$3
`json
{
"$schema": "https://raw.githubusercontent.com/tctinh/agent-hive/main/packages/opencode-hive/schema/agent_hive.schema.json",
"disableSkills": ["brainstorming", "writing-plans"],
"disableMcps": ["websearch", "ast_grep"]
}
`#### Available Skills
| ID | Description |
|----|-------------|
|
| Use before any creative work. Explores user intent, requirements, and design through collaborative dialogue before implementation. |
| writing-plans | Use when you have a spec or requirements for a multi-step task. Creates detailed implementation plans with bite-sized tasks. |
| executing-plans | Use when you have a written implementation plan. Executes tasks in batches with review checkpoints. |
| dispatching-parallel-agents | Use when facing 2+ independent tasks. Dispatches multiple agents to work concurrently on unrelated problems. |
| test-driven-development | Use when implementing any feature or bugfix. Enforces write-test-first, red-green-refactor cycle. |
| systematic-debugging | Use when encountering any bug or test failure. Requires root cause investigation before proposing fixes. |
| code-reviewer | Use when reviewing implementation changes against an approved plan or task to catch missing requirements, YAGNI, dead code, and risky patterns. |
| verification-before-completion | Use before claiming work is complete. Requires running verification commands and confirming output before success claims. |#### Available MCPs
| ID | Description | Requirements |
|----|-------------|--------------|
|
websearch | Web search via Exa AI. Real-time web searches and content scraping. | Set EXA_API_KEY env var |
| context7 | Library documentation lookup via Context7. Query up-to-date docs for any programming library. | None |
| grep_app | GitHub code search via grep.app. Find real-world code examples from public repositories. | None |
| ast_grep | AST-aware code search and replace via ast-grep. Pattern matching across 25+ languages. | None (runs via npx) |$3
Each agent can have specific skills enabled. If configured, only those skills appear in
hive_skill():`json
{
"agents": {
"hive-master": {
"skills": ["brainstorming", "writing-plans", "executing-plans"]
},
"forager-worker": {
"skills": ["test-driven-development", "verification-before-completion"]
}
}
}
`How
filtering works:| Config | Result |
|--------|--------|
|
skills omitted | All skills enabled (minus global disableSkills) |
| skills: [] | All skills enabled (minus global disableSkills) |
| skills: ["tdd", "debug"] | Only those skills enabled |Note: Wildcards like
["*"] are not supported - use explicit skill names or omit the field entirely for all skills.$3
Use
autoLoadSkills to automatically inject skills into an agent's system prompt at session start.`json
{
"$schema": "https://raw.githubusercontent.com/tctinh/agent-hive/main/packages/opencode-hive/schema/agent_hive.schema.json",
"agents": {
"hive-master": {
"autoLoadSkills": ["parallel-exploration"]
},
"forager-worker": {
"autoLoadSkills": ["test-driven-development", "verification-before-completion"]
}
}
}
`Supported skill sources:
accepts both Hive builtin skill IDs and file-based skill IDs. Resolution order:1. Hive builtin — Skills bundled with opencode-hive (always win if ID matches)
2. Project OpenCode —
3. Global OpenCode —
4. Project Claude —
5. Global Claude — Skill IDs must be safe directory names (no
, \, .., or .). Missing or invalid skills emit a warning and are skipped—startup continues without failure.How
skills and autoLoadSkills interact:-
skills controls what appears in hive_skill() — the agent can manually load these on demand
- autoLoadSkills injects skills unconditionally at session start — no manual loading needed
- These are independent: a skill can be auto-loaded but not appear in hive_skill(), or vice versa
- User autoLoadSkills are merged with defaults (use global disableSkills to remove defaults)Default auto-load skills by agent:
| Agent | autoLoadSkills default |
|-------|------------------------|
|
hive-master | parallel-exploration |
| forager-worker | test-driven-development, verification-before-completion |
| scout-researcher | (none) |
| architect-planner | parallel-exploration |
| swarm-orchestrator | (none) |$3
You can set a
variant for each Hive agent to control model reasoning/effort level. Variants are keys that map to model-specific option overrides defined in your opencode.json.`json
{
"$schema": "https://raw.githubusercontent.com/tctinh/agent-hive/main/packages/opencode-hive/schema/agent_hive.schema.json",
"agents": {
"hive-master": {
"model": "anthropic/claude-sonnet-4-20250514",
"variant": "high"
},
"forager-worker": {
"model": "anthropic/claude-sonnet-4-20250514",
"variant": "medium"
},
"scout-researcher": {
"variant": "low"
}
}
}
`The
value must match a key in your OpenCode config at provider.. For example, with Anthropic models you might configure thinking budgets:`json
// opencode.json
{
"provider": {
"anthropic": {
"models": {
"claude-sonnet-4-20250514": {
"variants": {
"low": { "thinking": { "budget_tokens": 5000 } },
"medium": { "thinking": { "budget_tokens": 10000 } },
"high": { "thinking": { "budget_tokens": 25000 } }
}
}
}
}
}
}
`Precedence: If a prompt already has an explicit variant set, the per-agent config acts as a default and will not override it. Invalid or missing variant keys are treated as no-op (the model runs with default settings).
$3
Override models for specific agents:
json
{
"agents": {
"hive-master": {
"model": "anthropic/claude-sonnet-4-20250514",
"temperature": 0.5
}
}
}
``For the full experience, install vscode-hive to review plans inline with comments.
MIT with Commons Clause — Free for personal and non-commercial use. See LICENSE for details.
---
Stop vibing. Start hiving. 🐝