Add magic-cc-codex-worker

README-zh.md

@@ -59,6 +59,7 @@
 - [ceo-quality-controller-agent](./plugins/ceo-quality-controller-agent)
 - [claude-desktop-extension](./plugins/claude-desktop-extension)
 - [lyra](./plugins/lyra)
+- [magic-cc-codex-worker](./plugins/magic-cc-codex-worker)
 - [model-context-protocol-mcp-expert](./plugins/model-context-protocol-mcp-expert)
 - [problem-solver-specialist](./plugins/problem-solver-specialist)
 - [studio-coach](./plugins/studio-coach)

README.md

@@ -59,6 +59,7 @@ Install or disable them dynamically with the `/plugin` command — enabling you
 - [ceo-quality-controller-agent](./plugins/ceo-quality-controller-agent)
 - [claude-desktop-extension](./plugins/claude-desktop-extension)
 - [lyra](./plugins/lyra)
+- [magic-cc-codex-worker](./plugins/magic-cc-codex-worker)
 - [model-context-protocol-mcp-expert](./plugins/model-context-protocol-mcp-expert)
 - [problem-solver-specialist](./plugins/problem-solver-specialist)
 - [studio-coach](./plugins/studio-coach)

plugins/magic-cc-codex-worker/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "magic-codex",
+  "version": "0.3.3",
+  "description": "Parallel Codex workers inside Claude Code — multi-agent orchestration with git worktree isolation, resumable sessions, and dual-model PR review.",
+  "author": {
+    "name": "Wenqing Yu",
+    "url": "https://github.com/wenqingyu"
+  },
+  "homepage": "https://github.com/wenqingyu/magic-cc-codex-worker",
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "keywords": ["codex", "mcp", "agent", "claude-code"]
+}

plugins/magic-cc-codex-worker/.mcp.json

@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "magic-codex": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/index.js"],
+      "env": {
+        "MAGIC_CODEX_STATE_DIR": ".magic-codex"
+      }
+    },
+    "codex-raw": {
+      "command": "codex",
+      "args": ["mcp-server"]
+    }
+  }
+}

plugins/magic-cc-codex-worker/agents/implementer.md

@@ -0,0 +1,24 @@
+---
+name: implementer
+description: Delegates autonomous implementation work to a Codex agent running in an isolated git worktree. Use when the task is a self-contained code change (bug fix, feature addition, refactor) that can finish without interactive clarification. The Codex agent will create a branch, commit its work, and return a summary — Claude reviews the diff before merging. Do NOT use for exploratory work, research, or anything requiring cross-cutting synthesis across the codebase.
+tools: ["mcp__magic-codex__spawn", "mcp__magic-codex__status", "mcp__magic-codex__result", "mcp__magic-codex__merge", "mcp__magic-codex__discard"]
+---
+
+You coordinate a Codex implementer agent to do autonomous coding work on behalf of the main Claude conversation.
+
+**Protocol:**
+
+1. Call `spawn` with `role: "implementer"`, a clear prompt describing the task, and optionally `issue_id` / `base_ref`.
+2. Record the `agent_id`.
+3. Poll `status(agent_id)` every 20–30 seconds. Show concise progress updates ("still running, 2m elapsed").
+4. When status becomes `completed`:
+   - Fetch full `result(agent_id)` for the agent's summary.
+   - Inspect the worktree diff (path in `worktree_path`) via git commands or file reads.
+   - Report the diff summary + agent's notes back to the caller.
+   - Suggest `merge` (if work looks good) or `discard` (if not).
+5. When status becomes `failed`: report the error and the partial diff (if any) for inspection.
+
+**Never:**
+- Merge without the caller's approval.
+- Resume a cancelled agent without explicit ask — its work may not compose with later changes.
+- Discard a completed agent whose diff the caller hasn't seen.

plugins/magic-cc-codex-worker/agents/planner.md

@@ -0,0 +1,17 @@
+---
+name: planner
+description: Delegates planning work to a Codex planner agent (read-only, no worktree). Use when you want a second pass on an implementation plan, or when plan creation itself would consume significant Claude context. The Codex planner returns a structured markdown plan the caller can review, adopt, or reject.
+tools: ["mcp__magic-codex__spawn", "mcp__magic-codex__status", "mcp__magic-codex__result"]
+---
+
+You coordinate a Codex planner agent to produce an implementation plan for a task.
+
+**Protocol:**
+
+1. Call `spawn` with `role: "planner"` and a prompt that specifies the task + any constraints (tech stack, style, testing expectations).
+2. Poll `status(agent_id)` every 20 seconds.
+3. When status becomes `completed`, return the plan verbatim. Do not blend it with your own opinions — the caller wants a distinct second plan to compare against.
+
+**Prompt guidance:**
+
+Planning works best when the prompt includes: the problem statement, known constraints, acceptance criteria, and explicit non-goals. Ambiguous prompts produce shallow plans.

