Agent Plugin

The Constellation Agent Plugin packages Constellation's code intelligence for any client that implements the open, vendor-neutral Agent Plugins specification. One plugin bundles the Constellation MCP server with contextual skills that teach your agent when and how to use it, without tying you to a specific AI coding tool.

Source: github.com/ShiftinBits/constellation-agent-plugin

Overview

Feature	Description
MCP Server	The constellation server exposes the code_intel tool for querying your code graph
6 Skills	Contextual knowledge for status checks, architecture overviews, dependency analysis, dead-code discovery, impact analysis, and troubleshooting, loaded automatically when relevant

Because the Agent Plugins specification defines skills and MCP configuration as its portable components, this plugin has no client-specific commands or hooks. Skills cover the same workflows: instead of a slash command, you ask in natural language and the matching skill activates. If your tool has a dedicated Constellation plugin (see Official Plugins), prefer that for the deepest integration; use this plugin everywhere else.

Installation

Prerequisites

• An AI agent that supports the Agent Plugins specification
• A Constellation account
• Constellation CLI utility installed
• A project previously indexed in Constellation

Quick Start

1. Install the plugin

   Installation steps vary by client; point yours at the plugin repository or a local clone of it.

   git clone https://github.com/ShiftinBits/constellation-agent-plugin.git

2. Configure authentication using an Access Key

   _{Enter the following in your terminal:}

   npx @constellationdev/cli auth

   The MCP server reads CONSTELLATION_ACCESS_KEY from the process environment, so the key must be present in the environment your agent client launches from.

3. Verify the connection

   Ask your agent:

   Is Constellation working?

   The constellation-status skill activates and runs a connectivity check.

Skills

Skills provide contextual knowledge that your agent automatically loads based on your questions. You don't need to invoke them explicitly.

constellation-status

Activates when you ask:

• "Is Constellation working?", "check Constellation status"
• "Run a health check", "is the project indexed?"

Provides:

• A quick ping for connectivity and authentication
• A full health check reporting primary language and indexed file/symbol counts

> Is Constellation working?

Constellation Health Check
===========================
MCP Server:  OK
API Auth:    OK
Project:     TypeScript project
Index:       1,247 files, 8,932 symbols

All systems operational.

architecture-overview

Activates when you ask:

• "Explain the architecture", "how is this project structured?"
• "What languages are used?", "give me an overview of this codebase"

Provides:

• Primary language, frameworks, and total file/symbol counts
• Language distribution and symbol breakdown
• Dependency hotspots, the most connected hub files in the codebase

> How is this project structured?

Primary Language: TypeScript
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%)

Dependency Hotspots:
├── src/services/user.service.ts (14 in / 6 out)
├── src/models/index.ts (11 in / 2 out)
└── src/utils/currency.ts (9 in / 1 out)

dependency-analysis

Activates when you ask:

• "What does X import?", "what depends on X?"
• "Are there circular dependencies?"

Provides:

• Forward analysis: internal dependencies, external packages, and circular dependency detection
• Reverse analysis: every file that depends on the one you name

> What does src/services/payment.service.ts depend on?

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

No circular dependencies detected.

dead-code

Activates when you ask:

• "Find dead code", "unused exports", "orphaned code"
• "What code is never used?"

Provides:

• A scan for exported symbols that are never imported, grouped by file
• Orphan reasons with confidence scores, plus guidance to confirm with usage tracing before deleting

> Find unused functions in this codebase

Found 7 orphaned functions:
├── src/utils/legacy.ts
│   ├── formatLegacyDate
│   └── parseLegacyConfig
├── src/helpers/deprecated.ts
│   └── oldValidation
...

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

impact-analysis

Activates when you discuss:

• Renaming, refactoring, deleting, or moving a symbol or file
• Changing a function signature or exported interface
• Questions like "what would break if...", "is X safe to remove", "what depends on X"

Provides:

• Guidance on when to call api.impactAnalysis and how to pair it with getDependencies, getDependents, and traceSymbolUsage for broader context
• Risk-interpretation table (Low / Medium / High / Critical) keyed off breakingChangeRisk.riskLevel, file count, export status, and test exposure
• A standard reporting format (symbol, risk, scope, top dependents, test exposure, recommendation)
• Text-search fallback procedure when the MCP tool is unavailable or the symbol can't be found

Example interaction:

You: "Rename AuthService to AuthenticationService"
Agent: "Before renaming, let me analyze the potential impact..."
[impact-analysis skill activates, runs api.impactAnalysis,
 reports risk + dependents before any edits are made]

constellation-troubleshooting

Activates when you encounter:

• Error codes (AUTH_ERROR, PROJECT_NOT_INDEXED, MCP_UNAVAILABLE, etc.)
• Connectivity or authentication issues
• MCP server problems or unexpected empty results

Provides:

• Quick diagnosis flowchart for common issues
• MCP server troubleshooting steps
• Error code explanations with specific fixes (full reference bundled with the skill)
• Recovery procedures for each error type

Troubleshooting

Common Errors

Error	Cause	Solution
MCP_UNAVAILABLE	MCP server not running	Restart your agent client to reinitialize connections
AUTH_ERROR	Missing or invalid Access key	Run const auth; ensure CONSTELLATION_ACCESS_KEY is set in your client's environment
PROJECT_NOT_INDEXED	Project needs indexing	Run const 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 the code_intel tool is unavailable:

1. Restart your agent client - MCP connections initialize at startup

2. Verify MCP server can run:

   npx @constellationdev/mcp@latest --version

3. Check the plugin's mcp.json:

   {
   	"$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
   	"mcpServers": {
   		"constellation": {
   			"type": "stdio",
   			"command": "npx",
   			"args": ["-y", "@constellationdev/mcp@latest"]
   		}
   	}
   }

   Note there is no env block: the Agent Plugins specification only expands ${PLUGIN_ROOT} and ${PLUGIN_DATA} placeholders, so the server inherits CONSTELLATION_ACCESS_KEY from your client's process environment.

Getting Help

• Check the Constellation Documentation
• Report issues on GitHub

Advanced Usage

Parallel API Execution

The Constellation API uses Code Mode, which allows your agent to write JavaScript that executes multiple API calls in parallel. This makes complex analyses significantly faster:

// 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
Utility	ping

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

Related Documentation

• Official Plugins - Client-specific plugins with commands and hooks
• MCP Server - For direct MCP integration without the plugin
• CLI Tool - For indexing your codebase
• Agent Plugins Specification - The open packaging standard this plugin targets