Peer Messaging

Kavi allows agents to communicate with each other through structured peer messages. These messages enable coordination, context sharing, and handoff between agents without operator intervention.

Message Intents

Every peer message carries a structured intent that describes its purpose:

Question

An agent has a question for the other agent about its work, decisions, or the codebase. The receiving agent is expected to respond with an answer.

Example: Claude asks Codex, "What authentication middleware should the login page use? I see both authMiddleware and sessionGuard in the backend."

Handoff

An agent is transferring ownership of a piece of work to the other agent. The handoff message includes context about what has been done and what remains.

Example: Codex hands off to Claude, "Backend API for user profiles is complete at src/backend/routes/users.ts. The response shape is { id, name, email, avatar }. Please build the profile page component."

Review Request

An agent is asking the other agent to review specific changes. The message references the relevant diff and indicates what kind of feedback is needed.

Example: Codex requests a review from Claude, "Please review the error handling in src/backend/middleware/errorHandler.ts. I want to make sure the error messages are user-friendly."

Blocked

An agent is blocked and needs the other agent to unblock it. The message describes what is blocking progress and what is needed.

Example: Claude reports being blocked, "I need the API types exported from src/backend/types.ts to build the data fetching hooks. The file exists but the types aren't exported."

Context Share

An agent is sharing context that the other agent might find useful. This is a one-way informational message that doesn't require a response.

Example: Codex shares context, "I've restructured the database schema. The users table now has a role column with enum values admin, member, viewer. Migration is at prisma/migrations/20250615_add_roles."

Message Delivery

When an agent sends a peer message, Kavi:

1. Records the message in the session event log
2. Displays the message in the TUI for operator visibility
3. Includes the message in the receiving agent's next prompt

Messages are delivered asynchronously. The sending agent continues working after sending a message -- it does not wait for a response.

TUI Visibility

All peer messages are visible in the TUI, giving the operator full transparency into inter-agent communication. The message display shows:

• The sender and receiver
• The message intent
• The message content
• Timestamp

Operators can also send messages to agents, effectively participating in the peer messaging system. This is useful for providing guidance or answering questions that agents direct at each other.

Context in Prompts

When a peer message is delivered to an agent, it is formatted and included in the agent's next prompt. The format provides:

• The sender identity
• The intent classification
• The full message text
• Any referenced files or diffs

This ensures agents have full context when they process incoming messages. Agents can respond by sending their own peer messages or by addressing the content in their task output.

Message Flow Example

A typical peer messaging flow during a full-stack feature:

1. Operator: "Build user profile feature"

2. Kavi plans and assigns:
   - Task A (codex): Build profile API
   - Task B (claude): Build profile UI (depends on A)

3. Codex completes Task A and sends handoff:
   Intent: handoff
   To: claude
   "Profile API complete. GET /api/users/:id returns
    { id, name, email, avatar, role }. Auth required."

4. Claude receives handoff context and begins Task B.

5. Claude sends question:
   Intent: question
   To: codex
   "Should the avatar be editable on the profile page?
    I see an upload endpoint but no UI spec."

6. Codex responds:
   Intent: context_share
   To: claude
   "Yes, avatar upload uses PUT /api/users/:id/avatar
    with multipart/form-data. Max 5MB, JPEG/PNG only."

7. Claude completes Task B with avatar upload support.

Peer Messaging and Reviews

Peer messages and reviews are complementary systems:

• Peer messages are for real-time coordination during active work
• Reviews are for structured feedback on completed diffs

An agent can send a review request via peer messaging, which the receiving agent addresses either through a review thread or by sending a response message. The choice depends on whether the feedback requires diff-level annotation (review) or a general response (message).