send-agent-message

Send a message to an octomux agent

Send a message or instruction to a specific agent within a running task.

When to use

• Nudging a stuck agent with additional guidance
• Sending follow-up instructions mid-task
• Redirecting an agent's approach
• Providing context an agent is missing

Steps

1. Identify the task:

   • If the user provides a task ID, use it directly
   • If the user references a task by title or description, 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
       

       Find the matching task from the list.

2. Resolve agent number to agent ID: The send-message command/tool requires the agent's nanoid, not its label. Get task details to map "Agent N" to the actual ID. Prefer MCP when available; otherwise fall back to the CLI:

   • MCP: mcp__octomux__get_task({ task_id: '<task-id>' })
   • CLI fallback:

     octomux get-task <task-id> --json
     

   Parse the agents array. Each agent has:

   • id — the nanoid (use this as the agent identifier)
   • label — display name like "Agent 1", "Agent 2"
   • status — running, stopped, etc.
   • window_index — tmux window index

   If the user says "Agent 2", find the agent with label: "Agent 2" and use its id.

   If the task has only one agent, use that agent's ID without asking.

3. Check agent status:

   • If the agent's status is stopped, do NOT send the message. Inform the user that the agent is stopped and suggest resuming the task first.
   • Only send messages to agents with status: "running".

4. Send the message:

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

   MCP (preferred):

   mcp__octomux__send_message({
     task_id: '<task-id>',
     message: '<message>',
   })
   

   CLI fallback: