add-agent

Add an agent to an octomux task

Attach a new Claude Code agent to an existing running task. The new agent is a fresh tmux window inside the task's tmux session, sharing the task's worktree/cwd. Each task can hold multiple agents working in parallel in the same worktree.

Distinction from send-agent-message

• add-agent — creates a NEW agent (new tmux window, new Claude Code process) attached to an existing task. Use this to spin up an additional helper agent (e.g. a reviewer) alongside the original agent.
• send-agent-message — sends a message to an ALREADY-RUNNING agent via tmux send-keys. Use this to nudge or redirect an agent that is already working.

If you want another voice in the task, use add-agent. If you want to talk to the voice already there, use send-agent-message.

When to use

• Adding a reviewer / QA agent alongside an implementing agent
• Spawning an additional helper to work on a subtask in the same worktree
• Continuing an interrupted task with a fresh prompt without losing the original context in the running agent

Steps

1. Identify the task:

   • If the user provides a task ID, use it directly
   • Otherwise look it up. Prefer the MCP tool when available (you're in the orchestrator); otherwise fall back to the CLI:
     • MCP: mcp__octomux__list_tasks()
     • CLI fallback: octomux list-tasks --json
   • The task must be in running status — add-agent will fail otherwise

2. Craft a focused initial prompt for the new agent. Keep it specific: the new agent lands in the same worktree but knows nothing about what the first agent has been doing.

3. Add the agent:

   Prefer the MCP tool when available (you're in the orchestrator); otherwise fall back to the CLI.

   MCP (preferred):

   mcp__octomux__add_agent({
     task_id: '<task-id>',
     prompt: '<initial prompt for the new agent>',
     label: '<optional label>',      // optional — defaults to server-assigned "Agent N"
     model: '<optional model id>',   // optional — e.g. "claude-opus-4-8"
   })