https://github.com/shiftinbits/constellation-claude
Codebase Understanding for Claude Code
https://github.com/shiftinbits/constellation-claude
agentic-ai agentic-ai-development ai ai-driven-development claude claude-code claude-code-plugin claude-code-skills code code-analysis mcp software-development
Last synced: 17 days ago
JSON representation
Codebase Understanding for Claude Code
- Host: GitHub
- URL: https://github.com/shiftinbits/constellation-claude
- Owner: ShiftinBits
- License: agpl-3.0
- Created: 2025-12-25T15:55:17.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-05-01T05:16:40.000Z (about 1 month ago)
- Last Synced: 2026-05-01T07:17:47.382Z (about 1 month ago)
- Topics: agentic-ai, agentic-ai-development, ai, ai-driven-development, claude, claude-code, claude-code-plugin, claude-code-skills, code, code-analysis, mcp, software-development
- Language: JavaScript
- Homepage: https://docs.constellationdev.io/plugins/claude-code/
- Size: 78.1 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# 
Constellation Plugin for Claude Code
[](https://github.com/ShiftinBits/constellation-mcp) [](LICENSE)
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 ` | Analyze blast radius before changing a symbol |
| `/constellation:deps [--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](https://app.constellationdev.io))
2. **Project indexed** in Constellation
3. **Access key** configured
### Quick Start
```bash
# Add the marketplace to Claude
claude plugin marketplace add ShiftinBits/constellation-claude
# Install the Constellation Claude plugin
claude plugin install constellation@constellation-plugins
```
## 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
- [Constellation Documentation](https://docs.constellationdev.io) — Full platform documentation
- [MCP Server](https://github.com/shiftinbits/constellation-mcp) — Underlying MCP server
- [Claude Code Plugins](https://docs.anthropic.com/claude-code/plugins) — Plugin development guide
## License
GNU Affero General Public License v3.0 (AGPL-3.0)
Copyright © 2026 ShiftinBits Inc.
See [LICENSE](LICENSE) file for details.