ship is a small terminal workspace that gives you and your coding agents somewhere steady to work while everyone else keeps shipping more slop.
run your editor, shells and agents side by side, see who needs you, and close the window without stopping the work.
$ curl -fsSL https://raw.githubusercontent.com/ shipmux/ ship/ main/ install.sh | sh
v0.1.0, used every day on linux and macos.
for running a few agents at once while you still read what they write. if you leave agents running nonstop overnight, you're likely shipping slop, and ship isn't really built for that. all of this works today on linux and macos, and windows is best effort.
close the window or press alt-q, and your programs keep running on the background server. run ship again to carry on.
after a server restart or reboot, your tabs, splits, stacks and directories return with fresh shells. the layout comes back, not the old running programs.
open ship from more than one terminal. each window chooses what to look at, while the tabs, panes and running programs are shared.
see who's working, waiting for an answer or finished unseen. a sound lets you know when something needs attention, and alt-a takes you there.
keep the api, docs and review under one project tab. fold the parts you aren't looking at, and move or rename tabs with the keyboard or mouse.
split when you want things side by side, or press alt-s for a shell on top without making your panes smaller. the pane behind it keeps running.
press alt-e to open scrollback in your editor and search with familiar keys. or drag to copy straight from a pane.
open panes, send text or keys and read output with ship commands. use explicit pane ids so changing your selection doesn't redirect a script.
an agent can open a second pane, give another agent a task, wait for its status report and read the reply. no sdk or plugin needed.
a script can follow ship with ship watch and put short text, called tags, on tabs and panes. the git example shows each tab's branch and pull request in the sidebar.
change keys and menus, add a tmux-style prefix, or run your own scripts from a key. save the config and open windows pick up the changes.
the crew stand in for agents. each plate shows the glyph and the word ship would show for that state. press alt-a, as you would in ship, to call the next one who needs you.
errorlookout
blockednavigator
workingdeckhand
unseencook
idlecaptain
this is the water everyone else keeps shipping into, like readmes that promise everything, pull requests nobody read to the end, and features that exist because generating them was cheaper than deciding not to.
ship can't review your work for you, and it doesn't try. it gives you somewhere to stay involved, with your editor beside the agents, a sidebar that tells you who needs an answer, and room to check what came back before you send it out.
your programs live on a background server. the terminal window is how you look at them, and the cli lets scripts and agents join in.
the first ship starts a server for you. detach, close the terminal or open another window, and the same programs are still there. each window can look at a different part of the work.
the local connection is restricted to your user account. to work on another machine, use ssh. stopping the server is different from closing a window: ship server stop ends every program inside it.
keep an editor beside a test run, nest smaller tasks under a project tab, or stack a spare shell over a busy pane. new splits and stacked shells open in the directory you were working in. zoom in when you need more room, then return to the same layout.
claude code, codex, pi and crush report their own state through the program status protocol. ship shows it in the sidebar and on their tabs, so an agent waiting for permission stays visible even when its tab is folded. ship keeps no list of agents to update, so any program that reports its own state shows up the same way.
create a pane, run a command, read its output and close it, all from a shell script. commands that return tabs or panes print json, pane read prints text, and commands with no result stay quiet on success.
try this with ship and jq installed. a demo tab appears, a command counts to 100, and the last three lines come back to your terminal.
$ 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 98 99 100 $ ship tab close --tab "$TAB"
ship --help lists every command.an agent can open a second agent in a pane, send it a task and read back the answer, using the same commands you would type yourself.
waiting uses the program's status reports, not a guess at what's on screen. a reply might mean finished, blocked on a question or an error, so the caller can decide what to do next. the handoff guide covers the full loop and what to do if a wait fails.
install ship, open a shell and try a split. these are enough to get started, with the rest in the docs when you want it.
on linux or macos, install the latest release:
$ curl -fsSL https://raw.githubusercontent.com/ shipmux/ ship/ main/ install.sh | sh
later, ship update gets newer releases.
elsewhere, or to build it yourself, follow building from source.
run ship to open a shell. try alt-| to split it, then alt-q to detach. run ship again and both shells are still there.
on macos, set your terminal to use option as alt, often called "option as meta", or ship's keys will type special characters instead.
full build and update instructionsread the docsship on github
in normal mode, ship uses alt chords and other keys go to the selected pane. start with these, and keep the full key list nearby.
| alt-n | new tab with a shell |
|---|---|
| alt-x | close the tab |
| alt-| alt-- | split the pane right or down |
| alt-s | stack a shell in front of the pane |
| alt-, alt-. | previous or next pane in the stack |
| alt-e | open scrollback in your editor |
| alt-h alt-j alt-k alt-l | move to the pane left, below, above or right |
| alt-tab | next pane in the tab |
| alt-a | jump to the next agent that needs you |
| alt-p | panes mode to move, swap or rename; esc leaves |
| alt-f | zoom the pane to fill the tab, or unzoom |
| alt-r | resize mode: h j k l move the pane's edge, esc leaves |
| alt-t | tabs mode to navigate, fold, move or rename; esc leaves |
| alt-b | hide or show the sidebar |
| alt-pageup alt-pagedown | scroll the pane up or down a page |
| alt-q | detach |
the mouse works too, a little further down.
alt-e opens a pane's whole history in your editor, and alt-q detaches without stopping anything. recorded in CI for each release.ship reads ~/.config/ship/config.toml, or $XDG_CONFIG_HOME/ship/config.toml. without one it uses its defaults, and a running window picks up changes as soon as you save.
[server.defaults.pane] exit_behavior = "keep_failed" # keep failed commands open [client] sidebar_width = 34 [client.modes.normal.keys] "ctrl-b" = { action = { client.mode = "prefix" } } # tmux habits [client.modes.prefix] kind = "oneshot" # back to normal after one key [client.modes.prefix.keys] "c" = { action = { server.tab.create = { starter = "shell", select = true } } } "ctrl-b" = { action = { client.send = "ctrl-b" } }
copy only what you want to change. this example keeps failed commands open, makes the sidebar wider and adds a tmux-style prefix. ship config check lists any mistakes before you try it.
custom keys, menus, sounds and scripts in the docs
claude code, codex, pi and crush report their own state, so they show up in the sidebar with no setup. a sound plays when one finishes or needs you, and alt-a takes you there.
alt-a goes to it. real agents, recorded in CI like the one at the waterline.click a pane, a tab or an agent to select it, scroll with the wheel and drag to copy text. drag borders to resize, drag sidebar rows to move tabs, and right-click for actions.
stop the server or restart the machine, and your tabs, splits, stacks and directories come back with fresh shells. the layout comes back, not the programs that were running.
ship server stop, then ship: the same tabs, fresh shells. recorded in CI for each release.$ curl -fsSL https://raw.githubusercontent.com/ shipmux/ ship/ main/ install.sh | sh
start with one shell, add a split, and see how it fits the way you work.