plugins/magic-cc-codex-worker/agents/reviewer.md

@@ -0,0 +1,20 @@
+---
+name: reviewer
+description: Runs a Codex-powered read-only code review using a SOTA GPT model. Use as a second-opinion reviewer alongside Claude's own review for PRs, contentious diffs, or security-sensitive changes. Useful precisely because it's a different model family — it catches different classes of issues than Claude does.
+tools: ["mcp__magic-codex__spawn", "mcp__magic-codex__status", "mcp__magic-codex__result"]
+---
+
+You coordinate a Codex reviewer agent to produce a code review report.
+
+**Protocol:**
+
+1. Call `spawn` with `role: "reviewer"`. Include `pr_number` if reviewing a PR. Construct a clear prompt describing what to review and what dimensions matter (correctness, security, tests, performance).
+2. Poll `status(agent_id)` every 20 seconds. Reviews usually complete within 2-5 minutes.
+3. When status becomes `completed`:
+   - Fetch full `result(agent_id)`.
+   - Return the Codex review verbatim to the caller, clearly labeled as "Codex (GPT) review".
+   - Do NOT summarize or merge it with Claude's review — the caller wants both raw perspectives for comparison.
+
+**Prompt guidance:**
+
+The reviewer is most valuable when asked for specifics: file:line citations, concrete failure modes, security concerns with data flow reasoning. Avoid "is this good?" — ask "what correctness, security, or test-coverage issues does this have?"

plugins/magic-cc-codex-worker/commands/cancel.md

@@ -0,0 +1,8 @@
+---
+description: Cancel a running Codex agent (optionally --force to also remove its worktree)
+disable-model-invocation: true
+---
+
+Parse `$ARGUMENTS`. First token is the agent_id. If `--force` appears anywhere, pass `force: true` (also removes the worktree + branch).
+
+Call `magic-codex` MCP tool `cancel` and report whether the worktree was preserved (the default) so the user can still inspect partial work.

plugins/magic-cc-codex-worker/commands/discard.md

@@ -0,0 +1,8 @@
+---
+description: Discard a terminal Codex agent's worktree and delete its branch
+disable-model-invocation: true
+---
+
+Parse `$ARGUMENTS` as `<agent_id>`. Call `magic-codex` MCP tool `discard`.
+
+If the agent is still running, explain the user must `/magic-codex:cancel` first. This action is irreversible; warn before proceeding on any agent whose work has not been reviewed.

plugins/magic-cc-codex-worker/commands/fan-out.md

@@ -0,0 +1,24 @@
+---
+description: Fan out multiple Codex implementer agents in parallel, one per subtask or per Linear epic child
+disable-model-invocation: true
+---
+
+Two modes based on `$ARGUMENTS`:
+
+**Mode 1: Epic fan-out (MF projects only).** If `$ARGUMENTS` is a Linear epic identifier (e.g. `TEAM-100`):
+1. Read the epic's child issues via Linear MCP (`mcp__claude_ai_Linear__list_issues` with `parentId: <epic-id>`).
+2. For each child whose status is Backlog or Todo, call `magic-codex` `spawn` with:
+   - `role: "implementer"`
+   - `prompt`: a clear task description from the child's title + description
+   - `issue_id`: the child's identifier
+3. Collect all `agent_id`s. Report: "Spawned N agents for epic TEAM-100 children: [list]."
+4. Suggest polling via `/magic-codex:status` (no args → all-agents table) until all terminal.
+
+**Mode 2: Inline list.** If `$ARGUMENTS` is a list of prompts separated by `---` or `;;`:
+1. Split into N prompts.
+2. Spawn one implementer per prompt (no `issue_id`).
+3. Return the agent_ids.
+
+**Guardrails:**
+- Warn if spawning more than 5 agents at once (resource concern, and most users want to review in batches).
+- If `get_delegation_policy` returns `minimal`, ask the user to confirm before fan-out (fan-out is high-delegation by definition).

plugins/magic-cc-codex-worker/commands/merge.md

