Codex Plugin

The Constellation plugin for OpenAI Codex supercharges your AI-assisted development workflow with deep codebase understanding. It provides $constellation: skills and session hooks that leverage Constellation's code intelligence platform.

Source: github.com/ShiftinBits/constellation-codex

Overview

Feature	Description
8 Skills	`$constellation:` workflows for setup, code intelligence, and troubleshooting
Hooks	Setup check and session guidance, a nudge toward `code_intel` for symbol searches, an index freshness note after git commands, `code_intel` usage tracking, an optional Impact section for pull requests, and two opt-in hooks that add symbol definitions to searches and impact notices to patches

Installation

Prerequisites

OpenAI Codex installed
A Constellation account
Constellation CLI utility installed
A project previously indexed in Constellation

Quick Start

Install the plugin from the marketplace:
_{Enter the following in your terminal:}
1. Add the Constellation marketplace:
```
codex plugin marketplace add ShiftinBits/constellation-codex
```
2. Install from the marketplace using <plugin>@<marketplace>:
```
codex plugin add constellation@constellation-local
```
You can also browse and install from the Codex CLI /plugins browser or the ChatGPT desktop app Plugins Directory. The Codex IDE extension does not support plugins.
Configure authentication:
_{Enter the following in your terminal:}
```
npx @constellationdev/cli auth
```
Trust the hooks:
_{Enter the following in Codex:}
```
/hooks
```
Review and trust the Constellation hooks. Codex skips plugin hooks until they are trusted, and asks again after any plugin update that changes them.
Verify the connection:
_{Enter the following in Codex:}
```
$constellation:status
```

Not sure where you are? Run $constellation:get-started in Codex for guided setup.

Reduce Approval Prompts

Optionally let Codex call the Constellation MCP tools without asking each time. Add this to ~/.codex/config.toml:

[plugins."constellation@constellation-local".mcp_servers.constellation]
default_tools_approval_mode = "approve"

Uninstall

_{Enter the following in your terminal:}

codex plugin uninstall constellation

Skills

Codex exposes Constellation workflows as plugin skills. Invoke them explicitly with the $constellation: prefix when you want a specific analysis path. Codex also selects get-started, impact, deps, unused, architecture, and troubleshooting on its own when a request matches; status and diagnose run only when you invoke them.

Get Started

$constellation:get-started

Walks you through setup in order, skipping steps you have already completed: install the CLI, run constellation auth, run constellation init and constellation index, restart Codex so the MCP server receives the key, trust the hooks in /hooks, and confirm with $constellation:status.

On macOS, GUI apps such as the ChatGPT desktop app may hold a stale environment. After constellation auth, fully quit and relaunch the app so it picks up the new CONSTELLATION_ACCESS_KEY.

Status

$constellation:status

Check Constellation API connectivity and authentication status.

> $constellation:status

Status: Connected
Authentication valid, project access confirmed
Note: Use $constellation:diagnose to check indexing status

If issues are detected, the skill reports the specific error code and a targeted remediation step.

Diagnose

$constellation:diagnose

Run a quick health check for MCP connectivity, API authentication, and project indexing.

> $constellation:diagnose

Constellation Health Check
===========================
MCP Server:  OK
API Auth:    OK
Project:     TypeScript project
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 - API key missing or invalid.

Quick Fix: Run `constellation auth` to configure credentials.

Architecture

$constellation:architecture

Get a high-level overview of your codebase structure.

> $constellation:architecture

Project Summary
- Primary Language: TypeScript
- Files: 1,247
- Symbols: 8,932
- Languages: TypeScript, JavaScript

Dependency Hotspots
- src/services/user.service.ts
- src/controllers/user.controller.ts
- src/utils/currency.ts

The architecture skill summarizes language distribution, symbol breakdown, dependency hotspots, and concise observations about the codebase shape.

Impact

$constellation:impact <symbol> [file]

Analyze the blast radius before changing a symbol.

> $constellation:impact validateUser src/auth/validator.ts

Symbol: validateUser (function)
Risk Level: MEDIUM
Files Affected: 12
Direct Dependents: 34
Impacted Test Files: 3

Recommendations:
- Update unit tests in auth.spec.ts
- Check integration with UserController

