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 = \x3Ctool>
  

  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:

cd \x3Cproject>
# worktree + tmux in one command:
claude -w \x3Cbranch-name> --tmux --dangerously-skip-permissions

• -w \x3Cname> 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:

# Create worktree
git -C \x3Cproject> worktree add -b \x3Cbranch> \x3Cworktree-path> main

# Symlink env files
ln -sf \x3Cproject>/.env \x3Cworktree-path>/.env
ln -sf \x3Cproject>/.env.local \x3Cworktree-path>/.env.local   # if exists

# Create tmux session and launch agent
tmux new-session -d -s \x3Ctask-name> -c \x3Cworktree-path>
tmux send-keys -t \x3Ctask-name> "nvm use 20 && \x3Ctool-command>" Enter

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:

tmux list-sessions

Then send the task:

tmux send-keys -t \x3Csession-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 \x3Csession-name> Enter

Step 4: Relay plan to user

# Poll for plan output
tmux capture-pane -t \x3Ctask-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

# Send user's response
tmux send-keys -t \x3Ctask-name> -l -- "\x3Cuser response>"
sleep 0.1
tmux send-keys -t \x3Ctask-name> Enter

# Check if waiting for input
tmux capture-pane -t \x3Ctask-name> -p | tail -10 | grep -E "❯|Yes.*No|proceed|permission|plan|approve"

Step 5: Parallel tasks

Same pattern, multiple sessions:

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:

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):

tmux kill-session -t \x3Cbranch-name>
git worktree remove \x3Cworktree-path>   # branch preserved

For other tools (manual worktree):

git -C \x3Cproject> worktree remove \x3Cworktree-path>   # branch preserved
tmux kill-session -t \x3Ctask-name>

User can then test in main workspace:

git switch \x3Cbranch>

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