stevengonsalvez/coding-agent

/coding-agent — Delegate Coding Work

Delegate coding tasks to subagents or run Claude Code/Codex in separate tmux sessions on the host. Choose the right pattern for the job.

When to use each pattern

| Situation | Pattern | |-----------|---------| | Bounded task with clear spec (fix bug, implement feature, write tests) | Task tool (subagent) | | Long-running interactive session, needs persistence | tmux + claude --dangerously-skip-permissions | | PR review — checkout and inspect | tmux + clone to /tmp | | Multiple independent fixes in parallel | tmux + git worktrees | | Claude Code capped or erroring | tmux + Codex fallback |

---

Pattern 1: Task Tool (Primary Pattern)

Use the Task tool to delegate focused coding work to a subagent. The subagent runs inside the same SDK session with full tool access (Bash, Read, Write, Edit, Glob, Grep). This is the default choice for most coding tasks.

When to use

• Implement a feature, fix a bug, write tests
• Refactor a module or file
• Analyse a codebase and produce a report
• Any multi-step work that needs tool use but doesn't require an interactive terminal

How to invoke

Task({
  description: "Fix the rate-limiting bug in the API gateway",
  prompt: "..."
})

Prompt template

Write the Task prompt as a complete standalone brief. The subagent has no memory of the conversation that spawned it. Include:

1. What to do — specific, unambiguous objective
2. Where to work — directory, repo, relevant files
3. Constraints — branch to use, things not to touch, style rules
4. Definition of done — what success looks like
5. How to report back — summarise files changed, tests run, result

Task({
  description: "Implement retry logic for the Slack webhook sender",
  prompt: """
    You are a backend engineer implementing retry logic for a webhook sender.

    Repository: /workspace/project
    Target file: src/channels/slack.ts — the `sendWebhook` function

    Task:
    - Add exponential backoff retry (max 3 attempts, base delay 500ms)
    - Only retry on 429 and 5xx HTTP responses
    - Preserve the existing function signature
    - Do NOT modify other files

    Constraints:
    - TypeScript strict mode is on
    - No new dependencies — use built-in fetch and setTimeout
    - Keep the existing error-logging pattern (console.error with context object)

    When done:
    - Run `npm run build` to verify compilation
    - Summarise: files changed, retry logic approach, any edge cases handled
  """
})

Multi-subagent parallelism

Run independent tasks simultaneously. Do NOT chain tasks that depend on each other's output — wait for the first to complete.

// Run two independent fixes in parallel
Task({ description: "Fix auth timeout", prompt: "..." })
Task({ description: "Fix typos in CLAUDE.md", prompt: "..." })

// Then, once both complete, run the dependent task
Task({ description: "Integration test for auth + config", prompt: "..." })

---

Pattern 2: tmux — Long-running Claude Code Session

For interactive, open-ended, or very long coding sessions that would exhaust context in a subagent. Claude Code runs on the host with full filesystem access and persistent terminal state.

When to use

• Session expected to run for 30+ minutes
• Work requires watching logs or waiting for build pipelines
• You need to send follow-up prompts mid-session
• Persistence matters (survives network drops)

Standard launch sequence

# 1. Generate a session name
TIMESTAMP=$(date +%s)
SESSION="agent-${TIMESTAMP}"
WORK_DIR="/path/to/repo"   # absolute path always

# 2. Create tmux session and start Claude Code
tmux new-session -d -s "$SESSION" -c "$WORK_DIR"
tmux send-keys -t "$SESSION" "claude --dangerously-skip-permissions" C-m

# 3. Wait for Claude to initialise (check for prompt, not just sleep)
sleep 3
tmux capture-pane -p -t "$SESSION" -S -30  # verify it's ready

# 4. Send the task (use -l flag for safe literal sending)
tmux send-keys -t "$SESSION" -l "Your full task description here"
tmux send-keys -t "$SESSION" C-m

# 5. Report session info back to user
echo "Session: $SESSION"
echo "Monitor: tmux attach -t $SESSION"
echo "Capture: tmux capture-pane -p -t $SESSION -S -100"
echo "Kill:    tmux kill-session -t $SESSION"

Check progress without blocking

# Tail the last 50 lines of output
tmux capture-pane -p -t "$SESSION" -S -50

# Check if Claude is still working (look for spinner or output activity)
tmux capture-pane -p -t "$SESSION" -S -5

Send a follow-up prompt

# Only send follow-up when the previous task is clearly done
tmux send-keys -t "$SESSION" -l "Now run the test suite and fix any failures"
tmux send-keys -t "$SESSION" C-m

Headless (non-interactive) mode

For scripted work where you want output captured to a log file rather than interactive:

TIMESTAMP=$(date +%s)
SESSION="agent-${TIMESTAMP}"
WORK_DIR="/path/to/repo"
LOG="/tmp/agent-${TIMESTAMP}.log"

tmux new-session -d -s "$SESSION" -c "$WORK_DIR"
tmux send-keys -t "$SESSION" \
  "claude -p 'Your full task prompt here' --dangerously-skip-permissions 2>&1 | tee $LOG" C-m

echo "Output logged to: $LOG"
echo "Monitor: tmux attach -t $SESSION"

---

Pattern 3: PR Review

Review a pull request without touching the live project. Always clone or checkout to /tmp.

TIMESTAMP=$(date +%s)
SESSION="pr-review-${TIMESTAMP}"
PR_NUMBER="42"
REPO="owner/repo"
WORK_DIR="/tmp/pr-review-${TIMESTAMP}"

# Clone and checkout the PR branch
git clone "https://github.com/${REPO}.git" "$WORK_DIR"
cd "$WORK_DIR"
gh pr checkout "$PR_NUMBER"

