GitHub Copilot Plugin

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

Source: github.com/ShiftinBits/constellation-copilot

Overview

Feature	Description
7 Skills	Contextual knowledge loaded automatically based on your questions
3 Agents	Codebase exploration, risk assessment, and dependency analysis
2 Hooks	Intelligent tool guidance and context preservation

Installation

Prerequisites

GitHub Copilot subscription (CLI or VS Code)
A Constellation account
Constellation CLI utility installed
A project previously indexed in Constellation

Quick Start

Install the plugin from GitHub:
_{Enter the following in your terminal:}
```
copilot plugin install ShiftinBits/constellation-copilot
```
Configure authentication:
_{Enter the following in your terminal:}
```
constellation auth
```
Verify the connection:
_{Enter the following in Copilot:}
```
/constellation:status
```

Uninstall

_{Enter the following in your terminal:}

copilot plugin uninstall constellation

Skills

Copilot automatically activates specialized analysis based on your questions. You don't need to invoke them explicitly — they load contextual knowledge when relevant topics come up.

Status

/constellation:status

Check API connectivity and project indexing status.

> /constellation:status

Status: Connected /
   - API Connection: Active
   - Authentication: Valid
   - Project Access: Confirmed
   - Last Indexed: 2026-04-07 at 22:42:17 UTC
   - Response Time: 569ms

The Constellation code intelligence service is running and fully operational.

If issues are detected, the skill provides specific error codes and remediation steps. For detailed diagnostics, use the diagnose skill.

Diagnose

Quick health check for Constellation connectivity and authentication.

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 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

Get a high-level overview of your codebase structure.

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

Analyze the blast radius before changing a symbol.

Triggers when you ask about: impact of changes, blast radius, risk assessment

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

Map dependencies or find what depends on a file.

Triggers when you ask about: file dependencies, circular dependencies, module coupling

Dependencies:

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:

Dependents (7):
├── src/controllers/payment.controller.ts
├── src/controllers/checkout.controller.ts
├── src/services/order.service.ts
└── ... 4 more

Unused

Find orphaned exports and dead code.

Triggers when you ask about: dead code, orphaned exports, unused functions

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.

Troubleshooting

Diagnose Constellation issues with error code reference.

Triggers when you encounter: error codes, debugging, connection problems

Error: AUTH_ERROR

Cause: Access key is missing, invalid, or expired.

Quick Fixes:
1. Run: constellation auth
2. Verify CONSTELLATION_ACCESS_KEY environment variable
3. Check key hasn't been revoked in dashboard

Still stuck? Ask for a full health check with the diagnose skill.

Agents

Copilot agents are specialized 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"

Example:

You: "Rename AuthService to AuthenticationService"
Copilot: "Before renaming, let me analyze the potential impact..."
[Launches impact-investigator agent]

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

Hooks

The plugin includes two hooks that guide Copilot toward using Constellation's code intelligence and preserve context across the session.

Code Intel Preference Hook

Event: sessionStart

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

Behavior:

Injects a prompt that tells Copilot 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 Copilot starts — no user interaction required

Search Nudge Hook

Event: preToolUse

Purpose: Guides Copilot toward semantic search when appropriate.

Behavior:

Triggers when Copilot is about to use Grep or Glob
Reminds Copilot 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

Troubleshooting

Quick Diagnostics

Ask Copilot to run a health check:

Check Constellation connectivity

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 Copilot 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
Skills not activating	Plugin not loaded	Restart the CLI/editor or reinstall the plugin
Changes not taking effect	Plugin cached	Uninstall and reinstall: `copilot plugin uninstall constellation && copilot plugin install ShiftinBits/constellation-copilot`

MCP Server Issues

If you see MCP connection errors:

Restart Copilot - 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"]
    }
  }
}

Step-by-Step Diagnostics

Run health check:
```
/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 writing 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`

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
GitHub Copilot Documentation - Official GitHub Copilot docs

Overview​

Installation​

Prerequisites​

Quick Start​

Uninstall​

Skills​

Status​

Diagnose​

Architecture​

Impact​

Deps​

Unused​

Troubleshooting​

Agents​

source-scout​

impact-investigator​

dependency-detective​

Hooks​

Code Intel Preference Hook​

Search Nudge 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

Uninstall

Skills

Status

Diagnose

Architecture

Impact

Deps

Unused

Troubleshooting

Agents

source-scout

impact-investigator

dependency-detective

Hooks

Code Intel Preference Hook

Search Nudge 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