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
7 Skills	`$constellation:` workflows for common code intelligence and troubleshooting tasks
2 Hooks	Session initialization and a Bash post-tool nudge toward `code_intel` for structural queries

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 install constellation@constellation-plugins
```
Configure authentication:
_{Enter the following in your terminal:}
```
npx @constellationdev/cli auth
```
Verify the connection:
_{Enter the following in Codex:}
```
$constellation:status
```

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.

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:     my-awesome-app
Index:       1,247 files, 8,932 symbols

All systems operational.

When issues are detected:

Constellation Health Check
===========================
MCP Server:  OK
API Auth:    FAILED

Issue: Authentication failed - 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
- Project: my-awesome-app
- Files: 1,247
- Symbols: 8,932
- Languages: TypeScript, JavaScript

Key Directories
- src/services
- src/controllers
- src/utils

The architecture skill summarizes language distribution, symbol breakdown, key directories, 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
Symbols Affected: 34
Test Coverage: 67%

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 (line 23)
│   └── parseLegacyConfig (line 45)
├── src/helpers/deprecated.ts
│   └── oldValidation (line 12)
└── ...

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.

Session Start Hook

Event: SessionStart

Purpose: Establishes code_intel as the primary tool for code search and navigation at the start of a Codex session.

Behavior:

Reminds Codex to prefer code_intel for finding definitions, references, callers, dependencies, impact, and architecture
Positions text search tools (grep, glob, awk, rg) as a fallback for literal text or as a backup
Only fires when CONSTELLATION_ACCESS_KEY is configured

Bash Post-Tool Nudge

Event: PostToolUse (matcher: Bash)

Purpose: Reminds Codex to prefer code_intel after running shell-based search commands.

Behavior:

Inspects the executed Bash command and triggers when it contains grep, rg, glob, awk, or findstr
Injects a reminder to use code_intel first for structural code queries on subsequent searches
Only fires when CONSTELLATION_ACCESS_KEY is configured

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

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​

Uninstall​

Skills​

Status​

Diagnose​

Architecture​

Impact​

Deps​

Unused​

Troubleshooting​

Hooks​

Session Start Hook​

Bash Post-Tool Nudge​

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

Uninstall

Skills

Status

Diagnose

Architecture

Impact

Deps

Unused

Troubleshooting

Hooks

Session Start Hook

Bash Post-Tool Nudge

Troubleshooting

Quick Diagnostics

Common Errors

MCP Server Issues

Step-by-Step Diagnostics

Advanced Usage

Parallel API Execution

Available API Methods

Related Documentation