cc-delegate

# cc-delegate > WorkBuddy standard entrance skill for commanding local Claude Code to perform long tasks and seamlessly hand over without losing memory. > Current version: **v1.10.3** (all defects cleared, 46/47 tests passed) ## Brief Introduction You (using WorkBuddy on your computer) want to instruct another "construction team" - local Claude Code - to perform a task that can be divided into several parts (e.g., video editing, writing long documents, or refactoring code in stages). This skill set is the **general contractor**: responsible for assigning tasks, monitoring progress, and accurately reassigning tasks if needed, while ensuring that the construction team remembers the previous task. ## What Problems Does It Solve Ordinary methods of calling Claude Code have a significant drawback: each call is a "blank slate," and the previous task is forgotten. Long tasks cannot be completed in one go, and if the task is too large, it cannot be handled. cc-delegate solves this problem in two ways: 1. **Handover Key (Stateful Mode)**: Use WorkBuddy's Bash to directly call the local `claude` command line, and in the first step, record its "session ID." Subsequent steps use this key (`--resume`) to continue the task, and Claude Code natively remembers the cross-call context. 2. **Handover Note (HANDOFF fallback)**: Each time a task is assigned, Claude Code leaves a note in the directory, detailing "whether the task is completed / where it was completed / what to do next." This approach is resistant to restarts and key loss. Additionally, it includes three layers of insurance, real-time monitoring, and a session registry to ensure that remote or next-day continuation of tasks does not get混乱. ## Architecture Overview (30-second summary) ### cc-delegate = MCP Bridge + Skill Intelligence | Layer | Who | Function | |------|--------|------| | **MCP Bridge** (`@steipete/claude-code-mcp`) | steipete (open-source community, MIT license) | Packages local Claude Code CLI into an MCP tool for WorkBuddy to call | | **cc-delegate Skill** | Us (gugug168 + WB Assistant) | Builds a scheduling system on the bridge: memory handover, progress monitoring, accurate killing, session registry, and window polling | > Analogy: **steipete built the highway (MCP Bridge), and we run a smart logistics system (cc-delegate) on it.** The highway only ensures that cars can pass through, while the logistics system handles scheduling, tracking, anti-loss, and continuation. ### Data Flow ``` Your instruction ("CC go to E:/AI generate video script") ↓ WorkBuddy dialogue layer ↓ ┌─────────────────────┬──────────────────────┐ │ Channel 1 MCP │ Channel 2 Bash direct │ │ WB → MCP Bridge → CC │ WB → Bash → CC │ │ Simple single task │ Long task / needs memory │ │ Parameters: only pass │ Parameters: all free │ │ prompt + workFolder │ --resume / --perm etc. │ └─────────────────────┴──────────────────────┘ ↓ Claude Code CLI (local) ↓ Product falls into workFolder directory ``` ### MCP Bridge Parameters: Official 6, WB only passes 2 The MCP Bridge's `claude_code` tool defines 6 parameters, but **WB's connector layer does whitelist cutting**: | Parameter | Official support | WB can use? | What to do | |------|:--:|:--:|------| | `prompt` | ✅ | ✅ | Direct pass | | `workFolder` | ✅ | ✅ | Specify CC working directory | | `sessionId` | ✅ | ❌ Cut off | → Use Bash channel `claude --resume` | | `permissionMode` | ✅ | ❌ Cut off | Default bypassPermissions, usually no need to change | | `messages` | ✅ | ❌ Cut off | Advanced scenarios only | | `stateless` | ✅ | ❌ Cut off | No --resume means stateless | > For a complete in-depth analysis of the architecture, see **[ARCHITECTURE.md](ARCHITECTURE.md)**. ## Features | Feature | Description | |---|---| | Standard delegation entrance | Calling represents "commanding CC to work," automatically completing MCP acceptance → directory pre-check → delegation → post-verification → audit reporting | | Stateful handover | Bash directly calls `claude` CLI + `--resume <sid>`, bypassing MCP parameter whitelist, CC native memory cross-call context | | Session registry | Centralized registry "project name → session number / working directory / progress," next day or remote continuation, automatically find the session to resume | | Real-time process monitoring | Assign a monitor to see what CC is doing, whether it's stuck, and accurately kill **only this** process if stuck, without harming history | | Mandatory audit | Read CC's local original dialogue record, report which skills were called, which files were moved, and the process is traceable | | Stateful handover HANDOFF | Each task assigned, CC writes a handover document, single task marked `STATUS: DONE`, multi-step marked `IN_PROGRESS` + next step | | Window polling | WB in the current window polls the "glass board" status every 30 seconds (DONE / needs selection / in progress), long tasks rely on multi-round splicing to support arbitrary duration, single window closed loop without interruption | ## Directory Structure ``` cc-delegate/ ├── SKILL.md # Skill main document (user manual + configuration + pit record + iteration record) ├── ARCHITECTURE.md # Architecture overview (MCP Bridge vs. skill / dual channels / parameter whitelist / decision tree) ├── scripts/ │ ├── cc_delegate.py # Call encapsulation: assemble instruction, parse receipt, decide next step, write glass board + charter │ ├── poll_tick.py # Window polling single query board: read glass board status → output DONE / needs selection / in progress / BLOCKED / abnormal │ ├── cc_monitor.py # Real-time monitoring CC progress, accurate killing, extracting session number (SID) │ └── session_registry.py # Session registry: register / lookup / list / close ├── references/ │ ├── audit-parsing.md # Audit parsing details (how to read CC's original dialogue record) │ └── monitor-reference.md # Monitoring script complete parameter table and advanced usage ├── mcp-config.example.json # MCP Bridge configuration reference template (copy to ~/.workbuddy/mcp.json and append) ├── README.md ├── LICENSE └── .gitignore ``` > Runtime generated `sessions.json` (registry data) and `__pycache__/` are not included in the repository, see `.gitignore`. ## Installation ### Step 1: Install MCP Bridge (one-time) cc-delegate relies on `claude-code-mcp` MCP Bridge to connect WorkBuddy and local Claude Code. The configuration file is `~/.workbuddy/mcp.json` (⚠️ note: no dot prefix, not `.mcp.json`). In the `"mcpServers"` section of `mcp.json`, add: ```json "claude-code-mcp": { "type": "stdio", "command": "npx", "args": ["-y", "@steipete/claude-code-mcp@latest"], "runtime": {"type": "node", "version": ">=20"}, "timeout": 600000, "disabled": false } ``` > Complete template see `mcp-config.example.json` in the repository; note not to delete other existing servers (e.g., `connector-proxy`). After configuration: 1. Save JSON (use `python -m json.tool` to verify legality) 2. **Restart WorkBuddy** (MCP tool loads at startup, changes take effect after restart) 3. Open a new session → settings may have a popup, **approve** the server 4. Verification: in a new session, ask "Help me search for `claude_code` tool using ToolSearch," and if it's found, the bridge is connected. > If encountering `npx` timeout (sandbox blocking network package), install locally: `npm install -g @steipete/claude-code-mcp`, then change `command` to the absolute path of `node_modules/.bin/claude-code-mcp`. ### Step 2: Install Skill ```bash git clone https://github.com/gugug168/cc-delegate.git \ "$HOME/.workbuddy/skills/cc-delegate" ``` After restarting WorkBuddy, say "Call Claude Code to do XXX" or "Let CC continue doing" to trigger. ### Prerequisites Summary | Condition | Description | |------|------| | WorkBuddy | Installed and logged in | | MCP Bridge | `claude-code-mcp` configured in `~/.workbuddy/mcp.json` and restarted + approved | | Claude Code CLI | `claude` command available in terminal | | Node.js | >= 20 (MCP Bridge runtime requirement) | | Python | 3.10+ (skill script pure standard library, no pip package required) | ## Usage ### Scenario 1: Divide a Long Task into Two Parts (Stateful Handover) **Part 1** (no key, automatically start and record session number): ```bash SID=$(python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_monitor.py" \ --workfolder "<your working directory>" --marker "TID=demo_p1" --print-sid) claude --dangerously-skip-permissions -p "<Part 1 task prompt>" ``` **Part 2** (take key handover, CC remembers Part 1): ```bash claude --dangerously-skip-permissions -p "<Part 2 task prompt>" --resume "$SID" ``` ### Scenario 2: Real-time Monitoring / Accurate Termination ```bash # See what CC is doing, whether it's stuck python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_monitor.py" \ --workfolder "<your working directory>" --marker "TID=demo_p1" # Confirm stuck and not a legitimate long task, accurately terminate this (no harm to history) python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_monitor.py" \ --workfolder "<your working directory>" --marker "TID=demo_p1" --kill ``` ### Scenario 3: Session Registry (Next-day Continuation) ```bash # Register this session python "$HOME/.workbuddy/skills/cc-delegate/scripts/session_registry.py" \ register --project 我的项目 --sid "$SID" --workfolder "<path>" --marker "TID=demo_p1" # Next day remote access, automatically find the session number to resume SID=$(python "$HOME/.workbuddy/skills/cc-delegate/scripts/session_registry.py" \ lookup --project 我的项目) ``` See `references/monitor-reference.md` and `SKILL.md` for more complete parameters and decision trees. ### Scenario 4: Window Polling (Long Task Single-window Closed Loop) ```bash # 1. Write task charter (general contractor with judgment, even if awakened, knows when to decide and when to call) python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_delegate.py" \ write-charter --workfolder "<working directory>" --json '{"task":"write report","auto_actions":["IN_PROGRESS:CONTINUE"]}' # 2. Assign CC to work (background), WB in current window checks every 30 seconds python "$HOME/.workbuddy/skills/cc-delegate/scripts/poll_tick.py" \ --workfolder "<working directory>" # Output: DONE (finished) / NEEDS_USER_INPUT (ask) / IN_PROGRESS (continue waiting) / BLOCKED (reassign) # 3. Post-completion cleanup python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_delegate.py" \ parse --workfolder "<working directory>" # Parse receipt python "$HOME/.workbuddy/skills/cc-delegate/scripts/cc_delegate.py" \ decide --workfolder "<working directory>" # Decide next step (CONSUME=finished / RETRY=reassign / ESCALATE=call) ``` > Long tasks (>8 minutes) rely on WB dialogue-level multi-round splicing to support arbitrary duration, each round checking glass board status without losing, single window uninterrupted. ## License [MIT](LICENSE) —— Use, modify, and redistribute freely, just keep the origin.