@hiai-gg/hiai-opencode 0.1.9 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.env.example +0 -19
- package/AGENTS.md +214 -54
- package/ARCHITECTURE.md +9 -11
- package/LICENSE.md +4 -3
- package/README.md +68 -135
- package/assets/cli/hiai-opencode.mjs +137 -86
- package/config/.logs/subtask2.log +2 -0
- package/config/.mcp.json +45 -0
- package/config/.opencode/palace/knowledge_graph.sqlite3 +0 -0
- package/config/.opencode/palace/knowledge_graph.sqlite3-shm +0 -0
- package/config/.opencode/palace/knowledge_graph.sqlite3-wal +0 -0
- package/config/hiai-opencode.schema.json +176 -62
- package/dist/agents/builtin-agents/{guard-agent.d.ts → manager-agent.d.ts} +1 -1
- package/dist/agents/dynamic-agent-policy-sections.d.ts +2 -0
- package/dist/agents/{guard → manager}/agent.d.ts +7 -7
- package/dist/agents/manager/default-prompt-sections.d.ts +5 -0
- package/dist/agents/manager/default.d.ts +2 -0
- package/dist/agents/manager/index.d.ts +2 -0
- package/dist/agents/{guard → manager}/prompt-section-builder.d.ts +1 -1
- package/dist/agents/{guard → manager}/shared-prompt.d.ts +2 -2
- package/dist/agents/prompt-library/index.d.ts +0 -1
- package/dist/agents/strategist/behavioral-summary.d.ts +1 -1
- package/dist/agents/strategist/high-accuracy-mode.d.ts +1 -1
- package/dist/agents/strategist/identity-constraints.d.ts +1 -1
- package/dist/agents/strategist/index.d.ts +1 -1
- package/dist/agents/strategist/interview-mode.d.ts +1 -1
- package/dist/agents/strategist/plan-generation.d.ts +1 -1
- package/dist/agents/strategist/plan-template.d.ts +1 -1
- package/dist/agents/strategist/system-prompt.d.ts +3 -3
- package/dist/agents/types.d.ts +2 -2
- package/dist/agents/writer.d.ts +7 -0
- package/dist/config/index.d.ts +4 -6
- package/dist/config/platform-schema.d.ts +64 -56
- package/dist/config/schema/agent-names.d.ts +9 -10
- package/dist/config/schema/agent-overrides.d.ts +2 -258
- package/dist/config/schema/browser-automation.d.ts +0 -4
- package/dist/config/schema/{oh-my-opencode-config.d.ts → hiai-opencode-config.d.ts} +2 -261
- package/dist/config/schema/hooks.d.ts +1 -1
- package/dist/config/schema/index.d.ts +2 -2
- package/dist/config/types.d.ts +7 -5
- package/dist/create-hooks.d.ts +3 -0
- package/dist/features/boulder-state/constants.d.ts +1 -1
- package/dist/features/boulder-state/types.d.ts +1 -1
- package/dist/features/builtin-commands/templates/refactor.d.ts +1 -1
- package/dist/features/builtin-skills/skills/{playwright.d.ts → agent-browser.d.ts} +0 -1
- package/dist/features/builtin-skills/skills/index.d.ts +1 -2
- package/dist/hooks/critic-plans-only/agent-matcher.d.ts +1 -0
- package/dist/hooks/critic-plans-only/constants.d.ts +6 -0
- package/dist/hooks/critic-plans-only/hook.d.ts +11 -0
- package/dist/hooks/critic-plans-only/index.d.ts +3 -0
- package/dist/hooks/critic-plans-only/path-policy.d.ts +1 -0
- package/dist/hooks/index.d.ts +2 -1
- package/dist/hooks/json-error-recovery/hook.d.ts +1 -1
- package/dist/hooks/manager/hook-name.d.ts +1 -0
- package/dist/hooks/{guard → manager}/system-reminder-templates.d.ts +2 -2
- package/dist/hooks/mempalace-auto-save/constants.d.ts +1 -0
- package/dist/hooks/mempalace-auto-save/handler.d.ts +13 -0
- package/dist/hooks/mempalace-auto-save/index.d.ts +15 -0
- package/dist/hooks/mempalace-auto-save/types.d.ts +16 -0
- package/dist/hooks/strategist-md-only/constants.d.ts +2 -2
- package/dist/index.js +1266 -1920
- package/dist/internals/plugins/pty/pty/tools/list.d.ts +2 -5
- package/dist/mcp/registry.d.ts +1 -1
- package/dist/mcp/types.d.ts +0 -4
- package/dist/plugin/hooks/create-continuation-hooks.d.ts +4 -0
- package/dist/plugin/tool-registry.d.ts +4 -2
- package/dist/plugin-handlers/agent-priority-order.d.ts +2 -2
- package/dist/shared/agent-display-names.d.ts +2 -2
- package/dist/shared/system-directive.d.ts +2 -2
- package/dist/tools/agent-browser/constants.d.ts +16 -0
- package/dist/tools/agent-browser/index.d.ts +4 -0
- package/dist/tools/agent-browser/integration.d.ts +2 -0
- package/dist/tools/agent-browser/tools.d.ts +2 -0
- package/dist/tools/agent-browser/types.d.ts +80 -0
- package/dist/tools/call-hiai-agent/background-agent-executor.d.ts +5 -0
- package/dist/tools/{call-omo-agent → call-hiai-agent}/background-executor.d.ts +2 -2
- package/dist/tools/call-hiai-agent/constants.d.ts +3 -0
- package/dist/tools/{call-omo-agent → call-hiai-agent}/index.d.ts +1 -1
- package/dist/tools/{call-omo-agent → call-hiai-agent}/session-creator.d.ts +2 -2
- package/dist/tools/{call-omo-agent → call-hiai-agent}/subagent-session-creator.d.ts +2 -2
- package/dist/tools/{call-omo-agent → call-hiai-agent}/sync-executor.d.ts +2 -2
- package/dist/tools/{call-omo-agent → call-hiai-agent}/tools.d.ts +1 -1
- package/dist/tools/{call-omo-agent → call-hiai-agent}/types.d.ts +2 -2
- package/dist/tools/delegate-task/constants.d.ts +1 -1
- package/dist/tools/delegate-task/sub-agent.d.ts +1 -1
- package/dist/tools/index.d.ts +2 -1
- package/dist/tools/task/todo-sync.d.ts +1 -1
- package/docs/HOOKS.md +126 -0
- package/docs/HOOK_TIMINGS.md +58 -0
- package/docs/PERMISSIONS.md +84 -0
- package/docs/quickstart.md +60 -0
- package/hiai-opencode.json +10 -22
- package/package.json +13 -11
- package/skills/firecrawl-cli/SKILL.md +314 -0
- package/skills/firecrawl-cli/rules/install.md +98 -0
- package/assets/mcp/playwright.mjs +0 -83
- package/assets/mcp/rag.mjs +0 -236
- package/dist/agents/brainstormer.d.ts +0 -7
- package/dist/agents/guard/default-prompt-sections.d.ts +0 -6
- package/dist/agents/guard/default.d.ts +0 -2
- package/dist/agents/guard/index.d.ts +0 -2
- package/dist/agents/platform-manager.d.ts +0 -7
- package/dist/agents/prompt-library/platform.d.ts +0 -1
- package/dist/features/builtin-skills/skills/playwright-cli.d.ts +0 -10
- package/dist/hooks/guard/hook-name.d.ts +0 -1
- package/dist/tools/call-omo-agent/background-agent-executor.d.ts +0 -5
- package/dist/tools/call-omo-agent/constants.d.ts +0 -3
- /package/dist/hooks/{guard → manager}/background-launch-session-tracking.d.ts +0 -0
- /package/dist/hooks/{guard → manager}/bob-path.d.ts +0 -0
- /package/dist/hooks/{guard → manager}/boulder-continuation-injector.d.ts +0 -0
- /package/dist/hooks/{guard → manager}/boulder-session-lineage.d.ts +0 -0
- /package/dist/hooks/{guard → manager}/event-handler.d.ts +0 -0
- /package/dist/hooks/{guard → manager}/final-wave-approval-gate.d.ts +0 -0
- /package/dist/hooks/{guard → manager}/final-wave-plan-state.d.ts +0 -0
- /package/dist/hooks/{guard → manager}/guard-hook.d.ts +0 -0
- /package/dist/hooks/{guard → manager}/idle-event.d.ts +0 -0
- /package/dist/hooks/{guard → manager}/index.d.ts +0 -0
- /package/dist/hooks/{guard → manager}/is-abort-error.d.ts +0 -0
- /package/dist/hooks/{guard → manager}/recent-model-resolver.d.ts +0 -0
- /package/dist/hooks/{guard → manager}/resolve-active-boulder-session.d.ts +0 -0
- /package/dist/hooks/{guard → manager}/session-last-agent.d.ts +0 -0
- /package/dist/hooks/{guard → manager}/subagent-session-id.d.ts +0 -0
- /package/dist/hooks/{guard → manager}/task-context.d.ts +0 -0
- /package/dist/hooks/{guard → manager}/tool-execute-after.d.ts +0 -0
- /package/dist/hooks/{guard → manager}/tool-execute-before.d.ts +0 -0
- /package/dist/hooks/{guard → manager}/types.d.ts +0 -0
- /package/dist/hooks/{guard → manager}/verification-reminders.d.ts +0 -0
- /package/dist/hooks/{guard → manager}/write-edit-tool-policy.d.ts +0 -0
- /package/dist/tools/{call-omo-agent → call-hiai-agent}/agent-resolver.d.ts +0 -0
- /package/dist/tools/{call-omo-agent → call-hiai-agent}/completion-poller.d.ts +0 -0
- /package/dist/tools/{call-omo-agent → call-hiai-agent}/message-dir.d.ts +0 -0
- /package/dist/tools/{call-omo-agent → call-hiai-agent}/message-processor.d.ts +0 -0
- /package/dist/tools/{call-omo-agent → call-hiai-agent}/message-storage-directory.d.ts +0 -0
- /package/dist/tools/{call-omo-agent → call-hiai-agent}/tool-context-with-metadata.d.ts +0 -0
package/README.md
CHANGED
|
@@ -1,14 +1,16 @@
|
|
|
1
1
|
# hiai-opencode
|
|
2
2
|
|
|
3
3
|
[](https://github.com/HiAi-gg/hiai-opencode/actions/workflows/ci.yml?query=branch%3Amain)
|
|
4
|
+
[](https://www.npmjs.com/package/@hiai-gg/hiai-opencode)
|
|
5
|
+
[](LICENSE.md)
|
|
4
6
|
|
|
5
7
|
`hiai-opencode` is an OpenCode plugin that turns vanilla OpenCode into an opinionated multi-agent cockpit.
|
|
6
8
|
|
|
7
9
|
**What you get on top of plain OpenCode:**
|
|
8
10
|
|
|
9
|
-
- **
|
|
10
|
-
- **Mode → agent routing** for `task()` delegation — `quick`/`bounded`/`unspecified-low` → Sub, `deep`/`cross-module` → Coder, `ultrabrain` → Strategist, `visual-engineering`/`artistry` → Designer, `writing` →
|
|
11
|
-
- **MCP wiring out of the box** — Stitch, Firecrawl, Context7, grep_app,
|
|
11
|
+
- **14-agent canonical model (9 visible + 5 hidden)** with peer-aware prompts — Bob orchestrates, Coder/Sub implement, Strategist plans, Critic gates, Researcher discovers via Context7/Firecrawl/grep_app/MemPalace, Designer drives Stitch UI generation, Writer owns copy/SEO, Vision extracts PDFs/images, Manager keeps memory, Quality Guardian reviews, Sandbox sandboxes bash.
|
|
12
|
+
- **Mode → agent routing** for `task()` delegation — `quick`/`bounded`/`unspecified-low` → Sub, `deep`/`cross-module` → Coder, `ultrabrain` → Strategist, `visual-engineering`/`artistry` → Designer, `writing` → Writer, `git-ops` → Manager. No more "everything routes to coder".
|
|
13
|
+
- **MCP wiring out of the box** — Stitch, Firecrawl, Context7, grep_app, MemPalace, Sequential-Thinking. Each agent's prompt knows which MCP servers it owns.
|
|
12
14
|
- **LSP defaults** for TypeScript, Svelte, ESLint, Bash, Pyright. Coder must run `lsp_diagnostics` after every edit.
|
|
13
15
|
- **Permission discipline** — read-only agents cannot delegate; write-capable agents have explicit file-scope limits.
|
|
14
16
|
|
|
@@ -39,21 +41,30 @@ Then run `hiai-opencode doctor`, `hiai-opencode mcp-status`, and `opencode debug
|
|
|
39
41
|
|
|
40
42
|
For the full operator playbook, see [AGENTS.md](AGENTS.md). 🤖
|
|
41
43
|
|
|
44
|
+
|
|
42
45
|
## Agents
|
|
43
46
|
|
|
47
|
+
**9 Visible Primary Agents:**
|
|
48
|
+
|
|
44
49
|
| Agent | Role | When to use |
|
|
45
50
|
|-------|------|-------------|
|
|
46
51
|
| `Bob` | Orchestrator, router, distributor | Entry point; complex tasks needing multi-agent coordination |
|
|
47
52
|
| `Coder` | Deep implementation, focused execution | Complex features, refactors, deep work |
|
|
48
|
-
| `Sub` | Bounded cheap executor | Small targeted changes, quick fixes |
|
|
49
53
|
| `Strategist` | Planning, architecture, pre-check | Scope definition, architectural decisions |
|
|
50
|
-
| `
|
|
54
|
+
| `Manager` | Delegation orchestrator, TODO tracker | Coordinates specialists, maintains session continuity |
|
|
51
55
|
| `Critic` | Review gate, high-accuracy verification | Plan review, code review, regression catch |
|
|
56
|
+
| `Designer` | UI/visual direction via Stitch MCP | Visual problems, design systems, screen generation |
|
|
52
57
|
| `Researcher` | Local + external search | Codebase exploration, documentation discovery |
|
|
53
|
-
| `
|
|
54
|
-
| `
|
|
55
|
-
|
|
56
|
-
|
|
58
|
+
| `Writer` | Content, copy, positioning, SEO | Website copy, product messaging, naming |
|
|
59
|
+
| `Vision` | PDF/image/diagram extraction, browser UI verification | Multimodal analysis, live browser verification |
|
|
60
|
+
|
|
61
|
+
**5 Hidden System Agents** (used internally, not for direct selection):
|
|
62
|
+
|
|
63
|
+
- `Agent Skills` — Skill registry, discovery, and capability orchestration
|
|
64
|
+
- `Sub` — Compatibility wrapper for bounded execution (folded into Coder's contour)
|
|
65
|
+
- `build` — Default executor (OpenCode system agent)
|
|
66
|
+
- `plan` — Plan mode agent (OpenCode system agent)
|
|
67
|
+
- `Quality Guardian` — Post-implementation review and bug investigation (compatibility alias for Critic)
|
|
57
68
|
|
|
58
69
|
## Modes (Task Routing)
|
|
59
70
|
|
|
@@ -61,16 +72,16 @@ Mode determines prompt append, variant, and reasoning effort. The executor agent
|
|
|
61
72
|
|
|
62
73
|
| Mode | Agent | Prompt variant | When to use |
|
|
63
74
|
|------|-------|----------------|-------------|
|
|
64
|
-
| `quick` | `
|
|
65
|
-
| `writing` | `
|
|
75
|
+
| `quick` | `coder` (via fast bounded contour) | Fast bounded | Small targeted changes |
|
|
76
|
+
| `writing` | `writer` | Docs/prose | Content, i18n, copy |
|
|
66
77
|
| `deep` | `coder` | Deep reasoning | Complex implementation |
|
|
67
78
|
| `ultrabrain` | `strategist` | Plan-only | Architecture, hard logic |
|
|
68
79
|
| `visual-engineering` | `designer` | UI/visual | Visual problems |
|
|
69
80
|
| `artistry` | `designer` | Creative | Brand, SEO, creative |
|
|
70
81
|
| `git` | `platform-manager` | Git ops | Version control operations |
|
|
71
|
-
| `bounded` | `
|
|
82
|
+
| `bounded` | `coder` (via fast bounded contour) | Mid-tier bounded | Moderate effort changes |
|
|
72
83
|
| `cross-module` | `coder` | Deep substantial | Multi-component changes |
|
|
73
|
-
| `unspecified-low` | `
|
|
84
|
+
| `unspecified-low` | `coder` (via fast bounded contour) | Bounded | Unclassified small tasks |
|
|
74
85
|
| `unspecified-high` | `coder` | Deep | Unclassified substantial tasks |
|
|
75
86
|
|
|
76
87
|
## Integrations
|
|
@@ -80,22 +91,18 @@ MCP integrations and which agents use them:
|
|
|
80
91
|
| Service | Key env var | Agent(s) | What it's for |
|
|
81
92
|
|---------|------------|----------|---------------|
|
|
82
93
|
| Stitch | `STITCH_AI_API_KEY` | Designer | UI generation, design systems, screen variants |
|
|
83
|
-
| Firecrawl | `FIRECRAWL_API_KEY` | Researcher |
|
|
94
|
+
| Firecrawl | `FIRECRAWL_API_KEY` | Researcher | CLI skill (not MCP) for web scraping, crawl, extract, search |
|
|
84
95
|
| Context7 | `CONTEXT7_API_KEY` | Researcher, Coder | Library API documentation |
|
|
85
96
|
| grep_app | — | Researcher | GitHub OSS code pattern search |
|
|
86
|
-
|
|
|
87
|
-
| websearch (Tavily) | `TAVILY_API_KEY` | Researcher | General web search (alt provider) |
|
|
88
|
-
| RAG | `OPENCODE_RAG_URL` | Researcher, Brainstormer, Manager | Project knowledge base |
|
|
89
|
-
| MemPalace | — | Manager (primary), all agents | Project memory and past decisions |
|
|
97
|
+
| MemPalace | MEMPALACE_PYTHON (optional) | Manager (primary), all agents | Project memory and past decisions |
|
|
90
98
|
| Sequential-Thinking | — | Strategist, Critic | Deep reasoning for planning/review |
|
|
91
|
-
| Playwright | — | Coder | Browser tests and automation |
|
|
92
99
|
|
|
93
100
|
## What You Get
|
|
94
101
|
|
|
95
|
-
- **
|
|
102
|
+
- **9 visible primary agents** + **5 hidden system agents** (Agent Skills, Sub, build, plan, Quality Guardian)
|
|
96
103
|
- **Mode-based task routing** via `task(category=..., ...)` or `task(mode=..., ...)`
|
|
97
104
|
- Skill materialization into OpenCode's `skills/` view
|
|
98
|
-
- MCP wiring for `
|
|
105
|
+
- MCP wiring for `stitch`, `sequential-thinking`, `firecrawl-cli`, `mempalace`, `context7`, and `grep_app`
|
|
99
106
|
- LSP wiring for TypeScript, Svelte, Python, Bash, and ESLint
|
|
100
107
|
|
|
101
108
|
## Continuation, Ralph-Loop, And Auto-Start
|
|
@@ -138,10 +145,7 @@ Optional, depending on which services you want:
|
|
|
138
145
|
- `FIRECRAWL_API_KEY` for Firecrawl
|
|
139
146
|
- `STITCH_AI_API_KEY` for Stitch
|
|
140
147
|
- `CONTEXT7_API_KEY` for Context7
|
|
141
|
-
- `EXA_API_KEY` for higher Exa websearch limits
|
|
142
|
-
- `TAVILY_API_KEY` when `mcp.websearch.provider` is `tavily`
|
|
143
148
|
- Python 3.9+ or `uv` for MemPalace
|
|
144
|
-
- a running RAG endpoint if you enable `rag`
|
|
145
149
|
- local language servers if you want LSP beyond the npm-bootstrapped helpers
|
|
146
150
|
|
|
147
151
|
## Install
|
|
@@ -158,14 +162,15 @@ Optional Dynamic Context Pruning plugin:
|
|
|
158
162
|
opencode plugin @tarquinen/opencode-dcp@latest --global
|
|
159
163
|
```
|
|
160
164
|
|
|
161
|
-
Do not put MCP server packages such as
|
|
165
|
+
Do not put MCP server packages such as `@modelcontextprotocol/server-sequential-thinking` into the OpenCode `plugin` array. They are MCP servers, not OpenCode plugins. Install the CLI skill separately using `opencode plugin` or `npm install -g @mendableai/firecrawl`.
|
|
162
166
|
|
|
163
167
|
Manual OpenCode config equivalent:
|
|
164
168
|
|
|
165
169
|
```json
|
|
166
170
|
{
|
|
167
171
|
"$schema": "https://opencode.ai/config.json",
|
|
168
|
-
"plugin": ["@hiai-gg/hiai-opencode"
|
|
172
|
+
"plugin": ["@hiai-gg/hiai-opencode",
|
|
173
|
+
"@tarquinen/opencode-dcp@latest"]
|
|
169
174
|
}
|
|
170
175
|
```
|
|
171
176
|
|
|
@@ -194,23 +199,19 @@ If you installed only from npm/OpenCode and do not have this repository checked
|
|
|
194
199
|
```json
|
|
195
200
|
{
|
|
196
201
|
"models": {
|
|
197
|
-
"bob": { "model": "
|
|
198
|
-
"coder": { "model": "
|
|
199
|
-
"strategist": { "model": "
|
|
200
|
-
"
|
|
201
|
-
"critic": { "model": "
|
|
202
|
+
"bob": { "model": "kimi-for-coding/k2p6", "recommended": "xhigh" },
|
|
203
|
+
"coder": { "model": "minimax-coding-plan/MiniMax-M2.7", "recommended": "high" },
|
|
204
|
+
"strategist": { "model": "deepseek/deepseek-v4-pro", "recommended": "high" },
|
|
205
|
+
"manager": { "model": "opencode-go/qwen3.6-plus", "recommended": "middle" },
|
|
206
|
+
"critic": { "model": "opencode-go/mimo-v2.5-pro", "recommended": "high" },
|
|
202
207
|
"designer": { "model": "openrouter/google/gemini-3.1-pro-preview", "recommended": "design" },
|
|
203
208
|
"researcher": { "model": "openrouter/deepseek/deepseek-v4-flash", "recommended": "fast" },
|
|
204
|
-
"
|
|
205
|
-
"brainstormer": { "model": "openrouter/mistralai/mistral-small-2603", "recommended": "writing" },
|
|
209
|
+
"writer": { "model": "openrouter/mistralai/mistral-small-2603", "recommended": "writing" },
|
|
206
210
|
"vision": { "model": "openrouter/google/gemma-4-26b-a4b-it", "recommended": "vision" }
|
|
207
211
|
},
|
|
208
212
|
"mcp": {
|
|
209
|
-
"playwright": { "enabled": true },
|
|
210
213
|
"sequential-thinking": { "enabled": true },
|
|
211
|
-
"firecrawl": { "enabled": true },
|
|
212
214
|
"mempalace": { "enabled": true, "pythonPath": "{env:MEMPALACE_PYTHON:-./.venv/bin/python}" },
|
|
213
|
-
"rag": { "enabled": false },
|
|
214
215
|
"stitch": { "enabled": false },
|
|
215
216
|
"context7": { "enabled": true }
|
|
216
217
|
}
|
|
@@ -236,9 +237,6 @@ Use the exact model IDs printed by OpenCode in `hiai-opencode.json`. For example
|
|
|
236
237
|
export FIRECRAWL_API_KEY=...
|
|
237
238
|
export STITCH_AI_API_KEY=...
|
|
238
239
|
export CONTEXT7_API_KEY=...
|
|
239
|
-
export EXA_API_KEY=...
|
|
240
|
-
# or, if mcp.websearch.provider is "tavily":
|
|
241
|
-
export TAVILY_API_KEY=...
|
|
242
240
|
```
|
|
243
241
|
|
|
244
242
|
See [Environment Variables And Keys](#environment-variables-and-keys) for the full list.
|
|
@@ -265,7 +263,7 @@ opencode mcp list --print-logs --log-level INFO
|
|
|
265
263
|
Direct npm install is only needed for development or inspection:
|
|
266
264
|
|
|
267
265
|
```bash
|
|
268
|
-
|
|
266
|
+
bun install
|
|
269
267
|
```
|
|
270
268
|
|
|
271
269
|
Local development:
|
|
@@ -293,11 +291,9 @@ Find or create hiai-opencode.json in the project root or .opencode/. Use its mcp
|
|
|
293
291
|
Keep skill discovery deterministic unless I explicitly ask for external skills. Leave global_opencode, project_claude, global_claude, project_agents, and global_agents disabled by default.
|
|
294
292
|
|
|
295
293
|
Enable only services that can run on this machine:
|
|
296
|
-
- playwright: requires node/npx; optionally set HIAI_PLAYWRIGHT_INSTALL_BROWSERS=1 before first run if browser binaries are needed.
|
|
297
294
|
- sequential-thinking: requires node/npx.
|
|
298
|
-
- firecrawl: requires FIRECRAWL_API_KEY.
|
|
295
|
+
- firecrawl-cli: uses CLI skill at `skills/firecrawl-cli/` and requires `FIRECRAWL_API_KEY` for web scraping and extraction tasks.
|
|
299
296
|
- mempalace: requires uv or Python 3.9+ with pip; set `mcp.mempalace.pythonPath` (or `MEMPALACE_PYTHON`) if needed. Leave `HIAI_MCP_AUTO_INSTALL` enabled unless the user forbids package installation.
|
|
300
|
-
- rag: requires OPENCODE_RAG_URL or a running local endpoint at http://localhost:9002/tools/search.
|
|
301
297
|
- stitch: requires STITCH_AI_API_KEY.
|
|
302
298
|
- context7: works without a key but use CONTEXT7_API_KEY if available.
|
|
303
299
|
|
|
@@ -341,12 +337,12 @@ Important prompt entrypoints:
|
|
|
341
337
|
- `Bob`: [src/agents/bob.ts](src/agents/bob.ts) and `src/agents/bob/*`
|
|
342
338
|
- `Coder`: `src/agents/coder/*`
|
|
343
339
|
- `Strategist`: `src/agents/strategist/*`
|
|
344
|
-
- `
|
|
340
|
+
- `Manager`: `src/agents/manager/*`
|
|
345
341
|
- `Critic`: `src/agents/critic/*`
|
|
346
342
|
- `Vision`: [src/agents/ui.ts](src/agents/ui.ts)
|
|
347
343
|
- `Manager`: [src/agents/platform-manager.ts](src/agents/platform-manager.ts)
|
|
348
344
|
- `Researcher`: [src/agents/researcher.ts](src/agents/researcher.ts)
|
|
349
|
-
- `
|
|
345
|
+
- `Writer` / `Writer`: [src/agents/writer.ts](src/agents/writer.ts)
|
|
350
346
|
|
|
351
347
|
Name mapping and visibility:
|
|
352
348
|
|
|
@@ -368,16 +364,15 @@ Built-in helper skills include browser automation, frontend UI/UX, review, git w
|
|
|
368
364
|
Website/product copy should use:
|
|
369
365
|
|
|
370
366
|
```text
|
|
371
|
-
task(subagent_type="
|
|
367
|
+
task(subagent_type="writer", load_skills=["website-copywriting"], ...)
|
|
372
368
|
```
|
|
373
369
|
|
|
374
|
-
`writer`, `copywriter`, and `content-writer` are aliases for `
|
|
370
|
+
`writer`, `copywriter`, and `content-writer` are aliases for `writer`.
|
|
375
371
|
|
|
376
372
|
Manager memory stewardship:
|
|
377
373
|
|
|
378
374
|
- Use `task(subagent_type="platform-manager", ...)` or `task(subagent_type="manager", ...)` for MemPalace cleanup, session ledgers, TODO hygiene, and architecture decision handoff.
|
|
379
375
|
- Manager writes only durable decisions and important project state. It should not dump raw chat logs into memory.
|
|
380
|
-
- RAG is retrieval-first by default; Manager syncs architecture summaries to RAG only when the configured endpoint exposes write/upsert capability.
|
|
381
376
|
|
|
382
377
|
Skill discovery defaults:
|
|
383
378
|
|
|
@@ -427,14 +422,11 @@ Important service variables:
|
|
|
427
422
|
- `STITCH_AI_API_KEY`
|
|
428
423
|
- `FIRECRAWL_API_KEY`
|
|
429
424
|
- `CONTEXT7_API_KEY`
|
|
430
|
-
- `EXA_API_KEY`
|
|
431
|
-
- `TAVILY_API_KEY`
|
|
432
425
|
- `OLLAMA_BASE_URL`
|
|
433
426
|
- `OLLAMA_MODEL`
|
|
434
427
|
- `MEMPALACE_PYTHON`
|
|
435
428
|
- `MEMPALACE_PALACE_PATH`
|
|
436
|
-
|
|
437
|
-
- `HIAI_PLAYWRIGHT_INSTALL_BROWSERS`
|
|
429
|
+
|
|
438
430
|
- `HIAI_MCP_AUTO_INSTALL`
|
|
439
431
|
- `HIAI_OPENCODE_AUTO_EXPORT_MCP`
|
|
440
432
|
- `HIAI_OPENCODE_MCP_EXPORT_PATH`
|
|
@@ -450,9 +442,7 @@ The user-facing MCP switchboard is the `mcp` object in `hiai-opencode.json`:
|
|
|
450
442
|
```json
|
|
451
443
|
{
|
|
452
444
|
"mcp": {
|
|
453
|
-
"playwright": { "enabled": true },
|
|
454
445
|
"mempalace": { "enabled": false },
|
|
455
|
-
"websearch": { "enabled": true, "provider": "exa" },
|
|
456
446
|
"grep_app": { "enabled": true }
|
|
457
447
|
}
|
|
458
448
|
}
|
|
@@ -464,48 +454,42 @@ The source of truth for default MCP wiring is `src/mcp/registry.ts`. Change that
|
|
|
464
454
|
|
|
465
455
|
- `stitch`
|
|
466
456
|
- `context7`
|
|
467
|
-
- `websearch`: defaults to Exa remote MCP. `EXA_API_KEY` is optional for Exa; set `"provider": "tavily"` and `TAVILY_API_KEY` to use Tavily.
|
|
468
457
|
- `grep_app`
|
|
469
458
|
|
|
470
459
|
### Works with local helper bootstrap
|
|
471
460
|
|
|
472
|
-
- `playwright`: launches `@playwright/mcp@latest` through the helper npm runner. Set `HIAI_PLAYWRIGHT_INSTALL_BROWSERS=1` if you want the launcher to install Chromium on first start.
|
|
473
461
|
- `sequential-thinking`: launches `@modelcontextprotocol/server-sequential-thinking` through the helper npm runner.
|
|
474
|
-
- `firecrawl`:
|
|
475
|
-
|
|
476
|
-
### Playwright On Minimal Linux Hosts
|
|
462
|
+
- `firecrawl`: uses the CLI skill at `skills/firecrawl-cli/` and requires `FIRECRAWL_API_KEY` for web scraping and extraction tasks.
|
|
477
463
|
|
|
478
|
-
|
|
464
|
+
### Browser Automation
|
|
479
465
|
|
|
480
|
-
|
|
466
|
+
For browser automation, use the `/agent-browser` skill instead of an MCP server. The CLI uses native Chrome via CDP — no Playwright.
|
|
481
467
|
|
|
482
|
-
|
|
483
|
-
|
|
468
|
+
**Install** (Bun):
|
|
469
|
+
```bash
|
|
470
|
+
bun add -g agent-browser && agent-browser install
|
|
471
|
+
```
|
|
484
472
|
|
|
485
|
-
|
|
473
|
+
Or via npm:
|
|
474
|
+
```bash
|
|
475
|
+
npm i -g agent-browser && agent-browser install
|
|
476
|
+
```
|
|
486
477
|
|
|
487
|
-
|
|
478
|
+
Repo: https://github.com/vercel-labs/agent-browser
|
|
488
479
|
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
}
|
|
497
|
-
}
|
|
498
|
-
}
|
|
499
|
-
```
|
|
480
|
+
Key environment variables (`AGENT_BROWSER_*`):
|
|
481
|
+
- `AGENT_BROWSER_HEADED=1` — show browser window
|
|
482
|
+
- `AGENT_BROWSER_SESSION=name` — isolated session
|
|
483
|
+
- `AGENT_BROWSER_PROFILE=path` — persistent profile
|
|
484
|
+
- `AGENT_BROWSER_PROVIDER=name` — cloud provider (browserbase, browseruse, kernel)
|
|
485
|
+
- `AGENT_BROWSER_AUTO_CONNECT=1` — auto-discover running Chrome
|
|
486
|
+
- `AGENT_BROWSER_EXECUTABLE_PATH` — custom browser binary
|
|
500
487
|
|
|
501
|
-
-
|
|
502
|
-
- Use a remote/CDP browser or the `agent-browser`/`playwright-cli` skill path if those tools are installed.
|
|
503
|
-
- Use `curl` only as a degraded HTTP check. It does not replace browser interaction, screenshots, auth flows, or client-side app verification.
|
|
488
|
+
Use `/agent-browser` skill in OpenCode for browser tasks — navigation, snapshots, screenshots, form filling, console/network inspection.
|
|
504
489
|
|
|
505
490
|
### Needs upstream runtime or extra setup
|
|
506
491
|
|
|
507
492
|
- `mempalace`: prefers `uv`; otherwise uses Python. You can force interpreter selection via `mcp.mempalace.pythonPath` or `MEMPALACE_PYTHON`. If `HIAI_MCP_AUTO_INSTALL` is not `0`, `false`, or `no`, the launcher can run `python -m pip install --user mempalace` on first start.
|
|
508
|
-
- `rag`: requires your own running endpoint
|
|
509
493
|
|
|
510
494
|
### Important Windows note
|
|
511
495
|
|
|
@@ -518,47 +502,6 @@ This most often affects `sequential-thinking` and `mempalace`, and sometimes loc
|
|
|
518
502
|
|
|
519
503
|
## Troubleshooting MCP Servers
|
|
520
504
|
|
|
521
|
-
### Firecrawl tools return "FIRECRAWL_API_KEY missing"
|
|
522
|
-
|
|
523
|
-
The `skill_mcp` env scrubber filters `process.env` before launching stdio MCP servers — secret-shaped names (`*_API_KEY`, `*_TOKEN`, etc.) and npm/pnpm config vars are stripped so they cannot leak into a malicious server. Keys you set via `hiai-opencode.json` are an explicit allowlist and pass through.
|
|
524
|
-
|
|
525
|
-
If your key only lives in `process.env`, move it into the MCP `environment` block:
|
|
526
|
-
|
|
527
|
-
```json
|
|
528
|
-
{
|
|
529
|
-
"mcp": {
|
|
530
|
-
"firecrawl": {
|
|
531
|
-
"enabled": true,
|
|
532
|
-
"environment": { "FIRECRAWL_API_KEY": "fc-..." }
|
|
533
|
-
}
|
|
534
|
-
}
|
|
535
|
-
}
|
|
536
|
-
```
|
|
537
|
-
|
|
538
|
-
(Versions ≤ 0.1.8 had a bug where customEnv was merged before filtering, so even an explicit `FIRECRAWL_API_KEY` got stripped. Fixed in 0.1.9 — explicit `environment` always wins over the filter.)
|
|
539
|
-
|
|
540
|
-
### Playwright MCP fails to find Chromium
|
|
541
|
-
|
|
542
|
-
When `@playwright/mcp` cannot locate a system browser, point it at one explicitly:
|
|
543
|
-
|
|
544
|
-
```json
|
|
545
|
-
{
|
|
546
|
-
"mcp": {
|
|
547
|
-
"playwright": {
|
|
548
|
-
"enabled": true,
|
|
549
|
-
"environment": {
|
|
550
|
-
"PLAYWRIGHT_MCP_EXECUTABLE_PATH": "/usr/bin/chromium"
|
|
551
|
-
}
|
|
552
|
-
}
|
|
553
|
-
}
|
|
554
|
-
}
|
|
555
|
-
```
|
|
556
|
-
|
|
557
|
-
The path can be Chromium, Chrome, or Edge. Run `npx playwright install chromium` first if no browser is installed.
|
|
558
|
-
|
|
559
|
-
### `skill_mcp(playwright)` connects to localhost:3001 and fails
|
|
560
|
-
|
|
561
|
-
If `mcp__playwright__browser_*` works but `skill_mcp(mcp_name="playwright", ...)` errors with a connection to `localhost:3001/mcp`, you have a leftover HTTP-mode MCP registration in your global or parent `opencode.json`. Either start the HTTP server, or remove that registration so the plugin's stdio registration (`npx @playwright/mcp@latest`) is the only one. As a workaround, agents (Vision, Critic) can call `mcp__playwright__browser_*` direct tools instead of going through `skill_mcp`.
|
|
562
505
|
|
|
563
506
|
## Diagnostics
|
|
564
507
|
|
|
@@ -593,17 +536,6 @@ Inside OpenCode, use the slash command:
|
|
|
593
536
|
/mcp-status
|
|
594
537
|
```
|
|
595
538
|
|
|
596
|
-
Example output:
|
|
597
|
-
|
|
598
|
-
```text
|
|
599
|
-
MCP Servers:
|
|
600
|
-
✅ playwright - backend ok
|
|
601
|
-
⚠️ rag - enabled, http://localhost:9002/tools/search not reachable
|
|
602
|
-
✅ firecrawl - backend ok
|
|
603
|
-
❌ mempalace - python not found
|
|
604
|
-
⚠️ stitch - enabled, API key missing (STITCH_AI_API_KEY)
|
|
605
|
-
```
|
|
606
|
-
|
|
607
539
|
`hiai-opencode export-mcp` writes a standard `.mcp.json` so hosts whose `mcp list` ignores plugin runtime MCP can still show the same servers statically. Exports are marker-tagged as hiai-managed; by default, the command avoids overwriting non-managed files unless `HIAI_OPENCODE_EXPORT_MCP_MODE=force` is set.
|
|
608
540
|
|
|
609
541
|
Use:
|
|
@@ -626,12 +558,13 @@ opencode mcp list --print-logs --log-level INFO
|
|
|
626
558
|
| Planning / workflow influences | [obra/superpowers](https://github.com/obra/superpowers) | planning, review, and debugging ideas |
|
|
627
559
|
| Specialist / platform influences | [vtemian/micode](https://github.com/vtemian/micode) | platform-style specialist behavior |
|
|
628
560
|
| Agent skill ecosystem | [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | tactical workflow skill ideas |
|
|
561
|
+
| Supabase Postgres skill | [supabase/agent-skills](https://github.com/supabase/agent-skills/blob/main/skills/supabase-postgres-best-practices/SKILL.md) | Postgres best practices skill |
|
|
562
|
+
| Browser automation | [vercel-labs/agent-browser](https://github.com/vercel-labs/agent-browser) | CLI-based browser automation via CDP |
|
|
629
563
|
| Optional external plugin | [Opencode-DCP/opencode-dynamic-context-pruning](https://github.com/Opencode-DCP/opencode-dynamic-context-pruning) | installed separately |
|
|
630
564
|
| MemPalace | [MemPalace/mempalace](https://github.com/MemPalace/mempalace) | external MCP/runtime |
|
|
631
|
-
| Playwright MCP | [microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp) | external MCP |
|
|
632
565
|
| Sequential Thinking | [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) | external MCP |
|
|
633
|
-
| Firecrawl
|
|
634
|
-
| Context7 MCP | [upstash/context7
|
|
566
|
+
| Firecrawl CLI skill | [firecrawl/firecrawl](https://github.com/firecrawl/firecrawl) | CLI-based web scraping, crawl, extract, search |
|
|
567
|
+
| Context7 MCP | [upstash/context7](https://github.com/upstash/context7) | external MCP |
|
|
635
568
|
| bun-pty / PTY ecosystem | [shekohex/opencode-pty](https://github.com/shekohex/opencode-pty) | PTY/runtime integration influence |
|
|
636
569
|
|
|
637
570
|
## Build And Publish
|