@@ -0,0 +1,11 @@
+---
+description: Merge a completed Codex implementer's worktree back into its base_ref
+disable-model-invocation: true
+---
+
+Parse `$ARGUMENTS`: first token is `agent_id`. Optional flags:
+- `--strategy squash|ff|rebase` (default: squash)
+- `--keep-worktree` (don't auto-remove after)
+- `--message "commit msg"` (for squash strategy)
+
+Call `magic-codex` MCP tool `merge`. On success, show the merged SHA and base ref. On conflict or other failure, surface the error and suggest manual resolution inside the worktree.

plugins/magic-cc-codex-worker/commands/mode.md

@@ -0,0 +1,27 @@
+---
+description: View or set the magic-codex delegation level (minimal/balance/max)
+disable-model-invocation: true
+---
+
+If `$ARGUMENTS` is empty, call the `magic-codex` MCP tool `get_delegation_policy` and show the current level, its source (env/project/user/default), and a one-line summary of each level.
+
+Otherwise parse `$ARGUMENTS`. The first token must be one of `minimal`, `balance`, `max`. Optional flag `--project` writes the setting to the project repo instead of user-global.
+
+**Default behavior — user-global (affects every project for this user):**
+
+1. Ensure `~/.magic-codex/` directory exists (create it if missing).
+2. Write `~/.magic-codex/config.toml` with:
+   ```toml
+   [delegation]
+   level = "<value>"
+   ```
+   If the file already exists, preserve any other sections and only update the `[delegation]` block.
+3. Confirm: "Delegation level set to `<value>` (user-global at `~/.magic-codex/config.toml`). Affects every project for this user."
+
+**With `--project` flag — project-scoped (affects only this repo, team-wide when committed):**
+
+1. Resolve the repo root via `git rev-parse --show-toplevel`. If not inside a git repo, abort and tell the user to drop the flag to use the user-global form instead.
+2. Write `<repo-root>/magic-codex.toml` with the same `[delegation]` block.
+3. Confirm: "Delegation level set to `<value>` (project-scoped at `<repo-root>/magic-codex.toml`). Commit this file to share with your team."
+
+Precedence when the MCP server resolves the active level: `MAGIC_CODEX_DELEGATION_LEVEL` env var > project `magic-codex.toml` > user-global `~/.magic-codex/config.toml` > built-in default (`balance`).

plugins/magic-cc-codex-worker/commands/resume.md

@@ -0,0 +1,10 @@
+---
+description: Continue a completed/failed/cancelled Codex agent with a new prompt
+disable-model-invocation: true
+---
+
+Parse `$ARGUMENTS` as `<agent_id> <prompt...>`.
+
+Call `magic-codex` MCP tool `resume` with `agent_id` and `prompt`. If the tool rejects (still running, no thread_id, etc.), explain the reason clearly.
+
+After success, remind the user to poll `/magic-codex:status $agent_id`.

plugins/magic-cc-codex-worker/commands/review-pr.md

@@ -0,0 +1,19 @@
+---
+description: Spawn a Codex reviewer agent against a specific PR
+disable-model-invocation: true
+---
+
+Parse `$ARGUMENTS` as `<pr_number>`. Build a spawn input:
+
+```json
+{
+  "role": "reviewer",
+  "prompt": "Review PR #<pr_number> for correctness, security, test coverage, and edge cases. Return a structured report with file:line citations.",
+  "pr_number": <pr_number>,
+  "overrides": { "timeout_seconds": 900 }
+}
+```
+
+Call `magic-codex` MCP tool `spawn`. Return the `agent_id` and the full Codex reviewer output once `/magic-codex:status` shows it completed.
+
+Pair this with Claude's own review (either interactive or via `/mf-pr-reviewer` if present) to get a dual-model perspective — the Codex reviewer uses a different model stack and tends to flag different concerns.

plugins/magic-cc-codex-worker/commands/spawn.md

@@ -0,0 +1,14 @@
+---
+description: Launch a Codex agent in the background (implementer/reviewer/planner/generic)
+disable-model-invocation: true
+---
+
+Parse `$ARGUMENTS` as `<role> <prompt...>`. Valid roles: `implementer`, `reviewer`, `planner`, `generic`.
+
+Then call the `magic-codex` MCP tool `spawn` with:
+- `role`: the parsed role
+- `prompt`: the rest of the arguments
+
+Return the `agent_id` and remind the user they can check progress with `/magic-codex:status $agent_id`.
+
+If the user hasn't specified a role, default to `generic` and use the full `$ARGUMENTS` as prompt.

plugins/magic-cc-codex-worker/commands/status.md

@@ -0,0 +1,8 @@
+---
+description: Show status of Codex agents — one agent by id, or all
+disable-model-invocation: true
+---
+
+If `$ARGUMENTS` contains an agent_id (starts with `codex-`), call the `magic-codex` MCP `status` tool with `agent_id`. Otherwise call it with no args.
+
+Render the response as a compact table: agent_id, role, status, started_at, last_output_preview. For all-agent queries, include the summary counts.