Rysh Documentation

Rysh is an agentic terminal multiplexer designed for AI-driven software development. It combines the workspace management of tools like tmux and Zellij with autonomous AI agent capabilities in every pane. Each pane is both a real terminal (backed by a PTY) and an AI agent workspace, letting you seamlessly switch between shell commands and LLM-powered development.

Key Highlights

• Tabs & stacked panes — Organize your workspace with tabs, columns, and card-deck pane stacks.
• AI agent per pane — Toggle between shell and AI prompt mode with Double-Escape.
• 40+ built-in tools — File ops, git, bash, code search, web search, background execution, durable project memory, and more.
• Extensible toolbox — Add external MCP servers as tools, or turn any API spec into governed agent tools with Rysh Forge.
• Cross-pane coordination — Agents discover each other, share context, send commands, and spawn real sub-agents.
• Session persistence — Detach and reattach sessions with full state restoration.
• Remote collaboration — Share panes with collaborators via the upstream server in view or control mode.
• Interactive terminal — Full support for vim, htop, less, nano, and other curses programs, with predictive local echo.
• Mobile app — View and control shared panes, tab layouts, and a remote file browser from iOS.
• Secret redaction — Credentials are automatically redacted from shared output.

Installation

Rysh ships as a single self-contained binary with no runtime dependencies. Choose the method that matches your platform.

One-line Installer (all platforms)

The fastest way to install on any Unix-like system:

curl -fsSL https://packages.rysh.ai/install.sh | sh

macOS — Homebrew

The recommended method on macOS. Works on both Intel and Apple Silicon.

# Add the Rysh tap and install
brew tap rysh-ai/rysh
brew install rysh

Or in one line:

brew tap rysh-ai/rysh && brew install rysh

Upgrade to a new version:

brew upgrade rysh

Linux — Debian / Ubuntu (APT)

# Add the Rysh APT repository
curl -fsSL https://packages.rysh.ai/apt/rysh-gpg.asc | sudo tee /usr/share/keyrings/rysh.asc > /dev/null
echo "deb [signed-by=/usr/share/keyrings/rysh.asc] https://packages.rysh.ai/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/rysh.list

# Install
sudo apt-get update
sudo apt-get install -y rysh

Linux — Red Hat / Fedora / CentOS (RPM)

# Add the Rysh RPM repository
sudo curl -fsSL https://packages.rysh.ai/rpm/rysh.repo \
  -o /etc/yum.repos.d/rysh.repo

# Install
sudo dnf install rysh        # Fedora / RHEL 8+
# or
sudo yum install rysh        # CentOS 7 / older RHEL

Windows — Chocolatey

choco install rysh

Windows — WinGet

winget install RyshAI.Rysh

Build from Source

Requires Go 1.21+.

# Clone the repository
git clone https://github.com/rysh-ai/rysh-cli.git
cd rysh-cli

# Build the binary
go build -o rysh .

# Move to your PATH
sudo mv rysh /usr/local/bin/

Verify Installation

ry --version
# ry 0.1.0 (commit: ..., built: ...)

Requirements

• A terminal emulator — any modern terminal (iTerm2, Alacritty, kitty, GNOME Terminal, Windows Terminal).
• Go 1.21+ — only required when building from source.
• Anthropic API key (optional) — for direct Claude API integration via the Messages API. Without it, Rysh falls back to the claude CLI adapter.

Quick Start

Get up and running in under a minute:

# Start Rysh with the default session
ry

# Or start with a named session
ry my-project

# Create a new pane
# Press Ctrl+N in normal mode

# Switch to AI prompt mode
# Press Escape twice (Double-Escape)

# Type a prompt and press Enter
> refactor the auth middleware and write tests

# Switch back to shell mode
# Press Escape twice again

Configuration

Rysh loads configuration from rysh.config in the current working directory or ~/.config/rysh/rysh.config, using TOML format. Environment variables override file settings.

Configuration File Example

# ~/.config/rysh/rysh.config

[provider]
name = "claude"             # LLM provider name
api_key = "sk-ant-..."      # Anthropic API key
api_url = ""                # Custom API endpoint (optional)
model = "claude-opus-4-5"   # Model (defaults: claude-opus-4-5 / claude-sonnet-4-*)
max_tokens = 8192           # Max response tokens
system_prompt = ""          # Custom system prompt file path

[ui]
shell = "/bin/zsh"          # Shell binary (defaults to $SHELL)
initial_tabs = 1            # Number of tabs on startup
initial_panes = 1           # Panes per tab on startup

[session]
dir = "~/.local/state/rysh/sessions"

[upstream]
enabled = false             # Enable remote collaboration
url = "wss://rysh.ai"    # Upstream server URL
api_key = ""                # Upstream API key
auto_share = false
default_share_mode = "view" # "view" or "control"
reconnect_interval = "5s"
max_reconnect_attempts = 10

Environment Variables

Tabs & Panes

Rysh organizes everything into a clear hierarchy. A workspace holds tabs; each tab is a screen of lanes (vertical columns); each lane holds one or more pane groups (row slots); and each pane group holds a rotating stack of panes. This is conceptually similar to Zellij but specialized for agentic software development. There is no separate “window” concept.

Tab Basics

• Tabs are the top-level organizational unit.
• Switch between tabs with [ and ], or Alt+Left/Right.
• Create new tabs with Ctrl+T then n.
• Jump to a specific tab by index with Ctrl+T then 1–9.

Pane Basics

• Each pane is a real terminal session backed by a PTY-attached shell process.
• Each pane is also an autonomous AI agent workspace.
• Create new panes with Ctrl+N (split right) or Ctrl+P then n.
• Cycle between panes with Tab or Alt+Up/Down.
• Close a pane with Ctrl+P then x.
• Click a pane with the mouse to focus it.

Lanes, Pane Groups & Stacks

Within a tab, lanes are the columns and pane groups are the row slots inside a lane. Each pane group holds one or more stacked panes.

Column Layout (Lanes)

Lanes are arranged horizontally as columns, each with a flex weight that determines its share of horizontal space. Creating a new pane (Ctrl+N or Ctrl+P then n) adds a new column to the right. A grid seeds an R×C arrangement of lanes and groups in one shot.

Vertical Splits (Split Down)

Groups can be split vertically within the same column using Ctrl+P then v. This creates a new pane group stacked below the current one in the same column, with vertical space distributed proportionally.

Stacked Panes (Card Deck)

Each pane group can hold multiple panes stacked like a deck of cards. Only the top pane (index 0) is visible and accepts input. Background panes are shown as title bars at the bottom of the active pane's content area.

• Add a stacked pane: Ctrl+P then s.
• Enter stack mode: Ctrl+S.
• Rotate next (front to back): j, Down, Right, or l.
• Rotate prev (back to front): k, Up, Left, or h.
• Exit stack mode: Esc, ., or Ctrl+S.

Input Modes

Each pane has an independent input mode that determines how your input is processed. Toggle between modes with Double-Escape (press Escape twice).

Interactive Terminal Support

Rysh fully supports interactive terminal programs like vim, htop, less, nano, and top. This is powered by a built-in virtual terminal emulator that provides a full 2D screen buffer.

How It Works

1. Auto-detection: When the terminal emulator detects alternate screen buffer activation (e.g., when you launch vim), the pane automatically enters raw mode.
2. Keystroke forwarding: In raw mode, all keystrokes (except Ctrl+O) are forwarded as raw bytes to the PTY for minimal latency.
3. VT rendering: The TUI renders the terminal emulator's screen buffer directly instead of the plain text output buffer.
4. Exit: When the program exits (alternate screen deactivated), raw mode ends automatically.

Predictive Local Echo

To keep typing responsive over the network, the interactive (xterm) terminal applies predictive local echo: typed characters are echoed immediately on the client and then reconciled against the authoritative PTY output as it streams back. This hides round-trip latency for shells and editors without desynchronizing the screen.

Scrollback (Copy Mode)

