Installation

From Binary #

One command on Linux and macOS. The install script downloads the latest release, detects your platform, verifies checksums, and installs both binaries — thurbox (the TUI) and thurbox-cli (the headless one) — to ~/.local/bin .

curl -fsSL https://raw.githubusercontent.com/Thurbeen/thurbox/main/scripts/install.sh | sh

Then run it:

thurbox

The script handles:

• Platform detection (Linux/macOS, x86_64/aarch64)
• Automatic version fetching with API rate limit fallback
• SHA256 checksum verification
• Creating ~/.local/bin if needed
• Post-install instructions

Custom install directory

export INSTALL_DIR=/usr/local/bin
curl -fsSL https://raw.githubusercontent.com/Thurbeen/thurbox/main/scripts/install.sh | sh

Specific version

export VERSION=v2.5.4
curl -fsSL https://raw.githubusercontent.com/Thurbeen/thurbox/main/scripts/install.sh | sh

Without a pin you get the newest release. Every version is on the releases page.

Optional RMUX backend

RMUX is a Rust terminal multiplexer with a tmux-compatible command interface. Thurbox requires RMUX 0.10.0 or newer. Install it separately on the session machine; cargo install rmux --locked is one upstream option. Follow the upstream installation guide for packages and archive layout, then check rmux -V.

Press Ctrl+N and choose RMUX immediately after tmux in the multiplexer picker. Locally it appears when rmux resolves on PATH. It was tested with thurbox on Linux; macOS, real SSH, WSL execution and native Windows integration remain unverified. Defaults stay tmux on POSIX and psmux on native Windows. See multiplexer configuration and the verified version table and troubleshooting.

Windows (PowerShell)

On native Windows the install script is PowerShell, and it is the recommended route — unlike the winget and Chocolatey packages below, it always carries the newest release. It installs to %LOCALAPPDATA%\Programs\thurbox (added to your user PATH).

irm https://raw.githubusercontent.com/Thurbeen/thurbox/main/scripts/install.ps1 | iex

Set $env:THURBOX_VERSION = 'v2.5.4' before that line to pin a specific version instead of taking the newest.

Available platforms

winget (Windows) #

On Windows, install the prebuilt x86_64 binaries with winget (Microsoft's package manager, bundled with Windows 10/11):

winget install Thurbeen.thurbox

Installs thurbox.exe and thurbox-cli.exe from the GitHub Release as portable commands on your PATH . Needs psmux as the multiplexer, installed separately.

Chocolatey (Windows) #

On Windows, install the prebuilt x86_64 binaries from the Chocolatey community repository :

choco install thurbox

Installs thurbox.exe and thurbox-cli.exe from the GitHub Release and shims them onto your PATH . Needs psmux as the multiplexer, installed separately (there is no Chocolatey package for it). New versions go through community-repo moderation before they appear.

Homebrew #

On macOS or Linux, install the prebuilt binaries from the thurbox tap :

brew install thurbeen/thurbox/thurbox

This installs thurbox and thurbox-cli , pulling in tmux and git as dependencies. Supported on macOS Apple Silicon and Linux x86_64 and aarch64 (Intel macOS has no release binary — build from source there).

Arch Linux (AUR) #

Thurbox is on the AUR as thurbox (builds from source) and thurbox-bin (prebuilt release binary). Install with your AUR helper:

paru -S thurbox-bin   # prebuilt binary (fastest)
paru -S thurbox       # build from source

tmux is pulled in as a dependency. Swap paru for yay or your preferred helper.

Nix and NixOS #

The repository is a flake. It builds both binaries from source against Cargo.lock and puts tmux and git on their PATH , after anything you already have there. It covers x86_64 and aarch64 Linux and Apple Silicon macOS. CI builds it on x86_64 Linux only.

nix run github:Thurbeen/thurbox                      # try it without installing
nix profile install github:Thurbeen/thurbox          # install into your profile

On NixOS, add the flake to your system flake and enable its module:

{
  inputs.thurbox.url = "github:Thurbeen/thurbox";

  outputs = { nixpkgs, thurbox, ... }: {
    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        thurbox.nixosModules.default
        { programs.thurbox.enable = true; }
      ];
    };
  };
}

overlays.default adds pkgs.thurbox if you'd rather list the package yourself, and homeManagerModules.default offers the same programs.thurbox options under Home Manager. The only other option, programs.thurbox.automations.enable , sets up the user timer from packaging/systemd (or the launchd agent from packaging/launchd under Home Manager on macOS) so automations keep firing after a reboot.

A flake build isn't a release. It reports its version as 0.0.0-unstable-<date>+<commit> and never updates itself, because Nix owns the binary. To pin a version, point the input at a tag, for example github:Thurbeen/thurbox/v2.30.3 .

