Fork the current Claude Code session into a new cmux pane or workspace, preserving full conversation context.
Language Rules
- Auto-detect input language → output in the same language
- Japanese input → Japanese output, use
references/fork-guide.ja.md - English input → English output, use
references/fork-guide.md - Explicit override takes priority
Prerequisites
BEFORE forking, verify cmux environment:
echo $CMUX_SOCKET_PATH
- If empty or unset → stop with error:
- EN: "Error: Not running inside a cmux session. Please start Claude Code from within cmux."
- JA: "Error: Not running inside a cmux session. Please launch Claude Code inside cmux."
- If set → proceed
Permission Mode
By default, fork with --dangerously-skip-permissions to avoid re-approving every tool in the forked session. Use interactive mode only when explicitly requested.
| User Input Pattern | Mode | Flag |
|---|---|---|
| (default) | skip permissions | --dangerously-skip-permissions |
| "interactive", "interactive mode", "with approval", "with permissions" | interactive | (none) |
Direction Mapping
Parse the user's request to determine fork direction. Use the first match from the table below. If no direction keyword is found, use the default (right).
| User Input Pattern | Direction | cmux Command |
|---|---|---|
| (no direction specified) | right | cmux new-split right |
| "right", "to the right", "right direction" | right | cmux new-split right |
| "down", "below", "downward", "downward direction" | down | cmux new-split down |
| "new workspace", "workspace", "new workspace", "another workspace", "new WS" | workspace | cmux new-workspace |
Execution Steps
Step 1: Determine Direction and Permission Mode
Parse the user's input against the Direction Mapping and Permission Mode tables above.
- Direction default:
right - Permission default:
--dangerously-skip-permissions
Step 2: Create Surface
Run the appropriate cmux command based on direction:
For pane split (right or down):
cmux new-split right
# or
cmux new-split down
The command outputs: OK surface:{N} workspace:{N}
Extract the surface handle (e.g., surface:31) from the output.
For new workspace:
cmux new-workspace
The command outputs: OK surface:{N} workspace:{N}
Extract both the surface and workspace handles from the output.
Step 3: Launch Forked Claude Code
Send the fork command to the new surface. Default includes --dangerously-skip-permissions to avoid re-approving tools:
Default (auto-approve — recommended):
cmux send --surface surface:{N} "claude --continue --fork-session --dangerously-skip-permissions\n"
Interactive mode (if user explicitly requested):
cmux send --surface surface:{N} "claude --continue --fork-session\n"
Where surface:{N} is the handle extracted in Step 2.
Step 4: Verify Launch
Wait briefly, then read the new surface to confirm Claude Code started:
sleep 3
cmux read-screen --surface surface:{N}
Check the output for:
- Claude Code startup message or prompt → success
- Error messages or empty screen → may need more time; retry once after
sleep 3
Step 5: Report Result
On success, report to the user:
- EN: "Forked session to
surface:{N}. The new session has your full conversation context." - JA: "
surface:{N}The session has been forked. The conversation context has been carried over."
On failure, report the error:
- EN: "Failed to start forked session. Check the new pane for errors."
- JA: "Failed to launch the forked session. Please check the error in the new pane."
Error Handling
| Situation | Response |
|---|---|
CMUX_SOCKET_PATH not set |
Error: not in cmux session |
cmux new-split fails |
Report error; cmux may not be running |
claude --continue --fork-session fails |
Report error; session history may be empty (first launch) |
| No prompt detected after retry | Warn user; suggest checking the new pane manually |
Notes
- By default,
--dangerously-skip-permissionsis used so the forked session doesn't require re-approving every tool. Use interactive mode if you want manual approval. - This skill only forks Claude Code sessions. To launch other agents (Codex, Gemini CLI), use
cmux-delegateinstead. - For detailed cmux command reference and troubleshooting, see the reference guide.