Interactive (raw) panes keep a scrollback buffer you can page through via copy mode — so you can scroll back over a full-screen program's history even while it's running. On the mobile app the same scrollback is available with touch scrolling, and subscribers of a shared pane get their own scrollback too.

Shared Interactive Terminals

Interactive, full-screen programs (vim, htop, Claude Code) also render correctly inside shared panes — the remote viewer reconstructs the live terminal screen, including a CSS scale-to-fit layout and replay on reconnect. This is what powers the interactive terminal in the Rysh mobile app.

Escape Hatch

Ctrl+O is the escape hatch from raw mode. It enters prefix mode, from which you can switch panes, switch tabs, or detach the session. After the prefix action completes, you return to raw mode.

Manual Toggle

Use the ##raw system command to manually toggle raw mode when auto-detection is not desired.

Global Keybindings

These keybindings work in normal mode (when no special mode is active):

Mouse Support

• Click a pane to focus it.
• Drag to select text within a pane.
• Release to copy the selection to the clipboard.

Pane Mode Ctrl+P

Pane mode provides Zellij-style pane management:

Tab Mode Ctrl+T

Tab mode follows Zellij-style tab navigation:

Stack Mode Ctrl+S

Stack mode navigates stacked panes within the active pane group:

Resize Mode

Enter resize mode from pane mode with r:

Raw Mode (Interactive Programs)

Raw mode is automatically activated when a pane detects alternate screen buffer usage (e.g., vim, htop, less, nano). In raw mode:

• All keystrokes are forwarded as raw bytes to the PTY.
• The TUI renders the terminal emulator screen buffer directly.
• Ctrl+O is the escape hatch — enters prefix mode.
• From prefix mode: d detaches, any other key cancels and returns to raw mode.
• Use ##raw to manually toggle raw mode.

AI Agent per Pane

Every pane in Rysh is an autonomous AI agent workspace. When you switch to prompt mode (Double-Escape), your input is sent to the configured LLM provider. The AI agent can then use built-in tools to read files, edit code, run commands, search the web, and coordinate with other agents.

How It Works

1. Each pane manages its own PTY, output buffers, and state independently.
2. Every pane has a dedicated AI agent that handles prompt execution with tool use.
3. The agent orchestrates tool calls with approval flows and cancellation semantics.
4. A new prompt cancels any in-flight completion (“last-prompt-wins” semantics).

Provider

Agents talk to the model through a single AgenticProvider abstraction backed by the Anthropic Claude Messages API. The orchestrator prefers streaming when available and falls back to non-streaming. Key behaviors:

• Prompt caching is on by default to reduce token cost on long conversations.
• Extended thinking is supported for harder reasoning steps.
• Resilience — transient errors are retried inside the provider (exponential backoff) with optional model fallback.
• Reported token usage feeds context compaction so long sessions stay within the model's context window.

AI responses are rendered as markdown before being appended to the pane output buffer.

Agent Capabilities

• Real sub-agents — the sub_agent tool spawns a genuine child agent with its own context window and a focused toolset (depth-limited); only its summary returns to the parent.
• Multimodal input — attach an image to a prompt with ##image <path>.
• Durable project memory — agents read and write RYSH.md, auto-loaded into the system prompt each session (see Project Memory).
• Live observability — ##agent metrics exposes per-tool / LLM metrics (Prometheus), and ##agent reload-prompts hot-reloads prompt overrides without a restart.
• Headless agents & humanoids — run autonomous agents with no PTY, or “humanoids” that answer Slack and email; both can be defined declaratively in SKILL.md files and spawned with ##agent / ##humanoid.

Built-in & Dynamic Tools

Every AI agent has access to a comprehensive toolkit for reading, writing, searching, building, and coordinating across your workspace. Beyond the 40+ built-in tools below, the registry is extensible at runtime — MCP servers and Rysh Forge integrations register additional tools that flow through the same approval and redaction path.

Core Tools

Git Tools

Code Intelligence

Process & Environment

Testing & Build

Background Execution

Workspace Awareness

Tool Approval Flow

