Monorepo + multi-project — one workspace, many brainclaw stores

A single repo is the easy case. The interesting one — and the one most agent users actually live in — is a workspace where multiple projects need to talk. Maybe it’s a monorepo with frontend/ + backend/ + worker/ each owning their lifecycle. Maybe it’s two sibling repos (my-app + my-app-cms) sharing context. brainclaw handles both.

Pattern 1 — Monorepo with nested stores

You have a top-level repo with multiple workable projects underneath. Each gets its own brainclaw store, and a parent store at the workspace root coordinates across them.

my-monorepo/
├── .brainclaw/                # workspace store (parent)
├── apps/
│   ├── web/
│   │   ├── .brainclaw/        # child store
│   │   └── package.json
│   └── api/
│       ├── .brainclaw/        # child store
│       └── package.json
└── packages/
    └── shared/
        ├── .brainclaw/        # child store
        └── package.json

cd my-monorepo
brainclaw init                  # workspace root
brainclaw init --cwd apps/web   # child store for the frontend
brainclaw init --cwd apps/api   # child store for the backend

The workspace root sees all child stores via its store chain. From the root: bclaw_context kind=board shows plans / claims / handoffs across every child. From a child: same call shows just that child’s state. Same canonical grammar, different scope.

Switch the active project from anywhere in the workspace:

brainclaw --project=web list-plans       # list plans in apps/web/
bclaw_coordinate intent=assign \
  targetAgents=[codex] \
  project=api \
  task="Add JWT verify middleware"

The agent doing the dispatch doesn’t have to cd into apps/api/ — the project argument routes the call there. This is the pattern that keeps your shell pinned at the workspace root while you orchestrate work across child projects.

Pattern 2 — Sibling repos linked together

You have two (or three) separate Git repos that share context: my-app and my-app-marketing-site say. They live in different directories, but you’d like a trap captured on one to be queryable from the other, or to dispatch work into the site project from the app project’s session.

~/code/
├── my-app/
│   ├── .brainclaw/            # standalone store
│   └── package.json
└── my-app-marketing-site/
    ├── .brainclaw/            # standalone store
    └── package.json

# From my-app, link the sibling project
cd ~/code/my-app
brainclaw link add ../my-app-marketing-site

# Verify
brainclaw link list
# → my-app-marketing-site  ✓
#       path: ../my-app-marketing-site
#       role: subscriber

# From the my-app session, query the site's traps natively
bclaw_get entity=trap id=trp#36 project=my-app-marketing-site

# Dispatch a brief into the site project's inbox
bclaw_coordinate intent=assign \
  targetAgents=[claude-code] \
  project=my-app-marketing-site \
  task="Update the changelog block for v1.5.3"

Cross-project access works on every canonical-grammar verb (bclaw_find/get/create/update/remove/transition), on bclaw_context, and on bclaw_coordinate. Identity is sourced from the calling project; writes + audit land in the target. Unknown project names throw — no silent fallback.

The CLI exposes the same as a global --project <name> flag, mutually exclusive with --cwd:

brainclaw --project=my-app-marketing-site list-plans
brainclaw --project=my-app-marketing-site decision "Drop /pricing route"

When to pick which

Situation	Pattern
One repo, multiple top-level packages, shared root config	Monorepo + nested stores — workspace root sees everything via store chain.
Two or more separate repos that need to share traps / decisions / context	Sibling repos + cross_project_links — brainclaw link add from each side that needs the link.
Mix: a root workspace AND a sibling repo elsewhere	Both patterns compose — the workspace store-chain handles children, and cross_project_links handles the sibling. The project argument resolves through both transparently.

Cross-project dispatch is inbox-only

When you dispatch with project=<name>, brainclaw force-disables auto-spawn and emits a warning. The target agent picks up the brief async via its own bclaw_work next time it runs. Reason: spawn cwd / worktree semantics are tied to the target’s git repo — auto-spawning from the source process would land in the wrong working tree. The async pickup keeps the lifecycle coherent and matches how the v1.5.3 ship intentionally scoped Phase 1.

What’s NOT yet supported

• Cross-machine federation — every project in a cross_project_links setup needs to be reachable via local path. Cross-machine sync (Pull-and-Materialize via the brainclaw-cloud transport) is on the roadmap as the federation Phase 1 (pln#365 / EPIC pln#499), not shipped.
• Cross-project auto-spawn — see above. Phase 1b-β remains an open optimisation.

For the day-to-day: orchestrate one or many projects on the same machine, all from the same session, no cd juggling. That’s the pattern.