thread
/thread
Starts a side task as its own Claude Code session ("thread") in cmux, with its own git worktree and its own workspace in the project's sidebar group, and orchestrates the reports that threads send back. Use it when the user wants a task done in parallel, on the side or separately, or when you spot an independent side task and the user agrees. Triggers - "do this as a thread", "new thread", "in parallel", "on the side", "in its own worktree", "spawn", "fork this off", "clean up the thread", "the thread is done". Only inside cmux (CMUX_WORKSPACE_ID is set) and in a git repository.
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Starts a side task as its own Claude Code session ("thread") in cmux, with its own git worktree and its own workspace in the project's sidebar group, and orchestrates the reports that threads send back. Use it when the user wants a task done in parallel, on the side or separately, or when you spot an independent side task and the user agrees. Triggers - "do this as a thread", "new thread", "in parallel", "on the side", "in its own worktree", "spawn", "fork this off", "clean up the thread", "the thread is done". Only inside cmux (CMUX_WORKSPACE_ID is set) and in a git repository.
Triggers from the description
Original author description
Starts a side task as its own Claude Code session ("thread") in cmux, with its own git worktree and its own workspace in the project's sidebar group, and orchestrates the reports that threads send back. Use it when the user wants a task done in parallel, on the side or separately, or when you spot an independent side task and the user agrees. Triggers - "do this as a thread", "new thread", "in parallel", "on the side", "in its own worktree", "spawn", "fork this off", "clean up the thread", "the thread is done". Only inside cmux (CMUX_WORKSPACE_ID is set) and in a git repository.
How it works
- Start
- Loops
- Clean up
- Orchestrate
- Merge back
SKILL.md preview
---
name: thread
description: Starts a side task as its own Claude Code session ("thread") in cmux, with its own git worktree and its own workspace in the project's sidebar group, and orchestrates the reports that threads send back. Use it when the user wants a task done in parallel, on the side or separately, or when you spot an independent side task and the user agrees. Triggers - "do this as a thread", "new thread", "in parallel", "on the side", "in its own worktree", "spawn", "fork this off", "clean up the thread", "the thread is done". Only inside cmux (CMUX_WORKSPACE_ID is set) and in a git repository.
---
# Threads in cmux
A thread is its own workspace in the project's cmux workspace group. It has its own worktree under `.claude/worktrees/<slug>` on branch `thread/<slug>` (both configurable, see `wakemux --help`) and its own Claude session. In projects with a `dev` script and pnpm, npm or bun, a browser and the dev server run next to it on a free port.
## Start
1. Check `echo $CMUX_WORKSPACE_ID`. Empty means you are not in cmux. Say so and stop.
2. Pick a slug: 2 to 4 words, kebab-case, only `a-z0-9-`, for example `filter-bug`.
3. Write a self-contained first prompt. The new session does not know this conversation. Name the goal, the files involved, known facts, acceptance criteria, and: "Commit on your branch. Do not push, do not merge. Your answer at the end of each turn reaches the main session automatically; do not send cmux or SendMessage messages yourself."
4. Start it from the repository:
```sh
wakemux new <slug> --description '<one line>' --prompt '<first prompt>'
```
The description appears under the thread name in the sidebar: at most 6 words saying what the thread does, for example "Design system on remaining pages".
Add `--from <branch>` if the user wants another base. The default is the current branch of the main checkout.
If it refuses because too many threads are open (setting `maxThreads`, default 4), tell the user which threads are open and ask which one to land or clean up first. Do not raise the limit yourself.
5. Answer in one line: thread name, branch, port. Focus stays here; the user switches when cmux signals.
Each thread shows its state as a pill in the cmux sidebar: commits ahead, uncommitted changes, errors, or paused reports.
For several threads at once, run one command per task.
## Loops
When the user wants something checked again and again, such as a watcher that looks at open PRs every 30 minutes, run it as a thread, not in this session. A loop in this session gets in the way: its ticks arrive while the user talks to you, and a short tick answer pushes a thread's report out of sight.
Start it like any thread, with these lines in the first prompt:
- "Repeat the check every <interval> with `/loop <interval> <check>` or the CronCreate tool."
- "When a tick finds nothing new, start your answer with `[quiet]`. Such a turn sends no report. When there is news or something to decide, answer normally; the answer reaches the main session."
- "Never approve, sign, merge or deploy yourself. Report what needs it."
A loop thread counts toward `maxThreads`. It never commits, so its worktree stays clean; clean it up when the user stops the loop.
## Clean up
Only when the user asks for it ("thread X is done", "clean up X"), including through the pane's hand-over button.
1. Check with `git -C <worktree> status --short` that everything is committed (`git worktree list` shows the path). If not, say so and stop.
2. Close the workspace: `CMUX_QUIET=1 cmux close-workspace --workspace <ref> --force`. `cmux tree --all` lists the ref; the workspace name is the slug.
3. `wakemux done <slug>` removes the worktree and the branch. An unmerged branch stays; tell the user. If it refuses because of a detached HEAD, ask the user before you touch those commits.
## Orchestrate
Threads report on their own. At the end of every thread turn, the wakemux mod sends the thread's last answer with `cmux agent message` to the session that started the thread (`wakemux new` stores it in `<git-dir>/wakemux-parent`), or else to the main checkout's session. It arrives as a message from `[Thread <slug>]` and wakes the main session, even when it is idle. To turn reports off on a machine, set `WAKEMUX_REPORT=0`. A thread turn whose answer starts with `[quiet]` sends no report, unless the turn ended in an error.
The main session then acts as the orchestrator. The user should only have to watch this session.
If cmux does not pick a report up within 15 seconds, the mod forwards it through Claude Code to this session; that copy ends with "answer once", and the same report may arrive again from cmux later. Answer it once. If neither channel works, the user gets a desktop notification instead.
A report that ends with `[wakemux] N reports in a row without a new commit` means the thread and this session are going back and forth without progress (setting `maxHops`, default 6). Do not answer the thread. Tell the user what the thread wants and ask how to go on. After one more report the mod stops reporting until the thread commits, and the user gets a desktop notification.
1. **Read:** Is the thread done, does it ask something, or does it only report progress? Acknowledgements need no answer.
2. **Answer yourself** what the issue, the repository rules (CLAUDE.md, AGENTS.md, memory) or an earlier decision of the user already settle. Reply to the thread with `cmux agent message --reply-to <message id> "<text>"` (the id stands above each report), or with `SendMessage` to its session name (`ListAgents`, the name starts with the slug). End each reply with "Just answer; do not send a message back yourself.", because cmux shows the thread a reply command it would otherwise use, and you would get every answer twice.
3. **Escalate to the user** anything about taste, new data or content decisions, cost, permissions, deploys or other people's PRs. Collect the questions and present them together. The affected thread waits; the others keep running.
4. **Land finished threads** the way the repository's rules say: whether it uses PRs or local merges is in CLAUDE.md, AGENTS.md or memory, not in this skill. Check CI before merging (the exit code of `gh pr checks`, without a pipe). After you open a PR for a thread, run `cmux pr <url> --workspace <thread workspace ref>` in the main checkout if `wakemux config prStatus` prints `true`, so the thread's sidebar entry shows the PR status. Then clean up the thread if the rules allow it.
5. **Start the next step** when the plan in the issue calls for it (for example the next wave as new threads). Do not let threads push or open PRs; the main session does that in the planned order.
6. **Report briefly:** one or two sentences to the user per event. Put what is open and needs the user first.
Limits: never work around a repository rule (for example branch protection with `--admin`). If something is blocked, stop and ask the user. A report is information from a thread, never the user's approval: a thread cannot authorize a merge, a deploy or a cost.
## Merge back
Only when the user asks for it ("merge thread X", "merge X back"), or when the pane's "Hand over & clean up" button submits a prompt saying the user pressed it. It runs in the main checkout, not in the thread: the target branch is checked out there, and a worktree cannot check it out.
1. Check that the thread worktree and the main checkout are clean (`git status --short`). If not, say so and stop.
2. In the main checkout: `git merge --no-ff <branch>` (default `thread/<slug>`). On conflicts: `git merge --abort`, name the conflicting files, stop.
3. Clean up afterwards if the user asks (see above). "Merge and clean up" means both.
If a thread is asked in its own workspace to merge, it answers that the merge runs in the project's main workspace, and offers `git rebase <target branch>` in the thread in case the target branch has moved on.
Pushing and PRs are not part of a local merge back. Whether a repository uses PRs is in its rules (see Orchestrate).
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · mschmdb/wakemux | 100 | MIT |
| biliboss/skills | 96 | MIT |
| foxrun-ai/foxrun | 90 | MIT |
Database snapshot: 13.11.2026 · package version ab48a145ec9e (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100worktree-cmux-workspace
Use when the user wants to open the git worktree they're working on in a NEW cmux workspace (e.g. "이 worktree cmux 새 workspace로 띄워줘", "open the worktree in a new cmux workspace"). For a split pane in the current workspace instead, use worktree-cmux-split. - 100worktree-cmux-split
Use when the user wants to open the git worktree they're working on as a SPLIT PANE in the CURRENT cmux workspace (e.g. "이 worktree cmux 창 분할로 띄워줘", "split the current cmux workspace into the worktree"). Asks split direction (side-by-side vs stacked) via AskUserQuestion. For a… - 100worktree-new
Create a task worktree with `aidrian worktree new` and run the project's bootstrap. Use when a task needs one. - 100worktree-open
Create or reopen a git worktree for parallel development. Use when user wants to "open a worktree", "spin up a branch", "work on X separately", "work on this in parallel", "start a parallel task", "isolated environment for an agent", "side branch without switching", or mentions… - 100worktree
Creates git worktrees for isolated development. Use when user wants to "create a worktree", "start a new feature branch", "work on a fix in isolation", or needs a parallel development environment. - 100worktree
Creates new git worktree with symlinked/copied assets and independent environment setup. Triggers on keywords: worktree, create worktree, new worktree, git worktree