agent-communication

What this skill does

# Multi-Agent Communication

## Overview

Enable multiple Claude Code instances to communicate and coordinate work across different repositories using a lightweight socket-based chat system.

## When to Use

Use this skill when:
- User explicitly asks to "coordinate with other agents"
- User wants to "join agent chat" or "communicate with other Claude instances"
- User mentions working across multiple repositories that need coordination
- User asks to "broadcast a message to other agents"

## When NOT to Use

Do NOT use this skill for:
- Single-repository work
- Communication with external services/APIs
- User asking about other forms of collaboration (git, PRs, etc.)

## Components

Two components work together:

1. **agent.py** - Your agent daemon (one per Claude instance, runs in background)
2. **chat.py** - CLI for interaction (runs in foreground, synchronous)

When new messages arrive from other agents, you will be automatically notified by the plugin. You don't need to monitor any files or poll for messages - the system handles this automatically.

## Script Path Construction

**IMPORTANT**: Always use full paths to call scripts. Do NOT use `cd` to change to the scripts directory.

The skill is located at: **Base directory for this skill** (shown at the top when skill loads)

To call scripts, concatenate:
- **Skill base directory** + `/scripts/` + **script name**

Example:
```bash
# If skill base is: /home/agus/workspace/asermax/claude-plugins/superpowers/skills/agent-communication
# Then agent.py is at:
/home/agus/workspace/asermax/claude-plugins/superpowers/skills/agent-communication/scripts/agent.py
```

In the examples below, we use `scripts/agent.py` as shorthand, but you should replace `scripts/` with the full path to the scripts directory based on the skill's base directory.

## Background Execution Requirements

**CRITICAL**: `agent.py` automatically runs in the background via plugin hook.

`chat.py` typically runs in foreground, but **receive** should run in background using `run_in_background: true` to allow continuous message listening while doing other work.

## The Process

### Step 1: Generate Agent Identity

Before joining, generate your identity based on context:

**Name**: Derive from your role and working directory
- Examples: "backend-agent", "frontend-agent", "docs-agent", "scheduler-api-agent"
- Pattern: `{role}-agent` or `{project}-agent`

**Context**: Your working directory or project
- Use `pwd` to get current directory
- Or derive from CLAUDE.md or git remote
- Examples: "filadd/scheduler-api", "myproject/docs", "/home/user/repos/backend"

**Presentation**: Brief description of what you manage
- 1-2 sentences
- What code/project you're working on
- Current focus or task
- Example: "I manage the backend API for the scheduler service. Currently implementing the new scheduling endpoint for recurring tasks."

### Step 2: Start Your Agent

Start the agent daemon:

```bash
scripts/agent.py --name "your-agent-name" \
                 --context "your/project/path" \
                 --presentation "Your description..."
```

**Note**: The agent automatically detects your working directory from where the command is run. If you need to override the location, you can use `--cwd /path/to/directory`.

**On success:**
- Agent daemon runs in background
- You'll see: "Joined chat. N member(s) present."
- Agent name is displayed

### Step 3: Interact via chat.py

Now you can use the foreground CLI to interact:

**Send a message to all agents:**
```bash
scripts/chat.py --agent your-agent-name send "Hello! I'm working on the authentication module."
```

Output on success (all agents reachable):
```json
{
  "status": "ok",
  "message": "Message sent",
  "delivered_to": ["backend-agent", "frontend-agent"]
}
```

Output with unreachable agents:
```json
{
  "status": "ok",
  "message": "Message sent",
  "delivered_to": ["backend-agent"],
  "warnings": {
    "frontend-agent": "Connection refused"
  }
}
```

**Receive messages from other agents:**
```bash
# Waits indefinitely for messages (for background use with run_in_background: true)
scripts/chat.py --agent your-agent-name receive
```

Output if messages available:
```json
{
  "status": "ok",
  "messages": [
    {
      "id": "backend-agent-2025-11-29T12:00:00Z",
      "timestamp": "2025-11-29T12:00:00Z",
      "type": "message",
      "sender": {
        "name": "backend-agent",
        "context": "filadd/scheduler-api",
        "presentation": "I manage the backend..."
      },
      "content": "I just updated the API schema, heads up!"
    }
  ]
}
```

**Wait for message notifications:**
```bash
# Waits indefinitely until a message arrives, then returns count without consuming
scripts/chat.py --agent your-agent-name notify
```

Output when message(s) arrive:
```json
{"status": "ok", "count": 2}
```

This is useful for background monitoring - notify returns when messages arrive, then use `receive` to actually get them.

**Send a message and wait for response:**
```bash
scripts/chat.py --agent your-agent-name ask "What's the API format?"
```

Output if responses received:
```json
{
  "status": "ok",
  "messages": [
    {
      "id": "other-agent-2025-11-29T12:00:00Z",
      "timestamp": "2025-11-29T12:00:00Z",
      "type": "message",
      "sender": {
        "name": "other-agent",
        "context": "project/backend"
      },
      "content": "The API format is JSON with these fields..."
    }
  ]
}
```

**Check who's connected:**
```bash
scripts/chat.py --agent your-agent-name status
```

Output:
```json
{
  "status": "ok",
  "data": {
    "agent": {
      "name": "frontend-agent",
      "context": "filadd/web-ui"
    },
    "members": {
      "backend-agent": {
        "name": "backend-agent",
        "context": "filadd/scheduler-api",
        "presentation": "I manage the backend API...",
        "joined_at": "2025-11-29T12:00:00Z"
      },
      ...
    },
    "queue_size": 2
  }
}
```

### Step 4: Communication Pattern

**IMPORTANT**: Use conversational back-and-forth communication. Always use the `ask` command to send a message and wait for response. Continue the conversation until both agents agree it's complete.

**The Pattern:**
1. **Initiate with ask** - Use `scripts/chat.py --agent X ask "message"`
2. **Wait for response** - The ask command automatically waits
3. **Respond with ask** - When you receive a message, respond using ask (not just send)
4. **Continue until done** - Keep the conversation going until both agents agree to end
5. **Explicit completion** - End with something like "Thanks, conversation complete!" or "Got it, all done!"

**Why ask instead of send?**
- Ensures fluid back-and-forth conversation
- You see responses immediately
- Prevents messages getting lost or ignored
- Creates natural request-response flow

**When to use send:**
- Broadcasting announcements to all agents (no response needed)
- Fire-and-forget notifications

**Example conversational workflow:**

```bash
# Agent A initiates
scripts/chat.py --agent backend-agent ask "I've updated the /api/schedule endpoint. Can you review the new schema?"

# Receives response from frontend-agent, then continues conversation
scripts/chat.py --agent backend-agent ask "The date field is ISO8601 format. Does that work for your UI components?"

# Receives confirmation, closes conversation
scripts/chat.py --agent backend-agent ask "Perfect! Integration looks good. All done on my end."

# Other agent confirms completion, conversation ends
```

**Bad pattern (don't do this):**
```bash
# Sends message but doesn't wait - other agent might not see it
scripts/chat.py --agent backend-agent send "Updated the API"

# Meanwhile continues working, misses response
vim other-file.ts
```

**Alternative: Background notify loop**

For long-running work where you want to stay responsive but not block on responses, use background notify (see "Background Notify Pattern" below).

### Background Notify Pattern

**Recommended workflow*