brainclaw privacy

Analytics only if you say yes.

The site works without analytics. If you opt in, we use analytics to understand what helps and what confuses people. No ads. No resale. No dark patterns.

Privacy details

quickstart

Quickstart — install brainclaw with one prompt

Add brainclaw to your project in under a minute. Tell your agent to install it; brainclaw handles the rest. Walks through what gets created, why each file matters, and how to verify it works.

The shortest path to brainclaw is to tell your AI agent to install it. The agent installs the package, runs brainclaw init, which detects your stack, scans existing docs, derives memory seeds, and writes the agent-native instruction file (CLAUDE.md, AGENTS.md, .cursor/rules/, .windsurfrules, GEMINI.md, …) so the next session of any agent picks it up automatically.

Install with one prompt

> Please install and initialize brainclaw in this project.
> Run: npm install -g brainclaw && brainclaw init

That’s the whole onboarding for a solo developer on a fresh repo. The agent will run the commands, answer the interactive prompts (or use brainclaw init --yes for defaults), and commit the generated files to Git.

Four startup paths

The one-prompt above glues together two things that are useful to keep separate when you’re joining an existing repo or onboarding a teammate.

1. Machine setup — one-time per machine

> Run: npm install -g brainclaw

Installs the brainclaw and bclaw binaries globally. Required so the MCP server resolves to a pinned binary instead of an npx re-fetch on every agent session.

2. New project — bootstrap

> Run: brainclaw init

Run inside the repo root. Detects your stack, derives memory seeds, writes the agent-native instruction file (CLAUDE.md, AGENTS.md, …), and creates .brainclaw/. Commit everything.

3. Joining an existing brainclaw repo

You cloned a repo that already has .brainclaw/ committed. Do not run brainclaw init — it would re-scaffold and may overwrite the project memory. Step 1 (machine install) is enough; on the next agent session, the existing instruction file is read and the project memory activates.

To double-check the project is healthy:

> Run: brainclaw doctor

4. Bootstrap — the one-liner

The combined path covers cases 1 and 2 in a single prompt:

> Run: npm install -g brainclaw && brainclaw init

Use this for new projects. Skip it (use step 1 alone) when joining a repo that’s already brainclaw-enabled.

Why npm install -g first, not just npx brainclaw init?

npx brainclaw init works for the scaffolding step — but it doesn’t install brainclaw on the machine. It downloads the package into the npx cache, runs once, and leaves nothing behind. After init, the generated .mcp.json needs to spawn brainclaw mcp whenever the agent starts a session. Two paths:

  • npm install -g brainclaw (recommended) — .mcp.json resolves to the global binary at install time, every MCP startup is fast and pinned to a known version. Update with npm install -g brainclaw@latest.
  • npx brainclaw init only — .mcp.json falls back to npx brainclaw mcp. The first MCP startup may re-fetch from the npm registry (slow, online dependency). Acceptable for a try-it-out, fragile for long-lived projects.

Run npx brainclaw doctor after init either way — it tells you which mode the project is in and flags any drift between the installed version and what .mcp.json references.

What gets created

After init completes, you’ll see:

.brainclaw/                       # project memory store (Git-versioned)
├── config.yaml                   # project name, id, current agent, links
├── memory/                       # decisions, constraints, traps, instructions — one file per item
├── coordination/                 # plans, claims, handoffs, sessions, agent_runs
├── code/                         # Code Map — structural index (symbols, imports); rebuildable, safe to delete
├── project.md                    # generated human-readable summary of the local state
└── audit.log                     # JSONL of every state mutation

PROJECT.md                        # your canonical domain rules (repo root) — injected into the agent files
CLAUDE.md / AGENTS.md / GEMINI.md # agent-native instruction file (per detected agent)
.mcp.json                         # MCP server config so the agent can talk to brainclaw
.claude/commands/brainclaw.md     # slash command (Claude Code only)

Commit .brainclaw/, the agent files, and .mcp.json. They are the project’s shared memory. Other machines and other agents read them on the next session and resume from the same context.

Verify it works

In a fresh agent session, ask:

> What plans are currently in_progress on this project?

If the agent answers with concrete plan items, MCP is talking to brainclaw and memory is wired. If it says “I don’t know” or hallucinates a generic answer, check:

  • Is .mcp.json present and committed?
  • Does the agent’s instruction file (e.g. CLAUDE.md) reference brainclaw?
  • Did npx brainclaw doctor pass?

brainclaw doctor is the diagnostic. It checks store integrity, agent registration, MCP catalog version, and surfaces repair candidates.

What you get

  • Project memory in .brainclaw/ (Git-versioned, local-first, no cloud required)
  • A Code Map in .brainclaw/code/ — a structural index agents query (brainclaw code-map brief <path>) to know what to read before they grep
  • An MCP server with 66+ tools covering session, memory, claims, plans, dispatch, federation, cross-project routing
  • Agent-native instruction files refreshed on every session-end so they reflect the project’s current state, not a stale snapshot
  • Canonical grammar across 17 entities — six verbs, every entity, no per-entity tool to learn

Next steps