Rysh

The Rysh CLI: an agentic terminal multiplexer written in Go. Tabs, panes, splits, and vim/htop working exactly as you expect — except every pane is also an agent that can answer prompts and call tools.

This repository holds the CLI itself. It depends on rysh-cli-shared.

Building or contributing? Start at rysh-cli-parent — it carries the Makefile, the Go workspace, and CI, and wires this module to a local checkout of the shared one.

Video tutorials

Five narrated, subtitled walkthroughs of what rysh actually does, in order — each one assumes the previous. Every player below is live on this page; press play, nothing leaves GitHub. The first four are recorded against the build the install line gives you, so every command in them is one you can type.

Start at 1 even if you have used tmux or Zellij for years — the panes look familiar and the session model underneath them does not, which is video 2.

Secrets stay on your machine

SecretNAT is on by default. Secrets are substituted with tokens in the request body before it leaves the machine, and a response carrying a live credential in plaintext is reported into the pane. Responses are not rewritten — by design.

The mapping is reversible locally, so ##snat get <token> hands you back the real value in your own pane, and the model only ever saw the token.

Install

Two binaries exist and they are not interchangeable:

The names differ so that one machine can carry both. Every install command in this README installs rysh, and a script, alias or doc written for one does not run against the other — which is the whole reason the names differ. Check what you have with rysh version or ry version.

This repository is the rysh half: Apache-2.0, with LICENSE and NOTICE beside the source you are reading.

macOS and Linux

The open-source build, from source:

go install github.com/rysh-ai/rysh-cli-code/cmd/rysh@latest

The binary lands in $(go env GOPATH)/bin as rysh. Requires Go 1.25.3 or newer — the floor declared in this module's go.mod.

The open-source build, prebuilt:

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

Installs rysh from this repository's own releases — the Apache-2.0 binary, not ry. It resolves the newest release at run time; set RYSH_VERSION to pin one instead, or RYSH_INSTALL_DIR to choose where it lands.

The prebuilt distribution — installs ry, not rysh. It is the packaged product and a separate distribution; nothing in it is produced by this repository, so ry --help describing a command is not evidence about the source here. Use go install above if you want the build whose source you are reading.

Its install commands are deliberately not reproduced here: this README documents the open-source build. The prebuilt distribution has its own channels and its own documentation.

Windows

WSL2 is the supported path. Native Windows compiles and runs, but it cannot open a pane — those are two different claims and both are true:

• GOOS=windows GOARCH=amd64 go build ./... succeeds — the windows/amd64 target builds clean from this source. This repository's .goreleaser.yml names that archive cli-only on purpose, so the artifact says what it is.
• It cannot start a session. Rysh's PTY layer has no ConPTY implementation, so platform.PTYSupported is false on Windows and every session-opening command is refused up front with WSL guidance — rather than starting a session and then failing on your first pane (cmd/rysh/pty_preflight.go).
• What it can do is the pane-less command set, including talking to a session running in WSL from the Windows side: rysh send, rysh exec, rysh prompt, rysh list-sessions, rysh install, rysh eval, rysh doctor.

For a real session, install WSL2 and use the Linux instructions inside it — the Linux build runs unmodified:

wsl --install

# inside WSL
go install github.com/rysh-ai/rysh-cli-code/cmd/rysh@latest   # rysh

Native panes need ConPTY behind the same seam; it is not implemented yet.

Build from scratch

This module alone builds standalone — it carries no replace directive, so the shared module resolves from its published version:

git clone https://github.com/rysh-ai/rysh-cli-code
cd rysh-cli-code
go build ./cmd/rysh          # -> ./rysh

From the superrepo, which is how to develop against both modules at once — its go.work wires the shared module to the sibling checkout, so an edit there is picked up without a release round-trip:

git clone --recursive https://github.com/rysh-ai/rysh-cli-parent
cd rysh-cli-parent
make build       # -> bin/rysh
make install     # -> ~/.local/bin/rysh   (override with PREFIX=)
make test        # both modules

Go 1.25.3 or newer either way.

First run

export ANTHROPIC_API_KEY=sk-ant-...
rysh onboard --provider anthropic --key-env ANTHROPIC_API_KEY
rysh doctor

onboard validates the key, writes a project-local rysh.config.yaml, and opens your session. rysh --help lists the full command surface.

Each pane has an input mode and Esc Esc cycles it: shell (a real PTY) → prompt (goes to the LLM) → rysh (multiplexer commands) → chat (conversation, no tools). Those four are enabled by default; ##mode list shows what a pane has and ##mode new <mode> adds the rest.

The parent repo README has the keybindings, sessions, agents and humanoids.

A first session, start to finish

One path from nothing to two Claude panes posting to a board. Step 4 needs Claude Code installed as claude. ##codex works the same way if you use Codex instead.

1. Install and onboard, in the directory you want to work in. Config is project-local, so onboarding writes rysh.config.yaml and .rysh/ right here:

go install github.com/rysh-ai/rysh-cli-code/cmd/rysh@latest
export ANTHROPIC_API_KEY=sk-ant-...
rysh onboard --provider anthropic --key-env ANTHROPIC_API_KEY

2. Open a session.

rysh create first

You are now in one pane, in shell mode. Press Esc Esc until the pane's mode reads rysh.

3. Make a stack.

##new stack 2

