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, 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
2 Skills	Contextual troubleshooting knowledge plus proactive impact analysis loaded when relevant
4 Hooks	Nudge Claude toward `code_intel` over text search at session start, in subagents, and before Grep/Glob/Bash search commands

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 `const 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.

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

impact-analysis

Activates when you discuss:

Renaming, refactoring, deleting, or moving a symbol or file
Changing a function signature or exported interface
Removing code suspected to be dead
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, file count, public-API exposure, and test coverage
A standard reporting format (symbol, risk, scope, top dependents, coverage, recommendation)
Grep-based fallback procedure when the MCP tool is unavailable or the symbol can't be found

Example interaction:

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

Hooks

The plugin registers three Claude Code hook events with four matchers in total. All hooks shell out to small Node scripts in the plugin's hooks/ directory and emit hookSpecificOutput.additionalContext to inject reminders into Claude's context. Every hook is gated on the CONSTELLATION_ACCESS_KEY environment variable being set — without a key, the hooks are silent no-ops, so the plugin doesn't nag in environments where Constellation isn't configured.

SessionStart Hook

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

Behavior:

Injects context telling 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 spawned subagents.

Behavior:

Fires for every subagent spawn (built-ins like Explore and Plan, plus any user-defined agents)
Injects the same code_intel guidance as SessionStart
Built-in subagents don't inherit project-level AGENTS.md, so this hook bridges the gap

PreToolUse Hook — Grep/Glob matcher

Purpose: Guides Claude toward semantic search when about to invoke a text-search tool.

Behavior:

Triggers when Claude is about to use the Grep or Glob tool
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

PreToolUse Hook — Bash matcher

Purpose: Catches the same class of search performed via the shell rather than the dedicated tools.

Behavior:

Inspects tool_input.command for any Bash invocation
Emits the same code_intel-first reminder when the command starts with grep, rg, glob, awk, or findstr (and isn't part of a pipeline — pipeline usage is intentionally exempted, as those typically chain output rather than search the codebase)
Stays silent for all other shell commands

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 `const auth`
`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 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"],
      "env": {
         "CONSTELLATION_ACCESS_KEY": "${CONSTELLATION_ACCESS_KEY}",
      }
    }
  }
}

Step-by-Step Diagnostics

Run health check:
```
/constellation:diagnose
```
Check connectivity:
```
/constellation:status
```
Verify CLI status:
```
const status
```
Re-index if needed:
```
const 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​

Skills​

constellation-troubleshooting​

impact-analysis​

Hooks​

SessionStart Hook​

SubagentStart Hook​

PreToolUse Hook — Grep/Glob matcher​

PreToolUse Hook — Bash matcher​

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

Skills

constellation-troubleshooting

impact-analysis

Hooks

SessionStart Hook

SubagentStart Hook

PreToolUse Hook — Grep/Glob matcher

PreToolUse Hook — Bash matcher

Troubleshooting

Quick Diagnostics

Common Errors

MCP Server Issues

Step-by-Step Diagnostics

Getting Help

Advanced Usage

Parallel API Execution

Available API Methods

Related Documentation