Use this before refactoring, renaming, deleting, or changing shared code. If the risk is high or critical, Codex emphasizes caution and highlights the most important dependents to review.

Deps

$constellation:deps <file> [--reverse]

Map dependencies for a file, or use --reverse to find what depends on it.

Dependencies:

> $constellation:deps src/services/payment.service.ts

Dependencies (12):
├── Internal (8)
│   ├── src/models/payment.model.ts
│   ├── src/utils/currency.ts
│   └── ...
└── External (4)
    ├── stripe
    ├── lodash
    └── ...

No circular dependencies detected.

Dependents:

> $constellation:deps src/services/payment.service.ts --reverse

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

Unused

$constellation:unused [kind]

Find exported code that is never imported or used anywhere in the codebase. Optionally filter by function, class, type, interface, or variable.

> $constellation:unused function

Found 7 orphaned functions:
├── src/utils/legacy.ts
│   ├── formatLegacyDate
│   └── parseLegacyConfig
├── src/helpers/deprecated.ts
│   └── oldValidation
└── ...

Recommendation: Review each orphaned export before removing it; some may be entry points or dynamically imported.

Troubleshooting

$constellation:troubleshooting

Diagnose Constellation errors, indexing problems, authentication issues, and MCP failures.

> $constellation:troubleshooting AUTH_ERROR

Issue: Authentication failed - API key missing or invalid.
Quick Fix: Run `constellation auth` in your shell.

Use this skill when Constellation tool calls fail, the MCP server is unavailable, Codex reports failed reconnects, or an error code such as AUTH_ERROR, PROJECT_NOT_INDEXED, or API_UNREACHABLE appears.

Hooks

The plugin includes hooks that guide Codex toward Constellation's structural code intelligence (code_intel) instead of relying on text search for code understanding. Hooks are advisory: they add context for Codex and never block a command or a patch.

Hooks are on by default ([features].hooks = false turns them off). Codex skips plugin hooks until you trust them in /hooks, and asks again after any plugin update that changes them.

All hooks except the setup check require an ak: access key and a constellation.json in the project tree (or, when Codex starts in a folder above several projects, in one of its subdirectories), so they stay silent elsewhere. Hooks never send source code to the Constellation API, and their output never includes source code. The two opt-in hooks hand the shell command or the full patch text to the local constellation MCP server process, which keeps it on your machine; only symbol names and project-relative paths reach the API. Hooks fail open if anything goes wrong.

Nothing new runs by default. The PR Impact Section hook is off until you set CONSTELLATION_PR_IMPACT, and the plugin does not register the Symbol Search Augmentation and Impact Notice hooks at all, so they cost nothing until you add them yourself (see Opt-in Hooks).

Session Start

Event: SessionStart (matcher: startup|resume|clear|compact)

Behavior:

Establishes code_intel as the primary tool for definitions, usages, callers, dependencies, impact, architecture, and dead code, with text search for literal strings, config values, and logs
On startup, shows a warning when CONSTELLATION_ACCESS_KEY is missing or invalid and points to $constellation:get-started
On startup in a git repository without a constellation.json, tells Codex the project is not indexed

Subagent Start

Event: SubagentStart

Behavior: Gives subagents the same code_intel guidance as the main session.

Symbol Search Nudge

Event: PostToolUse (matcher: Bash)

Behavior:

Fires only when a shell search such as grep or rg looks like a symbol lookup (for example rg "UserService") inside an indexed project; literal searches such as rg "connection refused" are left alone
Reminds Codex that code_intel finds definitions and usages across files
Stays quiet for the rest of a turn once Codex has used code_intel
Limited per session (3 by default, tracked separately for each subagent)

Symbol Search Augmentation

Event: PostToolUse (matcher: Bash, mcp_tool hook)

Behavior:

Opt-in: the plugin does not load it until you add it
When a shell search such as grep, rg, or git grep looks like a symbol lookup, calls code_intel in hook mode and adds a line with where the symbol is defined and how many usages it has
Fires once per symbol per session
The Symbol Search Nudge still fires alongside it unless CONSTELLATION_NUDGE_LIMIT=0