# Start Claude Code in that directory
tmux new-session -d -s "$SESSION" -c "$WORK_DIR"
tmux send-keys -t "$SESSION" "claude --dangerously-skip-permissions" C-m
sleep 3

# Send the review brief
tmux send-keys -t "$SESSION" -l \
  "Review PR #${PR_NUMBER}. Check correctness, security, test coverage, and style. Summarise findings."
tmux send-keys -t "$SESSION" C-m

echo "Review session: $SESSION"
echo "Attach: tmux attach -t $SESSION"

Rules for PR reviews:

• NEVER run the agent inside /workspace/project or the live NanoClaw dir
• Clone to /tmp/pr-review-{timestamp} — isolated, disposable
• Clean up after: rm -rf /tmp/pr-review-${TIMESTAMP}

---

Pattern 4: Parallel Fixes with Git Worktrees

Work on multiple issues simultaneously without branch-switching conflicts. Each worktree is an independent checkout of the repo on its own branch.

REPO_DIR="/workspace/project"    # or wherever the main repo lives
BASE_BRANCH="main"

# Create two worktrees for two independent issues
git -C "$REPO_DIR" worktree add /tmp/fix-issue-101 -b fix/issue-101 "$BASE_BRANCH"
git -C "$REPO_DIR" worktree add /tmp/fix-issue-102 -b fix/issue-102 "$BASE_BRANCH"

# Spawn a Claude Code session per worktree
STAMP=$(date +%s)

tmux new-session -d -s "agent-101-${STAMP}" -c "/tmp/fix-issue-101"
tmux send-keys -t "agent-101-${STAMP}" "claude --dangerously-skip-permissions" C-m
sleep 3
tmux send-keys -t "agent-101-${STAMP}" -l "Fix issue #101: [description]"
tmux send-keys -t "agent-101-${STAMP}" C-m

tmux new-session -d -s "agent-102-${STAMP}" -c "/tmp/fix-issue-102"
tmux send-keys -t "agent-102-${STAMP}" "claude --dangerously-skip-permissions" C-m
sleep 3
tmux send-keys -t "agent-102-${STAMP}" -l "Fix issue #102: [description]"
tmux send-keys -t "agent-102-${STAMP}" C-m

echo "Sessions running:"
echo "  tmux attach -t agent-101-${STAMP}"
echo "  tmux attach -t agent-102-${STAMP}"

Cleaning up worktrees when done:

git -C "$REPO_DIR" worktree remove /tmp/fix-issue-101
git -C "$REPO_DIR" worktree remove /tmp/fix-issue-102

---

Pattern 5: Codex Fallback

If Claude Code is rate-capped or unavailable, fall back to Codex CLI. Same tmux pattern — swap the command.

Check availability first

# Check Claude Code
claude --version 2>/dev/null && echo "CC: available" || echo "CC: not found"

# Check Codex
which codex 2>/dev/null && echo "Codex: available" || echo "Codex: not installed"

Codex session (full-auto mode)

TIMESTAMP=$(date +%s)
SESSION="codex-${TIMESTAMP}"
WORK_DIR="/path/to/repo"

tmux new-session -d -s "$SESSION" -c "$WORK_DIR"
tmux send-keys -t "$SESSION" \
  "codex exec --full-auto 'Your task description'" C-m

echo "Codex session: $SESSION"
echo "Capture: tmux capture-pane -p -t $SESSION -S -50"

Codex interactive mode (yolo)

tmux new-session -d -s "$SESSION" -c "$WORK_DIR"
tmux send-keys -t "$SESSION" "codex --yolo" C-m
sleep 3
tmux send-keys -t "$SESSION" -l "Your task description"
tmux send-keys -t "$SESSION" C-m

Fallback decision tree

Task tool → preferred for all bounded work
    ↓ Claude Code session needed (long/interactive)
tmux + claude --dangerously-skip-permissions
    ↓ CC capped or erroring after 2 retries
tmux + codex exec --full-auto
    ↓ Codex not installed
Report to user: install codex or retry later

---

Session Management

List all running agent sessions

tmux list-sessions 2>/dev/null | grep -E "^(agent|codex|pr-review)-"

Kill a specific session

tmux kill-session -t "agent-${TIMESTAMP}"

Never use tmux kill-server — it destroys all sessions across all users and projects.

Session naming conventions

| Prefix | Use | |--------|-----| | agent-{timestamp} | Claude Code general coding session | | codex-{timestamp} | Codex fallback session | | pr-review-{timestamp} | PR review checkout |

---

Rules

1. Task tool is the default. Only reach for tmux if the task is genuinely long-running or interactive.

2. PR reviews always use /tmp. Never run an agent inside /workspace/project for review work — contamination risk.

3. Never block on tmux. After starting a session, report the session name and move on. Use tmux capture-pane to check progress, never tmux attach from within tool calls.

4. One task per session. Don't reuse a tmux session for unrelated work. Each session has a clear purpose.

5. Absolute paths only. tmux sessions do not inherit your working directory reliably. Always use -c "$WORK_DIR" with an absolute path when creating sessions.

6. Literal key sending. Use tmux send-keys -t SESSION -l "text" (the -l flag) for any prompt text containing special characters. Without -l, characters like $, {, }, * will be interpreted by the shell.

7. No bash pty:true. That is an OpenClaw-specific API that does not exist here. All interactive terminal work goes through tmux.

8. No process action:log. Also OpenClaw-only. Use tmux capture-pane -p -t SESSION -S -N to read session output.

9. Codex check before use. Always run which codex before attempting a Codex session. Don't assume it's installed.

10. Clean up worktrees. After merging or discarding worktree work, remove it: git worktree remove /tmp/fix-{issue}.