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 that ask Claude to run a common analysis and answer in the conversation
Skills	Troubleshooting knowledge and proactive impact analysis that Claude loads on its own when they are relevant
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.287 or later. This is the plugin's stated floor; older versions are expected to load the plugin and run none of its hooks, the pane or the indicators, though this is untested.
• A Constellation account
• The Constellation CLI (constellation, or its shorter alias const)
• A project indexed in Constellation

Quick Start

1. Add the Constellation plugin marketplace

   _{Enter the following in Claude Code:}

   /plugin marketplace add ShiftinBits/constellation-claude

2. Install the plugin

   _{Enter the following in Claude Code:}

   /plugin install constellation@constellation-plugins --scope project

3. Reload plugins

   _{Enter the following in Claude Code:}

   /reload-plugins

4. Sign in with an access key

   _{Enter the following in your terminal:}

   const auth

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

5. Verify the connection

   _{Enter the following in Claude Code:}

   /constellation:status

6. Open the Constellation pane

   _{Enter the following in Claude Code:}

   /constellation

How Constellation Output Looks

Everything the plugin shows follows one visual language, so you can always tell at a glance that a line came from Constellation and what state it reports.

The brand line

Every line the plugin shows outside the /constellation pane opens with the Constellation mark:

✦ >_CONSTELLATION://CODE_INTEL · index 4 commits behind · indexed 2h ago

That covers the freshness line, the onboarding band, the code_intel call rows, the turn impact summary, log lines, the plugin's refusals and the hints Claude reads. Drawn rows paint the mark in Constellation's nebula blue. A few places deliberately leave it off:

• Toasts: Claude Code already titles each toast with the plugin's name, and the box is narrow.
• code_intel result rows: they sit directly under their branded call row. If a result row ever appears without the plugin's call row above it, it carries the mark itself.
• The spinner counts: the optional adoption counts beside the spinner keep to a short ✦ prefix.

Inside the pane, the header shows the full Constellation banner instead.

Status symbols

The mark ✦ only ever means "Constellation". States use their own symbols, and every symbol comes with a word, so nothing depends on color alone:

Symbol	Meaning	Examples
✓	Success	✓ ok, ✓ connected, ✓ LOW risk
⏱	Pending or in progress	⏱ pending, ⏱ indexing, ⏱ working
⚠	Warning	⚠ stale, ⚠ not indexed, ⚠ MEDIUM risk
✗	Error or failure	✗ AUTH_ERROR, ✗ failed, ✗ HIGH risk
ℹ	Information	ℹ Run /constellation:diagnose to …
·	Unknown or not checked	· not checked

Risk levels read ✓ LOW, ⚠ MEDIUM, ✗ HIGH and ✗ CRITICAL everywhere: in the tool rows, the pane, the analysis commands and the impact-analysis skill.

Line conventions

• Fields are separated with ·.
• The first field after the brand reads as a sentence (Not signed in), the rest stay short (run const auth).
• Commands to run are written plainly, ready to copy, with the CLI's const shorthand (const auth, const index).
• The indexed commit reads as of abc1234.
• Errors read ✗ CODE · headline · next step, the same in the tool rows, the pane, the commands and the freshness line.

Colors and themes

There is no color setting: the plugin follows your Claude Code theme (/theme, or the Theme row in /config).

Claude Code theme	What you get
dark, auto	The Constellation palette: nebula blue mark, green for success, gold for warnings, red for errors
light	The same palette, with gold and green swapped for Claude Code's warning and success colors, which read better on white
dark-ansi, light-ansi	Claude Code's own theme colors, so your terminal's ANSI palette decides the shades
dark-daltonized, light-daltonized	Claude Code's own color-blind-friendly theme colors

Color marks status and risk only; counts, selections and file names are plain text. The /constellation pane reads the theme when you run it, so after switching themes, run /constellation again to redraw it.

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 and methods) 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. In narrower terminals the banner shrinks to a boxed header, then to a single line; the Desktop app draws it as an image.

• 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, under a brand line naming the tab:

  ✦ >_CONSTELLATION://CODE_INTEL · Unused
  - 2 unused exports
  - src/util.ts
  - helper · function
  - Legacy · class
  - as of 0123456 · indexed 2h ago

  Long answers end with a +N more line 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. Every answer opens with the brand line and uses the status symbols above.

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 what failed and what was not checked, followed by the 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.

> /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 variable
• file-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 <kind>]

Finds exports nothing imports. Filter by --kind: function, class, type, interface or variable.

> /constellation:unused --kind function

✦ >_CONSTELLATION://CODE_INTEL · unused
7 unused exports · 7 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

Skills 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_UNAVAILABLE and others)
• Connectivity or authentication issues
• MCP server problems ("Failed to reconnect")
• Unexpected or empty results

