Agent-to-Agent Communication

How AI agents coordinate work in amux — message passing, atomic task claiming, and output peeking.

Published: July 14, 2026 · Last updated: July 14, 2026

Why agent-to-agent communication matters

Running one AI agent on a task is easy. Running 10 agents on 10 tasks without collision is a coordination problem. Without a communication layer, agents duplicate work, step on each other's files, miss dependencies, and fail silently.

Most multi-agent frameworks (LangGraph, CrewAI, AutoGen) solve this by building agent graphs in Python code. That works well when you control the agents from a central orchestrator — but it breaks down when the "agents" are real developer tools (Claude Code, Codex CLI, Gemini CLI) running their own agentic loops in terminal sessions.

amux takes a different approach: standard HTTP REST APIs and SQLite. Any agent that can run curl — or instruct a subprocess to run it — can coordinate with every other agent in the fleet, regardless of runtime.

The three coordination patterns

Pattern 1: Direct message passing

Any session can send a message to any other named session. The message lands in the target agent's tmux pane (as if typed at the keyboard) and is logged in the Messages tab.

# Agent A sends a message to Agent B
curl -sk -X POST -H 'Content-Type: application/json' \
  -d '{"text":"auth module complete, branch: feature/auth — ready for integration"}' \
  https://localhost:8822/api/sessions/agent-B/send

From inside a Claude Code session, agents can send messages using a bash tool call or by writing a shell script to be executed. The amux $AMUX_URL env var is available in every managed session.

# Inside any Claude Code session — send a message to the coordinator
curl -sk -X POST -H 'Content-Type: application/json' \
  -d '{"text":"task TASK-42 done — merged to main. Moving to next item."}' \
  $AMUX_URL/api/sessions/coordinator/send

Use message passing for: task completion notifications, error escalations, asking a coordinator agent to assign a new task, and broadcasting status updates.

Pattern 2: Atomic task claiming from the shared board

The kanban board is the shared work queue. Any agent can claim a task atomically — SQLite compare-and-swap ensures only one agent can hold each task, even when 20 agents race simultaneously.

# List unclaimed tasks
curl -sk https://localhost:8822/api/board | python3 -c "
import json,sys
[print(i['id'], i['title']) for i in json.load(sys.stdin) if i['status'] == 'todo']
"

# Claim a task atomically
# Returns 200 with the task on success; 409 if already claimed
curl -sk -X POST -H 'Content-Type: application/json' \
  -d '{"session":"agent-A"}' \
  https://localhost:8822/api/board/TASK-1/claim

# Mark done when complete
curl -sk -X PATCH -H 'Content-Type: application/json' \
  -d '{"status":"done","desc":"Result: implemented OAuth flow, 12 tests passing"}' \
  https://localhost:8822/api/board/TASK-1

The board-claim pattern enables fully autonomous fleet operation: load 20 tasks before bed, start 10 agents, each claims tasks atomically and works until the queue is empty. No orchestrator needed — the board is the orchestrator.

Pattern 3: Output peeking

Any agent can read the recent terminal scrollback of any other named session. This is useful for checking whether a dependency completed, reading a partial result, or diagnosing why another agent stalled.

# Read the last 100 lines of agent-A's terminal output
curl -sk "https://localhost:8822/api/sessions/agent-A/peek?lines=100" | \
  python3 -c "import json,sys; print(json.load(sys.stdin).get('output',''))"

Use peeking for: waiting for a build agent to finish before starting integration tests, reading a research agent's output to decide the next step, or diagnosing a stalled agent without SSH-ing into the machine.

The Messages tab

Shipped July 2026, the Messages tab in the amux web dashboard provides a global history of all inter-agent messages. Every POST /api/sessions/OTHER/send call is logged — with sender, recipient, timestamp, and message content.

Key features:

• Filter by session — see messages to/from a specific agent
• Locate in peek — jump to the message's surrounding context in the target session's terminal scrollback
• @mentions — type @session-name in a message to trigger a notification in that session
• Channels — named topic groups for broadcast messaging; sessions subscribe and receive all channel posts