From Source #

git clone https://github.com/Thurbeen/thurbox.git
cd thurbox
cargo build --release

The binaries will be at target/release/thurbox and target/release/thurbox-cli . Requires Rust 1.75+.

Prerequisites #

Quick Start #

1. Launch Thurbox — run thurbox in your terminal. You'll see the session sidebar and a terminal panel.
2. Create a session — press Ctrl+N to open the repo picker. Pick repos (optionally a worktree), name the session, then choose an agent.
3. Work with the agent — the terminal panel shows the live agent session. All keys are forwarded to the PTY.
4. Navigate — Ctrl+L / Ctrl+H cycle pane focus, Ctrl+J / Ctrl+K switch sessions.
5. Quit — Ctrl+Q detaches all sessions (tmux keeps them running). They resume on next launch.
6. Make it yours — Ctrl+, then ] lists every pane and lets you turn one off, Ctrl+Y changes the palette, F1 rebinds any chord. Or just ask an agent — see just ask for it .

Configuration #

Session state is stored in SQLite at ~/.local/share/thurbox/thurbox.db ( $XDG_DATA_HOME respected). Agent definitions live in ~/.config/thurbox/agents.toml (seeded on first run). Logs go to ~/.local/share/thurbox/thurbox.log .

Uninstall #

Removing the binary is not enough on its own: agent sessions keep running in tmux, Thurbox has written hook and skill files into your coding agents' own directories, and every worktree it created is registered in the repository it came from. Go through the steps below in order, because steps 1 and 2 need thurbox-cli , which step 3 removes. The paths are the defaults on Linux and macOS; Windows and remote hosts follow in step 5.

1. Stop sessions

Quit the TUI, then stop each multiplexer server Thurbox used. The command below stops the default POSIX tmux server, including its agent sessions and heartbeat. Destructive: this ends every running agent session, and any unsaved agent conversation with it.

thurbox-cli version --json      # note tmux_socket and data_dir
tmux -L thurbox kill-server     # stops every session and the heartbeat

For RMUX sessions run rmux -L <socket> kill-server; for psmux use psmux -L <socket> kill-server. Use the actual socket reported above. If sessions used more than one multiplexer, stop each server separately; stopping tmux leaves RMUX sessions running. Remote servers must be stopped on their hosts.

2. Remove what Thurbox added to other tools

Thurbox ships two built-in extensions that reach outside its own directories, and reinstalls both on every start unless you opt out. hooks wires your agents' status hooks: it merges entries into ~/.codex/hooks.json , ~/.gemini/settings.json and ~/.kimi-code/config.toml , and drops its own files for opencode, vibe, pi, omp, Copilot and grok. ui-skill installs the thurbox-ui skill into Claude Code, Codex, opencode, Copilot and ~/.agents . Each file is written only if that agent's directory already exists.

Deactivating an extension reverses its install. It deletes only files that still carry Thurbox's marker (the text thurbox `extension install` ), prunes Thurbox's entries from the merged files, and removes the arguments it added to agents.toml . A skill or hook file you edited and took the marker out of is yours, and is left alone.

thurbox-cli extension deactivate hooks
thurbox-cli extension deactivate ui-skill
thurbox-cli extension list                        # anything else you installed?
thurbox-cli extension uninstall <name> --purge   # for each one listed

That can leave empty directories behind — the thurbox-ui skill directories, and a hooks or plugin directory Thurbox created for an agent — and a merge target that Thurbox created itself, such as ~/.codex/hooks.json , as an empty {} . Delete those if you like; rmdir only removes a directory that is empty:

rmdir ~/.claude/skills/thurbox-ui ~/.codex/skills/thurbox-ui \
  ~/.config/opencode/skills/thurbox-ui ~/.copilot/skills/thurbox-ui \
  ~/.agents/skills/thurbox-ui 2>/dev/null

