Install

Install

View as markdown
Instructions for

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 the desktop app with Homebrew. Its cask depends on the CLI formula, so the command names both:

brew install jlong/shelbi/shelbi jlong/shelbi/shelbi-desktop

Then open Shelbi from Applications. On a fresh machine it opens the Welcome to Shelbi window, whose Add project starts the desktop app's short Add Project wizard. To get Shelbi's detected setup instead (a preflight of your repo, runner, and machine, then one plan card to confirm), run shelbi project add from inside the repository. See Set up your first project for both paths.

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

brew install jlong/shelbi/shelbi jlong/shelbi/shelbi-desktop

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 and its bundled configuration plugin. The hub daemon is started on demand the first time you open a project and exits when no project is open, so there is no service to install or enable.

The macOS desktop app (Shelbi.app, Apple silicon, macOS 15 or later) is a second client over the same daemon and sessions as the TUI. Its cask depends on the CLI formula, so name both when you install it, as in the macOS desktop app tab above.

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

Prerequisites

You need two things before you start:

  • An agent CLI. At least one of claude (Claude Code) or codex, installed and authenticated. If you install both, each agent (orchestrator, developer, review, and so on) recommends a runner and the project config can override it; workspaces don't pick one.
  • 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.

Shelbi runs each agent in its own Shelbi session, so there is no terminal multiplexer to install. It also runs fine inside tmux or Screen if you prefer to launch it from one.

Selecting and copying text

In the desktop app, drag with the left mouse button to select text in any terminal pane (the orchestrator, a workspace's agent, a review), then press ⌘C (Edit ▸ Copy) to copy it. No terminal configuration is involved: the app draws its terminals itself.

Remote workspaces need a compatible shelbi binary and the agent CLI on the machine they run on, plus an ssh host you can reach without a password prompt. shelbi machine setup finds or installs that binary for you.

Verify or start later

shelbi

Inside a registered project's directory, this opens that project. Anywhere else, with no hub daemon running, it opens the launch screen; with a daemon already running, it starts project setup for the current directory. 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 first asks where Shelbi should keep its global state (the Shelbi root, default ~/.shelbi) and bakes that path into the binary as its default. It skips the prompt when SHELBI_DEFAULT_ROOT is set or there is no terminal (for example under curl | sh), using ~/.shelbi in that case. It then runs cargo fetch --locked and cargo build --release, copies the binary to $HOME/bin/shelbi, and installs the bundled configuration plugin under <prefix>/share/shelbi/plugins/. 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. If a hub daemon is running, the script restarts it onto the new binary (pass --no-daemon to leave it alone). Run shelbi reload, or restart the TUI, so attached clients and the orchestrator pick up 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.

Next

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