Docs / Get started
Install
BrigadeStack runs on Linux, macOS, and Windows. Install the Python or npm package, then wire your first repo.
Set up with your agent
Release scope. The current stable release is 0.31.0. The commands below install the latest stable release. For a reproducible install, pin
brigadestack==0.31.0on PyPI orbrigadestack@0.31.0on npm. Work in development on main is not included.
Requirements
| Package | Needs |
|---|---|
| Python package | Python 3.11 or newer, with pipx or a virtual environment. |
| npm package | Node.js 22.15 or newer in the 22.x line, or 23.11 or newer. Linux with glibc (x64, arm64), macOS (x64, arm64), or Windows x64. Keep optional dependencies enabled. |
| npm first run | Provisions a managed Python runtime and may need network access. |
Install the package
pipx install brigadestack
brigadestack --version
Pinned: pipx install brigadestack==0.31.0. Don’t have pipx yet? Set it up first.
npm install -g brigadestack
brigadestack --version
Pinned: npm install -g brigadestack@0.31.0. For a one-off run without a global install, use npm exec --yes --package=brigadestack@0.31.0 -- brigadestack --version.
python3 -m venv .venv
.venv/bin/python -m pip install brigadestack
. .venv/bin/activate
brigadestack --version
Activating the venv puts brigadestack on PATH for that terminal, so the bare commands in the rest of this guide run from the venv. Run the activate line again in each new terminal.
In PowerShell, use py -m venv .venv, then .venv\Scripts\python.exe -m pip install brigadestack, then .venv\Scripts\Activate.ps1. If your execution policy blocks activation scripts, skip activation and type .venv\Scripts\brigadestack.exe wherever this guide says brigadestack.
Each package pins its stable dependency exactly: brigade-cli==0.31.0 on PyPI and @escoffier-labs/brigade@0.31.0 on npm. brigadestack --version prints brigade 0.31.0, and help output names the program brigade. Both names run the same CLI.
Set up pipx
Skip this step if pipx --version already works.
Ubuntu 23.04+ and Debian 12+ use an externally managed system Python. Install the distribution package:
sudo apt update
sudo apt install pipx
pipx ensurepath
On Fedora, run sudo dnf install pipx, then pipx ensurepath.
Arch Linux and Omarchy. On Arch Linux, install the python-pipx package:
sudo pacman -Syu --needed python-pipx
pipx ensurepath
This Arch command performs a full system upgrade and installs pipx. On Omarchy, use its package command:
omarchy pkg add python-pipx
pipx ensurepath
Use omarchy update for Omarchy system updates so its snapshots, migrations, and configuration updates run with the package upgrade.
Open a new terminal afterward and run pipx as your regular user. It keeps BrigadeStack isolated from the externally managed system Python. After an Arch upgrade replaces Python with a new minor version, an existing pipx environment may need rebuilding:
pipx reinstall brigadestack
brigadestack --version
Other distributions should use their pipx package when one is available. A direct python3 -m pip install --user pipx can fail with externally-managed-environment on systems that implement PEP 668.
brew install pipx
pipx ensurepath
With Scoop:
scoop install pipx
pipx ensurepath
Without Scoop, run py -m pip install --user pipx. Python may report that pipx.exe is not on PATH. Go to the directory printed by pip and run .\pipx.exe ensurepath, then open a new PowerShell window. If Python came from the Microsoft Store, use python3 instead of py.
The platform-specific pipx commands follow the official pipx installation guide.
Wire your first repo
These commands expect brigadestack on PATH: a pipx or npm install, or a terminal where the venv is activated. Install the built-in engines. brigadestack setup downloads the Code Intelligence and Evidence binaries from the release manifest, digest-verified, with no Rust or Go toolchain required:
brigadestack setup
Set up a repo, then verify the wiring:
brigadestack operator quickstart --target ./my-repo --harnesses codex
brigadestack operator doctor --target ./my-repo --profile local-operator
PowerShell accepts the same commands. You can also use Windows-style paths:
brigadestack operator quickstart --target .\my-repo --harnesses codex
brigadestack operator doctor --target .\my-repo --profile local-operator
WSL is optional. BrigadeStack runs natively on Windows. Worker CLIs must resolve to native executables. If an npm worker resolves only to a .cmd or .bat shim, BrigadeStack reports it and asks for a native launcher. Shell completions currently cover bash, zsh, and fish. brigadestack components verify is POSIX-only and returns unsupported-platform on Windows.
For an OpenClaw or Hermes workspace instead of a code repo:
brigadestack operator quickstart --target ~/agent-workspace --depth workspace --harnesses openclaw,hermes --owner openclaw
Use --dry-run first to preview the planned steps without writing anything. brigadestack init --target ./my-repo --harnesses codex --dry-run shows the full file-by-file list. Quickstart only wires the tools you select and leaves the rest alone.
The quickstart walks through a first handoff after this step. Prefer the lower-level pieces? brigadestack init lays down the files, brigadestack doctor checks the wiring, and brigadestack status reports over the component registry. brigadestack profiles list shows the built-in component profiles and brigadestack components list shows the components each profile selects, which is the component registry brigadestack status reports over. The older brigadestack stations spelling still works as a hidden alias.
Command names
brigadestack is the command this site uses. Existing brigade-cli installs and development builds provide the original brigade command, which runs the same CLI. The workspace config directory is .brigade.
Development build
Preview. To try work from main before it ships in a stable release:
pipx install git+https://github.com/escoffier-labs/brigade
This installs the brigade-cli package from main, which provides the brigade command. It does not add brigadestack. It may include unreleased changes and is not covered by the stable release notes.
Already using brigade
Nothing to migrate. The brigade command, the brigade-cli and @escoffier-labs/brigade packages, .brigade workspace files, and BRIGADE_* environment variables keep working. Existing pipx install brigade-cli installs keep working under that name.
The bridge packages add a second name for the same CLI, so brigade work brief and its brigadestack form run the same command. pipx and npm expose only brigadestack from the bridge package, and a global npm install leaves an existing global brigade executable in place.
The update check
The Python package runs one automatic network request of its own: a check against check.brigade.tools for the latest published brigade-cli version. npm installs skip it and send no request. The client normally uses a 24-hour cache for this check, and it is skipped when CI is set. The refresh can run after a command even when its output is piped or the command fails. Only the update notice is gated on a successful interactive command. To disable this update check:
export BRIGADE_NO_UPDATE_CHECK=1
$env:BRIGADE_NO_UPDATE_CHECK = "1"
The request sends the Brigade version and the operating system name in the User-Agent. When the header matches the exact format Brigade emits, the endpoint preserves a legacy weekly check and records a daily version observation: the ISO week, the UTC day, the version, a salted SHA-256 hash of the connecting address, the first and last timestamps for that day, a request count, and a flag marking a known operator address.
Your raw IP address is not stored in analytics. The optional operator egress list is separate secret configuration. Analytics also does not record your hostname, username, repository or project names, command arguments, file paths, or a persistent installation identifier. The hash includes the ISO week, and reports do not join sources across weeks. A weekly purge deletes rows older than 90 days.
The endpoint is public and answers anyone. A request that does not carry a Brigade User-Agent gets the same {"latest":"..."} response and is not recorded at all, so you can check the latest version by hand without being counted:
curl https://check.brigade.tools/v1/version
https://check.brigade.tools/privacy serves the same description as plaintext.
These counts are active sources, not people and not installations. Shared NAT, CI, and opting out can reduce counts. Rotating addresses, automation, and spoofed User-Agents can inflate them. The net bias is unknown.