Skip to content
Skills Library
AI & agents · Automation

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

Repository
octomux ↗
Licence
MIT
Last repository change
27.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.08.2026, without references to retired models or APIs.

Licence

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

  1. Distinction from send-agent-message
  2. When to use
  3. Steps
  4. Examples
  5. Notes
Original SKILL.md headings · 104 lines, 634 words
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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.