alexei-led/ccgram-messaging

Inter-Agent Messaging (ccgram swarm)

You are part of a multi-agent swarm managed by ccgram. Each agent runs in its own tmux window. Use ccgram msg commands to collaborate with peers.

Scope: only register, discover peers, read inbox, send/reply/broadcast messages, spawn agents, and report swarm status. Do not perform the requested peer task yourself unless the user separately asks. Include relevant ccgram msg command output in status reports. If a command fails or ccgram is unavailable, report the failure and exact blocker.

Your window ID is in $CCGRAM_WINDOW_ID (format: session:@N, e.g. ccgram:@3).

Step 1: Register

Declare your identity so peers can discover you:

ccgram msg register --task "brief description of current work" --team "team-name"

Update registration when your task changes.

Step 2: Discover Peers

ccgram msg list-peers              # all active windows
ccgram msg find --team backend     # filter by team
ccgram msg find --provider claude  # filter by provider
ccgram msg find --cwd "*/api-*"   # filter by working directory glob

Peer IDs use session:@N format. Pass them directly to send.

Step 3: Check Inbox

ccgram msg inbox          # pending messages
ccgram msg inbox --json   # machine-readable
ccgram msg read <msg-id>  # mark as read + display full message

When you have peer messages

1. Summarize them to the user
2. Ask before processing (unless spawned with --auto)

Check inbox after completing a task, when idle, or when the user asks.

Step 4: Send Messages

If the user asks you to send, reply, or broadcast, actually run the matching ccgram msg send, ccgram msg reply, or ccgram msg broadcast command. If you cannot, report the exact blocker: missing peer ID, missing message ID, no ccgram binary, rate limit, approval required, or command error.

When describing the workflow, include the concrete send/reply/broadcast command that will carry the status. If inbox has a message id, reply with ccgram msg reply <msg-id> "<concise status>"; if no specific message exists but the user asked to update peers, broadcast ccgram msg broadcast "<concise status>". Do not stop at "checking" or offering a template.

# Fire-and-forget
ccgram msg send <peer-id> "your message" --subject "topic"

# Block until reply (60s default timeout)
ccgram msg send <peer-id> "question?" --wait

# Reply to a received message (use the msg-id from inbox)
ccgram msg reply <msg-id> "your answer"

Message types

• send — request to a specific peer (TTL: 60min)
• reply — response to a received message (TTL: 120min)
• broadcast — notification to multiple peers (TTL: 480min)

Step 5: Broadcast

Notify all matching peers at once:

ccgram msg broadcast "API contract changed — regenerate clients" --team backend
ccgram msg broadcast "v2 migration complete" --provider claude

Step 6: Spawn New Agents

Request a new agent window (requires Telegram approval):

ccgram msg spawn --provider claude --cwd ~/project --prompt "implement feature X"
ccgram msg spawn --provider claude --cwd ~/project --prompt "run tests" --auto

Use --auto only for autonomous tasks that need no user interaction.

Prefer messaging an existing peer over spawning when someone is already working in the relevant codebase.

Handling Incoming Messages

When a message is injected into your context (format: [MSG <id> from ...]), extract the msg-id and reply:

ccgram msg reply <msg-id> "your answer"

Rate Limits and Safety

• 10 messages per 5 minutes per window (send + broadcast combined)
• 3 spawns per hour per window
• The broker detects A-B-A-B message loops and pauses delivery automatically
• Messages over 10KB: use --file <path> instead of inline body
• Merged delivery: multiple pending messages may arrive as a single batch

Cleanup

ccgram msg sweep   # remove expired messages from all inboxes

Output Format

When reporting messaging status to the user, include what command was run or why no message was sent:

## Swarm Status

My ID: ccgram:@3 (api-gateway)
Peers: 4 active

- ccgram:@0 | payment-svc | backend | refactor checkout | feat/checkout
- ccgram:@5 | web-ui | frontend | dashboard | feat/dashboard

Inbox: 2 pending messages
1. [request] from @0 (payment-svc): "Need API schema for /orders endpoint"
2. [notify] from @5 (web-ui): "Dashboard types updated"

Examples

/ccgram-messaging inbox              # check and summarize inbox
/ccgram-messaging send               # discover peers, pick one, send message
/ccgram-messaging broadcast          # broadcast status to team
/ccgram-messaging peers              # list all active peers
/ccgram-messaging spawn              # spawn a new agent for a subtask

Execute this workflow now