Skip to content

opencode.md

Latest commit

 

History

History
127 lines (102 loc) · 5.86 KB

opencode.md

File metadata and controls

127 lines (102 loc) · 5.86 KB

Installing deliberation in OpenCode

OpenCode (by SST) reads modular project artifacts from a .opencode/ directory and MCP servers from an opencode.json config. The deliberation artifacts are generated by scripts/sync-hosts.js from the canonical sources (prompts/*.md, plus the shared command/expert tables), and ship as:

  • .opencode/commands/*.md - one thin slash-command per fan-out / single-provider tool (/ask-all, /consensus, /ask-gpt, /ask-gemini, /ask-grok, /ask-openrouter). Each just calls the matching deliberation MCP tool.
  • .opencode/agents/*.md - one subagent per expert persona (architect, plan-reviewer, scope-analyst, code-reviewer, security-analyst, researcher, debugger), each with mode: subagent.

The MCP server itself is registered in your opencode.json (see below).

1. Register the MCP server

OpenCode loads MCP servers from the mcp key in opencode.json (project root) or ~/.config/opencode/opencode.json (global). The config file does not live inside .opencode/. Add a local (stdio) server:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "deliberation": {
      "type": "local",
      "command": ["npx", "-y", "@antonbabenko/deliberation-mcp"],
      "enabled": true,
      "environment": {}
    }
  }
}

Source: opencode.ai/docs/mcp-servers. type: "local" is a stdio server; command is the argv array; environment is optional. The bridges read provider credentials from the process environment OpenCode launches the server in, so an empty environment is fine - set keys in your shell (or add them under environment).

2. Drop in the commands and agents

Copy the generated .opencode/commands/ and .opencode/agents/ directories into your project (or into ~/.config/opencode/ for global use - OpenCode uses the same plural subdirectory names in both locations). The filename becomes the command / agent name (ask-all.md -> /ask-all, architect.md -> the architect subagent).

Source: opencode.ai/docs/commands, opencode.ai/docs/agents.

Provider credentials

The MCP server (npx -y @antonbabenko/deliberation-mcp, stdio) reads provider credentials from the host environment. Set whichever providers you use:

Provider How it authenticates
GPT (Codex) OpenAI / Codex CLI auth (Codex login or OPENAI_API_KEY)
Gemini The Antigravity CLI (agy) - sign in once with the CLI
Grok (xAI) XAI_API_KEY
OpenRouter OPENROUTER_API_KEY (advisory-only; declare models in ~/.config/deliberation/config.json)

You only need the providers you intend to call - missing keys just disable that one provider.

Optional npm plugin (not shipped)

A .opencode/plugins/ JS plugin could add a proactive "consider delegating" nudge, and opencode.json supports an npm plugin array:

{ "plugin": ["@antonbabenko/opencode-deliberation"] }

The npm name @antonbabenko/opencode-deliberation is currently unpublished and available (npm returns 404). It is reserved here but intentionally not shipped: the verified plugin hook API (event, tool.execute.before, tool.execute.after, shell.env, experimental.session.compacting) has no hook that injects a proactive delegation hint into the system prompt, so a plugin would add a runtime dependency for no verified behavior win. The subagents plus the command wrappers already give OpenCode the native delegation surface. If a suitable hook is added upstream, confirm the export shape at opencode.ai/docs/plugins before shipping.

Distribution

  • npm - reserve / publish @antonbabenko/opencode-deliberation if a plugin ever ships (the MCP server is already on npm as @antonbabenko/deliberation-mcp).
  • OpenCode ecosystem listing - submit to the official ecosystem page at opencode.ai/docs/ecosystem. [unverified] Confirm the exact submission path / PR target there.
  • awesome-opencode - open a PR to the community awesome-opencode list. [unverified] Confirm the repo path and listing format.

Notes / verified vs. unverified

Verified against the official docs (fetched live):

  • Command files live in .opencode/commands/ (plural); frontmatter keys description, agent, model, subtask; $ARGUMENTS / $1...$N for input. Source: opencode.ai/docs/commands.
  • Agent files live in .opencode/agents/ (plural); subagent uses mode: subagent; frontmatter description (required), mode, model, temperature, permission. Source: opencode.ai/docs/agents.
  • MCP mcp key shape (type: "local", command array, enabled, environment) and $schema: "https://opencode.ai/config.json". Source: opencode.ai/docs/mcp-servers.
  • The docs state the .opencode and ~/.config/opencode directories use plural subdirectory names (agents/, commands/, plugins/, ...); the config file opencode.json lives at the project root / global, not inside .opencode/. Source: opencode.ai/docs/config.
  • Plugin directory is .opencode/plugins/ (plural); a plugin is a named async export returning a hooks object. Source: opencode.ai/docs/plugins.
  • @antonbabenko/opencode-deliberation is unpublished/available on npm (404).

Unverified (confirm at the linked doc before relying on it):

  • The exact OpenCode ecosystem submission flow and awesome-opencode listing format.
  • Whether OpenCode does ${VAR} substitution inside environment (deliberation reads keys from the process env, so this is not needed).