add-agent
/add-agent
Use when you need to attach a new Claude Code agent (new tmux window) to an existing running octomux task, sharing the task's worktree and cwd
- Author
- shreypaharia ↗
- Repository
- octomux ↗
- Licence
- MIT
- Last repository change
- 27.08.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.08.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when you need to attach a new Claude Code agent (new tmux window) to an existing running octomux task, sharing the task's worktree and cwd
Original author description
Use when you need to attach a new Claude Code agent (new tmux window) to an existing running octomux task, sharing the task's worktree and cwd
How it works
- Distinction from send-agent-message
- When to use
- Steps
- Examples
- Notes
SKILL.md preview
---
name: add-agent
description: Use when you need to attach a new Claude Code agent (new tmux window) to an existing running octomux task, sharing the task's worktree and cwd
---
# 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"
})
```
**CLI fallback:**
```bash
octomux add-agent \
--task <task-id> \
--prompt '<initial prompt for the new agent>'
```
Optional CLI flags:
- `--agent <agent-type>` — use a Claude Code agent type (e.g. `code-reviewer`). Default: plain `claude` with no specific agent type.
- `--label <label>` — custom label for the new agent. Default: server-assigned `"Agent N"`.
4. **Report:** the command/tool returns the new agent's ID, label, and tmux window index on success. Pass the agent ID back to the user so they can `send-agent-message` to it later.
## Examples
**Add a reviewer to a running implementation task (MCP):**
```
mcp__octomux__add_agent({
task_id: 'ABC123XYZ',
label: 'Reviewer',
prompt: 'Review the diff on this branch against main. Focus on correctness and edge cases, flag anything risky.',
})
```
**Add a reviewer to a running implementation task (CLI fallback):**
```bash
octomux add-agent \
--task ABC123XYZ \
--agent code-reviewer \
--label 'Reviewer' \
--prompt 'Review the diff on this branch against main. Focus on correctness and edge cases, flag anything risky.'
```
**Add a second implementer to parallelize a subtask (MCP):**
```
mcp__octomux__add_agent({
task_id: 'ABC123XYZ',
prompt: 'While Agent 1 finishes the API work, scaffold the frontend table in src/pages/tasks/. Do not touch server/ files.',
})
```
**Add a second implementer to parallelize a subtask (CLI fallback):**
```bash
octomux add-agent \
--task ABC123XYZ \
--prompt 'While Agent 1 finishes the API work, scaffold the frontend table in src/pages/tasks/. Do not touch server/ files.'
```
## Notes
- The octomux server must be running (`octomux start`)
- The task must be in `running` status; `add-agent` fails on `draft`, `setting_up`, `closed`, or `error` tasks
- The new agent shares the task's worktree — both agents operate on the same files, so coordinate explicitly via prompts to avoid conflicts
- Monitor the new agent via `mcp__octomux__get_task({ task_id })` (MCP) or `octomux get-task <task-id>` (CLI) or the dashboard
Versions
The database has no other skills named add-agent.
Database snapshot: 13.11.2026 · package version 5385e9cafcfd (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100create-task
Use when creating an octomux task to dispatch autonomous Claude Code agents for building features, fixing bugs, or any code changes - 95tmux-start
Start issue work in a new tmux window with its own worktree. Use when the user has tmux running and wants issue startup to continue outside the current session. SKIP when not inside a tmux session ($TMUX unset) or when the user wants to work in the current session; use start-issue directly. - 100review-learnings
Extract reusable learnings from completed octomux agent sessions and append to .claude/rules/learnings.md. Use when reviewing what agents learned, or to manually add a learning. - 100worktree-task-launcher
Launch a canonical FX Workbench task in its own Git worktree and tmux window with an interactive fx agent. Use when asked to fork, launch, delegate, or start a task from a durable packet. - 100dispatch
Start a new agent session in a new window of the current tmux session, with Remote Control on, in a directory the user names, and give it a prompt only if the user says what it should do. Use ONLY when the user explicitly asks to dispatch, launch or start an agent (or a Claude,… - 100tmux-agent-plane
The system-wide index of the user's coding agents (Claude Code, Codex, Pi, OpenCode, Antigravity, Grok Build) across every tmux session, and the only way to work with them, through the `tmux-agent-plane` CLI. Load it first, before any tmux command, whenever a task touches…