# Quickstart

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

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

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

npm and venv installs, and pipx setup for each OS, are on the [install page](/docs/getting-started/install).

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

```bash
brigadestack init --target . --depth repo --harnesses claude,codex
```

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

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

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

```text
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](/docs/guides/handoffs) says when an agent writes one.

## 4. Turn it into memory

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

```bash
brigadestack ingest --target . --promote-cards
```

```text
  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](/docs/guides/handoffs#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:

```bash
brigadestack memory search "fake clock" --target .
```

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

```bash
brigadestack memory recall --target . --cwd . --query "fake clock"
```

```text
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](/docs/guides/fleet-hub#turn-on-shared-memory) covers the setup, and [Cloud agents](/docs/guides/cloud-agents) covers the connections.