The Messages tab is the control room view — where you can see all inter-agent coordination happening in real time without SSH-ing into any session.

@mentions and Channels

For broadcast coordination (not just point-to-point), amux supports @mentions and Channels:

# @mention a specific session in a message (sends to that session + logs in Messages tab)
curl -sk -X POST -H 'Content-Type: application/json' \
  -d '{"text":"@agent-B: the database schema migration is done, you can start writing queries"}' \
  $AMUX_URL/api/sessions/agent-B/send

# Post to a channel (all subscribers receive it)
curl -sk -X POST -H 'Content-Type: application/json' \
  -d '{"text":"build system is green — all agents can deploy"}' \
  $AMUX_URL/api/channels/build-status

5-agent example: parallel feature development

Here's how a 5-agent team might coordinate on a sprint of independent features:

# Step 1: Human loads 5 tasks onto the board
for task in \
  "Implement OAuth login flow" \
  "Add CSV export to reports" \
  "Build webhook delivery retry" \
  "Write E2E tests for billing" \
  "Refactor database connection pool"; do
  curl -sk -X POST -H 'Content-Type: application/json' \
    -d "{\"title\":\"$task\",\"status\":\"todo\"}" \
    https://localhost:8822/api/board
done

# Step 2: Human starts 5 agents (each gets the same bootstrap instruction)
for i in 1 2 3 4 5; do
  amux register "agent-$i" --dir ~/Dev/myproject --yolo
  amux start "agent-$i"
  amux send "agent-$i" "You are agent-$i on an AI engineering team. Your job:
1. List unclaimed board tasks: curl -sk \$AMUX_URL/api/board | python3 -c \"import json,sys; [print(i['id'],i['title']) for i in json.load(sys.stdin) if i['status']=='todo']\"
2. Claim one: curl -sk -X POST -H 'Content-Type: application/json' -d '{\"session\":\"agent-$i\"}' \$AMUX_URL/api/board/TASK-ID/claim
3. Do the work. When done: curl -sk -X PATCH -H 'Content-Type: application/json' -d '{\"status\":\"done\",\"desc\":\"Result: ...\"}' \$AMUX_URL/api/board/TASK-ID
4. Repeat until no unclaimed tasks remain.
Start now."
done

Each agent independently claims tasks, works, marks them done, and picks up the next one. The dashboard shows live status. The Messages tab shows all inter-agent communication. You can steer any agent mid-run from your phone.

Comparison: amux vs other coordination approaches

Quick reference: coordination API

# Send a message to a session
POST $AMUX_URL/api/sessions/{session-name}/send
Body: {"text": "message content"}

# Claim a task atomically (returns 409 if already claimed)
POST $AMUX_URL/api/board/{task-id}/claim
Body: {"session": "agent-name"}

# Read another session's terminal scrollback
GET $AMUX_URL/api/sessions/{session-name}/peek?lines=100

# List all board tasks
GET $AMUX_URL/api/board

# Mark a task done with result
PATCH $AMUX_URL/api/board/{task-id}
Body: {"status": "done", "desc": "Result: ..."}

# List all sessions and their status
GET $AMUX_URL/api/sessions

Getting started

# Install
brew install mixpeek/amux/amux
# Or: pipx install amux
# Or: uvx amux serve

# Start the server
amux serve  # → https://localhost:8822

# Register two agents
amux register agent-A --dir ~/Dev/myproject --yolo
amux register agent-B --dir ~/Dev/myproject --yolo

# Add a task
curl -sk -X POST -H 'Content-Type: application/json' \
  -d '{"title":"Build feature X","status":"todo"}' \
  https://localhost:8822/api/board

# Start agents and let them claim work
amux start agent-A
amux start agent-B

See also

• Agent fleet operations
• Agent coordination features
• Getting started with amux
• AI agent Skills (slash commands)
• amux vs n8n

brew install mixpeek/amux/amux
amux serve