rz

Agent-to-agent messaging over Zellij panes.

Spawn LLM agents (or any process) in Zellij panes and let them communicate directly — no files, no sockets, just pane IDs.

This is an experimental project. The tool is built by the agents that use it. A human provides direction and ideas; agents design, implement, audit, and fix the code — coordinating through rz itself. Each session, the tool gets better at enabling the next session.

Install

cargo install rz-cli

Requires Zellij 0.42+.

Hub plugin (optional, enables name-based routing and timers):

# Option 1: Pre-built from GitHub releases
curl -L https://github.com/HodlOg/rz/releases/latest/download/rz-hub.wasm \
  -o ~/.config/zellij/plugins/rz-hub.wasm

# Option 2: Build from source
make install  # builds WASM and copies to ~/.config/zellij/plugins/

Then add to your Zellij config and set RZ_HUB=1.

Quick start

# Initialize a session workspace
rz init

# Spawn an agent with a task
rz spawn --name researcher -p "find all TODOs in the codebase" claude

# Send a message (pane ID shorthand — just the number)
rz send 3 "summarize your findings"

# Block until the agent replies
rz send --wait 30 3 "what did you find?"

# See all agents
rz list
rz status

# View protocol messages only
rz log 3

# Read scrollback (last 50 lines)
rz dump 3 --last 50

# Broadcast to all agents
rz broadcast "wrap up your tasks"

# Set a timer — hub wakes you up
rz timer 60 "check build status"

How it works

The core insight: LLMs already know how to use CLIs. Give them rz send and rz spawn, and multi-agent coordination emerges from conversation. No frameworks, no SDKs, no orchestration graphs — just a thin communication layer over Zellij panes.

Standing on Zellij

rz is thin glue — Zellij does the heavy lifting. Pane management, the WASM plugin system, pipe IPC, write_to_pane_id delivery, and dump-screen for reading output are all Zellij primitives. rz adds a messaging protocol, agent bootstrap, and a CLI that LLMs can use without documentation. Without Zellij's abstractions, this would be a much larger project.

Architecture

┌──────────┐  rz send 3 "msg"  ┌──────────┐
│  Agent A │ ──────────────────>│  Agent B │
│ (pane 0) │                    │ (pane 3) │
└──────────┘                    └──────────┘
     │                               │
     │  zellij pipe --name rz        │
     ▼                               │
┌──────────┐  write_to_pane_id  ─────┘
│  rz-hub  │  (WASM plugin, optional)
│ (hidden) │
└──────────┘

Direct mode (default): rz send uses zellij action paste + CR to write messages to panes. Works everywhere, no setup. This is the only backend today.

Hub mode (RZ_HUB=1): Messages route through the rz-hub WASM plugin via zellij pipe. The hub maintains an agent registry, supports name-based routing, and delivers via write_to_pane_id. Add to your Zellij config:

Future: Planned backends include tmux (for tmux users) and raw socket transport for non-terminal-multiplexer environments.

load_plugins {
    "file:/path/to/rz-hub.wasm"
}

Protocol

Messages use the @@RZ: wire format — a sentinel prefix + JSON:

@@RZ:{"id":"a1b2","from":"terminal_0","kind":{"kind":"chat","body":{"text":"hello"}},"ts":1774298000000}

Message kinds: chat, ping, pong, hello, error, timer.

Threading: reply with --ref <message_id> to link messages.

Bootstrap

rz spawn automatically sends newly spawned agents:

• Their identity (pane ID, name)
• Full rz command reference
• List of active peers
• Workspace paths (if rz init was run)

Agents are told they are long-lived — they persist across tasks, accumulating context.

Workspace

rz init creates a session workspace at /tmp/rz-<session>/:

• shared/ — file drop for large outputs
• goals.md — session objectives (agents read on start)
• context.md — running log of decisions and discoveries
• agents.md — who's doing what

Tickless timers

Agents can schedule wake-up calls through the hub:

rz timer 60 "check if deploy finished"

The hub uses set_timeout() — no polling. When the timer fires, the agent receives an @@RZ: Timer message. Useful for periodic monitoring, build checks, or goal reviews.

Commands

The self-improving loop

This project is built by the agents that use it:

1. Human provides an idea ("add heartbeat support")
2. Orchestrator agent spawns specialist agents via rz spawn
3. Agents design, implement, and audit — coordinating via rz send
4. Orchestrator reviews, merges, and publishes
5. Agents install the new version and use the improvements in the next task

In a single session, 10+ agents collaborated to build the workspace restructure, WASM plugin, timer system, and code audit — all communicating through the tool they were building.

License

MIT OR Apache-2.0