# openai/codex-plugin-cc architecture

> Architecture diagram of the GitHub repository openai/codex-plugin-cc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openai/codex-plugin-cc
- Repository: https://github.com/openai/codex-plugin-cc

## Overview

This is a Claude Code plugin that delegates reviews and coding tasks to Codex. The principal workflow is: a Claude user invokes a slash command, the companion resolves review or task context, optionally records a background job, sends work through the Codex app-server runtime, persists status/results, and renders output back to Claude. Distinct stages include command dispatch, target preparation, execution, job lifecycle, and result presentation. The graph also includes session transfer and the optional stop-time review gate. Some command wiring is inferred from the README and tree; unsampled implementation links are omitted.

Main entry points: [`plugins/codex/scripts/codex-companion.mjs`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/codex-companion.mjs) (Companion CLI), [`plugins/codex/scripts/lib/app-server.mjs`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server.mjs) (App Server Client), [`plugins/codex/scripts/lib/state.mjs`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/state.mjs) (Job State Store), [`plugins/codex/commands/transfer.md`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/transfer.md) (Transfer Command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_commands["Command Interfaces"]
  node_review_cmd["Review Command<br/>[review.md]"]
  node_adversarial_cmd["Adversarial Review"]
  node_rescue_cmd["Rescue Command<br/>[rescue.md]"]
  node_transfer_cmd["Transfer Command<br/>[transfer.md]"]
  node_status_cmd["Status Command<br/>[status.md]"]
  node_result_cmd["Result Command<br/>[result.md]"]
  node_cancel_cmd["Cancel Command<br/>[cancel.md]"]
  node_setup_cmd["Setup Command<br/>[setup.md]"]
end

subgraph group_orchestration["Task Orchestration"]
  node_companion["Companion CLI"]
  node_git_context["Git Context<br/>[git.mjs]"]
  node_job_control["Job Control<br/>[job-control.mjs]"]
  node_result_rendering["Result Rendering<br/>[render.mjs]"]
end

subgraph group_runtime["Codex Runtime"]
  node_app_client["App Server Client<br/>[app-server.mjs]"]
  node_broker["Runtime Broker"]
  node_codex_service["Codex App Server"]
end

subgraph group_state_hooks["State And Hooks"]
  node_job_state[("Job State Store<br/>[state.mjs]")]
  node_session_transfer["Session Transfer"]
  node_session_hook["Session Lifecycle"]
  node_stop_gate["Stop Review Gate"]
end

node_claude_user(("Claude User"))
node_filesystem[("Claude Filesystem")]

node_claude_user -->|"invokes"| node_review_cmd
node_claude_user -->|"invokes"| node_adversarial_cmd
node_claude_user -->|"invokes"| node_rescue_cmd
node_claude_user -->|"invokes"| node_transfer_cmd
node_claude_user -->|"invokes"| node_status_cmd
node_claude_user -->|"invokes"| node_result_cmd
node_claude_user -->|"invokes"| node_cancel_cmd
node_claude_user -->|"invokes"| node_setup_cmd
node_review_cmd -->|"dispatches"| node_companion
node_adversarial_cmd -->|"dispatches"| node_companion
node_rescue_cmd -->|"dispatches"| node_companion
node_transfer_cmd -->|"dispatches"| node_companion
node_status_cmd -->|"dispatches"| node_companion
node_result_cmd -->|"dispatches"| node_companion
node_cancel_cmd -->|"dispatches"| node_companion
node_setup_cmd -->|"dispatches"| node_companion
node_companion -->|"resolves targets"| node_git_context
node_companion -->|"manages jobs"| node_job_control
node_companion -->|"runs turns"| node_app_client
node_companion -->|"renders output"| node_result_rendering
node_job_control -->|"reads jobs"| node_job_state
node_job_control -->|"checks runtime"| node_app_client
node_app_client -.->|"uses broker"| node_broker
node_app_client -->|"sends requests"| node_codex_service
node_broker -->|"proxies requests"| node_codex_service
node_companion -->|"writes jobs"| node_job_state
node_session_transfer -->|"reads transcript"| node_filesystem
node_transfer_cmd -->|"imports session"| node_session_transfer
node_session_hook -->|"cleans jobs"| node_job_state
node_session_hook -->|"shuts down"| node_broker
node_stop_gate -->|"checks jobs"| node_job_state
node_stop_gate -->|"runs review"| node_companion
node_companion -->|"returns results"| node_claude_user

click node_review_cmd "https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/review.md"
click node_adversarial_cmd "https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/adversarial-review.md"
click node_rescue_cmd "https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/rescue.md"
click node_transfer_cmd "https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/transfer.md"
click node_status_cmd "https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/status.md"
click node_result_cmd "https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/result.md"
click node_cancel_cmd "https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/cancel.md"
click node_setup_cmd "https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/setup.md"
click node_companion "https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/codex-companion.mjs"
click node_git_context "https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/git.mjs"
click node_job_control "https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/job-control.mjs"
click node_result_rendering "https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/render.mjs"
click node_app_client "https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server.mjs"
click node_broker "https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/app-server-broker.mjs"
click node_job_state "https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/state.mjs"
click node_session_transfer "https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/claude-session-transfer.mjs"
click node_session_hook "https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/session-lifecycle-hook.mjs"
click node_stop_gate "https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/stop-review-gate-hook.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_review_cmd,node_adversarial_cmd,node_rescue_cmd,node_transfer_cmd,node_status_cmd,node_result_cmd,node_cancel_cmd,node_setup_cmd,node_claude_user toneBlue
class node_companion,node_git_context,node_job_control,node_result_rendering,node_filesystem toneAmber
class node_app_client,node_broker,node_codex_service toneMint
class node_job_state,node_session_transfer,node_session_hook,node_stop_gate toneRose
```

## Components

### Command Interfaces

- [Review Command](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/review.md): `plugins/codex/commands/review.md`
- [Adversarial Review](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/adversarial-review.md): `plugins/codex/commands/adversarial-review.md`
- [Rescue Command](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/rescue.md): `plugins/codex/commands/rescue.md`
- [Transfer Command](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/transfer.md): `plugins/codex/commands/transfer.md`
- [Status Command](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/status.md): `plugins/codex/commands/status.md`
- [Result Command](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/result.md): `plugins/codex/commands/result.md`
- [Cancel Command](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/cancel.md): `plugins/codex/commands/cancel.md`
- [Setup Command](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/setup.md): `plugins/codex/commands/setup.md`

### Task Orchestration

- [Companion CLI](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/codex-companion.mjs): `plugins/codex/scripts/codex-companion.mjs`
- [Git Context](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/git.mjs): `plugins/codex/scripts/lib/git.mjs`
- [Job Control](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/job-control.mjs): `plugins/codex/scripts/lib/job-control.mjs`
- [Result Rendering](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/render.mjs): `plugins/codex/scripts/lib/render.mjs`

### Codex Runtime

- [App Server Client](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/app-server.mjs): `plugins/codex/scripts/lib/app-server.mjs`
- [Runtime Broker](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/app-server-broker.mjs): `plugins/codex/scripts/app-server-broker.mjs`
- **Codex App Server**

### State And Hooks

- [Job State Store](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/state.mjs): `plugins/codex/scripts/lib/state.mjs`
- [Session Transfer](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/lib/claude-session-transfer.mjs): `plugins/codex/scripts/lib/claude-session-transfer.mjs`
- [Session Lifecycle](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/session-lifecycle-hook.mjs): `plugins/codex/scripts/session-lifecycle-hook.mjs`
- [Stop Review Gate](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/scripts/stop-review-gate-hook.mjs): `plugins/codex/scripts/stop-review-gate-hook.mjs`

### Other components

- **Claude User**
- **Claude Filesystem**

## Connections

- Claude User → Review Command: invokes
- Claude User → Adversarial Review: invokes
- Claude User → Rescue Command: invokes
- Claude User → Transfer Command: invokes
- Claude User → Status Command: invokes
- Claude User → Result Command: invokes
- Claude User → Cancel Command: invokes
- Claude User → Setup Command: invokes
- Review Command → Companion CLI: dispatches
- Adversarial Review → Companion CLI: dispatches
- Rescue Command → Companion CLI: dispatches
- Transfer Command → Companion CLI: dispatches
- Status Command → Companion CLI: dispatches
- Result Command → Companion CLI: dispatches
- Cancel Command → Companion CLI: dispatches
- Setup Command → Companion CLI: dispatches
- Companion CLI → Git Context: resolves targets
- Companion CLI → Job Control: manages jobs
- Companion CLI → App Server Client: runs turns
- Companion CLI → Result Rendering: renders output
- Job Control → Job State Store: reads jobs
- Job Control → App Server Client: checks runtime
- App Server Client → Runtime Broker: uses broker
- App Server Client → Codex App Server: sends requests
- Runtime Broker → Codex App Server: proxies requests
- Companion CLI → Job State Store: writes jobs
- Session Transfer → Claude Filesystem: reads transcript
- Transfer Command → Session Transfer: imports session
- Session Lifecycle → Job State Store: cleans jobs
- Session Lifecycle → Runtime Broker: shuts down
- Stop Review Gate → Job State Store: checks jobs
- Stop Review Gate → Companion CLI: runs review
- Companion CLI → Claude User: returns results
