brainclaw / docs
Install brainclaw, then let your agents share memory, claim files, and hand off cleanly.
Quickstart
Use this sequence whether you are onboarding a repo yourself or asking an agent to do it for you.
Install and initialize brainclaw in the project so local memory, instructions, and coordination state exist before work starts. Init also builds the Code Map so agents know where things live before they grep.
npm install -g brainclaw && brainclaw initAgents should prefer MCP and start by loading session context. Operators can inspect the same state from the CLI.
bclaw context --digestBefore editing, ask the Code Map what to read — symbols, imports, and the memory attached to that scope — so the agent lands on the right files instead of grepping blind.
brainclaw code-map brief src/views/DocsPage.astroCreate a plan for meaningful work, claim the files or folders you will touch, then let the agent implement against that explicit scope.
bclaw claim create "Take docs page" --scope src/views/DocsPage.astroWhen the task is done, release the claim and end the session so the next agent or human can resume from clean shared state.
bclaw session-end --auto-releaseCore CLI commands
The CLI is the operator path: bootstrap, inspect, coordinate, and recover when MCP is not the active surface.
Use these commands when setting up the repo or checking the current project state.
npm install -g brainclaw && brainclaw initbclaw context --digestbclaw statusThese are the commands you use once real implementation starts.
bclaw plan create "Ship docs landing page" --priority highbclaw claim create "Take docs landing page" --scope src/views/DocsPage.astrobclaw claim release <claim-id>MCP runtime path
Capable agents should stay on MCP for live state instead of reconstructing project context from stale files.
bclaw_work Opens a session, reads context, and claims the scope — three steps in one call.
bclaw_context Pulls memory / board / delta context for the current scope. Replaces the old per-kind get_context tools.
bclaw_find / bclaw_get Lists or fetches any entity (plan, decision, claim, handoff, trap, …) — the canonical read surface.
bclaw_create / bclaw_update / bclaw_transition Captures decisions and traps, edits plans, advances lifecycle — the canonical write surface.
bclaw_coordinate Assigns work, consults agents, opens review or ideation loops with target agents.
bclaw_release_claim Closes the claim with a handoff and updates the plan in one call.
Storage layout
brainclaw stays local. The repo keeps plain-text memory and coordination state under `.brainclaw/`.
Typical layout
.brainclaw/
memory/
constraints/
decisions/
instructions/
traps/
coordination/
plans/
claims/
runtime/
sessions/
handoffs/
code/ # Code Map index (per-project, rebuildable)
project.md # legacy summary (superseded by /PROJECT.md since 1.9)
config.yaml
PROJECT.md # canonical human-readable summary (root).brainclaw/memory/ Durable project knowledge the next agent should be able to resume from.
.brainclaw/coordination/plans/ Shared work items with status, assignee, and linked claims.
.brainclaw/coordination/claims/ Advisory locks over files or folders to reduce collisions between agents.
.brainclaw/coordination/handoffs/ Snapshots an agent leaves behind so the next one resumes without re-reading the chat.
.brainclaw/coordination/runtime/ Short-lived observations, breadcrumbs, and operational notes.
.brainclaw/code/ Code Map: structural index of symbols, imports, and components — rebuildable, safe to delete.
PROJECT.md Canonical human-readable project summary at the repo root (legacy .brainclaw/project.md is derived).
Concepts & guides
Deeper dives on the primitives, patterns, and references that the brainclaw daily loop builds on.
The two facade entry points you call 10× a day. bclaw_work starts a session, claims scope, and returns context in one shot. bclaw_context pulls focused memory views without ceremony.
Read → conceptsThe six MCP verbs (find/get/create/update/remove/transition) that work uniformly on every brainclaw entity. Learn it once, reuse on plans, decisions, claims, handoffs, and everything else.
Read → conceptsHow claims reserve scope before edits, and how auto-worktree per claim isolates parallel work. The pattern that lets multiple agents touch the same repo at once.
Read → conceptsMulti-turn delegation patterns: how brainclaw drives review-and-fix cycles between two agents and runs ideation loops where one agent critiques another. Built on bclaw_coordinate + bclaw_loop.
Read → guidesHow to set brainclaw up across several related projects on the same machine: a monorepo with nested stores, sibling repos linked together, or a single workspace coordinating both. The patterns that scale beyond a single repo.
Read → guidesThe handful of failure modes that come up in real multi-agent sessions: stale claims, dispatch not landing, MCP server returning empty context, worktree wiped on merge. With recovery commands.
Read → referenceThe handful of MCP calls and CLI commands that cover 90% of day-to-day work: starting a session, reading context, claiming scope, capturing decisions.
Read →brainclaw
Initialize the repo, open the session, claim the work, then let the agent execute with live context instead of improvising.