Install

Install

View as markdown

Set this up with an AI agent

Copy a prompt describing this guide and paste it into Claude Code (or your agent of choice).

On macOS, install Shelbi and start its first-run setup in one command:

brew install jlong/shelbi/shelbi && shelbi

Shelbi checks your prerequisites and current Git checkout before it writes anything. See Set up your first project for the one-confirmation flow.

Shelbi also publishes a prebuilt Ubuntu package. The full package-manager commands are:

brew install jlong/shelbi/shelbi

The APT repository is signed, so apt update verifies the repository metadata before apt install sees the package. The first Ubuntu package is published for amd64 in the stable suite.

The APT key fingerprint is published at:

curl -fsSL https://apt.shelbi.dev/shelbi-archive-keyring.fingerprint

The package installs the shelbi binary only. It does not install or enable the daemon; run shelbi daemon install later if you want the hub daemon managed by your user service supervisor.

If you're hacking on Shelbi or testing unreleased changes, use the source-build path instead.

Prerequisites

You need three things before you start:

  • tmux 3.2 or later. Shelbi runs every workspace inside a tmux pane and drives it with send-keys / capture-pane; older releases miss features the TUI relies on. Homebrew and APT install this dependency for the hub, but remote workspace machines need it too.
  • An agent CLI. At least one of claude (Claude Code) or codex, installed and authenticated. Declare more than one later, and the project YAML picks per workspace.
  • Git and SSH. Shelbi creates git worktrees and can run workspaces on remote machines over SSH. The Ubuntu package depends on git and openssh-client; on macOS, install them with Xcode Command Line Tools or your usual package manager if they are not already present.

Install tmux with your package manager:

brew install tmux

Remote workspaces need the same tmux and agent CLI on the machine they run on, plus an ssh host you can reach without a password prompt.

Verify or start later

shelbi

With no project configured, this starts the guided setup. To check only the installed version, run shelbi --version.

Verify release artifacts manually

GitHub Releases are the source of truth for release artifacts, checksums, and artifact attestations. Package-manager installs verify checksums or signed repository metadata automatically, but you can verify downloads by hand.

For an Ubuntu .deb, download the package and checksums.txt from the same release tag:

version=0.1.0
curl -fsSLO "https://github.com/jlong/shelbi/releases/download/v${version}/checksums.txt"
curl -fsSLO "https://github.com/jlong/shelbi/releases/download/v${version}/shelbi_${version}_amd64.deb"
sha256sum -c checksums.txt --ignore-missing

For a macOS archive, verify the release tarball the Homebrew formula uses:

version=0.1.0
curl -fsSLO "https://github.com/jlong/shelbi/releases/download/v${version}/checksums.txt"
curl -fsSLO "https://github.com/jlong/shelbi/releases/download/v${version}/shelbi_Darwin_arm64.tar.gz"
grep "shelbi_Darwin_arm64.tar.gz" checksums.txt | shasum -a 256 --check -

Replace shelbi_Darwin_arm64.tar.gz with shelbi_Darwin_x86_64.tar.gz on Intel Macs. To inspect GitHub artifact attestations, use GitHub's attestation tooling against the same release artifact.

Install from source for development

The source install path is for contributors, local patches, and unreleased builds. It requires the stable Rust toolchain from rustup.

You can run the hosted source-build script:

curl -fsSL https://shelbi.dev/install.sh | sh

Or keep the checkout around to rebuild after pulling updates:

git clone https://github.com/jlong/shelbi.git
cd shelbi
./scripts/install.sh

The script runs cargo build --release and copies the binary to $HOME/bin/shelbi. Override the destination with SHELBI_INSTALL_PATH:

SHELBI_INSTALL_PATH=/usr/local/bin/shelbi ./scripts/install.sh

Re-run it any time you pull updates. One step rebuilds and reinstalls. The orchestrator and workspace panes re-shell into shelbi on every call, so they pick up the new binary automatically; only the sidebar, Tasks, and Review views need a manual shelbi reload to respawn against the new build.

macOS: the codesign step

On macOS the script re-signs the copied binary ad-hoc:

codesign --remove-signature "$INSTALL_PATH"
codesign --sign - "$INSTALL_PATH"

macOS: skip this and you get Killed: 9

cargo build embeds an ad-hoc signature; cp invalidates it, and the next exec dies with Killed: 9 and no useful error. Re-signing after the copy restores it. scripts/install.sh does this for you, so you only hit the failure if you copy the binary out of target/release/ by hand. Linux and Windows don't need it, and the script skips it there.

Troubleshooting

command not found: shelbi. The default install path is $HOME/bin/shelbi only when you install from source. Make sure that directory is on your PATH:

export PATH="$HOME/bin:$PATH"

Add the line to ~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish to make it persistent. Or pass SHELBI_INSTALL_PATH=/usr/local/bin/shelbi to the install script so the binary lands somewhere already on your PATH.

If Homebrew or APT installed the package, open a new shell and run which shelbi to confirm your package-manager binary directory is on PATH.

Killed: 9 on macOS, no other output. The codesign step didn't run. This usually means you copied the binary out of target/release/ by hand instead of using scripts/install.sh. Re-run the script, or run the codesign commands yourself against your install path.

cargo: command not found. Install Rust via rustup and restart your shell so ~/.cargo/bin is on your PATH. Cargo is only required for source builds.

tmux: command not found (or tmux 1.x warnings). Install or upgrade tmux to 3.2+. The TUI assumes modern pane title and popup support; older versions render incorrectly.

Next

You have the binary. Now point it at a repo with Set up your first project.