>_ Rysh← User docs
Home › Docs › Architecture

Rysh — Technical Documentation

An AI-agent-native terminal multiplexer with a multi-tenant cloud backend, a browser-control extension, and an embeddable website chatbot.

This docbook is generated from a reading of the source code of every sub-project (no prior docs were consulted). It describes what each component does, how they fit together, and the protocols that bind them.

What is Rysh?

Rysh is, at its core, a terminal multiplexer (in the spirit of tmux/zellij) in which every pane is a generic conversation surface. A pane can be:

  • a shell (a real PTY),
  • an AI coding agent (an autonomous LLM tool-use loop),
  • a ## system console (Rysh commands),
  • a chat buffer, or
  • an external channel (Slack, email, WhatsApp, phone, website chatbot).

All of these surfaces speak one message protocol over NATS, which is what lets Rysh share panes across machines, mirror whole tabs to collaborators, drive a browser from the cloud, and embed a chatbot on a third-party website — all reusing the same agentic engine.

The embeddable website chatbot is also resold as a standalone product, letchat.ai (a separate Go BFF + React dashboard repo). What has shipped across the chatbot platform and the letchat reseller layer is consolidated in chapter 12.

The five sub-projects

Sub-project Language One-line role
rysh-cli Go The terminal multiplexer + agent runtime (client/daemon, actor system, TUI, ~46-tool agent toolbox extensible via Rysh Forge and an MCP client). The product's heart.
rysh-server Go Multi-tenant cloud backend: auth, workspaces, billing, the NATS backbone with per-workspace isolation, server-side AI panes, embeddable chatbot.
rysh-shared Go Shared core: message types + codec, the agentic loop, provider abstraction, host-agnostic tools, the NATS↔actor bridge. Imported by CLI and server.
rysh-proto Protobuf Reference schemas (conversation/pane/memory/envelope). The live wire format is JSON, not protobuf — proto documents the shape.
rysh-chrome-plugin React/TypeScript Chrome MV3 side-panel that lets a server-side agent control the user's browser and chat with it.

How to read this docbook

Read top-to-bottom for a guided tour, or jump to a sub-project reference.

  1. Overview — vision, sub-projects, tech stack, glossary.
  2. System Architecture — the three pillars (actors, NATS bus, agentic loop), process & component models.
  3. Messaging & Protocol — the NATS envelope, codec, subject naming, conversation & memory models, message catalog.
  4. Agentic Engine — the orchestrator tool-use loop, approval flow, provider abstraction (in rysh-shared).
  5. Sub-project references:
  6. End-to-End Flows — cross-cutting sequence diagrams.
  7. Glossary & Configuration — terms, config reference, build/deploy.
  8. letchat.ai & the Chatbot Platform — Shipped Status — the embeddable chatbot, the letchat.ai reseller BFF, and everything shipped across both (rysh features F1–F11, letchat Tracks 1 & 2, gated Stripe + SMTP); §12.1b lists the services a customer receives.

Repository layout

rysh/                       (monorepo root; go.work workspace)
├── go.work                 # includes rysh-proto, rysh-server, rysh-shared
│                           #   (rysh-cli is intentionally EXCLUDED — own dep tree, build GOWORK=off)
├── Makefile
├── rysh-cli/               # terminal multiplexer + agent runtime  (separate repo*)
├── rysh-server/            # cloud backend
├── rysh-shared/            # shared Go core (agentic, msg, provider, tools, bridge)  (separate repo*)
├── rysh-proto/             # protobuf reference schemas  (separate repo*)
├── rysh-chrome-plugin/     # browser extension (React/TS)  (separate repo*)
├── rysh-mcp-samples/       # MCP demo samples (REST→MCP), demo code only  (separate repo)
└── docbook/                # ← this documentation

* Repo split (May 2026). rysh-cli, rysh-shared, rysh-proto, and rysh-chrome-plugin are now each managed as standalone git repositories and are .gitignored from the monorepo root; their directories remain physically present for local builds. rysh-mcp-samples is also its own repo but is demo/sample code, not a product sub-project — it is not in the Go workspace and is not part of the release pipeline. (A rysh-mobile React-Native app was briefly added then reverted — it is not part of Rysh.)

Module wiring. The Go workspace uses replace directives so rysh-server, rysh-shared, and rysh-proto resolve locally. rysh-cli is excluded from go.work (it pins its own dependency tree and is built/tested with GOWORK=off); it still consumes rysh-shared via a replace in its own go.mod. The installed CLI binary is named ry (with rysh as an alternate name).

A note on accuracy

This documentation reflects the code as written, including parts that are aspirational, stubbed, or legacy. Where something is not what its name suggests, the docs say so explicitly (e.g. the proto module is reference-only, the server's RateLimit middleware is a no-op, the Chrome plugin's root .js files are dead code, WhatsApp/Phone channels are stubs). See each sub-project doc's "Caveats" section.

Chapters

  1. 1. Overview
  2. 2. System Architecture
  3. 3. Messaging & Protocol
  4. 4. The Agentic Engine
  5. 5. `rysh-shared`
  6. 6. `rysh-cli`
  7. 7. `rysh-server`
  8. 8. `rysh-chrome-plugin`
  9. 9. `rysh-proto`
  10. 10. End-to-End Flows
  11. 11. Glossary, Configuration & Build
  12. 12. letchat.ai & the Chatbot Platform