Copilot CLI Plugin

The Constellation plugin for GitHub Copilot supercharges your AI-assisted development workflow with deep codebase understanding. It provides contextual skills 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
2 Hooks	Session-start guidance and search-tool nudges toward `code_intel`

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:}
1. Add the Constellation marketplace:
```
copilot plugin marketplace add ShiftinBits/constellation-copilot
```
2. Install from the marketplace using <plugin>@<marketplace>:
```
copilot plugin install constellation@constellation-plugins
```
Configure authentication:
_{Enter the following in your terminal:}
```
npx @constellationdev/cli 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 `const 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 Analysis

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: const 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.

Hooks

The plugin includes two hooks that guide Copilot toward using Constellation's code intelligence. Both hooks are implemented in Node.js (hooks/inject.js and hooks/bash.js) and ship with both bash and powershell commands so they run on macOS, Linux, and Windows. Each hook exits as a no-op unless CONSTELLATION_ACCESS_KEY is set and starts with ak:.

Code Intel Preference Hook

Event: sessionStart · Script: hooks/inject.js

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 · Script: hooks/bash.js

Purpose: Guides Copilot toward semantic search when about to invoke a text-search tool.

Behavior:

Fires when Copilot is about to call grep, rg, glob, or awk directly, or run a bash command containing grep/rg/glob/awk/findstr
Emits a one-line reminder that code_intel should be the first choice for symbol/structure queries
Stays silent for all other tools and for text-only searches that legitimately need literal matching

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 `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
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 const && 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"],
      "env": {
         "CONSTELLATION_ACCESS_KEY": "${CONSTELLATION_ACCESS_KEY}",
      }
    }
  }
}

Step-by-Step Diagnostics

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

Deps​

Unused​

Troubleshooting​

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 Analysis

Deps

Unused

Troubleshooting

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