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
4 Hooks	Intelligent tool guidance and context preservation

Installation

Prerequisites

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

Quick Start

Add the Constellation Plugin Marketplace to Claude Code
_{Enter the following in Claude Code:}
```
/plugin marketplace add ShiftinBits/constellation-claude
```
Install the Constellation Plugin
_{Enter the following in Claude Code:}
```
/plugin install constellation@constellation-plugins
```
Reload Plugins
_{Enter the following in Claude Code:}
```
/reload-plugins
```
Configure authentication using an Access Key
_{Enter the following in your terminal:}
```
npx @constellationdev/cli auth
```
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 four hooks that guide Claude toward using Constellation's code intelligence and preserve context across the session.

SessionStart Hook

Purpose: Establishes code_intel as the primary tool for code understanding at the start of every session.

Behavior:

Injects a prompt that tells Claude to use code_intel as its default tool for structural code questions
Establishes the mental model: code_intel for structure (definitions, callers, dependencies), Grep for literal text
Runs automatically when Claude Code starts — no user interaction required

SubagentStart Hook

Purpose: Extends Constellation awareness to built-in Explore and Plan subagents.

Behavior:

Matches Explore and Plan subagent types
Injects instructions to prefer code_intel over Grep/Glob for structural queries
Built-in subagents don't inherit plugin context, so this hook bridges the gap

PreToolUse Hook (Grep/Glob)

Purpose: Guides Claude toward semantic search when appropriate.

Behavior:

Triggers when Claude is about to use Grep or Glob
Reminds Claude that code_intel answers structural questions (symbol definitions, callers, dependencies) in one call vs. 3-5 text searches
Allows Grep/Glob for literal text searches (error messages, config values) or when code_intel is unavailable

PreCompact Hook

Purpose: Preserves Constellation context during conversation compaction.

Behavior:

Triggers on any context compaction event
Instructs Claude to retain: the code_intel primary tool directive, architectural insights, dependency relationships, and impact analysis results discovered during the session

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:

npx @constellationdev/mcp@latest --version

Check plugin configuration in .mcp.json:

{
  "mcpServers": {
    "constellation": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@constellationdev/mcp@latest"]
    }
  }
}

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

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​

SubagentStart Hook​

PreToolUse Hook (Grep/Glob)​

PreCompact 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

Quick Start

Commands

Status

Diagnose

Architecture

Impact

Deps

Unused

Agents

source-scout

impact-investigator

dependency-detective

Skills

constellation-troubleshooting

Hooks

SessionStart Hook

SubagentStart Hook

PreToolUse Hook (Grep/Glob)

PreCompact 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