@hiai-gg/hiai-opencode 0.1.8 → 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 +95 -95
- 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} +4 -261
- package/dist/config/schema/hooks.d.ts +1 -1
- package/dist/config/schema/index.d.ts +2 -2
- package/dist/config/schema/ralph-loop.d.ts +2 -0
- 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/hooks/todo-continuation-enforcer/auto-loop.d.ts +23 -0
- package/dist/hooks/todo-continuation-enforcer/handler.d.ts +5 -0
- package/dist/hooks/todo-continuation-enforcer/idle-event.d.ts +5 -0
- package/dist/hooks/todo-continuation-enforcer/types.d.ts +18 -0
- package/dist/index.js +1359 -1952
- 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 +6 -1
- 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 +14 -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
|
-
[](https://github.com/HiAi-gg/hiai-opencode/actions/workflows/ci.yml)
|
|
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,24 +91,43 @@ 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
|
|
|
108
|
+
## Continuation, Ralph-Loop, And Auto-Start
|
|
109
|
+
|
|
110
|
+
The plugin runs three layered mechanisms so a session does not give up halfway through a TODO list.
|
|
111
|
+
|
|
112
|
+
| Mechanism | Trigger | What it does |
|
|
113
|
+
|-----------|---------|--------------|
|
|
114
|
+
| **Todo continuation enforcer** | `session.idle` while open todos remain | Injects a continuation prompt after a 2s countdown. Backs off on stagnation, abort, token-limit, and pending-question. |
|
|
115
|
+
| **Ralph-loop** | `/ralph-loop <goal>` or `/ulw-loop <goal>` | Runs an explicit completion loop. Stops on `<promise>DONE</promise>`. Cancel with `/cancel-ralph`. |
|
|
116
|
+
| **Auto ralph-loop** | N+ open todos in one session | Auto-starts ralph-loop in ULTRAWORK mode so each iteration is forced to delegate to specialist agents (researcher / strategist / coder / critic). |
|
|
117
|
+
|
|
118
|
+
Tune the auto-start threshold in `hiai-opencode.json`:
|
|
119
|
+
|
|
120
|
+
```json
|
|
121
|
+
{
|
|
122
|
+
"ralph_loop": {
|
|
123
|
+
"enabled": true,
|
|
124
|
+
"auto_start_threshold": 5
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
`auto_start_threshold: 0` disables auto-start. The enforcer always yields to ralph-loop while it owns the session, so the two never inject duplicate prompts.
|
|
130
|
+
|
|
101
131
|
## Requirements
|
|
102
132
|
|
|
103
133
|
Minimum:
|
|
@@ -115,10 +145,7 @@ Optional, depending on which services you want:
|
|
|
115
145
|
- `FIRECRAWL_API_KEY` for Firecrawl
|
|
116
146
|
- `STITCH_AI_API_KEY` for Stitch
|
|
117
147
|
- `CONTEXT7_API_KEY` for Context7
|
|
118
|
-
- `EXA_API_KEY` for higher Exa websearch limits
|
|
119
|
-
- `TAVILY_API_KEY` when `mcp.websearch.provider` is `tavily`
|
|
120
148
|
- Python 3.9+ or `uv` for MemPalace
|
|
121
|
-
- a running RAG endpoint if you enable `rag`
|
|
122
149
|
- local language servers if you want LSP beyond the npm-bootstrapped helpers
|
|
123
150
|
|
|
124
151
|
## Install
|
|
@@ -135,14 +162,15 @@ Optional Dynamic Context Pruning plugin:
|
|
|
135
162
|
opencode plugin @tarquinen/opencode-dcp@latest --global
|
|
136
163
|
```
|
|
137
164
|
|
|
138
|
-
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`.
|
|
139
166
|
|
|
140
167
|
Manual OpenCode config equivalent:
|
|
141
168
|
|
|
142
169
|
```json
|
|
143
170
|
{
|
|
144
171
|
"$schema": "https://opencode.ai/config.json",
|
|
145
|
-
"plugin": ["@hiai-gg/hiai-opencode"
|
|
172
|
+
"plugin": ["@hiai-gg/hiai-opencode",
|
|
173
|
+
"@tarquinen/opencode-dcp@latest"]
|
|
146
174
|
}
|
|
147
175
|
```
|
|
148
176
|
|
|
@@ -171,23 +199,19 @@ If you installed only from npm/OpenCode and do not have this repository checked
|
|
|
171
199
|
```json
|
|
172
200
|
{
|
|
173
201
|
"models": {
|
|
174
|
-
"bob": { "model": "
|
|
175
|
-
"coder": { "model": "
|
|
176
|
-
"strategist": { "model": "
|
|
177
|
-
"
|
|
178
|
-
"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" },
|
|
179
207
|
"designer": { "model": "openrouter/google/gemini-3.1-pro-preview", "recommended": "design" },
|
|
180
208
|
"researcher": { "model": "openrouter/deepseek/deepseek-v4-flash", "recommended": "fast" },
|
|
181
|
-
"
|
|
182
|
-
"brainstormer": { "model": "openrouter/mistralai/mistral-small-2603", "recommended": "writing" },
|
|
209
|
+
"writer": { "model": "openrouter/mistralai/mistral-small-2603", "recommended": "writing" },
|
|
183
210
|
"vision": { "model": "openrouter/google/gemma-4-26b-a4b-it", "recommended": "vision" }
|
|
184
211
|
},
|
|
185
212
|
"mcp": {
|
|
186
|
-
"playwright": { "enabled": true },
|
|
187
213
|
"sequential-thinking": { "enabled": true },
|
|
188
|
-
"firecrawl": { "enabled": true },
|
|
189
214
|
"mempalace": { "enabled": true, "pythonPath": "{env:MEMPALACE_PYTHON:-./.venv/bin/python}" },
|
|
190
|
-
"rag": { "enabled": false },
|
|
191
215
|
"stitch": { "enabled": false },
|
|
192
216
|
"context7": { "enabled": true }
|
|
193
217
|
}
|
|
@@ -213,9 +237,6 @@ Use the exact model IDs printed by OpenCode in `hiai-opencode.json`. For example
|
|
|
213
237
|
export FIRECRAWL_API_KEY=...
|
|
214
238
|
export STITCH_AI_API_KEY=...
|
|
215
239
|
export CONTEXT7_API_KEY=...
|
|
216
|
-
export EXA_API_KEY=...
|
|
217
|
-
# or, if mcp.websearch.provider is "tavily":
|
|
218
|
-
export TAVILY_API_KEY=...
|
|
219
240
|
```
|
|
220
241
|
|
|
221
242
|
See [Environment Variables And Keys](#environment-variables-and-keys) for the full list.
|
|
@@ -242,7 +263,7 @@ opencode mcp list --print-logs --log-level INFO
|
|
|
242
263
|
Direct npm install is only needed for development or inspection:
|
|
243
264
|
|
|
244
265
|
```bash
|
|
245
|
-
|
|
266
|
+
bun install
|
|
246
267
|
```
|
|
247
268
|
|
|
248
269
|
Local development:
|
|
@@ -270,11 +291,9 @@ Find or create hiai-opencode.json in the project root or .opencode/. Use its mcp
|
|
|
270
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.
|
|
271
292
|
|
|
272
293
|
Enable only services that can run on this machine:
|
|
273
|
-
- playwright: requires node/npx; optionally set HIAI_PLAYWRIGHT_INSTALL_BROWSERS=1 before first run if browser binaries are needed.
|
|
274
294
|
- sequential-thinking: requires node/npx.
|
|
275
|
-
- 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.
|
|
276
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.
|
|
277
|
-
- rag: requires OPENCODE_RAG_URL or a running local endpoint at http://localhost:9002/tools/search.
|
|
278
297
|
- stitch: requires STITCH_AI_API_KEY.
|
|
279
298
|
- context7: works without a key but use CONTEXT7_API_KEY if available.
|
|
280
299
|
|
|
@@ -318,12 +337,12 @@ Important prompt entrypoints:
|
|
|
318
337
|
- `Bob`: [src/agents/bob.ts](src/agents/bob.ts) and `src/agents/bob/*`
|
|
319
338
|
- `Coder`: `src/agents/coder/*`
|
|
320
339
|
- `Strategist`: `src/agents/strategist/*`
|
|
321
|
-
- `
|
|
340
|
+
- `Manager`: `src/agents/manager/*`
|
|
322
341
|
- `Critic`: `src/agents/critic/*`
|
|
323
342
|
- `Vision`: [src/agents/ui.ts](src/agents/ui.ts)
|
|
324
343
|
- `Manager`: [src/agents/platform-manager.ts](src/agents/platform-manager.ts)
|
|
325
344
|
- `Researcher`: [src/agents/researcher.ts](src/agents/researcher.ts)
|
|
326
|
-
- `
|
|
345
|
+
- `Writer` / `Writer`: [src/agents/writer.ts](src/agents/writer.ts)
|
|
327
346
|
|
|
328
347
|
Name mapping and visibility:
|
|
329
348
|
|
|
@@ -345,16 +364,15 @@ Built-in helper skills include browser automation, frontend UI/UX, review, git w
|
|
|
345
364
|
Website/product copy should use:
|
|
346
365
|
|
|
347
366
|
```text
|
|
348
|
-
task(subagent_type="
|
|
367
|
+
task(subagent_type="writer", load_skills=["website-copywriting"], ...)
|
|
349
368
|
```
|
|
350
369
|
|
|
351
|
-
`writer`, `copywriter`, and `content-writer` are aliases for `
|
|
370
|
+
`writer`, `copywriter`, and `content-writer` are aliases for `writer`.
|
|
352
371
|
|
|
353
372
|
Manager memory stewardship:
|
|
354
373
|
|
|
355
374
|
- Use `task(subagent_type="platform-manager", ...)` or `task(subagent_type="manager", ...)` for MemPalace cleanup, session ledgers, TODO hygiene, and architecture decision handoff.
|
|
356
375
|
- Manager writes only durable decisions and important project state. It should not dump raw chat logs into memory.
|
|
357
|
-
- RAG is retrieval-first by default; Manager syncs architecture summaries to RAG only when the configured endpoint exposes write/upsert capability.
|
|
358
376
|
|
|
359
377
|
Skill discovery defaults:
|
|
360
378
|
|
|
@@ -404,14 +422,11 @@ Important service variables:
|
|
|
404
422
|
- `STITCH_AI_API_KEY`
|
|
405
423
|
- `FIRECRAWL_API_KEY`
|
|
406
424
|
- `CONTEXT7_API_KEY`
|
|
407
|
-
- `EXA_API_KEY`
|
|
408
|
-
- `TAVILY_API_KEY`
|
|
409
425
|
- `OLLAMA_BASE_URL`
|
|
410
426
|
- `OLLAMA_MODEL`
|
|
411
427
|
- `MEMPALACE_PYTHON`
|
|
412
428
|
- `MEMPALACE_PALACE_PATH`
|
|
413
|
-
|
|
414
|
-
- `HIAI_PLAYWRIGHT_INSTALL_BROWSERS`
|
|
429
|
+
|
|
415
430
|
- `HIAI_MCP_AUTO_INSTALL`
|
|
416
431
|
- `HIAI_OPENCODE_AUTO_EXPORT_MCP`
|
|
417
432
|
- `HIAI_OPENCODE_MCP_EXPORT_PATH`
|
|
@@ -427,9 +442,7 @@ The user-facing MCP switchboard is the `mcp` object in `hiai-opencode.json`:
|
|
|
427
442
|
```json
|
|
428
443
|
{
|
|
429
444
|
"mcp": {
|
|
430
|
-
"playwright": { "enabled": true },
|
|
431
445
|
"mempalace": { "enabled": false },
|
|
432
|
-
"websearch": { "enabled": true, "provider": "exa" },
|
|
433
446
|
"grep_app": { "enabled": true }
|
|
434
447
|
}
|
|
435
448
|
}
|
|
@@ -441,48 +454,42 @@ The source of truth for default MCP wiring is `src/mcp/registry.ts`. Change that
|
|
|
441
454
|
|
|
442
455
|
- `stitch`
|
|
443
456
|
- `context7`
|
|
444
|
-
- `websearch`: defaults to Exa remote MCP. `EXA_API_KEY` is optional for Exa; set `"provider": "tavily"` and `TAVILY_API_KEY` to use Tavily.
|
|
445
457
|
- `grep_app`
|
|
446
458
|
|
|
447
459
|
### Works with local helper bootstrap
|
|
448
460
|
|
|
449
|
-
- `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.
|
|
450
461
|
- `sequential-thinking`: launches `@modelcontextprotocol/server-sequential-thinking` through the helper npm runner.
|
|
451
|
-
- `firecrawl`:
|
|
462
|
+
- `firecrawl`: uses the CLI skill at `skills/firecrawl-cli/` and requires `FIRECRAWL_API_KEY` for web scraping and extraction tasks.
|
|
452
463
|
|
|
453
|
-
###
|
|
464
|
+
### Browser Automation
|
|
454
465
|
|
|
455
|
-
|
|
466
|
+
For browser automation, use the `/agent-browser` skill instead of an MCP server. The CLI uses native Chrome via CDP — no Playwright.
|
|
456
467
|
|
|
457
|
-
|
|
468
|
+
**Install** (Bun):
|
|
469
|
+
```bash
|
|
470
|
+
bun add -g agent-browser && agent-browser install
|
|
471
|
+
```
|
|
458
472
|
|
|
459
|
-
|
|
460
|
-
|
|
473
|
+
Or via npm:
|
|
474
|
+
```bash
|
|
475
|
+
npm i -g agent-browser && agent-browser install
|
|
476
|
+
```
|
|
461
477
|
|
|
462
|
-
|
|
478
|
+
Repo: https://github.com/vercel-labs/agent-browser
|
|
463
479
|
|
|
464
|
-
|
|
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
|
|
465
487
|
|
|
466
|
-
|
|
467
|
-
{
|
|
468
|
-
"mcp": {
|
|
469
|
-
"playwright": {
|
|
470
|
-
"enabled": true,
|
|
471
|
-
"command": ["node", "{pluginRoot}/assets/mcp/playwright.mjs", "--browser", "chrome"],
|
|
472
|
-
"timeout": 600000
|
|
473
|
-
}
|
|
474
|
-
}
|
|
475
|
-
}
|
|
476
|
-
```
|
|
477
|
-
|
|
478
|
-
- Try `--browser msedge` if Edge is installed.
|
|
479
|
-
- Use a remote/CDP browser or the `agent-browser`/`playwright-cli` skill path if those tools are installed.
|
|
480
|
-
- 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.
|
|
481
489
|
|
|
482
490
|
### Needs upstream runtime or extra setup
|
|
483
491
|
|
|
484
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.
|
|
485
|
-
- `rag`: requires your own running endpoint
|
|
486
493
|
|
|
487
494
|
### Important Windows note
|
|
488
495
|
|
|
@@ -493,6 +500,9 @@ On some Windows/OpenCode environments, local MCP process spawning can fail with
|
|
|
493
500
|
|
|
494
501
|
This most often affects `sequential-thinking` and `mempalace`, and sometimes local `npx`-backed tools.
|
|
495
502
|
|
|
503
|
+
## Troubleshooting MCP Servers
|
|
504
|
+
|
|
505
|
+
|
|
496
506
|
## Diagnostics
|
|
497
507
|
|
|
498
508
|
The plugin now emits startup warnings for common misconfiguration, including:
|
|
@@ -526,17 +536,6 @@ Inside OpenCode, use the slash command:
|
|
|
526
536
|
/mcp-status
|
|
527
537
|
```
|
|
528
538
|
|
|
529
|
-
Example output:
|
|
530
|
-
|
|
531
|
-
```text
|
|
532
|
-
MCP Servers:
|
|
533
|
-
✅ playwright - backend ok
|
|
534
|
-
⚠️ rag - enabled, http://localhost:9002/tools/search not reachable
|
|
535
|
-
✅ firecrawl - backend ok
|
|
536
|
-
❌ mempalace - python not found
|
|
537
|
-
⚠️ stitch - enabled, API key missing (STITCH_AI_API_KEY)
|
|
538
|
-
```
|
|
539
|
-
|
|
540
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.
|
|
541
540
|
|
|
542
541
|
Use:
|
|
@@ -559,12 +558,13 @@ opencode mcp list --print-logs --log-level INFO
|
|
|
559
558
|
| Planning / workflow influences | [obra/superpowers](https://github.com/obra/superpowers) | planning, review, and debugging ideas |
|
|
560
559
|
| Specialist / platform influences | [vtemian/micode](https://github.com/vtemian/micode) | platform-style specialist behavior |
|
|
561
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 |
|
|
562
563
|
| Optional external plugin | [Opencode-DCP/opencode-dynamic-context-pruning](https://github.com/Opencode-DCP/opencode-dynamic-context-pruning) | installed separately |
|
|
563
564
|
| MemPalace | [MemPalace/mempalace](https://github.com/MemPalace/mempalace) | external MCP/runtime |
|
|
564
|
-
| Playwright MCP | [microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp) | external MCP |
|
|
565
565
|
| Sequential Thinking | [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) | external MCP |
|
|
566
|
-
| Firecrawl
|
|
567
|
-
| 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 |
|
|
568
568
|
| bun-pty / PTY ecosystem | [shekohex/opencode-pty](https://github.com/shekohex/opencode-pty) | PTY/runtime integration influence |
|
|
569
569
|
|
|
570
570
|
## Build And Publish
|