Cursor Plugin

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

Source: github.com/ShiftinBits/constellation-cursor

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 Rules	Persistent AI guidance for code intelligence, tool preference, and context preservation
1 Hook	Session initialization that establishes code intelligence defaults

Installation

Prerequisites

Cursor installed
A Constellation account
Constellation CLI utility installed
A project previously indexed in Constellation

Quick Start

Add the Constellation Plugin Marketplace to Cursor
_{Enter the following in Cursor:}
```
/plugin marketplace add ShiftinBits/constellation-cursor
```
Install the Constellation Plugin
_{Enter the following in Cursor:}
```
/plugin install constellation@constellation-plugins
```
Reload Plugins
_{Enter the following in Cursor:}
```
/reload-plugins
```
Configure authentication using an Access Key
_{Enter the following in your terminal:}
```
constellation auth
```
Verify the connection
_{Enter the following in Cursor:}
```
/constellation:status
```

Commands

Commands are agent-executable actions invoked by typing / followed by the command name. The plugin includes 6 commands for common analysis workflows.

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.

Skills

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

constellation-troubleshooting

This skill activates automatically when the agent detects Constellation-related issues in the conversation.

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

Agents

Cursor 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

Rules

The plugin includes three .mdc rules that provide persistent AI guidance. Rules are automatically applied based on their configuration — no user action required.

code-intelligence

Always applied. Enhances the coding workflow with Constellation structural analysis. Instructs the agent to:

Run impactAnalysis() before modifying functions, classes, or interfaces
Check getDependencies() and findCircularDependencies() before adding imports
Use traceSymbolUsage() before renaming or deleting symbols
Provide architectural context using getCallGraph() and dependency analysis
Prefer searchSymbols() over Grep for finding definitions

prefer-code-intel

Applied intelligently (when the agent is about to use Grep/Glob for structural questions). Redirects structural code queries — symbol definitions, callers/callees, dependencies, impact analysis — to code_intel instead of Grep/Glob, which answers in one call what would take 3-5 text searches.

compact-preservation

Always applied. Ensures that key Constellation context survives context window compaction: the instruction that code_intel is the primary tool, and any architectural insights, dependency relationships, or impact analysis results discovered during the session.

Hooks

The plugin includes a single hook that runs at session start.

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 Cursor 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 Cursor starts — no user interaction required

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 Cursor 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 Cursor - 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": "${env:CONSTELLATION_ACCESS_KEY}"
         }
      }
   }
}

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 Cursor 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
Cursor Documentation - Official Cursor docs

Overview​

Installation​

Prerequisites​

Quick Start​

Commands​

Status​

Diagnose​

Architecture​

Impact​

Deps​

Unused​

Skills​

constellation-troubleshooting​

Agents​

source-scout​

impact-investigator​

dependency-detective​

Rules​

code-intelligence​

prefer-code-intel​

compact-preservation​

Hooks​

SessionStart 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

Skills

constellation-troubleshooting

Agents

source-scout

impact-investigator

dependency-detective

Rules

code-intelligence

prefer-code-intel

compact-preservation

Hooks

SessionStart 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