Cursor Plugin

The Constellation plugin for Cursor supercharges your AI-assisted development workflow with deep codebase understanding. It provides commands, contextual skills, hooks, and rules 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
4 Hooks	Session/subagent initialization, MCP auto-approval, and intelligent search-tool steering
2 Rules	Persistent AI guidance for code intelligence and context preservation

Installation

Prerequisites

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

Quick Start

Add the Constellation Plugin to your team's Cursor configuration

Use this flow to import the Constellation Cursor plugin GitHub repository as a team marketplace:

Starting from the Cursor Dashboard:
1. Go to Dashboard -> Settings -> Plugins.
2. In Team Marketplaces, click Import.
3. Paste the Constellation Cursor plugin GitHub repo URL and continue. https://github.com/ShiftinBits/constellation-cursor
4. Review the parsed plugins. Optionally set Team Access groups, then continue.
5. Set the marketplace name as Constellation Plugins.
6. Optionally set the description as Constellation plugins for Cursor.
7. Save all changes.
Each developer must configure Constellation authentication
_{Enter the following in your terminal:}
```
npx @constellationdev/cli auth
```
Verify the connection
_{Enter the following in Cursor Agent chat:}
```
/constellation-status
```

Commands

Commands are defined as markdown files in commands/ (each with name + description frontmatter). Invoke them with /constellation-<name>:

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 live under skills/ as SKILL.md files. Cursor can load them automatically when your question matches the skill description.

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

Hooks

Configured in hooks/hooks.json. All hooks are implemented as cross-platform Node.js scripts and gate their work on CONSTELLATION_ACCESS_KEY being set (starting with ak:):

Event	Implementation	Behavior
`sessionStart`	`node ./hooks/inject.js sessionStart`	Injects `code_intel` awareness at the start of a session
`subagentStart`	`node ./hooks/inject.js subagentStart` (matcher: `.*`)	Same guidance as session start, applied to Task subagents
`beforeMCPExecution`	`node ./hooks/allow-constellation-mcp.js` (matcher: `constellation`)	Auto-allows `code_intel` MCP calls; defers approval for other tools
`preToolUse`	`node ./hooks/pre-tool-steer.js` (matcher: `Shell`, `Grep`, `Glob`)	Nudges toward `code_intel`. Fires for `Grep`/`Glob` always, and for `Shell` only when the command contains `grep`/`rg`/`glob`/`awk`/`findstr`

Rules

The plugin includes two .mdc rules that provide persistent AI guidance. Rules are automatically applied — 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

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.

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 `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
Commands or skills not appearing	Plugin not loaded	Restart Cursor or verify the plugin is installed and paths resolve

MCP Server Issues

If you see "Failed to reconnect to 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:
```
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 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​

Hooks​

Rules​

code-intelligence​

compact-preservation​

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

Hooks

Rules

code-intelligence

compact-preservation

Troubleshooting

Quick Diagnostics

Common Errors

MCP Server Issues

Step-by-Step Diagnostics

Getting Help

Advanced Usage

Parallel API Execution

Available API Methods

Related Documentation