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: Setup worktree

# Always use a worktree — one per task
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

Step 2: Start tmux session with the chosen agent

tmux new-session -d -s <task-name> -c <worktree-path>

Then launch based on tool:

tmux send-keys -t <task-name> "nvm use 20 && <tool-command>" Enter

Step 3: Send task with plan-first instruction

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

Step 4: Relay plan to user

# 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

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

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

git -C <project> worktree remove <worktree-path>   # branch preserved
tmux kill-session -t <task-name>

# User can then test in main workspace:
# 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