# Install

> Prompt for your coding agent:
>
> Help me set up BrigadeStack on this machine. BrigadeStack gives my coding agents one shared memory and a record of the work they check: a shared task list, check records and handoff notes, kept as plain files in the repo or workspace.
>
> Guides: https://brigadestack.com/docs/getting-started/install and https://brigadestack.com/docs/getting-started/quickstart
>
> First, look around without changing anything. Check whether `brigadestack` or `brigade` is already installed, which of pipx, Python and Node are available, which agent CLIs are on my PATH, and whether this folder is a git repo or an agent workspace.
>
> Then ask me these questions in one message, each with your best guess from what you found:
>
> 1. Where should BrigadeStack go? This repo, another path, or an agent workspace such as OpenClaw or Hermes. A code repo uses `--depth repo` and a workspace uses `--depth workspace`.
> 2. Which agent tools do I use here? Supported ids: claude, codex, cursor, opencode, antigravity, pi, aider, goose, continue, copilot, qwen, kimi, adal, openhands, grok, amp, crush, openclaw, hermes.
> 3. Strict mode or off? Strict is the default: agents run tests and builds through `brigadestack work verify run`, keep a check record for each check, and cannot finish a session that changed code without one. Off keeps the shared brief, memory recall and handoffs, and drops that enforcement. In 0.31.0 these modes are named engineer and yolo.
> 4. If it is not installed yet: pipx (Python 3.11 or newer) or npm (Node.js 22.15 or newer)?
> 5. Do I already keep agent notes, memory files or handoff folders here that you should leave in place?
>
> After I answer:
>
> - Install with `pipx install brigadestack` or `npm install -g brigadestack`. If pipx is missing, follow the install guide for my OS. Confirm with `brigadestack --version`, then run `brigadestack setup` to add the built-in Code and Evidence engines.
> - Preview the wiring with `brigadestack operator quickstart --target <path> --depth <repo|workspace> --harnesses <ids> --dry-run` and show me the plan.
> - Run the same command without `--dry-run`. If I chose off, run `brigadestack work mode set yolo --target <path>` (0.32.0 and later also accept `off`).
> - Check it with `brigadestack operator doctor --target <path> --profile local-operator` and report every fail or todo line.
> - Tell me which files were added, which ones git ignores, and how my agents will use the brief, the check records and handoffs.
>
> Your shell has no terminal prompt, so always pass these flags. Do not commit, push or use sudo without asking. Stop and ask before overwriting existing files or running anything destructive.

> **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.0` on PyPI or `brigadestack@0.31.0` on 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

<!-- tabs: Install method -->

### pipx

```bash
pipx install brigadestack
brigadestack --version
```

Pinned: `pipx install brigadestack==0.31.0`. Don't have pipx yet? [Set it up first](#set-up-pipx).

### npm

```bash
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`.

### venv

```bash
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`.

<!-- /tabs -->

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.

<!-- tabs: Operating system -->

### Linux

Ubuntu 23.04+ and Debian 12+ use an externally managed system Python. Install the distribution package:

```bash
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](https://archlinux.org/packages/extra/any/python-pipx/):

```bash
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](https://omarchy.org/manual/other-packages/):

```bash
omarchy pkg add python-pipx
pipx ensurepath
```

Use `omarchy update` for [Omarchy system updates](https://omarchy.org/manual/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:

```bash
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.

### macOS

```bash
brew install pipx
pipx ensurepath
```

### Windows

With [Scoop](https://scoop.sh/):

```powershell
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`.

<!-- /tabs -->

The platform-specific `pipx` commands follow the [official pipx installation guide](https://pipx.pypa.io/latest/how-to/install-pipx.html).

## 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:

```bash
brigadestack setup
```

Set up a repo, then verify the wiring:

```bash
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:

```powershell
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:

```bash
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](/docs/getting-started/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:

```bash
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:

```bash
export BRIGADE_NO_UPDATE_CHECK=1
```

```powershell
$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:

```bash
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.