Constellation Plugin for Claude Code

MCP Server License: AGPL-3.0

While Constellation's MCP server provides raw code intelligence capabilities, this plugin enhances your Claude Code experience with:

Feature Benefit
Slash Commands Quick access to common workflows
Contextual Skills Claude automatically loads relevant knowledge — including proactive impact analysis before risky changes
Safety Hooks Nudges Claude toward code_intel over text search at session start, in subagents, and before Grep/Glob/Bash search commands

Features

Commands

Execute powerful analysis with simple slash commands:

Command Description
/constellation:status Check API connectivity and project indexing status
/constellation:diagnose Quick health check for connectivity and authentication
/constellation:impact <symbol> <file> Analyze blast radius before changing a symbol
/constellation:deps <file> [--reverse] Map dependencies or find what depends on a file
/constellation:unused Discover orphaned exports and dead code
/constellation:architecture Get a high-level overview of your codebase structure

Skills

Claude automatically activates specialized knowledge based on your questions:

Skill Triggers When You Ask About...
constellation-troubleshooting Error codes, connectivity issues, debugging problems
impact-analysis Renaming, refactoring, deleting, or moving symbols/files; "what would break if...", "is X dead code", "what depends on X"

Example Trigger:

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

Hooks

Event hooks enable intelligent, transparent assistance:

Hook Event (matcher) Behavior
Session Awareness SessionStart Injects code_intel MCP tool awareness at session start
Subagent Awareness SubagentStart Injects code_intel awareness into spawned subagents (built-ins like Explore/Plan don't inherit project AGENTS.md)
Search Tool Nudge PreToolUse (Grep|Glob) Reminds Claude to prefer code_intel over Grep/Glob for structural queries
Bash Search Nudge PreToolUse (Bash) Inspects the command and emits the same reminder when it starts with grep/rg/glob/awk/findstr

All hooks are gated on CONSTELLATION_ACCESS_KEY being set (no key → silent no-op, so the plugin doesn't nag in environments where Constellation isn't configured).

Installation

Prerequisites

  1. Constellation Account (see Constellation)
  2. Project indexed in Constellation
  3. Access key configured

Quick Start

# Add the marketplace to Claude
claude plugin marketplace add ShiftinBits/constellation-claude

# Install the Constellation Claude plugin
claude plugin install constellation@constellation-plugins --scope project

Usage Examples

Check Your Setup

> /constellation:status

Status: Connected
Project: my-awesome-app
Files Indexed: 1,247
Symbols: 8,932
Languages: TypeScript, JavaScript

Analyze Before Refactoring

> /constellation:impact validateUser src/auth/validator.ts

Symbol: validateUser (function)
Risk Level: MEDIUM
Files Affected: 12
Symbols Affected: 34
Test Coverage: 67%

Recommendations:
- Update unit tests in auth.spec.ts
- Check integration with UserController

Find Dead Code

> /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)
...

Understand Dependencies

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

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

No circular dependencies detected.

Troubleshooting

Common Issues

Issue Solution
AUTH_ERROR Check CONSTELLATION_ACCESS_KEY is set correctly, use constellation auth CLI command to set
PROJECT_NOT_INDEXED Run constellation index --full in your project
Commands not appearing Restart Claude Code or check plugin path

Documentation

License

GNU Affero General Public License v3.0 (AGPL-3.0)

Copyright © 2026 ShiftinBits Inc.

See LICENSE file for details.