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