OpenCode Plugin

The Constellation plugin for OpenCode supercharges your AI-assisted development workflow with deep codebase understanding. It provides slash commands, specialized agents, and session hooks that leverage Constellation's code intelligence platform.

Source: github.com/shiftinbits/constellation-opencode

Overview

Feature	Description
7 Commands	Quick access to common analysis workflows
3 Agents	Codebase exploration, risk assessment, and dependency analysis via @mention
2 Hooks	System prompt injection and context preservation

Installation

Prerequisites

OpenCode installed
A Constellation account
Constellation CLI utility installed
A project previously indexed in Constellation

Automatic Setup (Recommended)

Run constellation init in your project directory and select OpenCode when prompted. The CLI automatically configures both the plugin and MCP server in your project's opencode.json.

Manual Setup

Add the plugin to your project's opencode.json:
```
{
  "plugin": ["@constellationdev/opencode"]
}
```
OpenCode will automatically install the plugin at startup.
Configure authentication:
```
constellation auth
```
Restart OpenCode and verify:
```
/status
```

note

Install this plugin at the project level, not globally. It should only be enabled for projects that use Constellation.

Commands

Status

/status

Check API connectivity and project indexing status.

> /status

⏺ Status: Connected ✓

  Project Metrics:
  - Total Files: 60
  - Total Symbols: 36
  - Supported Languages: TypeScript (100%)

  Project Structure:
  - Modules: 3 (average size: 20 files)
  - Symbol Distribution: 368 constants, 305 properties, 140 functions...
  - Maintainability Score: 75/100

Diagnose

/diagnose

Quick health check for Constellation connectivity and authentication.

> /diagnose

Constellation Health Check
===========================
MCP Server:  OK
API Auth:    OK
Project:     my-awesome-app
Index:       1,247 files, 8,932 symbols

All systems operational.

Architecture

/architecture

Get a high-level overview of your codebase structure.

> /architecture

Project: my-awesome-app
Total Files: 1,247
Total Symbols: 8,932

Language Distribution:
├── TypeScript: 892 files (71.5%)
├── JavaScript: 312 files (25.0%)
└── JSON: 43 files (3.5%)

Key Directories:
├── src/services/: 1,234 symbols
├── src/components/: 892 symbols
└── src/utils/: 456 symbols

Impact

/impact <symbol> [file]

Analyze the blast radius before changing a symbol.

Arguments:

symbol - Name of the function, class, or variable
file - (Optional) Path to the file containing the symbol

> /impact UserService src/services/user.service.ts

Symbol: UserService (class)
Risk Level: HIGH
Files Affected: 23
Symbols Affected: 67
Public API Impact: Yes
Test Coverage: 72%

Top Affected Files:
├── src/controllers/user.controller.ts
├── src/controllers/auth.controller.ts
├── src/middleware/auth.middleware.ts
└── ... 20 more files

Recommendations:
- Review UserController before modifying
- Update unit tests in user.service.spec.ts
- Check integration with AuthService

Deps

/deps <file> [--reverse]

Map dependencies or find what depends on a file.

Arguments:

file - Path to the file to analyze
--reverse or -r - Show dependents instead of dependencies

Dependencies (default):

> /deps src/services/payment.service.ts

Dependencies (12):
├── Internal (8)
│   ├── src/models/payment.model.ts
│   ├── src/utils/currency.ts
│   └── ... 5 more
└── External (4)
    ├── stripe
    ├── lodash
    └── ... 2 more

No circular dependencies detected.

Dependents (with --reverse):

> /deps src/services/payment.service.ts --reverse

Dependents (7):
├── src/controllers/payment.controller.ts
├── src/controllers/checkout.controller.ts
└── ... 4 more

Unused

/unused [kind]

Find orphaned exports and dead code.

Arguments:

kind - (Optional) Filter by type: function, class, type, interface, or variable

> /unused function

Found 7 orphaned functions:
├── src/utils/legacy.ts
│   ├── formatLegacyDate (line 23)
│   └── parseLegacyConfig (line 45)
├── src/helpers/deprecated.ts
│   └── oldValidation (line 12)
└── ... more

Recommendation: Review these exports and remove if no longer needed.

Troubleshoot

/troubleshoot [error]

Diagnose Constellation issues with error code reference.

Arguments:

error - (Optional) Specific error code to look up (e.g., AUTH_ERROR)

> /troubleshoot AUTH_ERROR

Error: AUTH_ERROR
═══════════════════════════════════════════════════════════════

Cause: Access key is missing, invalid, or expired.

Quick Fixes:
1. Run: constellation auth
2. Verify CONSTELLATION_ACCESS_KEY environment variable
3. Check key hasn't been revoked in dashboard

Still stuck? Run /diagnose for full health check.

Agents

OpenCode agents are specialized assistants invoked via @mention. The plugin includes three agents that activate when you mention them in your conversation.

@source-scout

Purpose: Codebase exploration, understanding, and intelligent navigation.

Invoke with:

@source-scout What does this codebase do?
@source-scout Where is the authentication logic?
@source-scout Find all places that use UserService

What it does:

