Search BrigadeStack

Search BrigadeStack pages and docs.

BrigadeStack
Menu
Docs menu

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

Set up BrigadeStack

Give this prompt to 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

PackageNeeds
Python packagePython 3.11 or newer, with pipx or a virtual environment.
npm packageNode.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 runProvisions 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.

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.

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.