{"_id":"@anyi611/codex-claude-delegate-mcp","_rev":"2-889795217b70b7afb63b7d338e48141c","name":"@anyi611/codex-claude-delegate-mcp","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@anyi611/codex-claude-delegate-mcp","version":"0.1.0","license":"MIT","_id":"@anyi611/codex-claude-delegate-mcp@0.1.0","maintainers":[{"name":"anyi611","email":"xuewenchen182@gmail.com"}],"bin":{"codex-claude":"dist/cli.js"},"dist":{"shasum":"fc683dd417a8d4468b7d11d9d6a1585feb202181","tarball":"https://registry.npmjs.org/@anyi611/codex-claude-delegate-mcp/-/codex-claude-delegate-mcp-0.1.0.tgz","fileCount":42,"integrity":"sha512-FqG2vTFImnTDXwElZwiyUF9eic8WPNQiuEaUedZ1JP+7uu80ZM+1DZW5vzfn2juvgYD8hSq2eM5RDRKr2jXv0Q==","signatures":[{"sig":"MEUCIEYwOR8Sh3MGmy59MIZZ94YTI1Ct3rHChkTfxBk1Fao+AiEAyCqPqCLU+ZPsIbq4b1VLLS6xZ6jUHYZIq+P/2w6tthI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2256514},"main":"dist/server.js","type":"module","types":"./dist/server.d.ts","engines":{"node":">=20"},"gitHead":"cf2f1c86e6f3a8292473184b1a41af3db53580f2","scripts":{"dev":"tsx src/cli.ts","test":"vitest run","build":"tsc","start":"node dist/cli.js","typecheck":"tsc --noEmit","uninstall":"npm run build && node scripts/uninstall-plugin.mjs","audit:docs":"node --import tsx debug/doc-audit.ts","test:watch":"vitest","build:plugin":"esbuild src/server.ts src/job-runner.ts --bundle --platform=node --target=node22 --format=esm --packages=bundle --outdir=plugins/codex-claude-delegate/server --outbase=src","check:plugin":"node scripts/check-plugin.mjs","prepublishOnly":"npm run build && npm run typecheck && npm test && npm run build:plugin && npm run check:plugin","uninstall:dry-run":"node scripts/uninstall-plugin.mjs --dry-run"},"_npmUser":{"name":"anyi611","email":"xuewenchen182@gmail.com"},"_npmVersion":"11.12.1","description":"MCP server that lets Codex CLI delegate tasks to Claude Code","directories":{},"_nodeVersion":"25.9.0","dependencies":{"zod":"^4.4.2","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^3.2.4","esbuild":"^0.25.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/codex-claude-delegate-mcp_0.1.0_1778321694695_0.17926047473265427","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@anyi611/codex-claude-delegate-mcp","version":"0.1.1","description":"MCP server that lets Codex CLI delegate tasks to Claude Code","license":"MIT","type":"module","main":"dist/server.js","bin":{"codex-claude":"dist/cli.js"},"engines":{"node":">=20"},"scripts":{"build":"tsc","build:plugin":"esbuild src/server.ts src/job-runner.ts --bundle --platform=node --target=node22 --format=esm --packages=bundle --outdir=plugins/codex-claude-delegate/server --outbase=src","check:plugin":"node scripts/check-plugin.mjs","start":"node dist/cli.js","dev":"tsx src/cli.ts","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit","prepublishOnly":"npm run build && npm run typecheck && npm test && npm run build:plugin && npm run check:plugin","uninstall":"npm run build && node scripts/uninstall-plugin.mjs","uninstall:dry-run":"node scripts/uninstall-plugin.mjs --dry-run","audit:docs":"node --import tsx debug/doc-audit.ts"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","zod":"^4.4.2"},"devDependencies":{"@types/node":"^22.0.0","esbuild":"^0.25.0","tsx":"^4.0.0","typescript":"^5.7.0","vitest":"^3.2.4"},"gitHead":"cf2f1c86e6f3a8292473184b1a41af3db53580f2","types":"./dist/server.d.ts","_id":"@anyi611/codex-claude-delegate-mcp@0.1.1","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-sYyIar14ed1X0Dc6BQYMEF8Ekt6HOBcDvEI4QeCZaaIaYCHSOnoTkBjCahg9VoPTKCj6vkNbNJuxDuyrKu2Shg==","shasum":"5dd8b45a1b969bc348bc9938fedf63f77e3d9c54","tarball":"https://registry.npmjs.org/@anyi611/codex-claude-delegate-mcp/-/codex-claude-delegate-mcp-0.1.1.tgz","fileCount":42,"unpackedSize":2256514,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCcl2cwMR5WNVTE5fcDf7ja77RXZ9yzGduJTSy1GnLclgIhAMbkJRysVqN9m2t5z714whiQuTBJFAY6hTauv1MwSZEs"}]},"_npmUser":{"name":"anyi611","email":"xuewenchen182@gmail.com"},"directories":{},"maintainers":[{"name":"anyi611","email":"xuewenchen182@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/codex-claude-delegate-mcp_0.1.1_1778321826577_0.8923250910845462"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-09T10:14:54.587Z","modified":"2026-05-09T10:17:06.910Z","0.1.0":"2026-05-09T10:14:54.902Z","0.1.1":"2026-05-09T10:17:06.782Z"},"license":"MIT","description":"MCP server that lets Codex CLI delegate tasks to Claude Code","maintainers":[{"name":"anyi611","email":"xuewenchen182@gmail.com"}],"readme":"# codex-claude-delegate-mcp\n\nLet Codex delegate read/review/write tasks to Claude Code through a local MCP server.\n\n## Quick Start\n\n```bash\nnpm install -g @anyi611/codex-claude-delegate-mcp\ncodex-claude setup --write\ncodex-claude doctor\n```\n\nRestart Codex, then ask:\n\n```text\nUse claude_setup to check this repository.\n```\n\n### 60-Second Demo\n\n```text\n1. claude_setup                          → checks workspace readiness\n2. claude_task(mode=\"read\", ...)         → delegate a read analysis\n3. claude_task(mode=\"write\", ...)        → delegate a write task with instruction_files\n4. claude_job_wait(...)                  → poll until the job completes\n5. claude_result(...)                    → inspect results and changed files\n6. claude_apply(preview=true, ...)       → preview the diff\n7. user approval                         → user confirms\n8. claude_apply(cleanup=true, ...)       → apply changes and clean up worktree\n9. claude_cleanup(dry_run=true, ...)     → confirm no stale worktrees remain\n```\n\n## Features\n\n- **Delegate read/review/write tasks** — from Codex to Claude Code\n- **Isolated git worktree execution** — write tasks run in a separate worktree, leaving your main workspace untouched\n- **Background job polling** — all delegations are queued as background jobs with progress tracking\n- **Preview before apply** — review worktree diffs before landing changes in your main workspace\n- **Review gate** — optional stop-hook that prompts review before terminal state transitions\n\n## Install\n\n### Prerequisites\n\n- Codex CLI installed and authenticated\n- `node` >= 20 available in PATH\n- Claude Code CLI `claude` available in PATH (or set `CLAUDE_BIN`)\n- Git (write mode requires worktree support)\n\n### Global install (recommended)\n\n```bash\nnpm install -g @anyi611/codex-claude-delegate-mcp\n```\n\nVerify installation:\n\n```bash\ncodex-claude --version\n```\n\n### Setup\n\nWrite the MCP server configuration to Codex config:\n\n```bash\ncodex-claude setup --write\n```\n\nThis adds `command = \"codex-claude\"` with the default 6 tools to `~/.codex/config.toml`.\n\nOptions:\n\n| Flag | Description |\n|------|-------------|\n| `--force` | Overwrite existing claude_delegate config (creates timestamped backup) |\n| `--allow-root <path>` | Add a repository to `CODEX_CLAUDE_ALLOW_ROOTS` |\n| `--project` | Write to `./.codex/config.toml` instead of global config |\n| `--print` | Preview the config that would be written |\n\n### Doctor\n\nVerify your installation:\n\n```bash\ncodex-claude doctor\n```\n\nChecks Node.js ≥ 20, package version, Claude CLI path/version, Git, worktree support, Codex config, default tools, and allow roots.\n\n```bash\ncodex-claude doctor --json\n```\n\n### Print config\n\nSee the MCP server TOML config without writing:\n\n```bash\ncodex-claude print-config\ncodex-claude print-config --source /path/to/repo\ncodex-claude print-config --project\n```\n\n## Default tool set\n\n`setup --write` and `print-config` enable exactly 6 tools:\n\n| Tool | Usage |\n|------|-------|\n| `claude_setup` | First-use / check workspace readiness |\n| `claude_task` | **Recommended entry point**, auto-routes to read/review/write |\n| `claude_job_wait` | Poll background job until terminal state |\n| `claude_result` | Get the most relevant completed result + next_actions |\n| `claude_apply` | Preview or land worktree changes into main workspace |\n| `claude_cleanup` | Remove stale delegated worktrees (defaults to dry-run) |\n\n## Usage flow\n\n### Read-only analysis\n\n```text\nclaude_task(mode=\"read\", cwd=\"/path/to/repo\", task=\"Explain how auth works\")\n  → claude_job_wait(cwd=\"...\", job_id=\"job-xxx\")\n  → claude_result(cwd=\"...\", prefer=\"latest-job\")\n```\n\n### Review / audit\n\n```text\nclaude_task(mode=\"review\", cwd=\"/path/to/repo\", task=\"Check for security issues\")\n  → claude_job_wait → claude_result\n```\n\n### Write / apply / cleanup\n\n```text\nclaude_task(mode=\"write\", cwd=\"/path/to/repo\", task=\"Implement feature X\")\n  → claude_job_wait(cwd=\"...\", job_id=\"...\")\n  → claude_result(cwd=\"...\")\n  → claude_apply(cwd=\"...\", worktree_path=\".claude/worktrees/...\", preview=true)\n  → user confirms → claude_apply(cwd=\"...\", worktree_path=\"...\", cleanup=true, confirmed_by_user=true)\n  → claude_cleanup(cwd=\"...\", dry_run=true)\n```\n\n## Advanced / Debug tools\n\nThese tools are NOT in the default config. Enable them explicitly in `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.claude_delegate]\nenabled_tools = [\"claude_status\", \"claude_runs\", \"claude_run_inspect\", \"claude_workspace_status\", \"claude_review_gate\", \"claude_query\", \"claude_review\", \"claude_implement\", \"claude_jobs\", \"claude_job_result\", \"claude_job_cancel\", \"claude_job_cleanup\"]\n```\n\n| Tool | Purpose |\n|------|---------|\n| `claude_status` | Check Claude/Git/worktree/auth status |\n| `claude_runs` | List historical run logs |\n| `claude_run_inspect` | View single run details by run_id |\n| `claude_workspace_status` | Aggregated view: jobs / runs / sessions / worktrees |\n| `claude_review_gate` | Enable/disable/status review gate |\n| `claude_query` | Read-only Q&A (low-level entry) |\n| `claude_review` | Read-only review (low-level entry) |\n| `claude_implement` | Isolated worktree implementation (low-level entry) |\n| `claude_jobs` | List background jobs |\n| `claude_job_result` | Read job by job_id |\n| `claude_job_cancel` | Cancel a running job |\n| `claude_job_cleanup` | Clean old terminal job records |\n\n## Important notes\n\n- **`claude_task.files` is deprecated.** Use `instruction_files` instead. `claude_task.files` is treated as context only, not apply scope.\n- **`claude_implement.files`** is a strict scope control for cases where precise file constraints are needed.\n- **Uncommitted workspace changes:** Default returns `needs_user`. Pass `dirty_policy=committed` to ignore local changes, or `dirty_policy=snapshot` to copy dirty files into the worktree.\n- **Polling behavior:** `claude_job_wait` does not long-block. When `poll_too_soon=true`, wait until `next_allowed_poll_at`. When `waiting=true`, do not start a duplicate job.\n- **Turn caps:** `claude_task` does not accept `max_turns`. Use Advanced tools (`claude_query` / `claude_review` / `claude_implement`) when explicit turn limits are needed.\n- **Apply safety:** `preview=true` does not modify the main workspace. Non-preview `claude_apply` requires `confirmed_by_user=true` after user approval.\n- **Invalid combination:** `preview=true` + `cleanup=true` is rejected — preview should not delete the worktree.\n- **Next actions:** `claude_result` and `claude_job_wait` only suggest preview operations (`preview=true`), never direct non-preview apply.\n\n## Configuration\n\n### Allow roots\n\nDefault allowed roots are `~/projects`, `~/work`, `~/codex-claude`. Extend via:\n\n```toml\n# ~/.codex/config.toml\n[shell_environment_policy.set]\nCODEX_CLAUDE_ALLOW_ROOTS = \"/Users/you/projects:/Users/you/work:/Users/you/my-repo\"\n```\n\nOr use the CLI:\n\n```bash\ncodex-claude setup --write --allow-root \"$(pwd)\"\n```\n\n### Development / maintenance\n\nIf you are a maintainer building from source:\n\n```bash\ngit clone https://github.com/anyi61/codex-claude.git\ncd codex-claude\nnpm install\nnpm run build:plugin\nnpm run check:plugin\n```\n\nThe plugin directory (`plugins/`) remains as internal packaging. For development, use `npm run dev` or `npm run build`.\n\n## Troubleshooting\n\n| Problem | Fix |\n|---------|-----|\n| `claude` command not found | Install Claude Code CLI or set `CLAUDE_BIN` |\n| cwd outside allowed roots | `codex-claude setup --write --allow-root \"$(pwd)\"` |\n| Dangerous allow root | Use a specific repo path, not `/`, `/tmp`, `/etc`, or `$HOME` |\n| `poll_too_soon=true` | Wait until `next_allowed_poll_at`, do not start a new task |\n| `waiting=true` | Continue polling the same `job_id`, do not re-delegate |\n| Stale job | Use claude_result to inspect; with Advanced tools, claude_job_cancel may help |\n| Apply refused: dirty workspace | Commit/stash changes, or use `dirty_policy=committed` |\n| Missing `confirmed_by_user` | Show the preview and get explicit user approval before applying |\n| `preview=true` + `cleanup=true` | Split into preview and confirmed apply+cleanup |\n| Leftover worktrees | `claude_cleanup(cwd=\"...\", dry_run=true)` then `dry_run=false` |\n\n## Uninstall\n\n```bash\nnpm uninstall -g @anyi611/codex-claude-delegate-mcp\n```\n\nTo also remove the MCP server configuration from Codex, delete the `[mcp_servers.claude_delegate]` section from `~/.codex/config.toml` manually.\n\n## Security\n\n- `spawn(\"claude\", args[])` — no shell injection\n- `--tools` / `--allowedTools` / `--disallowedTools` — three-layer tool control\n- `--permission-mode dontAsk` — non-interactive safe mode\n- `sanitizeEnv()` — minimal environment (strips API keys, tokens, SSH agent)\n- `BRIDGE_DEPTH` — recursion protection (≥2 refused)\n- `validateCwd()` — realpath + allow roots whitelist\n- `dangerousRoot()` — rejects `/`, `/tmp`, `/etc`, `$HOME`\n\n## Known limitations\n\n- No real-time bidirectional communication (Codex → Claude one-shot delegation)\n- ~2-5s cold start per Claude invocation\n- No automatic worktree cleanup (use `claude_cleanup`)\n- Old job records lack fingerprint/heartbeat; stale classification falls back to updated_at\n- Stale detection is advisory only, does not auto-kill processes\n\n## Maintainer release checklist\n\n```bash\nnpm run typecheck\nnpm test\nnpm run build:plugin\nnpm run check:plugin\nnpm pack --dry-run\n```\n","readmeFilename":"README.md"}