`validateUser` (function) defined at `src/auth/validator.ts:12`, 34 usages. code_intel api.traceSymbolUsage lists every usage.

Index Freshness Note

Event: PostToolUse (matcher: Bash)

Behavior: After a git command that moves HEAD (commit, pull, checkout, merge, rebase), warns once per HEAD when the index is behind your checkout, and suggests constellation index once per session.

Usage Tracking

Event: PostToolUse (matcher: mcp__constellation__code_intel)

Behavior: Records that code_intel was used so nudges stay quiet for that turn, and remembers which commit the index reflects for the freshness note.

Impact Notice

Event: PreToolUse (matcher: apply_patch|Edit|Write, mcp_tool hook)

Behavior:

Opt-in: the plugin does not load it until you add it
Before Codex applies a patch, looks up the direct dependents of each file the patch updates, deletes, or moves (new files are skipped)
Notes only files at high risk (20 or more direct dependents) or critical risk (50 or more), with their top dependents, the symbols those dependents use, and test exposure, and suggests api.impactAnalysis or api.traceSymbolUsage before changing behavior
Fires once per file per session
Never blocks the patch

The Impact Notice takes patch paths relative to the directory Codex runs in, so it is accurate when Codex starts at the indexed project root (the directory with constellation.json). Started from a subdirectory, or from a workspace folder above several projects, it stays silent or undercounts.

PR Impact Section

Event: PostToolUse (matcher: Bash), inside the Symbol Search Nudge hook, so it adds no hook process of its own

Behavior:

Built in, but off until you set CONSTELLATION_PR_IMPACT=inform
Fires after a gh pr create (or gh pr new) in an indexed project, including one chained after other commands such as git push && gh pr create; skipped for --web, --dry-run, and --help
Codex runs PostToolUse only once the command finishes inside its shell yield window (10 seconds by default), so a slow chained command can miss it
Skipped when the PR body, given with --body or --body-file, already has an Impact heading
Lists the files the branch changes under the project root against its base (--base, else origin's default branch, else main), relative to that root, in an ## Impact skeleton of up to 50 files, and asks Codex to fill in each file's dependents with code_intel api.getDependents and add the section to the PR body, for example with gh pr edit
Fires once per project and branch per session
Never blocks the command; the hook itself runs only local git commands

Opt-in Hooks

Symbol Search Augmentation and the Impact Notice are mcp_tool hooks: on every matching Bash call or patch, Codex calls the constellation MCP server's code_intel tool in hook mode. The plugin ships them in plugins/constellation/hooks/opt-in-hooks.json but does not load that file. They need an @constellationdev/mcp release with hook mode; on a server without it, and on the first call while the server is still starting, they fail open and show a Failed hook row.

To turn them on:

Add them to your user hooks file, hooks.json in your Codex home (~/.codex, or $CODEX_HOME when set).

If you have no user hooks.json yet, download the shipped file as it is:
_{Enter the following in your terminal:}
```
f="${CODEX_HOME:-$HOME/.codex}/hooks.json"
[ -e "$f" ] && echo "$f exists, copy the groups by hand" || curl -fsSL https://raw.githubusercontent.com/ShiftinBits/constellation-codex/main/plugins/constellation/hooks/opt-in-hooks.json -o "$f"
```
If you already have one, copy the PostToolUse group with matcher Bash (Symbol Search Augmentation) and the PreToolUse group with matcher apply_patch|Edit|Write (Impact Notice) from the shipped file into the matching event arrays of yours.

Keep only one of the two groups to turn on only that hook. Codex also reads hooks from [hooks] tables in config.toml; keep your user hooks in one of the two places, since Codex warns when a config folder has both.
Restart Codex and trust the new hooks:
_{Enter the following in Codex:}
```
/hooks
```
Start Codex (restart it if it is running), open /hooks, and trust the new hooks. Codex does not run a user hook until you trust it, and asks again whenever the hook changes.
Copy the hooks again after a plugin update to pick up fixes; your copy does not update with the plugin.

The Symbol Search Nudge still fires alongside Symbol Search Augmentation; CONSTELLATION_NUDGE_LIMIT=0 turns nudges off. Do not define your own MCP server named constellation in config.toml: the hooks call the server by that name, and yours would take the place of the plugin's.

Settings

Variable	Default	Effect
`CONSTELLATION_NUDGE_LIMIT`	`3`	How many symbol search nudges Codex gets per session; `0` disables nudges
`CONSTELLATION_PR_IMPACT`	off	`inform` enables the PR Impact Section hook

Set these in the environment Codex is launched from, and restart Codex after changing them. Codex plugins have no per-plugin user settings, so environment variables are the settings mechanism.

Troubleshooting

Quick Diagnostics

Ask Codex to run a status check:

$constellation:status

For deeper diagnostics, run:

$constellation:diagnose

Common Errors

Error	Cause	Solution
`MCP_UNAVAILABLE`	MCP server not running	Restart Codex to reinitialize MCP connections
`AUTH_ERROR`	Missing or invalid access key	Run `constellation auth`
`PROJECT_NOT_INDEXED`	Project needs indexing	Run `constellation index --full`
`PROJECT_NOT_REGISTERED`	Project ID is unknown or unavailable	Verify project ID and organization access
`PROJECT_INACTIVE`	Project has been deactivated	Reactivate the project or choose another project
`API_UNREACHABLE`	Constellation API cannot be reached	Check network connectivity and API URL in `constellation.json`
Skills not appearing	Plugin not loaded	Restart Codex or check the plugin installation path
Hooks not running	Hooks not trusted	Open `/hooks` in Codex and trust the Constellation hooks
Hooks stop running after a change	Codex asks again whenever a hook changes	After a plugin update or an edit to your user `hooks.json`, open `/hooks` and re-trust the hooks
`Failed` hook row for an opt-in hook	The `constellation` MCP server has no hook mode, or your own server named `constellation` in `config.toml` takes the place of the plugin's	Use an `@constellationdev/mcp` release with hook mode and remove your own `constellation` server. A `Failed` row on the first call while the server is still starting is expected
Setting has no effect	Codex reads environment variables when it starts	Set `CONSTELLATION_PR_IMPACT` or `CONSTELLATION_NUDGE_LIMIT` in the environment Codex is launched from, then restart Codex
Impact Notice silent or undercounting	Codex started outside the indexed project root	Start Codex in the directory with `constellation.json`

MCP Server Issues

If you see MCP connection errors:

Restart Codex - MCP connections initialize at startup.

Verify the 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_vars": ["CONSTELLATION_ACCESS_KEY"]
		}
	}
}