Beyond these, the git worktrees and branches of step 4, and the Windows PATH entry of step 5, Thurbox writes nothing outside its own directories: no shell completions, no shell profile, no ~/.claude/settings.json (Claude Code gets its hooks through a --settings file in Thurbox's config directory), no tmux or git config, and no services.

3. Remove the binaries

Every install method ships both thurbox and thurbox-cli.

# curl one-liner (the tarball also puts a LICENSE file next to the binaries)
rm -f ~/.local/bin/thurbox ~/.local/bin/thurbox-cli ~/.local/bin/LICENSE
# ...or in the directory you set INSTALL_DIR to

brew uninstall thurbox          # Homebrew
paru -R thurbox-bin             # Arch (AUR), prebuilt package
paru -R thurbox                 # Arch (AUR), built from source
nix profile remove thurbox      # Nix, installed with nix profile install

On NixOS or Home Manager, delete programs.thurbox , thurbox.nixosModules.default or thurbox.homeManagerModules.default and the thurbox input from your flake, then rebuild with sudo nixos-rebuild switch or home-manager switch . If you had turned on automations.enable , the rebuild removes the timer too. The store copy stays until nix-collect-garbage .

A source build installs nothing: delete the clone, and any copy of target/release/thurbox or thurbox-cli you put on your PATH . Windows is in step 5.

4. Optionally remove worktrees, config and state

Every worktree Thurbox created lives under ~/.local/share/thurbox/worktrees/ , and can hold a lot, build output included. Each one is also registered in its repository's .git/worktrees , so remove them through git rather than just deleting the directory. Destructive: --force discards uncommitted changes in each worktree. The loop prints each branch and path first, and commits already on a branch stay there.

for wt in ~/.local/share/thurbox/worktrees/*/*/; do
  [ -e "$wt/.git" ] || continue
  echo "$(git -C "$wt" branch --show-current)  $wt"
  git -C "$wt" worktree remove --force "$wt"
done

Thurbox never deletes the branches it created; remove any you no longer want with git branch -D <branch> in their repository. If you already deleted the worktree directories by hand, run git worktree prune in each repository to drop the stale registrations.

Then delete Thurbox's own directories. Destructive: this erases the session database and history, logs, agents.toml , hosts.toml , your theme, keybindings and interface customisations, and the extension opt-outs from step 2 (a later reinstall starts from scratch).

rm -rf ~/.local/share/thurbox ~/.config/thurbox

5. Windows and remote hosts

Windows. The same steps, in PowerShell. Sessions run on psmux instead of tmux; step 2 is the same thurbox-cli extension commands, and the agent files it removes sit under %USERPROFILE% . Configuration lives in %APPDATA%\thurbox and state in %LOCALAPPDATA%\thurbox .

# 1. Stop sessions (destructive: ends every running agent session)
psmux -L thurbox kill-server

# 2. Remove what Thurbox added to other tools
thurbox-cli extension deactivate hooks
thurbox-cli extension deactivate ui-skill

# 3. Remove the binaries
winget uninstall Thurbeen.thurbox       # winget
choco uninstall thurbox                 # Chocolatey
# install.ps1: the install directory, and its entry in your user PATH
$dir = "$env:LOCALAPPDATA\Programs\thurbox"   # or your THURBOX_INSTALL_DIR
Remove-Item -Recurse -Force $dir
$path = [Environment]::GetEnvironmentVariable('Path', 'User') -split ';' |
  Where-Object { $_ -and $_ -ne $dir }
[Environment]::SetEnvironmentVariable('Path', ($path -join ';'), 'User')

# 4. Optional (destructive): worktrees, then config and state
Get-ChildItem "$env:LOCALAPPDATA\thurbox\worktrees\*\*" -Directory | ForEach-Object {
  git -C $_.FullName worktree remove --force $_.FullName
}
Remove-Item -Recurse -Force "$env:APPDATA\thurbox", "$env:LOCALAPPDATA\thurbox"

Remote hosts. Sessions on an ssh: or wsl: host from hosts.toml run on that host, and Thurbox never cleans a host up for you. On each host it may have left a tmux server, worktrees under ~/.local/share/thurbox/worktrees (or the host's worktrees_dir ), a copy of thurbox-cli and its database under ~/.local/share/thurbox , and the same agent hook files as step 2. Run this on the host, through ssh <host> or wsl -d <distro> . Destructive in the same way as steps 1 and 4. Use the host's socket from hosts.toml if you set one.

tmux -L thurbox kill-server
for wt in ~/.local/share/thurbox/worktrees/*/*/; do
  [ -e "$wt/.git" ] || continue
  git -C "$wt" worktree remove --force "$wt"
done
for f in ~/.config/opencode/plugin/thurbox-status.js ~/.vibe/hooks.toml \
  ~/.copilot/hooks/thurbox-status.json ~/.grok/hooks/thurbox-status.json \
  ~/.pi/agent/extensions/thurbox-status.ts ~/.omp/agent/extensions/thurbox-status.ts; do
  grep -qs 'thurbox `extension install`' "$f" && rm "$f"
done
rm -rf ~/.local/share/thurbox ~/.config/thurbox

The entries merged into ~/.codex/hooks.json , ~/.gemini/settings.json and ~/.kimi-code/config.toml on the host have no command to prune them: delete by hand each hook whose command mentions @thurbox_state or thurbox-cli session signal . A Windows host is the same with psmux and the Windows paths above.