Provides:

• A quick diagnosis flow for common issues
• MCP server troubleshooting steps
• Each error code with its cause and fix, presented as ✗ CODE · headline · next step
• Configuration checks and recovery procedures

impact-analysis

Activates when you discuss:

• Renaming, refactoring, deleting or moving a symbol or file
• 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 depends on X"

Provides:

• When to run impactAnalysis, and how to pair it with getDependencies, getDependents and traceSymbolUsage for wider context
• How to read the risk: ✓ LOW (fewer than 5 files, internal only), ⚠ 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, under the brand line
• A text-search fallback for when code_intel is unavailable or the symbol cannot be found

Example interaction:

You: "Rename AuthService to AuthenticationService"
Claude: "Before renaming, let me analyze the potential impact..."
[impact-analysis activates, runs api.impactAnalysis,
 and reports risk and dependents before any edit is made]

Code Intelligence Hooks

The plugin's hooks run in-process inside Claude Code, from a hooks module (hooks/register.ts, a Claude Code mod) that Claude Code loads into the session instead of starting a separate process for each event.

• Access key: the hooks are silent unless CONSTELLATION_ACCESS_KEY is set and starts with ak:, so the plugin never nags where Constellation isn't configured. The adoption counter is the exception: it counts code_intel calls with or without a key. The onboarding band and the /constellation pane 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.json in the searched directory (the call's path for Grep and Glob when set, else the working directory) or one of its parents.
• 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 Explore see the same guidance.
• Turn it all off: disable the plugin from /plugin, start Claude Code with --safe-mode, or set disableAllHooks in your settings. Individual features have their own options.

Hook	Event (matcher)	Behavior
Session awareness	classic.SessionStart	Establishes code_intel as Claude's default for structural questions (definitions, callers, dependencies) and text search for literal text, at session start and after clear, resume and compact
Subagent awareness	classic.SubagentStart	Gives every spawned subagent the same guidance; built-ins like Explore and Plan don't inherit your project's AGENTS.md
Search tool nudge	tool.call (Grep|Glob)	Reminds Claude to prefer code_intel before a symbol-like search
Bash search nudge	tool.call (Bash)	The same reminder for symbol-like searches run with grep, egrep, rg, ag, ack or git grep in the shell
Tool description guidance	tool.describe (Grep|Glob|Bash)	Adds a short rule to the search tools' descriptions. See Tool description guidance
Reminder budget	turn.start, tool.call (code_intel), classic.SessionStart	Limits the search reminders. See Reminder limit
Search result hint	tool.call (Grep|Bash)	Adds one code_intel line to the result of a symbol search. See Search result hint
Adoption counter	tool.call (code_intel, Grep|Glob|Bash), ui.render (Spinner)	Counts code_intel calls and text searches on your machine. See Adoption counter

The plugin's other hooks drive 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.

Search reminders

A reminder fires only for a search that looks like a symbol lookup, inside an indexed project. It reaches Claude as a branded line after the search result.