Uses Constellation's semantic search to find symbols intelligently
Analyzes architecture and provides codebase overviews
Traces symbol usage across the entire codebase
Maps call graphs to explain how components interact
Falls back gracefully to traditional tools if Constellation is unavailable

@impact-investigator

Purpose: Proactively assesses risk before refactoring, renaming, or deleting code.

Invoke with:

@impact-investigator I'm going to rename UserAuthService
@impact-investigator Is it safe to delete this function?
@impact-investigator I want to refactor this class

What it does:

Analyzes the impact of the proposed change
Identifies all files and symbols that would be affected
Assesses risk level (Low/Medium/High/Critical)
Warns about potential breaking changes to public APIs
Suggests the safest order for multi-file changes

Risk levels:

Low: < 5 files affected, no public API changes, high test coverage
Medium: 5-15 files affected, internal API changes, moderate coverage
High: > 15 files affected, public API changes, low test coverage
Critical: Core infrastructure, security-related, or widely-used utilities

@dependency-detective

Purpose: Detects circular dependencies and unhealthy coupling patterns.

Invoke with:

@dependency-detective Check for circular imports
@dependency-detective Are our modules too tightly coupled?
@dependency-detective Dependency health check before PR

What it does:

Detects circular dependencies in specified scope or entire codebase
Identifies overly coupled modules
Finds dependency chains that could cause problems
Suggests refactoring to improve dependency health
Verifies proposed imports won't create cycles

Breaking cycle strategies it suggests:

Interface extraction
Dependency inversion
Event-driven communication
Module restructuring
Lazy loading with dynamic imports

Hooks

The plugin includes two hooks that enhance OpenCode's behavior transparently.

System Prompt Hook

Event: experimental.chat.system.transform

Purpose: Injects Constellation awareness into every conversation.

Behavior:

Adds instructions that code_intel is the PRIMARY tool for code understanding
Provides mental model: Constellation for structure, Grep for literal text
Applied automatically at session start and for all agents

Context Preservation Hook

Event: experimental.session.compacting

Purpose: Preserves Constellation insights during context compaction.

Behavior:

Ensures architectural insights survive context window compaction
Preserves dependency relationships and impact analysis results
Maintains the instruction that Constellation is the primary code understanding tool

Troubleshooting

Quick Diagnostics

Run the built-in diagnostic command for a quick health check:

/diagnose

This checks MCP server connectivity, API authentication, and project indexing status with actionable fixes for each issue.

Common Errors

Error	Cause	Solution
`MCP_UNAVAILABLE`	MCP server not running	Restart OpenCode to reinitialize connections
`AUTH_ERROR`	Missing or invalid Access key	Run `constellation auth`
`PROJECT_NOT_INDEXED`	Project needs indexing	Run `constellation index --full`
`SYMBOL_NOT_FOUND`	Symbol not in index	Search with partial match or re-index
`API_UNREACHABLE`	API server not running	Check network and API URL in constellation.json
`FILE_NOT_FOUND`	File path not in index	Verify relative path, check language config

MCP Server Issues

If you see MCP connection errors:

Restart OpenCode - MCP connections initialize at startup

Verify MCP server can run:

npx @constellationdev/mcp@latest --version

Check configuration in opencode.json:

{
  "mcp": {
    "constellation": {
      "type": "local",
      "command": ["npx", "-y", "@constellationdev/mcp@latest"],
      "enabled": true
    }
  }
}

Step-by-Step Diagnostics

Run health check:
```
/diagnose
```
Check connectivity:
```
/status
```
Verify CLI status:
```
constellation status
```
Re-index if needed:
```
constellation index --full
```

Getting Help

Check the Constellation Documentation
Report issues on GitHub

Advanced Usage

Parallel API Execution

The Constellation API uses Code Mode, which allows writing JavaScript that executes multiple API calls in parallel:

// All three queries execute in parallel
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' })
]);

Available API Methods

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

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

MCP Server — For direct MCP integration without a plugin wrapper
CLI Tool — For indexing your codebase
OpenCode Documentation — Official OpenCode docs

Overview​

Installation​

Prerequisites​

Automatic Setup (Recommended)​

Manual Setup​

Commands​

Status​

Diagnose​

Architecture​

Impact​

Deps​

Unused​

Troubleshoot​

Agents​

@source-scout​

@impact-investigator​

@dependency-detective​

Hooks​

System Prompt Hook​

Context Preservation Hook​

Troubleshooting​

Quick Diagnostics​

Common Errors​

MCP Server Issues​

Step-by-Step Diagnostics​

Getting Help​

Advanced Usage​

Parallel API Execution​

Available API Methods​

Related Documentation​

Overview

Installation

Prerequisites

Automatic Setup (Recommended)

Manual Setup

Commands

Status

Diagnose

Architecture

Impact

Deps

Unused

Troubleshoot

Agents

@source-scout

@impact-investigator

@dependency-detective

Hooks

System Prompt Hook

Context Preservation Hook

Troubleshooting

Quick Diagnostics

Common Errors

MCP Server Issues

Step-by-Step Diagnostics

Getting Help

Advanced Usage

Parallel API Execution

Available API Methods

Related Documentation