OpenCode Plugin

The Constellation plugin for OpenCode is a lightweight integration layer: it registers the Constellation MCP server programmatically and instructs OpenCode to prefer code_intel over text search for code navigation tasks.

Source: github.com/ShiftinBits/constellation-opencode

Overview

Capability	How it works
MCP server registration	config hook spawns npx -y @constellationdev/mcp@latest and forwards CONSTELLATION_ACCESS_KEY
Tool preference	experimental.chat.system.transform appends a single instruction to the system prompt so the agent prefers code_intel over grep/glob/rg
Compaction-safe	experimental.session.compacting re-pushes that preference into compacted session summaries

note

This plugin ships with no skills, agents, or slash commands.

The OpenCode plugin specification does not yet support those resource types. However, this plugin does actively provide dynamic guidance to LLMs for better organic utilization of the code_intel tool.

Installation

Prerequisites

• OpenCode installed
• A Constellation account
• (Optional) Constellation CLI installed
• A project indexed in Constellation
• Constellation authentication configured
  • CONSTELLATION_ACCESS_KEY environment variable set
  • Automatically configure authentication using the CLI const auth command

Automatic Setup (Recommended)

Run const init in your project directory and select OpenCode when prompted. The CLI configures the plugin in your project's opencode.json.

Manual Setup

1. Add the plugin to your project's opencode.json:

   {
     "plugin": ["@constellationdev/opencode"]
   }

   OpenCode installs the plugin at startup. The config hook handles MCP server registration — no mcp block is required in opencode.json.

2. Configure authentication:

   const auth

3. Restart OpenCode and verify:

   In an OpenCode session, ask anything that exercises code understanding ("what does this codebase do?"). The agent should reach for code_intel rather than grep.

note

Install at the project level, not globally. The plugin should only be enabled for projects indexed by Constellation.

Behavior

The plugin always registers the MCP server. The system-prompt and compaction hooks attach only when CONSTELLATION_ACCESS_KEY starts with ak:. Without a valid key, the MCP server still spawns and surfaces its own auth error, but the system-prompt instruction is suppressed to avoid steering the agent toward a tool that cannot answer.

The system-prompt instruction is intentionally minimal — it tells the agent that code_intel is the preferred tool for symbol search, navigation, impact analysis, and architecture questions, and that text-search tools (grep, glob, awk, rg) should be used for literal text or as a fallback.

Hooks

Event	Purpose
config	Programmatically registers the constellation MCP server, spawned via npx -y @constellationdev/mcp@latest, with CONSTELLATION_ACCESS_KEY forwarded through the spawned process's environment.
experimental.chat.system.transform	Appends the code_intel preference instruction to the system prompt. Applies to all sessions, including subagents.
experimental.session.compacting	Re-pushes the preference into the compacted summary so it survives context-window compaction.

tool.execute.* hooks are intentionally not used — OpenCode does not currently propagate post-execute mutations back into the LLM-visible message stream in a way the plugin can rely on.

Using code_intel

Once installed, the Constellation MCP server exposes a single tool, code_intel, that accepts a JavaScript snippet executing against the Constellation API. OpenCode discovers and calls it like any other MCP tool — you don't invoke it directly.

Typical usage looks like this from the agent's perspective:

// Parallel queries via Code Mode
const [deps, dependents, usage] = await Promise.all([
  api.getDependencies({ filePath: 'src/service.ts' }),
  api.getDependents({ filePath: 'src/service.ts' }),
  api.traceSymbolUsage({ symbolName: 'MyClass', filePath: 'src/service.ts' })
]);

Category	Methods
Discovery	searchSymbols, getSymbolDetails
Dependencies	getDependencies, getDependents, findCircularDependencies
Tracing	traceSymbolUsage, getCallGraph
Impact	impactAnalysis, findOrphanedCode
Architecture	getArchitectureOverview

For the complete API reference, see the MCP Server Tools Reference.

Troubleshooting

Error	Cause	Solution
AUTH_ERROR	Missing or invalid access key	Run const auth; ensure CONSTELLATION_ACCESS_KEY starts with ak:
PROJECT_NOT_INDEXED	Project not yet indexed	Run const index --full from the project root
MCP_UNAVAILABLE	MCP server failed to start	Restart OpenCode; verify npx @constellationdev/mcp@latest --version works
code_intel tool missing	Plugin not loaded	Confirm opencode.json lists @constellationdev/opencode under plugin, then restart OpenCode
API_UNREACHABLE	API server not reachable	Check network and constellation.json API URL

For the complete error-code reference, see MCP Server Troubleshooting.

Verify the MCP server can run

npx @constellationdev/mcp@latest --version

Getting help

• Constellation Documentation
• Report issues on GitHub

Related Documentation

• MCP Server — Direct MCP integration without a plugin wrapper
• CLI Tool — Indexing your codebase
• OpenCode Documentation — Official OpenCode docs