# hiai-opencode

[![CI](https://github.com/HiAi-gg/hiai-opencode/actions/workflows/ci.yml/badge.svg?branch=main&event=push)](https://github.com/HiAi-gg/hiai-opencode/actions/workflows/ci.yml?query=branch%3Amain)
[![npm](https://img.shields.io/npm/v/@hiai-gg/hiai-opencode?style=flat-square&logo=npm)](https://www.npmjs.com/package/@hiai-gg/hiai-opencode)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE.md)

`hiai-opencode` is an OpenCode plugin that turns vanilla OpenCode into an opinionated multi-agent cockpit.

**What you get on top of plain OpenCode:**

- **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.
- **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".
- **MCP wiring out of the box** — Stitch, Context7, grep_app, MemPalace, Sequential-Thinking. Each agent's prompt knows which MCP servers it owns. Firecrawl is available as a CLI skill (not MCP).
- **LSP defaults** for TypeScript, Svelte, ESLint, Bash, Pyright. Coder must run `lsp_diagnostics` after every edit.
- **Permission discipline** — read-only agents cannot delegate; write-capable agents have explicit file-scope limits.

This repository is intended to be usable by someone who clones it from GitHub without any internal context. External MCP servers, skills, model providers, and auxiliary OpenCode plugins remain their own upstream projects; this plugin only provides OpenCode wiring, defaults, prompts, launchers, and documentation around them.

## Why This Exists

I wanted the "one install, give me the whole cockpit" setup. More agents, more MCP servers, more skills, better defaults, fewer tiny config islands. 🚀

The problem: all those great tools do not magically become friends just because you installed them. Some are npm packages, some are Python tools, some need API keys, some need a local service, and some only wake up after the first run. Meanwhile your main agent can waste half the context window just reading everything you bolted on. Not chill. 😅

So `hiai-opencode` is my attempt to wire the best pieces I use into one OpenCode-friendly shape: agents, prompts, skills, MCP launchers, LSP defaults, and a clean config surface. It does not claim ownership of the upstream tools. It just tries to make them cooperate.

After the first install, a few MCP services may still need local dependencies or keys. You have two options:

- Follow the setup sections below: [Install](#install), [Environment](#environment), and [MCP Service Notes](#mcp-service-notes).
- Or ask OpenCode to do the boring part for you. Paste this after installing:

```text
Read AGENTS.md and finish hiai-opencode setup for this workspace.

Keep OpenCode plugins separate from MCP servers. Do not add MCP server packages to the OpenCode plugin list.

Check which MCP services can run on this machine, update hiai-opencode.json, install only missing user-level or project-local dependencies, and report missing API keys without printing secret values.

Then run `hiai-opencode doctor`, `hiai-opencode mcp-status`, and `opencode debug config`.
```

For the full operator playbook, see [AGENTS.md](AGENTS.md). 🤖


## Agents

**9 Visible Primary Agents:**

| Agent | Role | When to use |
|-------|------|-------------|
| `Bob` | Orchestrator, router, distributor | Entry point; complex tasks needing multi-agent coordination |
| `Coder` | Deep implementation, focused execution | Complex features, refactors, deep work |
| `Strategist` | Planning, architecture, pre-check | Scope definition, architectural decisions |
| `Manager` | Delegation orchestrator, TODO tracker | Coordinates specialists, maintains session continuity |
| `Critic` | Review gate, high-accuracy verification | Plan review, code review, regression catch |
| `Designer` | UI/visual direction via Stitch MCP | Visual problems, design systems, screen generation |
| `Researcher` | Local + external search | Codebase exploration, documentation discovery via Context7/grep_app/Firecrawl CLI/MemPalace |
| `Writer` | Content, copy, positioning, SEO | Website copy, product messaging, naming |
| `Vision` | PDF/image/diagram extraction, browser UI verification | Multimodal analysis, live browser verification |

**5 Hidden System Agents** (used internally, not for direct selection):

- `Agent Skills` — Skill registry, discovery, and capability orchestration
- `Sub` — Compatibility wrapper for bounded execution (folded into Coder's contour)
- `build` — Default executor (OpenCode system agent)
- `plan` — Plan mode agent (OpenCode system agent)
- `Quality Guardian` — Post-implementation review and bug investigation (compatibility alias for Critic)

## Modes (Task Routing)

Mode determines prompt append, variant, and reasoning effort. The executor agent is selected via `mode → agent` mapping.

| Mode | Agent | Prompt variant | When to use |
|------|-------|----------------|-------------|
| `quick` | `coder` (via fast bounded contour) | Fast bounded | Small targeted changes |
| `writing` | `writer` | Docs/prose | Content, i18n, copy |
| `deep` | `coder` | Deep reasoning | Complex implementation |
| `ultrabrain` | `strategist` | Plan-only | Architecture, hard logic |
| `visual-engineering` | `designer` | UI/visual | Visual problems |
| `artistry` | `designer` | Creative | Brand, SEO, creative |
| `git` | `platform-manager` | Git ops | Version control operations |
| `bounded` | `coder` (via fast bounded contour) | Mid-tier bounded | Moderate effort changes |
| `cross-module` | `coder` | Deep substantial | Multi-component changes |
| `unspecified-low` | `coder` (via fast bounded contour) | Bounded | Unclassified small tasks |
| `unspecified-high` | `coder` | Deep | Unclassified substantial tasks |

## Integrations

MCP integrations and which agents use them:

| Service | Key env var | Agent(s) | What it's for |
|---------|------------|----------|---------------|
| Stitch | `STITCH_AI_API_KEY` | Designer | UI generation, design systems, screen variants |
| Firecrawl | `FIRECRAWL_API_KEY` | Researcher | CLI skill (not MCP) for web scraping, crawl, extract, search |
| Context7 | `CONTEXT7_API_KEY` | Researcher, Coder | Library API documentation |
| grep_app | — | Researcher | GitHub OSS code pattern search |
| MemPalace | MEMPALACE_PYTHON (optional) | Manager (primary), all agents | Project memory and past decisions |
| Sequential-Thinking | — | Strategist, Critic | Deep reasoning for planning/review |

## Design System

The plugin bundles a comprehensive design library sourced from [nexu-io/open-design](https://github.com/nexu-io/open-design) (Apache 2.0).

**150+ brand design systems** in `design-systems/` — each contains:
- `DESIGN.md` — brand voice, typography, color palette, component patterns, layout principles
- `tokens.css` — CSS custom properties for colors, spacing, typography, shadows
- `components.html` — reference HTML for key UI components

Brands include: Apple, Linear, Stripe, Vercel, Airbnb, BMW, Spotify, Notion, Figma, Supabase, and 140+ more.

**48 design skills** in `skills/` — covering:
- Visual storytelling, editorial layouts, motion design
- Figma integration (create, generate, implement, export)
- Canvas design, poster/hero layouts, slide decks
- Accessibility baselines, animation discipline, color theory

**Craft guidelines** in `craft/` — deep references on:
- Typography hierarchy (editorial + standard)
- Color systems and accessibility
- Form validation UX, state coverage patterns
- Laws of UX, RTL/bidirectional layout
- Anti-AI-slop patterns (preventing generic output)

**Prompt templates** in `prompt-templates/` — ready-made prompts for image generation and video production.

The Designer agent uses these assets to ground its output in real brand systems instead of generic AI aesthetics. When the Designer agent works on a task, it can reference brand-specific tokens, typography scales, and component patterns from the design-systems library.

## What You Get

- **9 visible primary agents** + **5 hidden system agents** (Agent Skills, Sub, build, plan, Quality Guardian)
- **Mode-based task routing** via `task(category=..., ...)` or `task(mode=..., ...)`
- Skill materialization into OpenCode's `skills/` view
- MCP wiring for `stitch`, `sequential-thinking`, `mempalace`, `context7`, and `grep_app` (Firecrawl is CLI skill only, not MCP)
- LSP wiring for TypeScript, Svelte, Python, Bash, and ESLint

## Continuation, Ralph-Loop, And Auto-Start

The plugin runs three layered mechanisms so a session does not give up halfway through a TODO list.

| Mechanism | Trigger | What it does |
|-----------|---------|--------------|
| **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. |
| **Ralph-loop** | `/ralph-loop <goal>` or `/ulw-loop <goal>` | Runs an explicit completion loop. Stops on `<promise>DONE</promise>`. Cancel with `/cancel-ralph`. |
| **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). |

Tune the auto-start threshold in `hiai-opencode.json`:

```json
{
  "ralph_loop": {
    "enabled": true,
    "auto_start_threshold": 5
  }
}
```

`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.

## Requirements

Minimum:

- OpenCode installed
- Node.js 18+
- Bun 1.3.14+

Usually required:

- at least one model provider connected in OpenCode for the model IDs you configure

Optional, depending on which services you want:

- `FIRECRAWL_API_KEY` for Firecrawl (CLI skill, not MCP)
- `STITCH_AI_API_KEY` for Stitch (MCP)
- `CONTEXT7_API_KEY` for Context7 (MCP)
- Python 3.9+ or `uv` for MemPalace (MCP)
- local language servers if you want LSP beyond the npm-bootstrapped helpers

## Install

### 1. Register the OpenCode plugin

```bash
opencode plugin @hiai-gg/hiai-opencode@latest --global
```

Optional Dynamic Context Pruning plugin:

```bash
opencode plugin @tarquinen/opencode-dcp@latest --global
```

Do not put MCP server packages such as `@modelcontextprotocol/server-sequential-thinking` into the OpenCode `plugin` array. They are MCP servers, not OpenCode plugins. Firecrawl is available as a CLI skill at `skills/firecrawl-cli/`, not as an MCP server.

Manual OpenCode config equivalent:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@hiai-gg/hiai-opencode",
    "@tarquinen/opencode-dcp@latest"]
}
```

The packaged minimal OpenCode example lives in [config/opencode.json](config/opencode.json).

### 2. Create project config

Create a project-level config file at `hiai-opencode.json` in the project root or at `.opencode/hiai-opencode.json`.

Bash:

```bash
mkdir -p .opencode
cp hiai-opencode.json .opencode/hiai-opencode.json
```

PowerShell:

```powershell
New-Item -ItemType Directory -Force .opencode
Copy-Item .\hiai-opencode.json .\.opencode\hiai-opencode.json
```

If you installed only from npm/OpenCode and do not have this repository checked out, create `.opencode/hiai-opencode.json` with the shape below and adjust it later.

```json
{
  "models": {
    "bob": { "model": "kimi-for-coding/k2p6", "recommended": "xhigh" },
    "coder": { "model": "minimax-coding-plan/MiniMax-M2.7", "recommended": "high" },
    "strategist": { "model": "deepseek/deepseek-v4-pro", "recommended": "high" },
    "manager": { "model": "opencode-go/qwen3.6-plus", "recommended": "middle" },
    "critic": { "model": "opencode-go/mimo-v2.5-pro", "recommended": "high" },
    "designer": { "model": "openrouter/google/gemini-3.1-pro-preview", "recommended": "design" },
    "researcher": { "model": "openrouter/deepseek/deepseek-v4-flash", "recommended": "fast" },
    "writer": { "model": "openrouter/mistralai/mistral-small-2603", "recommended": "writing" },
    "vision": { "model": "openrouter/google/gemma-4-26b-a4b-it", "recommended": "vision" }
  },
  "mcp": {
    "sequential-thinking": { "enabled": true },
    "mempalace": { "enabled": true, "pythonPath": "{env:MEMPALACE_PYTHON:-./.venv/bin/python}" },
    "stitch": { "enabled": false },
    "context7": { "enabled": true }
  }
}
```

By default, skill discovery is deterministic: `hiai-opencode` skills plus project-local `.opencode/skills` only. Global Claude/OpenCode/Agents skill folders are opt-in.

### 3. Connect models and add service keys

Model provider credentials belong to OpenCode Connect, not to `hiai-opencode`.
This plugin only reads the 10 model IDs in `models`. Internal routing derives hidden agents and task categories from those 10 choices.

Use OpenCode Connect to authorize the providers behind your configured model IDs. Then add only the service keys for MCP or search integrations you actually use:

```bash
opencode models
```

Use the exact model IDs printed by OpenCode in `hiai-opencode.json`. For example, `openrouter/minimax/minimax-m2.7` routes through OpenRouter, while `minimax/minimax-m2.7` routes through a direct Minimax provider only if that provider is connected in OpenCode.

```bash
export FIRECRAWL_API_KEY=...
export STITCH_AI_API_KEY=...
export CONTEXT7_API_KEY=...
```

See [Environment Variables And Keys](#environment-variables-and-keys) for the full list.

### 4. Start and verify

```bash
opencode
hiai-opencode doctor
hiai-opencode mcp-status
hiai-opencode export-mcp .opencode/.mcp.json
opencode debug config
opencode mcp list --print-logs --log-level INFO
```

`opencode mcp list` reads static `.mcp.json` files in many OpenCode versions. Runtime MCP servers launched by plugins may work but not appear there. If you want `opencode mcp list` visibility, run `hiai-opencode export-mcp .opencode/.mcp.json` first.

`hiai-opencode mcp-status` is the fastest visibility check. It does not change OpenCode config; it reports config location, enabled MCP services, missing keys, and basic local runtime availability.

`hiai-opencode doctor` is the broader install/runtime diagnostic. It includes MCP status, static `.mcp.json` freshness, OpenCode Connect visibility, skill materialization, agent naming/count checks, LSP runtime checks, MemPalace Python source selection, and real MCP tool probes.

## Development Install

Direct npm install is only needed for development or inspection:

```bash
bun install
```

Local development:

```bash
git clone https://github.com/HiAi-gg/hiai-opencode.git
cd hiai-opencode
bun install
bun run build
```

## Post-Install Bootstrap Prompt

After installing the plugin, you can ask OpenCode to finish local setup with this prompt:

```text
Inspect this OpenCode workspace and finish hiai-opencode setup.

Do not add MCP server packages to the OpenCode plugin list. Keep OpenCode plugins separate from MCP servers.

Check that @hiai-gg/hiai-opencode is registered. If Dynamic Context Pruning is requested, install @tarquinen/opencode-dcp as a separate OpenCode plugin.

Find or create hiai-opencode.json in the project root or .opencode/. Use its mcp object as the single switchboard for enabling or disabling MCP services.

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.

Enable only services that can run on this machine:
- sequential-thinking: requires node/npx.
- 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.
- stitch: requires STITCH_AI_API_KEY.
- context7: works without a key but use CONTEXT7_API_KEY if available.
- grep_app: no key required.
- firecrawl-cli: CLI skill (not MCP) at `skills/firecrawl-cli/`; requires FIRECRAWL_API_KEY.

Check .env.example, report missing keys without printing secret values, and never invent or hardcode API keys.

Run verification commands where available:
- opencode debug config
- hiai-opencode mcp-status
- hiai-opencode export-mcp .opencode/.mcp.json
- opencode mcp list --print-logs --log-level INFO

If a dependency is missing, install only user-level or project-local dependencies, explain every command before running it, and do not use sudo/admin rights unless the user explicitly asks.
```

## Where To Change Things

### Models

Canonical user-facing config for 10 primary agent models, MCP/LSP switches, service auth placeholders, and skill discovery:

- [hiai-opencode.json](hiai-opencode.json)

Runtime loader for the bundled canonical config:

- [src/config/defaults.ts](src/config/defaults.ts)

If you want to change model selection, edit the 10 entries in `models`. Do not add category-specific model choices unless you are intentionally developing the plugin internals.

Use fully qualified model IDs. Do not introduce local aliases like `hiai-fast`, `sonnet`, `fast`, or `high`.
After connecting providers in OpenCode, run `opencode models` and copy the exact model IDs from that output into `hiai-opencode.json`.

### Prompting

Prompting has two main layers:

1. source prompt files in [src/agents](src/agents)
2. runtime assembly in [src/plugin-handlers/agent-config-handler.ts](src/plugin-handlers/agent-config-handler.ts)

Important prompt entrypoints:

- `Bob`: `src/agents/bob/*`
- `Coder`: `src/agents/coder/*`
- `Strategist`: `src/agents/strategist/*`
- `Manager`: `src/agents/manager/*`
- `Critic`: `src/agents/critic/*`
- `Vision`: [src/agents/ui.ts](src/agents/ui.ts)
- `Researcher`: [src/agents/researcher.ts](src/agents/researcher.ts)
- `Writer`: [src/agents/writer.ts](src/agents/writer.ts)

Name mapping and visibility:

- [src/shared/agent-display-names.ts](src/shared/agent-display-names.ts)
- [src/plugin-handlers/agent-config-handler.ts](src/plugin-handlers/agent-config-handler.ts)

### Skills

Project skill definitions live under:

- [skills](skills)

Skill materialization logic:

- [src/features/builtin-skills/materialize.ts](src/features/builtin-skills/materialize.ts)

Built-in helper skills include browser automation, frontend UI/UX, review, git workflow, hiai-opencode setup, AI slop cleanup, and `website-copywriting`.

Website/product copy should use:

```text
task(subagent_type="writer", load_skills=["website-copywriting"], ...)
```

`writer`, `copywriter`, and `content-writer` are aliases for `writer`.

Manager memory stewardship:

- Use `task(subagent_type="platform-manager", ...)` or `task(subagent_type="manager", ...)` for MemPalace cleanup, session ledgers, TODO hygiene, and architecture decision handoff.
- Manager writes only durable decisions and important project state. It should not dump raw chat logs into memory.

Skill discovery defaults:

```json
{
  "skill_discovery": {
    "config_sources": true,
    "project_opencode": true,
    "global_opencode": false,
    "project_claude": false,
    "global_claude": false,
    "project_agents": false,
    "global_agents": false
  }
}
```

This keeps clean installs reproducible and avoids accidentally mixing Codex, Claude, Antigravity, and global OpenCode skill collections. To opt into external skill folders, enable the specific source you want instead of turning everything on.

### MCP

Default MCP registry:

- [src/mcp/registry.ts](src/mcp/registry.ts)

OpenCode MCP config assembly:

- [src/mcp/index.ts](src/mcp/index.ts)

Runtime helper launchers:

- [assets/mcp](assets/mcp)
- [assets/runtime](assets/runtime)

### LSP

LSP defaults are defined in:

- [src/config/defaults.ts](src/config/defaults.ts)

## Environment Variables And Keys

Model provider keys are handled by OpenCode Connect. Do not add `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, or `ANTHROPIC_API_KEY` to `hiai-opencode` config for normal model usage.

Important service variables:

- `STITCH_AI_API_KEY` (MCP)
- `FIRECRAWL_API_KEY` (CLI skill, not MCP)
- `CONTEXT7_API_KEY` (MCP)
- `OLLAMA_BASE_URL`
- `OLLAMA_MODEL`
- `MEMPALACE_PYTHON` (MCP)
- `MEMPALACE_PALACE_PATH` (MCP)

- `HIAI_MCP_AUTO_INSTALL`
- `HIAI_OPENCODE_AUTO_EXPORT_MCP`
- `HIAI_OPENCODE_MCP_EXPORT_PATH`

Optional headless or non-Connect fallback variables are documented in [.env.example](.env.example), but they are not required for normal OpenCode model auth.

Use [.env.example](.env.example) as the reference template. Create a local `.env` in your OpenCode environment or export these variables in your shell before startup.

## MCP Service Notes

The user-facing MCP switchboard is the `mcp` object in `hiai-opencode.json`:

```json
{
  "mcp": {
    "mempalace": { "enabled": false },
    "grep_app": { "enabled": true }
  }
}
```

The source of truth for default MCP wiring is `src/mcp/registry.ts`. Change that file when adding a new MCP integration or changing its launch command, required env vars, or install strategy.

### Works well as remote MCP

- `stitch`
- `context7`
- `grep_app`

### Works with local helper bootstrap

- `sequential-thinking`: launches `@modelcontextprotocol/server-sequential-thinking` through the helper npm runner.

### CLI skills (not MCP)

- `firecrawl`: uses the CLI skill at `skills/firecrawl-cli/` and requires `FIRECRAWL_API_KEY` for web scraping and extraction tasks. No MCP server needed.

### Browser Automation

For browser automation, use the `/agent-browser` skill instead of an MCP server. The CLI uses native Chrome via CDP — no Playwright.

**Install** (Bun):
```bash
bun add -g agent-browser && agent-browser install
```

Or via npm:
```bash
npm i -g agent-browser && agent-browser install
```

Repo: https://github.com/vercel-labs/agent-browser

Key environment variables (`AGENT_BROWSER_*`):
- `AGENT_BROWSER_HEADED=1` — show browser window
- `AGENT_BROWSER_SESSION=name` — isolated session
- `AGENT_BROWSER_PROFILE=path` — persistent profile
- `AGENT_BROWSER_PROVIDER=name` — cloud provider (browserbase, browseruse, kernel)
- `AGENT_BROWSER_AUTO_CONNECT=1` — auto-discover running Chrome
- `AGENT_BROWSER_EXECUTABLE_PATH` — custom browser binary

Use `/agent-browser` skill in OpenCode for browser tasks — navigation, snapshots, screenshots, form filling, console/network inspection.

### Needs upstream runtime or extra setup

- `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.

### Important Windows note

On some Windows/OpenCode environments, local MCP process spawning can fail with `EPERM` for `cmd` or `node`. If you see that:

- the plugin config is likely correct
- the remaining issue is the host runtime's local process spawn behavior

This most often affects `sequential-thinking` and `mempalace`, and sometimes local `npx`-backed tools.

## Troubleshooting MCP Servers


## Diagnostics

The plugin now emits startup warnings for common misconfiguration, including:

- `.opencode/opencode.json` containing `plugin: ["list"]`
- enabled MCP integrations with missing required env vars such as `STITCH_AI_API_KEY`

Available CLI:

```bash
hiai-opencode doctor
hiai-opencode mcp-status
hiai-opencode export-mcp .opencode/.mcp.json
```

By default, the plugin auto-exports `.opencode/.mcp.json` at workspace startup when the file is missing. This closes the visibility gap where runtime plugin MCP works but `opencode mcp list` only reads static files. Control it with:

```bash
export HIAI_OPENCODE_AUTO_EXPORT_MCP=if-missing  # default
export HIAI_OPENCODE_AUTO_EXPORT_MCP=always      # overwrite only managed hiai-opencode exports
export HIAI_OPENCODE_AUTO_EXPORT_MCP=force       # force overwrite even non-managed files
export HIAI_OPENCODE_AUTO_EXPORT_MCP=0           # disable auto-export
export HIAI_OPENCODE_MCP_EXPORT_PATH=.opencode/.mcp.json   # override path
export HIAI_OPENCODE_EXPORT_MCP_MODE=safe        # export-mcp command mode: safe|force
```

Inside OpenCode, use the slash command:

```text
/doctor
/mcp-status
```

`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.

Use:

```bash
hiai-opencode mcp-status
hiai-opencode export-mcp .opencode/.mcp.json
opencode debug config
opencode mcp list --print-logs --log-level INFO
```

## Core Components And Upstream Projects

`hiai-opencode` wires these projects and ideas into an OpenCode-friendly setup. Upstream projects remain independent; this table is attribution and orientation, not an ownership claim.

| Component | Upstream | Notes |
|---|---|---|
| OpenCode host/runtime | [anomalyco/opencode](https://github.com/anomalyco/opencode) | plugin host and runtime target |
| Core orchestration influences | [code-yeongyu/oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent) | architectural influence |
| Planning / workflow influences | [obra/superpowers](https://github.com/obra/superpowers) | planning, review, and debugging ideas |
| Specialist / platform influences | [vtemian/micode](https://github.com/vtemian/micode) | platform-style specialist behavior |
| Agent skill ecosystem | [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | tactical workflow skill ideas |
| 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 |
| Browser automation | [vercel-labs/agent-browser](https://github.com/vercel-labs/agent-browser) | CLI-based browser automation via CDP |
| Optional external plugin | [Opencode-DCP/opencode-dynamic-context-pruning](https://github.com/Opencode-DCP/opencode-dynamic-context-pruning) | installed separately |
| MemPalace | [MemPalace/mempalace](https://github.com/MemPalace/mempalace) | external MCP/runtime |
| Sequential Thinking | [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) | external MCP |
| Firecrawl CLI skill | [firecrawl/firecrawl](https://github.com/firecrawl/firecrawl) | CLI-based web scraping, crawl, extract, search (NOT an MCP server) |
| Context7 MCP | [upstash/context7](https://github.com/upstash/context7) | external MCP |
| bun-pty / PTY ecosystem | [shekohex/opencode-pty](https://github.com/shekohex/opencode-pty) | PTY/runtime integration influence |
| Design systems and skills | [nexu-io/open-design](https://github.com/nexu-io/open-design) | brand-grade design systems, design skills, craft guidelines (Apache 2.0) |

## Build And Publish

Build:

```bash
bun run build
```

Typecheck:

```bash
bun run typecheck
```

Prompt snapshots:

```bash
bun run prompts:measure
```

Before publishing:

1. run `bun run build`
2. run `npm pack --dry-run`
3. verify `debug config`
4. run `hiai-opencode export-mcp .opencode/.mcp.json` if you need static `mcp list` visibility

Publish:

```bash
npm publish --access public
```

User install after publish:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@hiai-gg/hiai-opencode"]
}
```

## Documentation Map

- [AGENTS.md](AGENTS.md): instructions for autonomous agents or tooling that need to install or modify the plugin
- [ARCHITECTURE.md](ARCHITECTURE.md): runtime wiring, prompting layers, and modification map
- [LICENSE.md](LICENSE.md): licensing and attribution