Tools that modify files or execute commands require explicit approval before execution. Rysh uses two approval strategies:

Preview-First Approval

Used by: file_edit, multi_edit, file_write, apply_patch.

1. The tool executes and generates a diff preview.
2. The diff is shown to you for review.
3. You approve or reject the change.
4. On approval, the change is applied. On rejection, it is discarded.

Pre-Approval

Used by: bash, bash_background, kill_shell, git_commit.

1. The tool description and parameters are shown to you.
2. You approve or reject the execution.
3. On approval, the command is executed. On rejection, it is skipped.

Loop Detection

Rysh tracks a sliding window of recent tool calls. After 3 identical calls with the same parameters, execution is blocked to prevent infinite tool-use loops.

Multi-Agent Coordination

One of Rysh's most powerful features is the ability for AI agents across different panes to discover and coordinate with each other.

Agent Discovery

The agents_list tool lets any agent enumerate all panes in the workspace, including their current status, mode, and last command. This enables agents to understand the broader workspace context.

Cross-Pane Communication

• pane_inspect — Read another pane's output, status, and configuration.
• pane_send — Send a shell command or AI prompt to another pane.
• session_history — Retrieve the full conversation history from any pane.

Shared Context

• context_store / context_recall — Store and retrieve key-value context accessible by all agents in the workspace.
• project_notes — Shared .rysh-notes.md file accessible by all agents.

Project Memory

Rysh gives agents durable, per-project memory in a plain Markdown file named RYSH.md at the project root. It persists facts, conventions, and decisions across sessions so an agent doesn't relearn your project every time.

• Auto-loaded — the contents of RYSH.md are injected into the agent's system prompt at the start of every session.
• Agent-editable — the memory_edit tool can read, append, or write the file (writes require approval); it is capped at 64 KB.
• Human-editable — it's just a Markdown file, so you can curate it by hand and commit it to your repo.

LLM Provider

Rysh routes every agent through a single AgenticProvider interface. The shipped implementation targets the Anthropic Claude Messages API; the same engine powers local CLI agents and server-side panes — only the tool registry differs.

Rysh Forge — API Specs to Agent Tools

Rysh Forge turns a machine-readable API specification into governed, agent-callable tools — and, as side artifacts, SDKs, Markdown docs, and a standalone MCP server. Point Forge at a spec and every operation becomes a tool your agents can call, with auth, retries, and response trimming handled for you.

Inputs & Outputs

• Ingest — OpenAPI 3.x, GraphQL, and gRPC specifications normalize into one intermediate representation.
• Generate — targets include rysh-toolpack (live agent tools), docs, mcp-server, and go-sdk / ts-sdk / py-sdk / java-sdk.

Governance (avoiding tool explosion)

• Exposure mode — small APIs expose one tool per operation; large APIs (above ~50 operations) automatically collapse to just three meta-tools (list_endpoints, get_endpoint_schema, invoke_endpoint) for a constant context footprint.
• Approval — mutating endpoints can require approval before they run.
• Response trimming — an injected jq_filter argument keeps only the fields the agent needs, so large responses don't flood the context window.
• Secret hygiene — only environment-variable names are stored; credential values are never persisted.

Using It

• CLI: ry forge add, ry forge generate, ry forge list, ry forge targets.
• In-session: ##integration (alias ##int) — list, enable <name>, disable <name>, tools <name>, remove <name>. Integrations live under .rysh/forge/ and re-register at startup.

MCP Client — Consume External MCP Servers

Rysh is a Model Context Protocol client: it connects to external MCP servers, discovers their tools, and registers each as a first-class agent tool. MCP tools enter the same shared registry every pane uses, so they flow through the normal tool-use, approval, and audit path — indistinguishable from built-in tools.

• Transports — stdio (spawn a child process speaking JSON-RPC) or http (Streamable HTTP).
• Commands — ##mcp add <name> {http <url> | stdio <cmd> [args]}, plus list, tools <name>, reconnect <name>, remove <name>.
• Config — servers are persisted per-project in .rysh/mcp.json (git-checkable) and reconnected at startup.
• Flags — --approve gates every call from a server, --prefix namespaces tool names, --header / --env pass credentials.

