Claude Code Plugin
The Constellation plugin for Claude Code gives Claude a structural understanding of your codebase and keeps it in view at the moments it matters. Claude learns to reach for Constellation's code graph instead of text search, sees the blast radius of a change before and after it makes it, and you get an interactive pane, index status and compact results right inside your session.
Source: github.com/ShiftinBits/constellation-claude
Overview
| Feature | What it does |
|---|---|
/constellation pane | Status, diagnostics, dependencies, dead code, a symbol explorer and adoption stats in one interactive pane, without starting a model turn |
| Analysis commands | Six /constellation:* commands you run to have Claude do a common analysis and answer in the conversation; Claude never runs them on its own |
| Skills | Troubleshooting knowledge and proactive impact analysis that Claude loads on its own when they are relevant |
| Output style | An opt-in Code Intelligence output style that has Claude check impact, dependencies and usages with code_intel as part of every response |
| Code intelligence hooks | Steer Claude toward code_intel for structural questions, add a graph hint to symbol searches, and count how often Claude uses the graph |
| Impact features | An optional gate before edits to high-impact files, a one-line impact summary after turns that change files, and an impact section for pull requests |
| In-session indicators | Index freshness above the prompt, compact code_intel rows in the transcript, and a sign-in and indexing band for projects that are not ready yet |
Installation
Prerequisites
- Claude Code 2.1.304 or later.
- A Constellation account
- The Constellation CLI (
constellation, or its shorter aliasconst) - A project indexed in Constellation
Quick Start
-
Install the plugin
Enter the following in your terminal:claude plugin install constellation --marketplace ShiftinBits/constellation-claudeOr, from inside Claude Code, add the marketplace, install the plugin and reload:
/plugin marketplace add ShiftinBits/constellation-claude/plugin install constellation@constellation-plugins --scope project/reload-plugins -
Sign in with an access key
Enter the following in your terminal:const authThis signs you in through the browser and stores
CONSTELLATION_ACCESS_KEY, the same credential the CLI and every other Constellation integration use. You can also press Sign in on the onboarding band that appears above the prompt when no key is set. -
Verify the connection
Enter the following in Claude Code:/constellation:status -
Open the Constellation pane
Enter the following in Claude Code:/constellation
:::tip Keep the plugin up to date
Auto-update is off by default for third-party marketplaces. Turn it on for this one under /plugin → Marketplaces.
:::
The /constellation Pane
/constellation [status|diagnose|deps <file>|unused [kind]|explore [query]|stats]
Type /constellation to open Constellation's interactive pane. It starts no model turn, so it works even while Claude is in the middle of one. With no argument it opens on the Status tab; name a tab to open it directly:
/constellation # Status tab
/constellation diagnose # health check
/constellation deps src/app.ts # a file's dependencies and dependents
/constellation unused function # unused exports of one kind
/constellation explore AuthService # search for a symbol
/constellation stats # code_intel adoption counts
| Tab | Key | Shows |
|---|---|---|
| Status | 1 | Connection and authentication, and the project |
| Diagnose | 2 | A health check of the connection, authentication and the project's index: whether it is indexed, its languages, symbol and file counts, and the indexed branch |
| Deps | 3 | A file's dependencies or dependents (switch direction with the selector); press a row to follow that file |
| Unused | 4 | Unused exports grouped by file, filterable by kind and loaded a page at a time; check entries and hand them off as a removal prompt in the prompt box, for you to edit and send |
| Explore | 5 | Search for a symbol, then open its details, usages, impact and (for functions, methods and generators) call graph; copy its file and line, or draft an Ask Claude prompt |
| Stats | 6 | The adoption counter for this session, today and the last 30 days |
Press r to refresh the current tab and Esc to close. The header shows the Constellation banner, then the project name with its indexed commit and age once the tab's query answers (the Stats tab shows none).
-
Project picker: run from a folder that holds several Constellation projects (such as a monorepo root), the pane lists them with when each was indexed, its languages and its file count. Press a row's number, or Enter for the first, to open it. The pick is remembered for that folder across sessions; press
p(Switch project) to choose again. -
Without a pane: where the session cannot draw a pane (for example in VS Code or a headless run), the command answers with a few lines of text instead:
✦ >_CONSTELLATION://CODE_INTEL · Unused- 2 unused exports- src/util.ts- helper · function- Legacy · class- as of 0123456 · indexed 2h agoLong answers stop after six lines with a
+N moreline, before theas ofline, so you know rows were left out. -
Stats needs no setup: the Stats tab sends no query and opens without an access key or an indexed project.
Analysis Commands
The /constellation:* commands ask Claude to run an analysis with code_intel and answer in the conversation. They are skills that only you run: Claude never invokes them on its own, and while one runs it calls code_intel directly instead of loading other skills.
Status
/constellation:status
Checks connectivity and authentication with a single ping. It does not inspect the index; use Diagnose for that.
> /constellation:status
✦ >_CONSTELLATION://CODE_INTEL · status
Connection ✓ ok
Auth ✓ ok
ℹ Run /constellation:diagnose to check the project's index.
When something is wrong, the answer is one error line with the fix, for example:
✦ >_CONSTELLATION://CODE_INTEL · status
✗ AUTH_ERROR · Your access key wasn't accepted · const auth
Diagnose
/constellation:diagnose
A health check of the MCP server, the API, authentication and the project's index.
> /constellation:diagnose
✦ >_CONSTELLATION://CODE_INTEL · diagnose
MCP server ✓ ok
API ✓ ok
Auth ✓ ok
Index ✓ ok · 1,247 files · 8,932 symbols · typescript
When issues are detected, each row shows its state (rows after a failure read · not checked), followed by the error and its fix:
> /constellation:diagnose
✦ >_CONSTELLATION://CODE_INTEL · diagnose
MCP server ✓ ok
API ✓ ok
Auth ✓ ok
Index ⚠ not indexed
✗ PROJECT_NOT_INDEXED · This project hasn't been indexed yet · const index
Architecture
/constellation:architecture
A high-level overview of your codebase: languages, symbol kinds, the most connected files and the top external packages, plus quality metrics (complexity, maintainability, test coverage) when the index has them.
> /constellation:architecture
✦ >_CONSTELLATION://CODE_INTEL · architecture
typescript · nestjs · 1,247 files · 8,932 symbols
Languages
• typescript · 892 files · 71.5%
• javascript · 312 files · 25.0%
Symbols
• function · 2,140
• class · 318
Hotspots
• src/services/user.service.ts · 14 in · 6 out
• src/models/index.ts · 11 in · 2 out
Packages
• @nestjs/common
• typeorm
Impact
/constellation:impact <symbol> [file-path]
Analyzes the blast radius before you change a symbol.
Arguments:
symbol: name of the function, class or variablefile-path(optional): path to the file that defines it, to tell apart symbols that share a name
> /constellation:impact validateUser src/auth/validator.ts
✦ >_CONSTELLATION://CODE_INTEL · impact
validateUser · function · src/auth/validator.ts:18
Risk ⚠ MEDIUM · exported and called from the auth and user modules
Scope 12 files · 9 direct dependents · exported
Tests 3 test files · 9 production files
Dependents
• login · function · src/auth/login.ts:42
• UserController · class · src/users/user.controller.ts:15
Recommendations
• Update unit tests in auth.spec.ts
• Check integration with UserController
Deps
/constellation:deps <file> [--reverse]
Maps a file's dependencies, or with --reverse (-r) the files that depend on it.
> /constellation:deps src/services/payment.service.ts
✦ >_CONSTELLATION://CODE_INTEL · deps
src/services/payment.service.ts · 8 internal · 4 external
Internal
• src/models/payment.model.ts · Payment, PaymentStatus
• src/utils/currency.ts · formatCurrency
External
• stripe
• lodash
Cycles ✓ none
> /constellation:deps src/services/payment.service.ts --reverse
✦ >_CONSTELLATION://CODE_INTEL · deps
src/services/payment.service.ts · 7 dependent files
Dependents
• src/controllers/payment.controller.ts · PaymentService
• src/services/order.service.ts · PaymentService
ℹ Review these files before changing src/services/payment.service.ts.
A circular dependency shows as ✗ <severity> · a.ts ▸ b.ts ▸ a.ts.
Unused
/constellation:unused [kind]
Finds exports nothing imports. Filter by kind, written bare (function) or as --kind function (-k): function, class, type, interface or variable. Results are grouped by file, and recommendations for confirming and removing them follow the list.
> /constellation:unused function
✦ >_CONSTELLATION://CODE_INTEL · unused
3 unused exports · 3 function
src/utils/legacy.ts · 2
• formatLegacyDate · function · line 31 · No external references · confidence 0.9
• parseLegacyConfig · function · line 58 · No external references · confidence 0.9
src/helpers/deprecated.ts · 1
• oldValidation · function · line 20 · No external references · confidence 0.8
With nothing to report, the answer is ✓ No unused exports found.
Skills
These skills, unlike the analysis commands, are knowledge Claude loads on its own when your conversation calls for it. You never need to invoke them.
constellation-troubleshooting
Activates when you encounter:
- Error codes (
AUTH_ERROR,PROJECT_NOT_INDEXED,MCP_UNAVAILABLEand others) - Connectivity or authentication issues
- Indexing problems
- MCP server problems ("Failed to reconnect")
- A Constellation command failing
Provides:
- A quick diagnosis flow for common issues
- MCP server troubleshooting steps
- Each error code with its cause and fix
- Configuration checks and recovery procedures
impact-analysis
Activates when you discuss:
- Renaming, refactoring, deleting, moving or restructuring a symbol or file, or any other non-trivial change to existing code, even when you have already said exactly what to change
- Changing a function signature or an exported interface
- Removing code that looks dead
- Questions like "what would break if…", "is X safe to remove" or "what uses X"
Purely additive changes (a new file or function, no signature changes) usually skip it.
Provides:
- When to run
impactAnalysis, how to pair it withgetDependenciesandgetDependentsfor wider context, andtraceSymbolUsageto confirm dead code - How to read the risk: the API's own risk level leads, with these rules of thumb:
✓ LOW(fewer than 5 files, internal only, tests among the dependents),⚠ MEDIUM(5 to 15 files, or some public surface),✗ HIGH(more than 15 files, an exported API, or no impacted tests) and✗ CRITICAL(core infrastructure, security-adjacent code or hub modules) - A standard report: symbol, risk, scope, top dependents, test exposure and a recommendation
- A change you have already asked for still gets made: the dependents become the list of places to update, and the report comes with the result rather than in place of it
- Fallbacks when
code_intelfails: a text search, flagged as incomplete, when the MCP server is unavailable or onAUTH_ERRORandPROJECT_NOT_INDEXED(after pointing you to/constellation:diagnose), and a broadersearchSymbolsor a path check when the symbol is not found
Example interaction:
You: "Rename AuthService to AuthenticationService"
Claude: "Before renaming, let me analyze the potential impact..."
[impact-analysis activates, runs api.impactAnalysis,
renames it in every dependent, and reports the risk with the result]
Code Intelligence Output Style
The plugin also ships an opt-in Code Intelligence output style. Choose it under Output style in /config. It keeps Claude Code's coding instructions and adds:
- Before changing code:
impactAnalysisbefore editing a function, class or interface;getDependenciesandfindCircularDependenciesbefore adding imports;traceSymbolUsagebefore renaming or deleting. - When explaining code: call graphs and dependencies for architectural context, not only line-by-line commentary.
- When exploring:
searchSymbolsandgetArchitectureOverviewbefore text search, which is kept for literal strings, config values and log messages.
Code Intelligence Hooks
- Access key: the hooks are silent unless
CONSTELLATION_ACCESS_KEYis set and starts withak:, so the plugin never nags where Constellation isn't configured. The adoption counter is the exception: it countscode_intelcalls with or without a key. The onboarding band and the/constellationpane also work without a key, since they help you sign in. - Indexed projects only: the search reminders, the tool description guidance, the search result hint and the counting of text searches also need a
constellation.jsonin the searched directory or one of its parents. The searched directory is the call'spathfor Grep and Glob, or a shell search's path argument (under any leadingcd <dir>orgit -C <dir>), else the working directory. The tool description guidance checks the working directory. - Additive: reminders, guidance and hints are added to what a tool call already returns, so a permission decision made by another hook is kept. Subagents such as
Exploresee the same guidance. - Every account type: the hooks use only Claude Code's native plugin events, so they run in full for Team and Enterprise accounts and on machines with managed settings, where Claude Code skips a plugin's classic hooks.
- Turn it all off: disable the plugin from
/plugin, start Claude Code with--safe-mode, or setdisableAllHooksin your settings. Individual features have their own options.
| Hook | Behavior |
|---|---|
| Search nudge | Reminds Claude to prefer code_intel before a symbol-like search with Grep or Glob, or with grep, egrep, rg, ag, ack or git grep in the shell |
| Tool description guidance | Adds a short rule to the search tools' descriptions that makes code_intel Claude's default for searching and navigating the codebase, in the main conversation and in subagents. See Tool description guidance |
| Reminder budget | Limits the search reminders. See Reminder limit |
| Search result hint | Adds one code_intel line to the result of a symbol search. See Search result hint |
| Adoption counter | Counts code_intel calls and text searches on your machine. See Adoption counter |
The plugin's other hooks drive the /constellation pane, the impact features, which can ask about or refuse an edit or a gh pr create when you turn them on, and the in-session indicators.
Reminder limit
The search reminders are rationed so they stay useful instead of repeating on every search:
- Per session: Claude gets at most
nudgeLimitreminders (default3). Only searches that would have drawn a reminder count against it. Each subagent has its own limit, because its context starts empty. - Same turn: when
code_intelwas already called earlier in the turn, a symbol search in that turn gets no reminder and uses none of the limit. The plugin's own lookups (such as the search result hint's) count as calls, so a search that draws a hint usually draws no reminder. For a subagent, the turn is its whole run. - Reset: the count starts over after
/clear, and when a session is resumed (/resume) or branched (/branch). - Not limited: the tool description guidance.
A nudgeLimit of 0 turns the search reminders off while keeping the description guidance.
Tool description guidance
In indexed projects, the plugin appends a short, constant rule to the descriptions of the Grep, Glob and Bash tools: use code_intel for symbol definitions, references, dependents, call graphs and impact, and keep text search for literal text.
- It is applied once per session. If the session starts outside an indexed project, it is added at the first turn after the working directory moves into one and then kept, so moving around never rewrites the prompt cache.
- Native macOS and Linux builds of Claude Code have no Grep or Glob tool, so there the Bash description carries the rule.
Search result hint
When Claude searches for a symbol with Grep, or with grep, egrep, rg, ag, ack or git grep in the shell, the search runs as usual and its result is kept exactly as it is. Alongside it, the plugin looks the symbol up with code_intel (the most used exact-name match, exported symbols first, with its usage count from the graph) and adds one line after the result:
✦ >_CONSTELLATION://CODE_INTEL · AuthService (class) is defined at src/auth/auth.service.ts:12, with 4 usages. Use code_intel for references, callers, and impact.
Claude learns the graph has the answer without being told off for searching. It applies to subagent searches too.
- Once per symbol: each symbol gets the hint once per project and per agent (the main conversation and each subagent), and again after
/clear,/resumeor/branch. Two searches running at once show it once. - Never in the way: the lookup starts with the search and has 2.5 seconds after the search finishes, which allows for the MCP server starting up. Past that, or on any error, the search result comes back unchanged. A symbol with no exact match is remembered, and a failed lookup (server down, sign-in needed) is not retried for a minute, so neither slows later searches.
- Skipped when
code_intelwas already called earlier in the turn, for patterns that are not symbol-like, and outside indexed projects. - Not limited by
nudgeLimit: the hint has its own once-per-symbol rule.
Turn it off with augmentGrep. For what the lookup sends, see Data Handling.
Adoption counter
The plugin counts how often Claude uses code_intel beside how often it searches text, so you can see whether Claude is really using the graph. The counts stay on your machine: they are never sent to Constellation or anywhere else.
- What counts: each
code_intelcall Claude or a subagent makes, and each search Claude or a subagent runs with Grep, Glob, orgrep,egrep,rg,ag,ackorgit grepin the shell, as symbol-like or literal by the same rules as the reminders. A search counts only wherecode_intelcould have answered it: with an access key set and inside an indexed project. - What does not: the plugin's own
code_intellookups (the search result hint, the impact features, the pane), a search another plugin runs, a call or search that was refused, and shell commands that are not searches. - Structural lookups: the percentage is
code_intelcalls out ofcode_intelcalls plus symbol-like searches. Literal searches are shown but left out, becausecode_intelcould not have answered them. - Where to see it: the Stats tab of
/constellation(or/constellation stats) shows this session, today and the last 30 days. Turn onshowAdoptionto also show the session's counts beside the spinner, for exampleSauteing · ✦ 5 code_intel / 1 grep…. - What is kept: numbers only, one entry per session per day, in the plugin's own store. Entries older than 30 days are deleted. The session's counts start over after
/clearand when a session is resumed or branched; the daily totals stay.
Impact Features
Three features use code_intel to show the blast radius of Claude's changes. All of them read dependents from the last indexed commit, so a branch with unindexed changes can show fewer or more than the working tree has, and counts can fall short where imports go through tsconfig path aliases or export * barrels. All of them fail open: an error or a slow lookup never blocks Claude.
Impact gate
Off by default. Set impactGate to act before Claude edits a file whose impact is at or above impactThreshold: high (the default) means 20 or more files depend on it directly, critical means 50 or more. The count comes from code_intel getDependents.
| Mode | Behavior |
|---|---|
off | Does nothing (default) |
ask | Sends Claude's first edit to such a file to Claude Code's own permission prompt, with the impact summary and the top dependents as the reason. Once you approve an edit to the file and it runs, later edits to it get Claude Code's own decision for the rest of the conversation. dialog and native, from earlier versions, work as ask |
require-analysis | Refuses Claude's first edit to such a file once, with the impact report as the reason, unless Claude already ran a code_intel impact query (impactAnalysis, traceSymbolUsage or getDependents) naming the file or a symbol its dependents import. The retry goes through. Use this mode for CI and headless runs, where no one can answer a prompt |
The reason leads with the risk:
HIGH risk · 25 dependents · src/core.ts · as of 0123456 · top dependents: src/auth.guard.ts, src/users.controller.ts
In ask, the prompt comes whether Claude Code would have run the edit without asking or was already going to ask, and a host program's permission callback gets the same prompt. Because the plugin asks, the prompt comes to you even in auto mode, where Claude Code's own asks go to the auto-mode classifier. A refused or failed edit leaves the file to be asked about again. Where no one can answer (a -p or SDK run with no permission callback), the edit is left to Claude Code's own decision. A failure to read the impact, or a lookup that takes more than 3 seconds, lets the edit through; in require-analysis that edit was the file's one check, so later edits to it go through as well.
Turn impact summary
On by default (turnSummary). After a turn that changed files, one line appears under Claude's answer:
✦ >_CONSTELLATION://CODE_INTEL · 3 files changed (1 new) · 12 downstream dependents (4 test files) · as of fba36d5
It counts edits made by subagents too. A file created during the turn counts as new and is not queried. Only files in one project are counted: the project of the first edited file inside one, so plan or scratch files and files in other projects are left out. A + after the count (such as 137+) means at least one changed file has 100 or more dependents, so the total is a minimum; the PR impact section marks it the same way. Only edits made with Claude Code's edit tools count, so files changed or deleted from the shell (such as with rm) are not tracked. If the lookup takes more than 2 seconds, no line is shown. The line is shown to you only; Claude does not read it.
PR impact section
When Claude runs gh pr create or gh pr new, the plugin lists the branch's changed files, their downstream dependents, the affected test files and the changed files' exported symbols that other files import:
## Impact
- **Changed files:** 2
- **Downstream dependents:** 2 (1 test file)
- **Most affected:** `src/a.test.ts`, `src/use.ts`
- **Exported symbols in use:** `makeA`, `A`
_From the code graph as of 0123456; imports through tsconfig path aliases or export * barrels may be undercounted._
Set it with prImpact:
| Mode | Behavior |
|---|---|
inform | Lets the command run and logs the section under a ✦ >_CONSTELLATION://CODE_INTEL · PR impact line (default) |
require | Refuses the first gh pr create per branch per session whose body has no ## Impact heading, with the section as the reason; Claude adds it and runs the command again, and that attempt goes through |
off | Does nothing |
Without --base, the base is the remote's default branch (origin/HEAD, else origin/main or origin/master); in a fork that is the fork's default branch, so pass --base there. A PR for another branch (--head) or repository (--repo, -R, or a GH_REPO= prefix on the command; an exported GH_REPO is not read), or a gh pr create after a cd the shell expands (~, $VAR, -), is left alone, even with require. A git or code_intel error, or a lookup that takes more than 8 seconds, lets the command run.
In-Session Indicators
Index freshness
When the index is behind your checkout or was taken at another commit, a line shows above the prompt:
✦ >_CONSTELLATION://CODE_INTEL · index 4 commits behind · indexed 2h ago
✦ >_CONSTELLATION://CODE_INTEL · index at fedcba9 · indexed 2h ago
When a ping or code_intel call fails and no index is known, the line shows the error and its next step (sign-in, setup and indexing errors appear on the onboarding band instead):
✦ >_CONSTELLATION://CODE_INTEL · ✗ <ERROR_CODE> · <next step>
Nothing is shown when the index matches HEAD, and the line steps aside while the onboarding band is up. The check runs at session start, after Claude runs a git commit, pull, checkout, merge or rebase, at the first turn after the working directory changes, and every 5 minutes; git runs locally, and only the session-start check and a move into another project ping Constellation (neither when constellation.json sets a custom apiUrl). Claude's own code_intel results also update the line. Where the session cannot draw (for example a headless run), an index that is commits behind is reported once per conversation as a log line instead.
Turn it off with showFreshness. Off, the plugin also skips the git checks and the pings behind the line.
code_intel tool rows
code_intel calls and results in the transcript get compact rows: the call row names the API methods Claude ran and the project, and the result row sums up what came back, with how long it took and the commit it came from:
✦ >_CONSTELLATION://CODE_INTEL · impactAnalysis, getDependents · constellation-core
✗ HIGH · 23 dependents · 140 ms · as of abc1234
An error shows its code, headline and next step, for example ✗ AUTH_ERROR · Your access key wasn't accepted · const auth. A running call shows running until it ends. An interrupted call, a result too large to read and a failure without an error code keep Claude Code's own row.
- Verbose: with
--verbose(or the Verbose row in/config), Claude Code's own rendering also shows under each row. - Turn them off: set
compactToolRowstofalseto keep Claude Code's own rows for everycode_intelcall.
Onboarding band
When the project isn't ready for Constellation, a band above the prompt says what is missing and offers to fix it:
✦ >_CONSTELLATION://CODE_INTEL · ⚠ setup Not signed in
Dismiss Sign in
| State | Badge | Offers |
|---|---|---|
| No access key | ⚠ setup | Sign in, which runs constellation auth |
| Access key no longer accepted | ✗ failed | Sign in |
| No Constellation project here | ⚠ setup | The const init command and a link to the web app |
| Project not registered | ✗ failed | A check of projectId in constellation.json |
| Project not indexed | ⚠ setup | Index this project, which runs constellation index --wait |
| Sign-in or indexing running | ⏱ working | The CLI's latest output line |
After a sign-in stores a new key, the plugins reload so the MCP server starts with it, and a Connected toast confirms it; a finished index shows Indexed this project. If the CLI isn't installed, the band shows how to install it. Dismiss hides that problem for the repository, across sessions; a different problem shows the band again. On Windows the band names the command to run in a terminal in place of the Sign in or Index this project button; Dismiss stays. Where the session cannot draw, the band's message is logged once, for example ✦ >_CONSTELLATION://CODE_INTEL · Not signed in · run const auth.
Options
Set options with /config (they appear under the Constellation plugin) or run claude plugin configure constellation.
| Option | Default | Effect |
|---|---|---|
nudgeLimit | 3 | Search reminders per session (and per subagent). 0 turns them off. See Reminder limit |
augmentGrep | true | Add the one-line search result hint to symbol searches |
showAdoption | false | Show the session's code_intel and symbol-search counts beside the spinner. See Adoption counter |
impactGate | off | off, ask or require-analysis (dialog and native work as ask). See Impact gate |
impactThreshold | high | The lowest impact level the gate acts on: high or critical |
turnSummary | true | Show the turn impact summary after turns that change files |
prImpact | inform | inform, require or off. See PR impact section |
showFreshness | true | Show the index freshness line above the prompt. Off, its git checks and pings stop too |
compactToolRows | true | Draw code_intel tool rows as compact Constellation rows. Off, Claude Code draws its own rows |
Data Handling
Source code is never sent to the Constellation API. The hooks module makes no network requests of its own: every code_intel query it makes goes through the plugin's MCP server, the same as Claude's own queries, and the only other network traffic is the Constellation CLI it starts when you press the onboarding band's buttons.
| Component | Reads | Sends |
|---|---|---|
| Reminders and description guidance | The tool call Claude is about to make (for Bash, the command) and whether a constellation.json exists | Nothing. They add text to Claude's context only |
Search result hint (augmentGrep) | The search pattern and the identifier in it. Never the search output | Only that identifier (for example AuthService), as a code_intel searchSymbols query through the MCP server. Nothing from the search output is sent |
Impact gate (impactGate) | The path of the file Claude is about to edit | Only the project-relative file path, to code_intel getDependents. Nothing from the file's contents |
Turn impact summary (turnSummary) | The paths of files Claude edits | Only project-relative paths, to code_intel getDependents. Nothing from the files' contents |
PR impact section (prImpact) | The gh pr create command, the PR body or body file, and the branch's changed file names from git | Only project-relative paths, to code_intel getDependents. Never the body text or file contents |
Index freshness (showFreshness) | The indexed commit (from ping and Claude's own code_intel results) and your checkout, via git rev-parse and git rev-list --count in the project root. Nothing when showFreshness is off | A ping through the MCP server at session start and when the working directory moves into another project. Nothing when showFreshness is off |
Tool rows (compactToolRows) | The code_intel call's code and cwd, and the result Claude already received | Nothing |
| Adoption counter | code_intel calls and search tool calls | Nothing. Counts never leave your machine |
| Onboarding band | Your access key, read back at the start of an interactive session from a login shell with printenv CONSTELLATION_ACCESS_KEY (on Windows, reg.exe query); looks for .git and constellation.json from the working directory up, and reads the project's constellation.json | A ping through the MCP server. Sets CONSTELLATION_ACCESS_KEY for the session and reloads all plugins after sign-in. Runs constellation auth or constellation index --wait only when you press Sign in or Index this project. The key read-back's output passes through any other plugin that hooks Claude Code's process calls |
| MCP server | Started with npx, which downloads the package from the npm registry. Reads constellation.json, the current git branch, and lines of local source files to attach snippets to results returned to Claude | Queries (symbol names, file paths, project ID, branch) to the Constellation API, plus a usage event after each code_intel call (project ID, branch, methods, estimated tokens, durations; no code). Turn usage events off with CONSTELLATION_USAGE_METRICS=false. This applies to the queries the hooks make as well |
/constellation pane | Your queries in the pane | File paths, symbol names and symbol IDs only, as code_intel queries |
The plugin keeps state in memory except for three things written to its own store under ~/.claude/plugins/store/: the project picked in the /constellation pane for a folder, the onboarding band's dismissal per repository, and the daily adoption counts (numbers only, deleted after 30 days). Git runs only through Claude Code's process call, in the project root, with the repository's fsmonitor, hooks, external diff and network fetches turned off. The only other processes are the onboarding band's key read-back, its command -v constellation lookup and the CLI commands you start from it. For the full list of Claude Code calls the module makes, see the plugin's Data Handling section.
Troubleshooting
Quick diagnostics
Run the built-in health check:
/constellation:diagnose
It checks the MCP server, the API, authentication and the project's index, and names the fix for each problem. The /constellation pane's Diagnose tab shows the same without starting a model turn.
Common errors
| Error | Cause | Fix |
|---|---|---|
MCP_UNAVAILABLE | The MCP server isn't connected | Restart Claude Code to reinitialize connections |
AUTH_ERROR | Missing or invalid access key | Run const auth, or press Sign in on the onboarding band |
PROJECT_NOT_INDEXED | The project needs indexing | Run const index, or press Index this project |
SYMBOL_NOT_FOUND | The symbol isn't in the index | Search with a partial name, or re-index |
CWD_NOT_INDEXED | The working directory is not an indexed project | Run from a project root that has a constellation.json; the error lists the candidate project roots |
API_UNREACHABLE | The API can't be reached | Check your network and the apiUrl in constellation.json |
FILE_NOT_FOUND | The file path isn't in the index | Check the project-relative path and the language configuration |
No reminders, hints or /constellation pane
Search reminders and hints stay silent unless all of these hold (the /constellation pane needs only the first and the last):
- Claude Code is 2.1.304 or later. Check with
claude --version. CONSTELLATION_ACCESS_KEYis set and starts withak:. Runconst authto set it.- A
constellation.jsonis in reach. Reminders, hints and the description guidance need one in the searched directory or a parent. They check only that the file exists, so also make sure the project is indexed (const index), orcode_intelanswersPROJECT_NOT_INDEXED. - Hooks are enabled. The plugin is enabled in
/plugin, Claude Code was not started with--safe-mode, anddisableAllHooksis not set.
Search reminders are also capped per session; see Reminder limit. If the freshness line or the compact tool rows are missing, check that showFreshness and compactToolRows are on.
MCP server issues
If you see "Failed to reconnect to plugin:constellation:constellation":
-
Restart Claude Code. MCP connections initialize at startup.
-
Verify the MCP server can run:
npx @constellationdev/mcp@latest --version -
Check the 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 the health check:
/constellation:diagnose -
Check connectivity:
/constellation:status -
Re-index if needed:
const index --full
Getting help
- Browse the Constellation Documentation
- Report issues on GitHub
Related Documentation
- MCP Server: direct MCP integration without the plugin
- CLI Tool: indexing your codebase
- Claude Code Documentation: the official Claude Code docs