From 8bdc1bdadf09b143293b3255723435d7face2ebe Mon Sep 17 00:00:00 2001 From: jinku Date: Sun, 5 Apr 2026 07:16:41 -0700 Subject: [PATCH 1/2] Rewrite README to match upstream structure --- README.md | 133 +++++++++++------------------------------------------- 1 file changed, 26 insertions(+), 107 deletions(-) diff --git a/README.md b/README.md index 429bdce..d96d9d3 100644 --- a/README.md +++ b/README.md @@ -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 @@ -23,12 +21,9 @@ 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 @@ -36,49 +31,37 @@ The biggest structural difference is runtime shape: Codex exposes a persistent a - 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 { @@ -91,7 +74,7 @@ Example entry: "name": "cc", "source": { "source": "local", - "path": "/absolute/path/to/cc-plugin-codex" + "path": "./plugins/cc" }, "policy": { "installation": "AVAILABLE", @@ -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 @@ -144,8 +129,6 @@ $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. @@ -153,7 +136,7 @@ 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 `, `--scope `, `--wait`, `--background`, and `--model `. @@ -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` @@ -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 `, and also accepts extra focus text after the flags. @@ -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: @@ -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. @@ -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. @@ -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 @@ -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 From 9fb0417455d176e4f28e75272631bf0927c3cd01 Mon Sep 17 00:00:00 2001 From: jinku Date: Sun, 5 Apr 2026 07:23:29 -0700 Subject: [PATCH 2/2] Prepare v1.0.0 release --- CHANGELOG.md | 7 +++++++ scripts/prepare-marketplace-plugin.mjs | 1 + 2 files changed, 8 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..636c730 --- /dev/null +++ b/CHANGELOG.md @@ -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. diff --git a/scripts/prepare-marketplace-plugin.mjs b/scripts/prepare-marketplace-plugin.mjs index f31ca0c..cdda0a2 100644 --- a/scripts/prepare-marketplace-plugin.mjs +++ b/scripts/prepare-marketplace-plugin.mjs @@ -22,6 +22,7 @@ if (!DEST) { const INCLUDED_PATHS = [ ".codex-plugin", + "CHANGELOG.md", "LICENSE", "NOTICE", "README.md",