Codex Plugin

The Constellation plugin for OpenAI Codex supercharges your AI-assisted development workflow with deep codebase understanding. It provides $constellation: skills, reference agents, 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
3 Agents	Reference prompts for codebase exploration, risk assessment, and dependency analysis
4 Hooks	Session initialization, subagent guidance, search nudges, and context preservation

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.

Agents

The Codex plugin includes reference agents that describe specialized workflows for deeper analysis. They are shipped with the plugin as reusable prompts for agent-oriented workflows.

source-scout

Purpose: Codebase exploration, understanding, and intelligent navigation.

Use when you ask things like:

"What does this codebase do?"
"Where is the authentication logic?"
"Find all places that use the UserService"
"How does the payment processing work?"
"Show me the API endpoints in this project"

What it does:

Uses Constellation's structural index to find symbols intelligently
Analyzes architecture and provides codebase overviews
Traces symbol usage across the codebase
Maps call graphs to explain how components interact
Falls back to traditional local tools when Constellation is unavailable

impact-investigator

Purpose: Proactively assesses risk before refactoring, renaming, or deleting code.

Use when you say things like:

"I'm going to rename UserAuthService to AuthenticationService"
"Let's delete this unused code"
"I want to refactor this class"

Example:

You: "Rename AuthService to AuthenticationService"
Codex: "Before renaming, let me analyze the potential impact..."
[Uses the impact investigation workflow]

What it does:

Analyzes the impact of the proposed change
Identifies all files and symbols that would be affected
Assesses risk level
Calculates blast radius and scope
Warns about potential breaking changes to public APIs
Suggests a safer order for multi-file changes

dependency-detective

Purpose: Detects circular dependencies and unhealthy coupling patterns.

Use when you say things like:

"I need to import UserService into AuthService"
"I'm worried our modules are too tightly coupled"
"Before I submit this PR, are there any dependency issues?"

What it does:

Detects circular dependencies in a specified scope or the entire codebase
Identifies overly coupled modules
Finds dependency chains that could cause problems
Suggests refactoring strategies to improve dependency health
Verifies proposed imports will not create cycles

Hooks

The plugin includes hooks that guide Codex toward Constellation's structural code intelligence and preserve useful context throughout the session.

Session Start Hook

Event: sessionStart

Purpose: Establishes Constellation as the primary code intelligence source at the start of a Codex session.

Behavior:

Reminds Codex to use Constellation for structural questions
Establishes the distinction between structural analysis and literal text search
Runs automatically when the session starts

Subagent Start Hook

Event: subagentStart

Purpose: Bridges Constellation awareness into spawned subagents.

Behavior:

Reminds subagents that Constellation is available for code intelligence
Encourages structural queries before broad text searches
Helps preserve consistent analysis behavior across delegated work

Search Nudge Hook

Event: preToolUseGrepGlob

Purpose: Guides Codex toward semantic structural queries when appropriate.

Behavior:

Triggers before Grep or Glob usage
Reminds Codex that Constellation can answer structural questions such as definitions, callers, dependencies, and impact in fewer calls
Allows text search for literal strings, config values, logs, and fallback analysis

Context Preservation Hook

Event: preCompact

Purpose: Preserves Constellation insights before context compaction.

Behavior:

Captures important architecture, dependency, and impact findings
Keeps project-specific Constellation insights available after summarization
Reduces repeated discovery work in long sessions

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​

Agents​

source-scout​

impact-investigator​

dependency-detective​

Hooks​

Session Start Hook​

Subagent Start Hook​

Search Nudge Hook​

Context Preservation Hook​

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

Agents

source-scout

impact-investigator

dependency-detective

Hooks

Session Start Hook

Subagent Start Hook

Search Nudge Hook

Context Preservation Hook

Troubleshooting

Quick Diagnostics

Common Errors

MCP Server Issues

Step-by-Step Diagnostics

Advanced Usage

Parallel API Execution

Available API Methods

Related Documentation