Skip to content
Back to search

cc-wsl-handoff

SkillWorks with Claude CodeGitHub

Hand a build or coding task to headless Claude Code in WSL, stay idle while it runs, and wake on a signal when it stops. Use for any multi-step build delegated from a Desktop chat.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/0xjonty--cc-wsl-handoff/badge.svg)](/listings/0xjonty--cc-wsl-handoff)

HTML

<a href="/listings/0xjonty--cc-wsl-handoff"><img src="/api/listings/0xjonty--cc-wsl-handoff/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

In WSL:

git clone https://github.com/0xJonty/cc-wsl-handoff.git
cd cc-wsl-handoff && ./install.sh      # copies bin/cc-* to ~/bin

Then add `SKILL.md` as a skill in Claude.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 53 lines
  1. ---
  2. name: cc-wsl-handoff
  3. description: Hand a build or coding task to headless Claude Code in WSL, stay idle while it runs, and wake on a signal when it stops. Use for any multi-step build delegated from a Desktop chat.
  4. ---
  5. # cc-wsl-handoff
  6. Run a task with headless Claude Code in the user's WSL and stay idle while it works. When the run stops for any reason, it fires a one-shot wake-up into this chat. Never poll the log: each check re-reads the whole chat and burns usage.
  7. ## Requirements
  8. - `wsl-exec` (device bridge) and the `send_later` scheduling tool in this chat.
  9. - WSL scripts `~/bin/cc-run`, `~/bin/cc-run-inner`, `~/bin/cc-status`, `~/bin/cc-tail` (installed by this repo's `install.sh`). If any are missing, stop and tell the user.
  10. - WSL Claude Code with auto mode and the `RemoteTrigger` tool.
  11. ## Procedure
  12. 0. **Clarify before building.** Check the request for each item below. Ask only about the ones it doesn't settle, in a single AskUserQuestion call (up to 4 questions, with the recommended option first), before writing any spec or launching anything. If the user isn't there to answer (scheduled or unattended), use the defaults shown and state them at the top of the spec.
  13. - **Git / GitHub:**
  14. - Local git only, or a GitHub repo too?
  15. - If GitHub: the repo name, public or private, and the owner (default: the signed-in `gh` account).
  16. - When to commit and push: after each working milestone, or only at the end?
  17. - Default: local git, commit at milestones, no GitHub. Only push to a public repo if the user said public in so many words.
  18. - **Model and effort:**
  19. - Which model: Sonnet 5 (recommended for implementation), Opus (hard research or design), or the Claude Code default from settings.json.
  20. - Which effort: low, medium, high or xhigh, or the default.
  21. - Default: Claude Code's defaults.
  22. - **Location:** a new folder (and its name under `~/build/`) or an existing project path. Default: a new `~/build/<slug>`.
  23. - **Done criteria and limits:**
  24. - What counts as finished (tests passing, a smoke test, a deploy).
  25. - Which live or external actions are allowed: real accounts, sending, posting, deploys, sudo.
  26. - Which secrets or logins the build needs.
  27. - Any cost or time cap.
  28. - Default: tests plus a local smoke test, no live writes, no sudo.
  29. Put every answer into SPEC.md and the task prompt, so the headless run has them and never has to ask.
  30. 1. **Prepare.** Pick or create the project folder in WSL. For anything non-trivial, write a SPEC.md and a short project CLAUDE.md first. Write the task prompt to `<dir>/.cc/<name>.txt`. Make it self-contained: say the run is headless with no human, that it should make reasonable decisions and log them in DECISIONS.md, and that it must end with a status of done / next / blockers / questions.
  31. 2. **Model and effort.** Use what step 0 settled. Pass an empty string to use the Claude Code defaults. Do not use Haiku: auto mode does not apply to it, so its file writes get denied. If the user picks Haiku, explain this and suggest Sonnet 5.
  32. 3. **Schedule the wake-up.** Call `send_later` with `delay_minutes` set to about 2× the expected run time plus 10, as a fallback only. The message must name the folder and say: "read only <dir>/.cc/status.json". Keep the returned `trigger_id`.
  33. 4. **Launch.** Run `~/bin/cc-run <dir> <uuid> <prompt-file> new <trigger_id> "<model>" "<effort>"`, using `uuidgen` for the uuid and keeping it for resumes. Pass `""` for either to use the default. It must print `started sid ...`; if it prints FAILED, show the runner.log lines.
  34. 5. **Go idle.** Tell the user in one line what's running and that you'll wake when it stops. End the turn. Do not poll.
  35. 6. **On wake.** Call ReadNotifications. Then delete this wake-up with `delete_trigger(<trigger_id>)`: an early fire does not cancel its fallback time, so it would go off again later. If the notification was the fallback itself, deleting it is harmless. Then read only `<dir>/.cc/status.json`. If the fallback fired, also read `.cc/wake.log`.
  36. - `running`: the fallback fired before the run finished. Schedule a new `send_later` with a new fallback time. Re-point the running build at it by writing the new id to `<dir>/.cc/wake-trigger` (`printf %s <new trigger_id> > <dir>/.cc/wake-trigger`); the build reads this file when it exits. Go idle.
  37. - `done` with no open questions: review the `result` text, spot-check specific files only if needed, and report to the user. No new wake-up is needed.
  38. - `done` with questions or blockers: write the answers to a new prompt file, schedule a new `send_later`, and run `cc-run <dir> <same uuid> <answers-file> resume <new trigger_id> "<model>" "<effort>"`. Go idle.
  39. - `error`: run `~/bin/cc-tail <dir>/.cc/latest.jsonl 10` and decide whether to fix and resume or report. A resume gets a new `send_later` with a new fallback time, the same as for questions.
  40. 7. After 3 resume loops without finishing, stop and check with the user.
  41. ## Rules
  42. - Git and GitHub steps go in the task prompt: when to commit, and whether to `gh repo create` and push (with name and visibility). Never let the headless run decide to make anything public.
  43. - Each wake-up fires only once. Make a new one for every launch or resume, and delete the previous one on every wake, so a stale fallback never goes off after the job is finished.
  44. - The wake fire carries no text; extra text is rejected. The status file carries the information.
  45. - Keep `wsl-exec` commands short. Commands containing `>`, `rm`, `mv` and similar need a confirmation call, which echoes the whole command back.
  46. - Bridge calls time out at about 80s, so never `sleep` longer than about 70s in one call.
  47. - Prefer launching from a fresh chat so each wake re-reads less context.
  48. - Live writes to external accounts (posting, sending, creating real records) need the user's go-ahead in the prompt. Don't let the headless run decide those.
README.md · README · 102 lines
  1. # cc-wsl-handoff
  2. A Claude skill plus helper scripts for delegating builds from a Claude Desktop chat to headless
  3. Claude Code in WSL, without polling. The Desktop chat launches the run, goes idle, and is woken by
  4. a signal the moment the run stops.
  5. ## How it works
  6. 1. The chat schedules a one-shot wake-up for itself (`send_later`) with a long fallback delay.
  7. 2. `cc-run` starts `claude -p` detached in WSL (`setsid -f`, so it survives the bridge shell closing).
  8. 3. When Claude Code exits for any reason, `cc-run-inner` writes `.cc/status.json`
  9. (`done` / `error`, turns, cost, final summary) and then fires the wake-up early through Claude
  10. Code's `RemoteTrigger` tool, with no text.
  11. 4. The chat wakes within about a minute, deletes that wake-up's fallback (an early fire doesn't cancel it), and reads only `status.json`. If there are questions, it
  12. answers them and resumes the same session.
  13. This costs about one chat step per run instead of one per polling interval.
  14. ## Install
  15. In WSL:
  16. ```sh
  17. git clone https://github.com/0xJonty/cc-wsl-handoff.git
  18. cd cc-wsl-handoff && ./install.sh # copies bin/cc-* to ~/bin
  19. ```
  20. Then add `SKILL.md` as a skill in Claude.
  21. ## Agent install
  22. Paste this into your coding agent (for example Claude Code running in WSL) and let it do the setup:
  23. ```text
  24. Install the cc-wsl-handoff skill and scripts from https://github.com/0xJonty/cc-wsl-handoff.
  25. 1. Check prerequisites in WSL2 and report anything missing:
  26. - `claude --version` works and Claude Code is signed in to the same Claude account I use in Claude Desktop.
  27. - `python3`, `uuidgen`, `setsid` and `realpath` exist. If any are missing, give me the exact `sudo apt install -y python3 uuid-runtime util-linux coreutils` line to run myself. Do not run sudo.
  28. 2. Clone the repo inside WSL and run `./install.sh`. Confirm ~/bin/cc-run, cc-run-inner, cc-status and cc-tail exist and are executable.
  29. 3. Verify headless auto mode works: in a new empty folder, run
  30. `claude -p "Create ok.txt containing ok, then reply done" --model claude-sonnet-5 --permission-mode auto`
  31. and confirm ok.txt was written. If it is refused, tell me auto mode is unavailable on this plan or setup.
  32. 4. Check the Windows side: claude_desktop_config.json (usually %APPDATA%\Claude\, or search %LOCALAPPDATA%) must have an MCP server that runs WSL commands. If none exists, install one: on Windows run `npm i -g mcp-wsl-exec`, back up the config, and MERGE (never overwrite other servers) an entry like
  33. "wsl-exec": { "command": "node", "args": ["<npm global root>\\mcp-wsl-exec\\dist\\index.js"] }
  34. using `npm root -g` for the real path.
  35. 5. Install the skill:
  36. - For Claude Code: copy SKILL.md to ~/.claude/skills/cc-wsl-handoff/SKILL.md.
  37. - For Claude Desktop/claude.ai: you can't upload it yourself. Tell me to add SKILL.md under Settings > Capabilities > Skills (or ask Claude in a chat to save it as a skill).
  38. 6. Tell me to restart Claude Desktop if the config changed. Then suggest a first test from a Desktop chat: "Use cc-wsl-handoff to have Claude Code create hello.txt in ~/cc-handoff-test." The chat should wake by itself within about a minute.
  39. Rules: never run sudo; never print tokens or credentials; back up any config file before editing it.
  40. ```
  41. ## Requirements
  42. **Windows side**
  43. - Windows 10/11 with WSL2 (tested on Ubuntu 24.04)
  44. - Claude Desktop app, with this chat linked to the computer (device bridge)
  45. - A WSL command MCP server registered in Claude Desktop, e.g. [`mcp-wsl-exec`](https://www.npmjs.com/package/mcp-wsl-exec), which needs Node.js on Windows
  46. - A Claude chat with the `send_later` scheduling tool (the scheduled-tasks feature)
  47. **WSL side**
  48. - Claude Code CLI (tested on 2.1.330), signed in to the **same Claude account** as the Desktop chat, with:
  49. - auto mode available on your plan (`--permission-mode auto`)
  50. - the `RemoteTrigger` tool
  51. - access to `claude-sonnet-5` (used to fire the wake-up)
  52. - `bash`, `python3` (3.8+), `uuidgen` (`uuid-runtime`), `setsid` and `realpath` (`util-linux` and `coreutils`, both preinstalled on Ubuntu)
  53. - Optional: `nvm`. The runner sources `~/.nvm/nvm.sh` if it exists and adds `~/.local/bin` to `PATH`, so `claude` and Node can be found in non-interactive shells
  54. - Optional: `git` and `gh` to clone this repo
  55. On Ubuntu, install anything missing with:
  56. ```sh
  57. sudo apt install -y python3 uuid-runtime util-linux coreutils
  58. ```
  59. ## Scripts
  60. | Script | Purpose |
  61. |---|---|
  62. | `cc-run <dir> <uuid> <prompt-file> <new\|resume> [trigger-id] [model] [effort]` | Start a detached run and confirm it started |
  63. | `cc-run-inner` | Runs Claude Code, writes `status.json`, fires the wake-up |
  64. | `cc-status <log> <exit>` | Summarises a stream-json log into `status.json` |
  65. | `cc-tail [log] [n]` | Compact view of a run log, for debugging |
  66. Runs use `--permission-mode auto` and `disableClaudeAiConnectors: true` (keeps the per-step context small).
  67. Model and effort are optional; pass `""` or omit them to use your Claude Code defaults.
  68. Before building, the skill asks about anything the request leaves open: Git/GitHub (repo name, visibility,
  69. commit cadence), model and effort, project location, and done criteria and limits.
  70. ## Gotchas
  71. - **Don't use Haiku:** auto mode doesn't apply to it, so its file writes and the trigger fire are refused.
  72. - **The fire must carry no text:** session-bound wake-ups reject extra text (`caller_text_resume_only`).
  73. - **Each wake-up fires once.** Create a new one for every launch or resume, and delete it on wake. The build reads its wake-up id from `.cc/wake-trigger` when it exits, so a still-running build can be re-pointed at a new one.
  74. - **Keep the fallback delay generous** in case the machine sleeps or the fire fails.
  75. ## Licence
  76. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.