Search BrigadeStack

Search BrigadeStack pages and docs.

BrigadeStack
Menu
Docs menu

Docs / Get started

Quickstart

Install BrigadeStack, leave a handoff in a repo, and see what a second agent tool finds.

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.

This page describes BrigadeStack 0.31.0. It needs a git repo, and everything runs on this machine with no backend to start.

1. Install

pipx install brigadestack
brigadestack --version

npm and venv installs, and pipx setup for each OS, are on the install page.

2. Set up a repo for two tools

Run this in a git repo. It sets up Claude Code and Codex in the same repo:

brigadestack init --target . --depth repo --harnesses claude,codex
brigade: gitignore created (.gitignore)
brigade: installed depth=repo harnesses=claude,codex -> ~/my-app
brigade: memory owner -> claude

After these lines it prints a note that tells your agent how to use BrigadeStack.

You can ignore the memory owner line for this path. The command creates .claude/, .codex/, .brigade/, AGENTS.md, CLAUDE.md and SAFETY_RULES.md. Each tool directory has a memory-handoffs/ folder, which is where that tool leaves notes.

3. Leave a handoff

A handoff is a short note an agent writes when a session learned something the repo does not already say. A card is one such fact saved as a Markdown file that every tool can search. In daily use the agent writes both. Here you write one by hand to see each step.

First write the card text. It must start with YAML frontmatter:

printf -- "---\ntopic: retry test fake clock\ncategory: gotcha\ntags: [tests]\n---\nRegister the timer, then advance the fake clock.\n" > ~/card.md

Then write the handoff into the Claude inbox:

brigadestack handoff draft --target . --inbox claude --type gotcha \
  --title "Retry test raced the fake clock" \
  --summary "The test advanced the fake clock before the timer was registered, so it failed about one run in ten." \
  --fact "Register the timer before advancing the clock." \
  --action create-card --target-card retry-test-fake-clock.md \
  --content-file ~/card.md
handoff draft: ~/my-app/.claude/memory-handoffs/20261113-204811-retry-test-raced-the-fake-clock.md
id: 20261113-204811-retry-test-raced-the-fake-clock
inbox: .claude/memory-handoffs
action: create-card
target_card: retry-test-fake-clock.md
lint: ok

Without the frontmatter the command refuses and writes nothing. Handoffs says when an agent writes one.

4. Turn it into memory

ingest reads the handoff inboxes. To write cards, pass --promote-cards:

brigadestack ingest --target . --promote-cards
  promote    20261113-204811-retry-test-raced-the-fake-clock.md  [card-promoted]

Processed 1  Promoted 1  Reinforced 0  Routed 0  Inboxed 0  Skipped 0  Failed 0
Status ok

The card is now at memory/cards/retry-test-fake-clock.md. To have ingest run every 30 minutes on its own, see Run it in the background.

5. See what the second tool finds

Codex was set up by the same init, in the same repo, so it reads the same memory/cards/ folder. Search it the way any tool can:

brigadestack memory search "fake clock" --target .
memory search: fake clock (1 match(es))
- memory/cards/retry-test-fake-clock.md  [0.90]  retry-test-fake-clock

memory recall is the short lookup the session hooks use. It prints the title, tags and path of each match, never the card body:

brigadestack memory recall --target . --cwd . --query "fake clock"
memory recall: fake clock
- retry-test-fake-clock | tags: [tests] | memory/cards/retry-test-fake-clock.md

In 0.31.0 a repo install does not run this lookup for a session on its own. Sessions get it at start once memory_recall_target is set in .brigade/config.json. Until then an agent finds the card by running memory search, which the AGENTS.md that init wrote tells it to do before it writes a handoff.

Share it across machines and cloud agents

Memory stays in this repo on this machine until a backend is running. The backend holds the same cards for another machine, another checkout of the repo, and cloud agents. Turn on shared memory covers the setup, and Cloud agents covers the connections.