Step-by-Step Diagnostics

Run plugin status:
```
$constellation:status
```
Run full diagnosis:
```
$constellation:diagnose
```
Verify CLI authentication:
```
constellation auth
```
Re-index if needed:
```
constellation index --full
```

Advanced Usage

Parallel API Execution

The Constellation MCP server uses Code Mode, which allows JavaScript snippets to execute 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 and managing projects
OpenAI Codex CLI Documentation - Official Codex documentation

Overview​

Installation​

Prerequisites​

Quick Start​

Reduce Approval Prompts​

Uninstall​

Skills​

Get Started​

Status​

Diagnose​

Architecture​

Impact​

Deps​

Unused​

Troubleshooting​

Hooks​

Session Start​

Subagent Start​

Symbol Search Nudge​

Symbol Search Augmentation​

Index Freshness Note​

Usage Tracking​

Impact Notice​

PR Impact Section​

Opt-in Hooks​

Settings​

Troubleshooting​

Quick Diagnostics​

Common Errors​

MCP Server Issues​

Step-by-Step Diagnostics​

Advanced Usage​

Parallel API Execution​

Available API Methods​

Related Documentation​

Overview

Installation

Prerequisites

Quick Start

Reduce Approval Prompts

Uninstall

Skills

Get Started

Status

Diagnose

Architecture

Impact

Deps

Unused

Troubleshooting

Hooks

Session Start

Subagent Start

Symbol Search Nudge

Symbol Search Augmentation

Index Freshness Note

Usage Tracking

Impact Notice

PR Impact Section

Opt-in Hooks

Settings

Troubleshooting

Quick Diagnostics

Common Errors

MCP Server Issues

Step-by-Step Diagnostics

Advanced Usage

Parallel API Execution

Available API Methods

Related Documentation