Overview

Run a shell, an editor and a few coding agents side by side. Ship is a terminal multiplexer, like tmux or Zellij, that keeps them running after you close the window. The sidebar shows which agents are working, waiting on you or done, and the CLI lets scripts and agents open panes and hand work to each other.

The README lists what works today and what isn't built yet.

Install

On Linux or macOS, install the latest release:

curl -fsSL https://raw.githubusercontent.com/shipmux/ship/main/install.sh | sh

The script puts ship in ~/.local/bin. On other platforms, follow Building from source. Then come back here for your first session.

First run

Run ship. It starts a server in the background if one isn't running, restores its saved tabs, and opens on the first tab's first pane. With nothing to restore, it creates a tab with your shell. Press alt-q to detach; the server and everything in it keeps running, and ship brings you back.

On macOS, set your terminal to use Option as Alt (often called "Option as Meta"), or Ship's keys will type special characters instead.

The keys to start with

All of Ship's default keys are Alt chords, and any other key goes to the program in the selected pane. These few are enough for a first session:

Key	Does
`alt-n`	New tab with a shell
`alt-\|` / `alt--`	Split the pane right / down
`alt-h` / `alt-j` / `alt-k` / `alt-l`	Move to the pane left, below, above or right
`alt-a`	Jump to the next agent that needs you
`alt-x`	Close the tab
`alt-q`	Detach

That's all you need for now. Keys lists the rest when you want them.

Try the CLI

Leave ship open in one terminal and try this from another. You'll need jq to read the IDs from Ship's JSON output:

TAB=$(ship tab create --name demo | jq -r .id)
PANE=$(ship pane create --tab "$TAB" --exit-behavior keep -- sh -c 'seq 100' | jq -r .id)
ship pane wait --pane "$PANE" --status exited >/dev/null
ship pane read --pane "$PANE" | tail -3

The last command prints:

98
99
100

The demo tab appears in the sidebar. When you're done, close it and its pane:

ship tab close --tab "$TAB"

Inside a Ship pane you can leave out --tab and --pane, since commands default to the pane they run in. Scripting Ship picks up from here.

Let your agent set you up

A coding agent can walk you through installing and configuring Ship. Paste this into one:

Help me understand and set up Ship. Read https://shipmux.github.io/ship/agent-guide.md first, then ask me how I like to work before you change anything.

Agents that want the whole map can start from llms.txt, which links a plain markdown copy of every page.

Guides

These cover day-to-day use, roughly in the order you'll run into things. CLI recipes use jq to read JSON fields.

When you need them

You can skip these until something sends you looking. ship --help, or --help on any command, lists every option.

Scripting

For scripts and agents that drive Ship from the command line.