• Grep: a pattern that looks like a symbol, such as AuthService, class UserService or getUser\(.
• Glob: a file stem in PascalCase or camelCase, such as **/UserService.ts.
• Bash: the plugin reads the leading command, up to the first unquoted |, ;, && or || (or the command after a leading cd <dir> &&). When it is grep, egrep, rg, ag, ack or git grep (also after git -C <dir> or variable assignments such as LC_ALL=C) and the pattern looks like a symbol, Claude gets the reminder. Flags and their values (-t ts, -A 3, -g '*.ts') are skipped, so rg -t ts getUser counts as a symbol search.

These get no reminder: quoted phrases and error text, TODO-style markers, regular expressions with character classes or alternation, language keywords such as import, extension globs such as **/*.ts, a grep after a pipe, awk and findstr.

Reminder limit

The search reminders are rationed so they stay useful instead of repeating on every search:

• Per session: Claude gets at most nudgeLimit reminders (default 3). 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_intel was already called earlier in the turn, a symbol search in that turn gets no reminder and uses none of the limit.
• Reset: the count starts over after /clear, and when a session is resumed (/resume) or forked (/branch).
• Not limited: the session and subagent awareness text and the tool description guidance.

A nudgeLimit of 0 turns the search reminders off while keeping the awareness text and 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 once 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 first and its result is kept exactly as it is. The plugin then 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, /resume or /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_intel was already called earlier in the turn, for patterns that are not symbol-like (the same rules as the reminders), 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_intel call Claude or a subagent makes, and each search Claude or a subagent runs with Grep, Glob, or grep, egrep, rg, ag, ack or git grep in the shell, as symbol-like or literal by the same rules as the reminders. A search counts only where code_intel could have answered it: with an access key set and inside an indexed project.
• What does not: the plugin's own code_intel lookups (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_intel calls out of code_intel calls plus symbol-like searches. Literal searches are shown but left out, because code_intel could 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 on showAdoption to also show the session's counts beside the spinner, for example Sauteing · ✦ 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 /clear and when a session is resumed or forked; 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)
dialog	Asks you before an edit Claude Code would run without asking, offering Proceed, Proceed and don't ask again for this file, or Cancel. An edit already headed to the permission prompt gets the impact summary as a toast beside it instead
native	Sends that edit to Claude Code's own permission prompt, with the impact summary as a toast
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 dialog

The summary leads with the risk, so a narrow toast that cuts the end still shows it:

HIGH risk · 25 dependents · src/core.ts · as of 0123456

The dialog and logs show the same line after the brand mark. If you cancel, Claude reads why and is asked to check with you before trying a different approach.

In auto mode, where such an edit goes to the auto-mode classifier rather than to you, both dialog and native ask you first, and the classifier still decides after you choose Proceed. 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 count of 100+ means a file has at least that many dependents. Files deleted with a shell rm are not tracked. 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 command once per branch per session, with the section as the reason, until the PR body has an ## Impact heading; Claude adds it and runs the command again
off	Does nothing

The brand line always sits above the ## Impact heading, never inside it, so the section pastes cleanly into a PR body. 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 or GH_REPO), or a gh pr create after a cd the shell expands (~, $VAR, -), is left alone, even with require. A git or code_intel error 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, with the brand mark in blue and the age dimmed:

✦ >_CONSTELLATION://CODE_INTEL · index 4 commits behind · indexed 2h ago
✦ >_CONSTELLATION://CODE_INTEL · index at fedcba9 · indexed 2h ago

When a ping fails and no index is known, the line shows the error as a red ✗ badge with the next step (or the headline, when there is no step), since the step is the part to act on:

✦ >_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, when the working directory changes and every 5 minutes; git runs locally and only the session-start and directory-change checks ping Constellation. Where the session cannot draw (for example a headless run), a stale index is reported once 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. Rows are cut at the terminal's width rather than wrapping.

• Verbose: with --verbose (or the Verbose row in /config), Claude Code's own rendering also shows under each row.
• Turn them off: set compactToolRows to false to keep Claude Code's own rows for every code_intel call.

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 the band for that repository until its state changes; a different problem shows it again. On Windows the band names the command to run in a terminal instead of offering buttons. 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, dialog, native or require-analysis. 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

Colors have no option: they follow your Claude Code theme. Earlier versions had a colors option; a saved value is now ignored.

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
Awareness, 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; in dialog and native modes, the permission mode of each prompt (never the prompt's text)	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 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	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
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):

1. Claude Code is 2.1.287 or later. Check with claude --version.
2. CONSTELLATION_ACCESS_KEY is set and starts with ak:. Run const auth to set it.
3. A constellation.json is 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), or code_intel answers PROJECT_NOT_INDEXED.
4. Hooks are enabled. The plugin is enabled in /plugin, Claude Code was not started with --safe-mode, and disableAllHooks is 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":

1. Restart Claude Code. MCP connections initialize at startup.

2. Verify the MCP server can run. The plugin pins the MCP server version in its .mcp.json (currently 1.2.11); check that version rather than @latest:

   npx @constellationdev/[email protected] --version

3. Check the plugin configuration in .mcp.json:

   {
   	"mcpServers": {
   		"constellation": {
   			"type": "stdio",
   			"command": "npx",
   			"args": ["-y", "@constellationdev/[email protected]"],
   			"env": {
   				"CONSTELLATION_ACCESS_KEY": "${CONSTELLATION_ACCESS_KEY}"
   			}
   		}
   	}
   }

Step-by-step diagnostics

1. Run the health check:

   /constellation:diagnose

2. Check connectivity:

   /constellation:status

3. Re-index if needed:

   const index --full

Getting help

• Browse the Constellation Documentation
• Report issues on GitHub

Advanced Usage

Parallel API execution

The Constellation MCP server uses Code Mode: Claude writes JavaScript that runs several API calls in parallel, which makes complex analyses much faster:

// All three queries run 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' }),
]);

The tool rows name every method a call ran, so impactAnalysis, getDependents above tells you at a glance what Claude asked.

Available API methods

Category	Methods
Discovery	searchSymbols, getSymbolDetails
Dependencies	getDependencies, getDependents, findCircularDependencies
Tracing	traceSymbolUsage, getCallGraph
Impact	impactAnalysis, findOrphanedCode
Architecture	getArchitectureOverview
Utility	ping

For the complete API, see the MCP Server Tools Reference.

Related Documentation

• MCP Server: direct MCP integration without the plugin
• CLI Tool: indexing your codebase
• Claude Code Documentation: the official Claude Code docs