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, and `code_intel` usage tracking

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 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 anywhere; they read only the hook input and local files, and fail open if anything goes wrong.

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)

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.

Settings

CONSTELLATION_NUDGE_LIMIT sets how many symbol search nudges Codex gets per session (default 3; 0 disables nudges). Set it in the environment Codex is launched from. 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

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​

Index Freshness Note​

Usage Tracking​

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

Index Freshness Note

Usage Tracking

Settings

Troubleshooting

Quick Diagnostics

Common Errors

MCP Server Issues

Step-by-Step Diagnostics

Advanced Usage

Parallel API Execution

Available API Methods

Related Documentation