Skip to content

Prepare v1.0.0 release #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sf-jin-ku merged 2 commits into from
Apr 5, 2026
Merged

Prepare v1.0.0 release #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8bdc1bd
Rewrite README to match upstream structure
Apr 5, 2026
9fb0417
Prepare v1.0.0 release
Apr 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Changelog

## v1.0.0

- Initial public release of the Claude Code plugin for Codex.
- Includes tracked review, adversarial review, rescue, status, result, cancel, and setup flows.
- Includes Codex hook integration, release CI, and marketplace sync automation.
133 changes: 26 additions & 107 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,8 @@
# cc-plugin-codex

Claude Code Plugin for Codex by Sendbird.
Use Claude Code from inside Codex for code reviews and delegated tasks.

Use Claude Code from inside Codex for code reviews, adversarial reviews, and tracked rescue-task delegation through the `$cc:*` skill surface.

This repository is maintained by Sendbird and is inspired by [openai/codex-plugin-cc](https://github.com/openai/codex-plugin-cc). The upstream project lets Claude Code call Codex. This repository mirrors that shape in the opposite direction so Codex can call Claude Code. It is not an official OpenAI or Anthropic repository.
This repository is maintained by Sendbird and follows the overall shape of [openai/codex-plugin-cc](https://github.com/openai/codex-plugin-cc), but in the opposite direction: Codex hosts the plugin and delegates work to Claude Code.

## What You Get

Expand All @@ -23,62 +21,47 @@ The goal is to stay close to the upstream OpenAI plugin's UX, but Claude Code an
| User command surface | Claude slash commands such as `/codex:review` | Codex skills such as `$cc:review` |
| Delegated runtime | Codex app-server + broker | Fresh `claude -p` subprocess per invocation |
| Review gate subject | Reviews the previous Claude response before Claude stops | Reviews the previous Codex response before Codex stops |
| Read-only enforcement | Codex server + OS sandbox | Claude tool allowlists plus temporary settings files |
| Rescue agent | Plugin-local Codex rescue agent inside Claude | Globally registered `cc-rescue` agent in `~/.codex/agents` |
| Rescue agent | Plugin-local Codex rescue agent inside Claude | Global `cc-rescue` agent in `~/.codex/agents` |
| Model / effort flags | Codex model names and Codex effort controls | Claude model names and Claude effort values: `low`, `medium`, `high`, `max` |

The biggest structural difference is runtime shape: Codex exposes a persistent app-server model, while Claude Code is a CLI. Because of that, this plugin wraps Claude Code through `scripts/claude-companion.mjs` and `scripts/lib/claude-cli.mjs`, and each review or task launches a fresh Claude subprocess instead of talking to a long-lived server. In the current implementation that subprocess is `claude -p`, not `claude -p --bare`, because `--bare` breaks Claude Code OAuth authentication.

## Requirements

- Codex with hook support
- Node.js 18 or later
- Claude Code CLI installed and authenticated
- `claude auth login`, or
- `ANTHROPIC_API_KEY` set in the environment
- either the hosted Sendbird Codex marketplace or a local plugin registration in Codex
- either the hosted Sendbird Codex marketplace or a local plugin registration

## Install

### Hosted marketplace install
### Hosted Marketplace Install

Install from the dedicated marketplace repository:
Add this GitHub repository as a repo marketplace in Codex:

```text
https://github.com/sendbird/codex-plugins
```

In Codex:

1. Add the GitHub repository above as a repo marketplace.
2. Install the plugin as:
Then install:

```text
cc@sendbird-codex
```

The plugin source repository for development and release work lives at:

```text
https://github.com/sendbird/cc-plugin-codex
```
This repository, `sendbird/cc-plugin-codex`, is the plugin source repository used for development and releases.

### Local development install
### Local Development Install

Clone this repository and `cd` into it:
Clone this repository under `~/plugins/cc`:

```bash
git clone https://github.com/sendbird/cc-plugin-codex.git
cd cc-plugin-codex
```

Add this plugin to your local Codex marketplace file at:

```text
~/.agents/plugins/marketplace.json
mkdir -p ~/plugins
git clone https://github.com/sendbird/cc-plugin-codex.git ~/plugins/cc
cd ~/plugins/cc
```

Example entry:
Add it to your local Codex marketplace file at `~/.agents/plugins/marketplace.json`:

```json
{
Expand All @@ -91,7 +74,7 @@ Example entry:
"name": "cc",
"source": {
"source": "local",
"path": "/absolute/path/to/cc-plugin-codex"
"path": "./plugins/cc"
},
"policy": {
"installation": "AVAILABLE",
Expand All @@ -103,7 +86,9 @@ Example entry:
}
```

Install the hooks and the global `cc-rescue` agent:
The plugin path is relative to the marketplace root, matching the current Codex marketplace spec.

Install hooks and the global `cc-rescue` agent:

```bash
node scripts/install-hooks.mjs
Expand Down Expand Up @@ -144,16 +129,14 @@ $cc:result

## Usage

The sections below intentionally mirror the upstream plugin's command layout. The main difference is the command surface: in Codex you invoke these as `$cc:*` skills instead of Claude slash commands.

### `$cc:review`

Runs a normal Claude Code review on your current work.

Use it when you want:

- a review of your current uncommitted changes
- a review of your branch compared to a base branch such as `main` or `master`
- a review of your branch compared to a base branch like `main`

It supports `--base <ref>`, `--scope <auto|working-tree|branch>`, `--wait`, `--background`, and `--model <model>`.

Expand All @@ -165,7 +148,7 @@ $cc:review --base main
$cc:review --background
```

This command is read-only and will not edit code. When run in the background, use `$cc:status` to check progress and `$cc:cancel` to stop it.
This command is read-only. When run in the background, use `$cc:status` to check progress and `$cc:cancel` to stop it.

### `$cc:adversarial-review`

Expand All @@ -175,7 +158,7 @@ Use it when you want:

- a review before shipping that challenges the direction, not just the code details
- review focused on design choices, tradeoffs, hidden assumptions, and alternative approaches
- pressure-testing around specific risk areas such as auth, data loss, rollback, race conditions, or reliability
- pressure-testing around specific risk areas like auth, data loss, rollback, race conditions, or reliability

It uses the same target selection as `$cc:review`, including `--base <ref>`, and also accepts extra focus text after the flags.

Expand All @@ -191,7 +174,7 @@ This command is read-only. It does not fix code.

### `$cc:rescue`

Hands a task to Claude Code through the globally registered `cc-rescue` agent and the tracked-job runtime.
Hands a task to Claude Code through the global `cc-rescue` agent.

Use it when you want Claude Code to:

Expand All @@ -212,12 +195,6 @@ $cc:rescue --model sonnet --effort medium investigate the flaky integration test
$cc:rescue --background investigate the regression
```

Notes:

- `--model` and `--effort` target the Claude runtime, not the Codex subagent.
- If you omit `--resume`, `--resume-last`, and `--fresh`, the plugin can offer to continue the latest Claude task for the current session.
- `--background` and `--wait` are Codex-side execution controls. The inner companion task still runs in the foreground inside its own subagent thread.

### `$cc:status`

Shows running and recent Claude Code jobs for the current repository.
Expand All @@ -229,12 +206,6 @@ $cc:status
$cc:status task-abc123
```

Use it to:

- check progress on background work
- see the latest completed job
- confirm whether a task is still running

### `$cc:result`

Shows the final stored Claude Code output for a finished job.
Expand Down Expand Up @@ -273,9 +244,7 @@ It also verifies:
- global `cc-rescue` registration
- current review-gate state for this workspace

If Claude Code is missing and `npm` is available, the setup flow can direct you to install it.

#### Enabling the review gate
#### Enabling Review Gate

```text
$cc:setup --enable-review-gate
Expand All @@ -297,74 +266,24 @@ $cc:status
$cc:result
```

### Challenge a Design Choice
### Challenge A Design Choice

```text
$cc:adversarial-review --background question the retry, rollback, and caching strategy
```

### Hand a Problem to Claude Code
### Hand A Problem To Claude Code

```text
$cc:rescue fix the failing test with the smallest safe patch
```

### Continue a Previous Claude Task
### Continue A Previous Claude Task

```text
$cc:rescue --resume apply the top fix from the last run
```

## Claude Code Integration

This plugin mirrors the upstream OpenAI plugin's command set and stop-review-gate semantics as closely as Claude Code allows, but the implementation has to match Claude's CLI-oriented runtime:

- `scripts/claude-companion.mjs` owns setup, review launches, tracked jobs, status/result/cancel, and stop-gate integration.
- `scripts/lib/claude-cli.mjs` wraps `claude -p` and parses `stream-json` output.
- `hooks/hooks.json` installs `SessionStart`, `SessionEnd`, `Stop`, and `UserPromptSubmit` hooks into Codex.
- Read-only reviews are enforced through Claude tool allowlists and temporary settings files, because Claude Code does not expose Codex's OS-level sandbox model.
- Nested rescue subagent sessions suppress interactive hooks so unread-result prompts and stop-time reviews stay attached to the user-facing Codex session instead of child helper sessions.

At a high level, the runtime looks like this:

```text
Codex (host)
└── Claude Code plugin
├── skills/*
├── hooks/*
├── agents/cc-rescue.toml (template)
└── scripts/claude-companion.mjs
└── scripts/lib/claude-cli.mjs
└── claude -p
```

## Development

Run the local test suite with:

```bash
npm test
npm run test:integration
npm run test:e2e
```

If you change hooks, skills, or the installed rescue agent contract, rerun:

```bash
node scripts/install-hooks.mjs
```

To enable local Git hooks for lint and typecheck before each commit, run:

```bash
npm run setup:git-hooks
```

## Acknowledgements

- Inspired by [openai/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Built as a reverse Codex-to-Claude companion for users who prefer to stay inside Codex

## License

Apache-2.0
1 change: 1 addition & 0 deletions scripts/prepare-marketplace-plugin.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ if (!DEST) {

const INCLUDED_PATHS = [
".codex-plugin",
"CHANGELOG.md",
"LICENSE",
"NOTICE",
"README.md",
Expand Down