The pane you typed in now has two more under it, in one stack. Ctrl+S then a digit jumps to that pane of the stack, and Esc leaves stack mode.

4. Put Claude in two of them. In pane 2 and then pane 3, in rysh mode:

##claude

Each pane now runs its own interactive Claude session. Give each a different task.

5. Open the board from pane 1:

##board open

Ask either Claude to report on the board when it finishes. From inside its pane, a post is one shell command, and rysh board tail reads the stream back:

rysh board post --as "$RYSH_PANE" -- 'parser wiring done'
rysh board tail --limit 20

The board belongs to this session, on this machine.

6. Step away. Ctrl+P d detaches and the session keeps running; rysh attach first brings you back. The tours below go deeper into each step.

Three tours

Commands starting with ## are typed into a pane in rysh mode. From outside the session, rysh exec -- '##<cmd>' runs the same thing and prints its output.

1. Create a session

rysh create work          # create and attach; add -d to leave it detached
rysh list-sessions        # what is running
rysh attach work          # come back to it later
rysh detach work          # leave it running
rysh stop work            # shut the daemon down

A session is a daemon plus its panes. It outlives your terminal, so closing the window detaches rather than kills.

2. Tabs, lanes, panes and stacks

A tab holds lanes (columns); a lane holds stacks; a stack holds panes, Zellij-style — one expanded, the rest collapsed to a title bar showing [N/M].

##new tab                 a new tab
##new lane                a new lane (column) in the active tab
##new pane                a pane at the bottom of the active lane
##new grid 4              4 panes stacked in the active lane
##new grid 3x4            3 lanes x 4 panes, in the active tab
##new grid 2x3x4          2 tabs x 3 lanes x 4 panes
##new stack 4             4 more stacked panes in the active stack

Look at what you built, and move things around:

##tab list                ##lane list           ##pane list
##panegroup layout        the lane layout, whole
##move pane up|down|left|right      reorder in the stack, or cross to the next lane
##move pane <p> to-lane <lane>      put a live pane somewhere else
##tab name build          ##lane name left      ##pane name builder

A stack with an agent in every pane is video 3 of the tutorials at the top of this page.

3. The agents board, fleets, and a fleet's own board

Panes can run an interactive Claude or Codex, and rysh remembers which, so a session stop/start resumes the same conversation:

##claude                  run claude in this pane, resumed automatically
##codex                   run codex in this pane, same deal
##pane new --claude "start on the parser"    a new pane, already working

The agents board is where those panes talk to each other and to you:

##board open              open the board pane
##board post <text>       post a milestone
##board reply <thread> <text>

An agent inside a pane posts without stealing focus, and reads back:

rysh board post --as "$RYSH_PANE" -- 'parser wiring done'
rysh board tail --limit 20

##board agent up starts a board agent — a hidden pane running Claude that sits in the path, routes messages between agents, and refuses a request it knows is stale. ##board agent visible draws it without moving your focus; ##board agent invisible puts it away while it keeps running.

A fleet is a named group of panes with a board of its own. Registering one opens no panes — it is the cheap half:

##fleet register epic-07 --board epic-07
##fleet state epic-07 up
##fleet list              ##fleet show epic-07
##fleet forget epic-07    drop it; the panes keep running

rysh board tail --fleet epic-07     # that fleet's stream, not the session's

A fleet may be claudes, codexes, or both — the commands are the same either way.

A fleet of Claude and Codex panes working off one shared board is video 4 of the tutorials at the top of this page; how to choose a fleet's shape — who sends orders to whom, and who reports where — is video 5.

Examples

examples/ in this repository is runnable. None of it needs a provider key.

Scripts. A .rysh file is a bash script whose ## lines are rysh commands: rysh script runs them, and plain bash reads them as comments. A script refuses to drive a session somebody is attached to, so point it at a detached one:

rysh create demo -d
rysh script examples/scripts/deploy-check.rysh --session demo staging

Each script's header comment has the full usage.

A fleet on its own board. examples/fleet/fleet-board.rysh registers a fleet, stacks three member panes (a lead and two workers), and has each one post to the fleet's board from its own pane. Then it reads the board back. Run it in a fresh session:

rysh create fleet-demo -d
rysh script examples/fleet/fleet-board.rysh --session fleet-demo
rysh board tail --fleet demo-fleet --session fleet-demo

The panes run plain shells. The comment at the end of the script is the next step: ##claude in each member, with work handed out by rysh ansa prompt and reported back on the board: a smaller version of what video 4 shows, on one machine.

A channel plugin. examples/plugins/echo-channel is the reference stdio channel plugin. It uses only the standard library, and every message sent to it comes straight back:

(cd examples/plugins/echo-channel && go build -o echo-channel .)
rysh channel install examples/plugins/echo-channel
rysh channel list

go test ./examples/plugins/echo-channel/ runs its test.

Layout

Contributing and security

This repository is a one-way export of a tree developed elsewhere, so a commit pushed straight here is overwritten by the next export rather than kept. That does not make patches pointless — CONTRIBUTING.md explains where one actually lands.

Found a vulnerability? Do not open a public issue, PR or discussion. Rysh runs shell commands and holds provider credentials on a developer's machine, so a public report is an exploit notice. SECURITY.md has the private channels.

License

Apache-2.0. See LICENSE and NOTICE.