Claude Code Worker (cc-bridge)

Run the interactive claude CLI so that both you and a boss Claude session can drive the same run. With the MCP server, one boss session — Claude Code CLI or Claude Desktop, the same rules in both — can start and drive CLI "worker" runs: hand out tasks, answer the workers' questions, and review their work at the end. Design: DESIGN.md. Plan: PLAN.md.

Install as a Claude Code plugin (cli-workers)

Windows (ConPTY), Node 24+, and the claude CLI on PATH; git for worktrees. macOS and Linux should work (prebuilt node-pty binaries, hidden runs only, ask dialog via osascript / zenity) but are untested. Check a setup with node cc-ctl.mjs doctor or the cc_doctor tool.

claude plugin marketplace add Rayudu0729/claude-code-worker
claude plugin install cli-workers@cli-workers

Or inside a session: /plugin marketplace add Rayudu0729/claude-code-worker, then /plugin install cli-workers@cli-workers. Start a new session afterwards.

The plugin brings:

To use the tools without permission prompts, add "permissions": { "allow": ["mcp__plugin_cli-workers_claude-code-worker"] } to ~/.claude/settings.json.

Manual install (without the plugin system)

git clone https://github.com/Rayudu0729/claude-code-worker $HOME\.claude\tools\cc-bridge
cd $HOME\.claude\tools\cc-bridge
npm ci
node smoke.mjs
claude mcp add -s user claude-code-worker -- node $HOME\.claude\tools\cc-bridge\cc-mcp.mjs

The boss rules are then in skills/worker-boss/SKILL.md; copy them into ~/.claude/CLAUDE.md.

Related MCP server: pokeclaw

Start a run (in your terminal; uses your CLI account)

node $HOME\.claude\tools\cc-bridge\cc-bridge.mjs start <name>
node $HOME\.claude\tools\cc-bridge\cc-bridge.mjs start <name> -- claude "/review"

Type in it as usual. It ends when claude exits.

Control it (from the boss session)

node $HOME\.claude\tools\cc-bridge\cc-ctl.mjs <command> <name> ...

Exit 3 = not running. Control is on 127.0.0.1 only, with a per-run token in %LOCALAPPDATA%\cc-bridge\<name>.json (removed on exit).

MCP server (native tools for the boss: Claude Code CLI or Desktop)

cc-mcp.mjs exposes the same controls as MCP tools, as the MCP server claude-code-worker. Through the plugin the tools appear as mcp__plugin_cli-workers_claude-code-worker__cc_*; with a manual install as mcp__claude-code-worker__cc_*, registered with:

claude mcp add -s user claude-code-worker -- node $HOME\.claude\tools\cc-bridge\cc-mcp.mjs

Runs started by the MCP server drop the host session's CLAUDECODE, CLAUDE_CODE_*, CLAUDE_AGENT_SDK_*, ANTHROPIC_BASE_URL etc. so they behave like a run from your own shell; any of those you set in your Windows user or system environment are kept. Hidden runs log the terminal stream to %LOCALAPPDATA%\cc-bridge\<name>.log.

Parallel work, queue and events

• Worktrees. cc_start with worktree: true creates <repo>-worktrees/<name> on branch worker/<name> (or the branch you name) from HEAD, so parallel workers never edit the same files. Uncommitted changes in the main checkout are not carried over. A new worktree's folder-trust prompt is accepted automatically. Merge the branch yourself, then cc_worktree remove (with delete_branch).

• Queue. cc_queue_add takes tasks { id, prompt, depends_on, ...cc_start options }. The MCP server checks the queue every 3 s, starts a task's worker once its dependencies are done, waits for the prompt, and sends the brief. States: pending → starting → running ⇄ needs_input → done | failed | blocked | cancelled. A task whose dependency fails is blocked. Finished workers stay up for review. The scheduler only runs while the boss session is open.

• Events. Each bridge watches its screen; when a claude turn ends it appends to %LOCALAPPDATA%\cc-bridge\events.jsonl: done (ended with a Worker report or a fresh JSON report), permission (a menu waits), question (anything else), plus exited, restarted, over_budget. Run the wait_any_command in the background and you are woken by the first worker that needs you.

• Reports. Workers also write their report as JSON to %LOCALAPPDATA%\cc-bridge\reports\<name>.json (the folder is passed with --add-dir). cc_wait since_send shows it first; cc_report returns it.

• Restarts. Each claude worker gets a --session-id. If it exits non-zero without cc_stop, the bridge restarts it with --resume <id> (or the original command when there was no conversation yet), up to restart times.

• Budgets. Token use is read from the worker's transcript (~/.claude/projects/*/<session id>.jsonl): tokens = input + cache writes + output, cache_read and the current context apart. It updates as claude writes messages (after a turn or tool approval). With budget_tokens the bridge stops the worker once tokens passes it.

• Roles. role: implementer (sonnet), explorer (haiku, plan mode, read-only), tester (sonnet), reviewer (opus, plan mode), docs (sonnet, low effort). Add or override in ~/.claude/cc-workers/roles.json: { "<role>": { "model", "effort", "permission_mode", "prompt" } }. Explicit cc_start arguments win.

Asking the user with a timeout

cc_ask_user shows a topmost dialog (Windows: one button per option, a free-text box, a countdown) that closes after timeout_sec (default 120). The call waits up to 50 s and returns pending with an id for cc_ask_result if the dialog is still open. If the user does not answer, the boss analyzes the question, picks the best option itself, says why, and lists it as a decision in its final summary; for risky or irreversible choices it picks the safe option.

Test

node $HOME\.claude\tools\cc-bridge\smoke.mjs
node $HOME\.claude\tools\cc-bridge\mcp-smoke.mjs [--visible]