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

Zellij's pane model gives you both high autonomy and high oversight — agents work independently in their panes while every scrollback is one rz dump away. The human operates at the architectural level, steering direction and messaging any agent directly. Agents handle implementation, design details, auditing, and coordination — spawning their own sub-agents when needed.

In a single session, 10+ agents built the workspace restructure, WASM plugin, timer system, and code audit — communicating through the tool they were building, improving it as they used it.

License

MIT OR Apache-2.0