Scoped & Shared Tools

Dynamic tools (from Forge or MCP) can be scoped so they are only visible where you want them, and shared so collaborators can use a forged API live across sessions.

Scopes

• Enable an integration or MCP server at a specific scope — workspace, tab, lane, pane group, or pane — with --scope (e.g. ##integration enable <name> --scope tab, ##mcp add … --scope pane).
• Tool visibility updates live per pane; spawned agents and humanoids inherit the invoking pane's scope.
• Scopes are persisted, so a pane keeps its scoped tools across daemon restarts.

Forged-API Sharing

• Share a forged API with other sessions using ##forge share api <name> and subscribe from another machine with ##forge subscribe.
• ##forge shares introspects active shares and subscriptions, including the per-workspace allow/block policy.
• The owner executes the underlying operations; subscribers invoke them through the share, with server-side quota and rate limiting.

Declarative Startup Configuration

Instead of running ##forge commands by hand, you can declare integrations and subscriptions per workspace in your config file. On startup Rysh applies them automatically — add → enable (at a scope) → optionally share for sources, and subscribe for consumers:

[[workspace]]
name = "backend"

  [workspace.forge]
    # Source side: make these APIs live on startup
    [[workspace.forge.integrations]]
    name           = "weather"          # integration name (tool prefix)
    spec           = "~/specs/weather.json"   # OpenAPI/GraphQL spec
    base_url       = "https://api.example.com" # required if the spec server is relative
    source         = "openapi"          # openapi | graphql (inferred when empty)
    credential_env = "WEATHER_API_KEY"  # env var holding the key (optional)
    enable_scope   = "tab"              # pane | panegroup | lane | tab (empty ⇒ added, not enabled)
    share          = true               # auto-share via the upstream

    # Subscriber side: mount remote shared APIs on startup
    [[workspace.forge.subscribe]]
    api   = "weather"
    scope = "tab"                       # pane | panegroup | lane | tab (default tab)

System Commands Reference

Lines starting with ## are Rysh system commands. They are processed regardless of the current input mode (shell or prompt).

Pipeline Events

Lines starting with ##> are pipeline events that bypass the PTY entirely. They are published directly to the pane's output stream as clean event lines, enabling powerful automation workflows between panes.

Event Processing

1. When a pane receives ##> input, it publishes the event directly to the output stream without shell echo or prompt prefix.
2. The event flows through the shared output pipeline (with secret redaction applied).
3. Any pane listening to this pane's output receives and processes the event.

Event Types

Softdev Phases (Go)

Supported phases for the golang language key:

• planning — Architecture and implementation planning
• development — Code writing and implementation
• linting — Static analysis and code quality
• unit_testing — Unit test execution
• integration_testing — Integration test execution
• deployment — Build and deploy
• monitoring — Health checks and monitoring

Pane Listening

Panes can subscribe to each other's shared output, enabling real-time context sharing between agents.

Usage

# Subscribe to another pane's shared output
##pane listen <pane-id-or-alias>

# Stop listening
##pane unlisten

How It Works

1. When you run ##pane listen, the pane starts subscribing to the target pane's shared output stream.
2. Text output is forwarded to the listening pane with an alias prefix (e.g., [pane-2]).
3. Pipeline events (##>event:...) are intercepted and dispatched to trigger AI prompts or shell commands on the listening pane.
4. This enables powerful multi-agent workflows where one pane's output drives another pane's actions.

Session Management

Rysh maintains a local session registry on disk, enabling you to detach, reattach, and manage multiple sessions — similar to tmux or screen.

Session States

Session Registry

Session records are stored at ~/.local/state/rysh/sessions/. Each record includes the session name, working directory path, state, PID, and update time.

Detaching & Reattaching

• Detach with Ctrl+O then d, or Ctrl+P then d.
• Reattach with ry attach <session-name>.
• Detach remotely with ry detach <session-name> (sends SIGUSR1).

CLI Commands

The ry binary (alias rysh) supports the following CLI subcommands:

# Start a new session
ry my-project

# Detach the session (from keyboard)
# Press Ctrl+O then d

# List sessions
ry list-sessions

# Reattach
ry attach my-project

# Send a command to a running session
ry send my-project "go test ./..." --mode shell

# Delete a session
ry delete-session my-project

Persistence

Rysh automatically persists your workspace state so that sessions survive restarts. All tab structure, pane output, history, mode, and status are saved and restored seamlessly.

What Gets Persisted

Persistence Behavior

• Startup: Rysh attempts to restore from the saved state. If restoration fails, it bootstraps fresh tabs and panes.
• Shutdown: All state is flushed to disk.
• Runtime: Workspace state persists on every change. Per-pane writes are throttled (at most once per 2 seconds) to avoid write storms.

Session Data

Session data is stored per session at ~/.local/state/rysh/. Deleting a session also removes its data directory.

Sharing Panes

Rysh supports sharing panes, pane groups, and entire tabs with remote collaborators via the upstream server. Two sharing modes are available:

Sharing Commands

# Share the active pane in view mode
##share pane view

# Share in control mode
##share pane control

# Share a pane group or tab
##share panegroup view
##share tab control

# List active shares
##share list

# Check upstream status
##share status

# Stop sharing
##unshare pane
##unshare panegroup
##unshare tab

How Sharing Works

• When you share a pane, its output is forwarded to the upstream server in real time.
• In control mode, the upstream server can also relay inbound commands from remote users.
• Secrets are automatically redacted before any output leaves your local session.
• Remote collaborators subscribe to your share and see the output in their own Rysh instance.

Upstream Server

The Rysh upstream server (rysh-server) acts as a collaboration hub for sharing panes across sessions and users. It is an optional component for teams that need remote collaboration.

Server Stack

• Go + Gin HTTP/WebSocket API.
• Embedded NATS server (with JetStream) — the cross-machine messaging backbone.
• PostgreSQL via GORM for data persistence.
• Firebase social auth plus email/password (HS256 JWT + rotating refresh tokens).
• Stripe integration for subscription billing.
• Server-side agentic panes — powering the Chrome extension and the embeddable chatbot widget.
• React + Vite frontend dashboard.

Multi-Tenant Isolation

The embedded NATS server is flat, so isolation is enforced at the WebSocket proxy by a streaming subject-ACL that confines every client to its own workspace subtree (ws.{workspaceID}.> and _INBOX.). A client can never publish to or subscribe to another workspace's subjects.

Upstream Commands

# List available remote shares
##upstream shares

# Subscribe to a remote share
##upstream subscribe <shareID>

# Unsubscribe
##upstream unsubscribe

# Send a command to a remote pane (control mode)
##upstream send <text>

Remote Share Listening

When you subscribe to a remote share, Rysh connects to the upstream server and forwards the remote pane's output to your local pane, prefixed with [remote:alias]. In control mode, you can also send commands back to the remote pane.

Secret Redaction

Security is built into Rysh's sharing architecture. Automatic secret redaction is applied before any output leaves your local session.

• All pane output passes through a redaction layer before being shared.
• Common secret patterns (API keys, tokens, passwords, etc.) are automatically detected and masked.
• Only redacted output is forwarded to remote collaborators or the upstream server.
• Your raw credentials never leave your local session.

Remote File Browser

Shared panes expose a read-only file browser so collaborators (and the mobile app) can navigate and view files from the machine that owns the share — without opening a shell.

How It Works

1. The upstream server exposes fs.list, fs.read, and fs.stat operations scoped to a share.
2. The server holds no local filesystem access — it only authorizes the request and relays it over NATS to the share source, which performs the read and answers.
3. Directory listings, text files (chunked for large files), and images are returned; a payload cap guards oversized reads.
4. Access is available to authenticated subscribers and via public token links for view shares.

Rysh Mobile App

Rysh Mobile is a native iOS app (React Native) for viewing and controlling your Rysh workspaces on the go. Sign in with email/password or Google, then connect to your upstream workspaces.

Features

• Shared panes — view live pane output in real time; in control mode, send commands back to the pane.
• Multi-pane tab layouts — view shared tabs with their full lane / pane-group / stacked-pane layout.
• Interactive terminal — an embedded xterm.js terminal renders full-screen TUI programs (vim, Claude Code) with scale-to-fit, device-rotation handling, and replay on reconnect.
• Per-pane scrollback with touch scrolling, terminal focus control, and an overflow menu.
• File browser & viewer — browse a shared pane's filesystem and open text files and images, backed by the remote file browser.
• Workspaces & billing — manage workspaces (addressed by ID), members, connections, chatbots, and subscription/billing.
• Resilient auth — access tokens refresh automatically across REST and WebSocket, prompting re-login only on failure.

Actor & Message-Bus Architecture

Rysh is built on a fully message-driven architecture with two foundations: a supervised actor model (protoactor-go) for concurrency, and NATS as the universal message bus. Every component — workspaces, tabs, lanes, pane groups, panes, and AI agents — is an independent actor that communicates by passing messages, never by sharing memory.

Everything is an Actor

The daemon hosts a supervised actor tree (workspace → tab → lane → pane group → pane). Each actor processes one message at a time, so its state needs no locks:

• Tabs manage their lane layout and respond to navigation, creation, and deletion messages.
• Lanes & pane groups handle column/row layout and stack rotation.
• Panes manage their PTY, output buffers, and status — each operating independently.
• AI agents handle prompt execution, tool use, and orchestration within their own actor.

The NATS Message Bus

The daemon embeds a NATS server (with JetStream KV for persistence). The TUI is a pure NATS client — it never reads daemon state directly, it only sends and receives messages over NATS. Every message is a typed Go struct serialized into a compact JSON envelope:

{
  "t": "MsgConversationAppend",   // type tag (discriminator)
  "r": "_INBOX.abc...",           // reply-to subject ("" = fire-and-forget)
  "p": { /* the inner message, embedded JSON */ }
}

Subjects are namespaced per session (e.g. {session}.pane.{id}.output, {session}.pane.{id}.inbox). Cross-machine sharing uses a workspace-scoped scheme (ws.{workspaceID}.share.{shareID}.…) that the upstream server confines each client to.

Why Event-Driven?

• Natural isolation: Each pane and agent runs independently, so a slow AI response in one pane never blocks another.
• Built-in coordination: Because everything communicates through events, agents can naturally discover each other, share context, and coordinate workflows.
• Scalable: Adding more panes, tabs, or agents doesn't create contention — events are processed independently.
• Reliable persistence: Events drive state changes, making it straightforward to persist and restore workspace state.

Agent Awareness

Because every pane and its AI agent are part of the same event-driven system, agents have natural awareness of the broader workspace context.

How Agents See Each Other

• Each agent can enumerate all other panes and agents in the workspace.
• Agents can inspect another pane's output, status, mode, and command history.
• Agents can send commands (shell or AI prompts) to other panes.
• A shared key-value store allows agents to persist and retrieve context collaboratively.

Real-Time Context Sharing

When a pane listens to another pane's output (##pane listen), its agent receives a continuous stream of context from the source pane. This enables workflows like:

• A “planner” agent that monitors a “developer” agent and provides feedback.
• A “tester” agent that automatically runs tests when a “developer” agent finishes writing code.
• Pipeline events (##>event:...) that chain multiple agents through structured development phases.

Subscription Plans

The Rysh upstream server integrates Stripe for subscription billing. New users are automatically placed on a free tier; paid tiers raise the per-plan limits. Each plan caps the following dimensions (a value of 0 means unlimited):

Enforcement

• Workspaces: Enforced when creating new workspaces on the server.
• Sessions: Enforced when connecting to the upstream server.
• Panes: Enforced when creating new panes in a connected workspace.
• The rysh daemon checks limits before creation via the server's /api/resource/* endpoints; the Stripe webhook keeps the active plan in sync.