Skill: yuanshenstarto/code-tmux (version 1.3.0)

--- name: code-tmux description: Run coding tasks using a persistent tmux session with git worktree isolation. Supports multiple coding agents (Claude Code, Codex, CodeBuddy, OpenCode, etc.). Activate when user asks to build, fix, refactor, or review code. Always uses tmux for persistent multi-turn conversation — never one-shot mode. --- # Coding Agent Task (tmux + worktree) Run coding tasks by spawning a coding agent in a **tmux session + git worktree**. Every task gets its own isolated branch and persistent conversation. ## Step 0: Determine which agent to use **Check memory first:** ``` memory_search("preferred coding agent tool") ``` - If found → use that tool, no need to ask - If not found → ask the user: > "Which coding agent should I use? (default: claude) > Options: claude, codex, opencode, codebuddy, or any CLI tool name" Then save the answer to memory: ``` memory: preferred_coding_agent = <tool> ``` Write to `MEMORY.md` under a "Preferences" section. **Default if user doesn't answer:** `claude` ## Step 1 & 2: Setup worktree + Start session ### If tool is `claude` (recommended) Use `claude -w` — it manages the worktree automatically. Add `--tmux` to also create a tmux session: ```bash cd <project> # worktree + tmux in one command: claude -w <branch-name> --tmux --dangerously-skip-permissions ``` - `-w <name>` creates and checks out a new git worktree branch automatically - `--tmux` opens it in a tmux session (uses iTerm2 panes if available, otherwise classic tmux) - No need to manually `git worktree add` or `tmux new-session` ### If tool is other (codex, opencode, codebuddy, etc.) Manage worktree and tmux manually: ```bash # Create worktree git -C <project> worktree add -b <branch> <worktree-path> main # Symlink env files ln -sf <project>/.env <worktree-path>/.env ln -sf <project>/.env.local <worktree-path>/.env.local # if exists # Create tmux session and launch agent tmux new-session -d -s <task-name> -c <worktree-path> tmux send-keys -t <task-name> "nvm use 20 && <tool-command>" Enter ``` | Tool | Command | |---|---| | `codex` | `codex` | | `opencode` | `opencode` | | `codebuddy` | `codebuddy` (or check its CLI name) | | other | use the tool's interactive CLI command | ## Step 3: Send task with plan-first instruction For `claude -w --tmux`, the session name is auto-set to the branch name. Find it with: ```bash tmux list-sessions ``` Then send the task: ```bash tmux send-keys -t <session-name> -l -- "Your task here. Before making any changes, show me a plan of what you intend to do and wait for my approval." sleep 0.1 tmux send-keys -t <session-name> Enter ``` ## Step 4: Relay plan to user ```bash # Poll for plan output tmux capture-pane -t <task-name> -p | tail -30 ``` When agent outputs a plan → **relay it to the user**, wait for their confirmation before proceeding. Relay flow: 1. Agent outputs plan → relay to user 2. User says "ok" / requests changes → forward to agent 3. Agent proceeds → monitor and relay further questions ```bash # Send user's response tmux send-keys -t <task-name> -l -- "<user response>" sleep 0.1 tmux send-keys -t <task-name> Enter # Check if waiting for input tmux capture-pane -t <task-name> -p | tail -10 | grep -E "❯|Yes.*No|proceed|permission|plan|approve" ``` ## Step 5: Parallel tasks Same pattern, multiple sessions: ```bash tmux new-session -d -s task-a -c /tmp/task-a tmux new-session -d -s task-b -c /tmp/task-b ``` Check all at once: ```bash for s in task-a task-b; do echo "=== $s ===" tmux capture-pane -t $s -p 2>/dev/null | tail -5 done ``` ## Step 6: Cleanup For `claude -w --tmux` (worktree auto-managed): ```bash tmux kill-session -t <branch-name> git worktree remove <worktree-path> # branch preserved ``` For other tools (manual worktree): ```bash git -C <project> worktree remove <worktree-path> # branch preserved tmux kill-session -t <task-name> ``` User can then test in main workspace: ```bash git switch <branch> ``` ## Rules - **Check memory first** — never ask for tool preference if already saved - **Always** use worktrees — one per task, no exceptions - **Always** use tmux — persistent session, multi-turn conversation - **Always** show plan first, wait for user approval before agent touches files - **Always** symlink `.env` files — don't copy - One status message when starting, one when done or stuck - See `references/troubleshooting.md` for common issues

path: README.md
content: # claude-code-tmux

An [OpenClaw](https://openclaw.ai) skill that runs coding tasks using a **persistent tmux session with git worktree isolation**.

Supports multiple coding agents — Claude Code, Codex, OpenCode, CodeBuddy, or any interactive CLI tool.

## What it does

- **Asks once, remembers forever** — first run asks which coding agent you prefer, saves it to memory, never asks again
- Every task gets its own **git worktree** (isolated branch, no file conflicts)
- Agent runs in a **tmux session** — persistent, multi-turn conversation
- **Plan mode by default** — agent always shows a plan and waits for your approval before touching files
- OpenClaw agent acts as **relay**: forwards plans/questions to you, sends your answers back

## Install

```bash
npx clawhub@latest install claude-code-tmux
```

Or clone directly:
```bash
git clone https://github.com/yuanshenstarto/claude-code-tmux.git
```

## Supported agents

| Agent | CLI |
|---|---|
| [Claude Code](https://github.com/anthropics/claude-code) | `claude` |
| [Codex](https://github.com/openai/codex) | `codex` |
| [OpenCode](https://github.com/sst/opencode) | `opencode` |
| CodeBuddy | `codebuddy` |
| Any interactive CLI | custom |

## Workflow

```
First run: "Which coding agent? (default: claude)" → saved to memory

You → OpenClaw agent → tmux session (your chosen agent) → git worktree
                  ↑_____________________________________________↓
                         relay: plans, questions, answers
```

When finished, the branch is preserved — switch to it in your main workspace to test.

## Requirements

- [tmux](https://github.com/tmux/tmux)
- Your preferred coding agent CLI installed
- Node.js >= 20 (for Claude Code / Codex)
- git

## License

MIT


path: references/troubleshooting.md
content: # Troubleshooting

## Claude Code doesn't start

```bash
# Check node version
tmux send-keys -t <session> "node --version" Enter
# If wrong version:
tmux send-keys -t <session> "nvm use 20 && claude --dangerously-skip-permissions" Enter
```

## Worktree branch conflict

```
fatal: 'feat/x' is already checked out at '/tmp/task-x'
```
Either remove the existing worktree first, or use a different branch name:
```bash
git worktree remove /tmp/task-x
# then retry
```

## .env not found in worktree

```bash
ln -sf <project>/.env <worktree-path>/.env
```

## tmux session already exists

```bash
tmux kill-session -t <name>
tmux new-session -d -s <name> -c <path>
```

## Claude Code hangs / no output

```bash
tmux capture-pane -t <session> -p | tail -20
# If stuck on a question, relay to user then:
tmux send-keys -t <session> "y" Enter
# or Ctrl+C to interrupt:
tmux send-keys -t <session> C-c
```

## Main workspace can't checkout worktree branch

Git won't allow two worktrees on the same branch simultaneously.
Remove the worktree first:
```bash
git worktree remove /tmp/task-x   # branch is preserved
git switch feat/x                  # now works in main workspace
```


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: stale | SkillSpector: suspicious (CRITICAL)