Claude Code Plugin

The Constellation plugin for Claude Code supercharges your AI-assisted development workflow with deep codebase understanding. It provides slash commands, contextual skills, proactive agents, and safety hooks that leverage Constellation's code intelligence platform.

Source: github.com/ShiftinBits/constellation-claude

Overview

Feature	Description
6 Commands	Quick access to common analysis workflows
1 Skill	Contextual troubleshooting knowledge loaded when issues occur
3 Agents	Proactive codebase exploration, risk assessment, and dependency analysis
3 Hooks	Silent availability detection and intelligent tool guidance

Installation

Prerequisites

Claude Code installed
A Constellation account
Constellation CLI utility installed
A project perviously indexed in Constellation

Quick Start

Add the Constellation Plugin Marketplace to Claude Code
_{Enter the following in Claude Code:}
```
/plugin marketplace add https://github.com/ShiftinBits/constellation-claude
```
Install the Constellation Plugin
_{Enter the following in Claude Code:}
```
/plugin install constellation@constellation-plugins
```
Exit Claude Code
_{Enter the following in Claude Code:}
```
/exit
```
Configure authentication using an Access Key
_{Enter the following in your terminal:}
```
constellation auth
```
Restart Claude Code
_{Enter the following in your terminal:}
```
claude
```
Verify the connection
_{Enter the following in Claude Code:}
```
/constellation:status
```

Commands

Status

/constellation:status

Check API connectivity and project indexing status.

> /constellation:status

⏺ Status: Connected ✓

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

  Project Structure:
  - Modules: 3 (average size: 20 files)
  - File Types: 26 library files, 15 application files, 15 utility files, 4 config files
  - Symbol Distribution: 368 constants, 305 properties, 140 functions, 62 interfaces, 56 methods, 36 types, 34 variables, 15 classes
  - Dependencies: 85 internal connections, 13 external packages
  - Maintainability Score: 75/100

  Most Connected Files:
  1. src/registry/McpToolDefinition.interface.ts (17 outgoing connections)
  2. src/client/constellation-client.ts (8 outgoing connections)
  3. src/config/config-manager.ts (6 outgoing connections)

If issues are detected, the command provides specific error codes and remediation steps. For detailed diagnostics, use /constellation:diagnose.

Diagnose

/constellation:diagnose

Quick health check for Constellation connectivity and authentication.

> /constellation:diagnose

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

All systems operational.

When issues are detected:

> /constellation:diagnose

Constellation Health Check
===========================
MCP Server:  OK
API Auth:    FAILED

Issue: Authentication failed - Access key missing or invalid.

Quick Fix: Run `constellation auth` to configure credentials.

Architecture

/constellation:architecture

Get a high-level overview of your codebase structure.

> /constellation: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

/constellation:impact <symbol> <file>

Analyze the blast radius before changing a symbol.

Arguments:

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

> /constellation: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

/constellation: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):

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

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

No circular dependencies detected.

Dependents (with --reverse):

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

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

Unused

/constellation:unused [--kind]

Find orphaned exports and dead code.

Arguments:

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

> /constellation:unused --kind function

Found 7 orphaned functions:
├── src/utils/legacy.ts
│   ├── formatLegacyDate (line 23)
│   └── parseLegacyConfig (line 45)
├── src/helpers/deprecated.ts
│   └── oldValidation (line 12)
├── src/services/unused.service.ts
│   ├── deprecatedMethod (line 34)
│   ├── unusedHelper (line 56)
│   └── legacyTransform (line 78)
└── src/utils/temp.ts
    └── debugLogger (line 8)

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

Agents

Claude Code agents are autonomous assistants that proactively help with specific tasks. The plugin includes three agents that activate based on your conversation.

source-scout

Purpose: Codebase exploration, understanding, and intelligent navigation.

Triggers when you ask things like:

"What does this codebase do?"
"Where is the authentication logic?"
"Find all places that use the UserService"
"How does the payment processing work?"
"Show me the API endpoints in this project"

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

Key capabilities:

Symbol search with filtering by type (class, function, interface, etc.)
Call graph analysis (who calls what)
Dependency chain tracing
Architecture overview with metrics

impact-investigator

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

Triggers when you say things like:

"I'm going to rename UserAuthService to AuthenticationService"
"Let's delete this unused code"
"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)
Calculates blast radius and scope
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.

Triggers when you say things like:

"I need to import UserService into AuthService"
"I'm worried our modules are too tightly coupled"
"Before I submit this PR, are there any dependency issues?"

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

Skills

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

constellation-troubleshooting

Activates when you encounter:

Error codes (AUTH_ERROR, PROJECT_NOT_INDEXED, MCP_UNAVAILABLE, etc.)
Connectivity or authentication issues
MCP server problems ("Failed to reconnect")
Unexpected results or empty queries

Provides:

Quick diagnosis flowchart for common issues
MCP server troubleshooting steps
Error code explanations with specific fixes
Configuration validation guidance
Recovery procedures for each error type

Hooks

The plugin includes three hooks that enhance Claude's behavior transparently.

SessionStart Hook

Purpose: Silently checks Constellation availability when a session begins.

Behavior:

Tests connectivity by calling the Constellation API
If available: Claude uses Constellation transparently for code navigation
If unavailable: Claude silently falls back to traditional tools (Grep, Glob, Read)
Never mentions Constellation status unless explicitly asked

This enables graceful degradation without interrupting your workflow.

PreToolUse Hook (Grep)

Purpose: Guides Claude toward semantic search when appropriate.

Behavior:

When Claude is about to use Grep for symbol search, suggests using Constellation's searchSymbols instead
Allows Grep for literal text searches (error messages, comments, config values)
Respects session availability - uses Grep if Constellation is unavailable

PreToolUse Hook (Write/Edit)

Purpose: Encourages impact analysis before significant code modifications.

Behavior:

For significant changes (renaming, deleting, restructuring): Suggests running impact analysis first
For minor changes (formatting, comments, small fixes): Proceeds directly
Respects session availability - proceeds without mention if Constellation is unavailable

Troubleshooting

Quick Diagnostics

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

/constellation: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 Claude Code 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 "Failed to reconnect to plugin:constellation:constellation":

Restart Claude Code - MCP connections initialize at startup
Verify MCP server can run:
```
mcp-constellation --version
```

Check plugin configuration in .mcp.json:

{
  "mcpServers": {
    "constellation": {
      "type": "stdio",
      "command": "mcp-constellation"
    }
  }
}

Step-by-Step Diagnostics

Run health check:
```
/constellation:diagnose
```
Check connectivity:
```
/constellation: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 Claude 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`

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

MCP Server - For direct MCP integration without the plugin
CLI Tool - For indexing your codebase
Claude Code Documentation - Official Claude Code docs

Overview​

Installation​

Prerequisites​

Quick Start​

Commands​

Status​

Diagnose​

Architecture​

Impact​

Deps​

Unused​

Agents​

source-scout​

impact-investigator​

dependency-detective​

Skills​

constellation-troubleshooting​

Hooks​

SessionStart Hook​

PreToolUse Hook (Grep)​

PreToolUse Hook (Write/Edit)​

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

Quick Start

Commands

Status

Diagnose

Architecture

Impact

Deps

Unused

Agents

source-scout

impact-investigator

dependency-detective

Skills

constellation-troubleshooting

Hooks

SessionStart Hook

PreToolUse Hook (Grep)

PreToolUse Hook (Write/Edit)

Troubleshooting

Quick Diagnostics

Common Errors

MCP Server Issues

Step-by-Step Diagnostics

Getting Help

Advanced Usage

Parallel API Execution

Available API Methods

Related Documentation