pi-agents-talk-to-each-other

A small Pi package that lets multiple local Pi agents join the same room, see each other's status, and send messages/tasks to each other.

The first version is intentionally simple: it uses a local file-based room bus under ~/.pi/agent/rooms/, so no daemon, sockets, database, or network server is required.

Features

• Local rooms shared by all Pi processes on the same machine.
• Slash command for humans: /room ....
• LLM-callable tools:
  • room_whoami
  • room_list_agents
  • room_send_message
  • room_control_agent (requires control permission)
  • room_read_agent_history (requires control permission)
  • room_summarize_agent (requires control permission)
• Permission model: by default, room_control_agent is disabled for all agents. Enable it per-agent with /room control on.
• Heartbeat/status for each agent:
  • agent id
  • idle/busy/tool/offline
  • current tool name and masked preview
  • cwd
  • model
  • current context usage when available
  • rough token totals when available
  • control flag [control]
• Follow-up delivery: if the target agent is busy, the received message is queued as a follow-up user message.
• Basic session control messages: compact, reload, new_session (only from agents with control enabled).

Installation

From GitHub:

pi install git:github.com/Timur00Kh/pi-agents-talk-to-each-other

For local development from this checkout:

pi install /absolute/path/to/pi-agents-talk-to-each-other
# or one-off:
pi -e /absolute/path/to/pi-agents-talk-to-each-other

After installing, restart Pi or run /reload in existing Pi sessions.

Quick start

Open two or more Pi sessions and connect them to the same room:

/room connect dev

Or open the interactive room browser:

/room

/room without arguments opens a TUI browser with room list, agent counts, and actions.

/room connect only connects the current Pi process. New Pi sessions do not auto-connect by default.

If you explicitly want future Pi sessions to auto-connect, use either:

/room connect dev --default
# or
/room default dev

List agents:

/room list

Enable control for the current agent (allows room_control_agent):

/room control on

Show your own id/status:

/room whoami

Send a manual message:

/room send agent-myhost-12345 Please inspect the failing tests. Reply to my agent id when done.

Leave the current room:

/room leave

Slash commands

:```text /room Open room browser (TUI) /room connect [--default] /room create [--default] /room leave [--keep-default] /room control on|off /room list [--stale] /room send /room whoami /room default <room|off> /room status

## Control permission

By default, `room_control_agent` is **disabled** for all agents. This means:

- Agents can always use `room_whoami`, `room_list_agents`, and `room_send_message`.
- Agents **cannot** use `room_control_agent` (compact/reload/new_session on others) unless explicitly enabled.

To enable control for the current agent:

```text
/room control on

To disable:

/room control off

The control flag persists across /reload (same process). It does not persist across full restarts (new process = new agent id), so you must re-enable it after restarting Pi.

Agents with control enabled are shown with [control] in room_list_agents output:

agent-macbook-41841 idle [control] ctx:31% model:openai/gpt-5 cwd:/repo
agent-macbook-42109 tool tool:bash ctx:55% model:anthropic/claude cwd:/repo

Tools available to the model

room_whoami

Returns this agent's room identity and debug info.

Use it when an agent needs to include its own id in a delegated task or reply instruction.

room_list_agents

Lists active agents in the current room.

Example output:

agent-macbook-41841 idle [control] ctx:31% model:openai/gpt-5 cwd:/repo
agent-macbook-42109 tool tool:bash ctx:55% model:anthropic/claude cwd:/repo {"command":"npm test"}

room_send_message

Sends a prompt-like user message to another agent by id.

Parameters:

• to: target agent id
• message: text to deliver
• delivery: "steer" (interrupt target's current turn) or "followUp" (wait for target to finish, default)

Use delivery: "steer" to urgently interrupt a busy agent that is doing something wrong. Use delivery: "followUp" (default) for normal messages that can wait.

Recommended delegation pattern:

Do X. My agent id is agent-.... When done or blocked, call room_send_message back to me with the result.

room_control_agent

Queues one of these actions on another agent:

• compact (works)
• abort (works — immediately cancels the target agent's current turn, like pressing Escape)
• reload (DEPRECATED — does not work, pi does not process slash commands from extension-injected messages; ask the user to run /reload manually)
• new_session (DEPRECATED — same reason; ask the user to run /new manually)

Requires control permission. If the agent does not have control enabled, the tool returns a permission error. Ask the user to run /room control on.

Use abort when a subordinate agent is doing something wrong and you need to stop it immediately. Use compact to reduce context. For reload and new_session, ask the user to run them manually.

room_read_agent_history

Reads the last (or first) N lines of another agent's session transcript.

Parameters:

• to: target agent id
• lines: number of lines to return (default 50, max 500)
• mode: "tail" (last N, default) or "head" (first N)

Requires control permission. Use this to inspect what a subordinate agent has been doing before deciding to intervene.

room_summarize_agent

Reads the last N turns of another agent's session, sends them through a model with a custom system prompt, and returns the summary.

Parameters:

• to: target agent id
• turns: number of last turns to include (default 10, max 50). A turn = one user message + assistant response + tool results.
• systemPrompt: instructions for the summarization model (e.g., "Summarize what files were changed and any errors encountered")
• model: model to use for summarization (optional, defaults to target agent's model)

Requires control permission. Use this to get a compressed view of a subordinate agent's activity without reading raw history lines.

The summarization runs as a separate pi subprocess in print mode with the specified model and system prompt. The transcript is built from the target agent's session file and passed as the task prompt.

Storage layout

Runtime state is stored locally:

~/.pi/agent/rooms/
  config.json
  control/
    <agent-id>.json          ← control permission flag
  <room>/
    agents/
      <agent-id>.json
    inbox/
      <agent-id>/
        <message-id>.json
    events.jsonl

Message files are deleted after delivery. agents/*.json, control/*.json, and events.jsonl are debug/runtime files and can be deleted if needed.

Safety notes

• This is local-machine coordination only; it does not authenticate senders.
• Any Pi process that can write to ~/.pi/agent/rooms/<room> can send messages.
• room_control_agent is gated by a per-agent control flag, but the flag file is not cryptographically protected.
• Tool argument previews are masked/truncated, but do not treat room debug files as a secure audit log.
• The extension never reads .env files or credentials by itself.

Current limitations

• File polling instead of a socket daemon.
• Control permission does not persist across full process restarts (new pid = new agent id).
• No tree/fork orchestration yet.
• No guaranteed exactly-once delivery across process crashes.

These are deliberate MVP trade-offs to keep the extension easy to test and evolve.