# Quickstart

Get brainclaw running in your project in under 5 minutes.

> **Joining a project that already has `.brainclaw/`?** Use [quickstart-existing-project.md](quickstart-existing-project.md) instead — this page is for setting up a new project from scratch.

If you're about to cut a release that changes the CLI, MCP, or context surface, run the checklist in [release-maintenance.md](release-maintenance.md) before publishing a local pack or npm build.

## Step 1: Install

```bash
npm install -g brainclaw
```

Requires Node.js 22.12+ (`engines.node = ">=22.12.0"`). CI exercises Node 22 (Active LTS) and Node 24 (current LTS) — Node 22 or 24 is the recommended runtime. Node 20 reached EOL in April 2026 and is no longer supported. Verify with `brainclaw --version`.

## Step 2: Bootstrap this machine

```bash
brainclaw setup-machine --yes
```

This configures the agents Brainclaw can see on the current machine and writes the machine-level MCP/user files it manages. It does **not** initialize the current repository yet.

## Step 3: Initialize or refresh your project

```bash
cd your-project
brainclaw init
```

**What happens:**
- Creates `.brainclaw/` when the project is new, or refreshes it safely when it already exists
- Detects your coding agent (Claude Code, Codex, Cursor, Copilot, Cline, Mistral Vibe, etc.)
- Refreshes the detected agent's project and machine integration files when applicable
- Writes instruction files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/brainclaw.md`, etc.)
- Installs session hooks (if supported by your agent)
- Adds `.brainclaw/` to `.gitignore`

If you want the explicit path for a second or late-arriving agent on an already initialized project, use:

```bash
brainclaw enable-agent <agent-name>
```

If you have multiple repos, use `brainclaw setup --yes` instead — it bootstraps the machine, scans your project directories, and initializes everything at once.

## Step 4: Restart your agent

Your coding agent needs to reload to pick up the new MCP configuration.

| Agent | How to reload |
|-------|---------------|
| **Claude Code** | Restart the CLI session or VS Code window |
| **Cursor** | Cmd/Ctrl+Shift+P → "Reload Window" |
| **Codex** | Start a new `codex` session |
| **Cline** | Reload VS Code window |
| **Windsurf** | Reload the editor |
| **Copilot** | Reload VS Code window (uses instruction file, not MCP) |

## Step 5: Verify it works

After reloading, tell your agent:

```text
Call bclaw_work with intent "resume" to check that brainclaw is connected.
```

The agent should respond with session info, project context, and available tools. If it does, brainclaw is connected.

From the CLI, you can also verify:

```bash
brainclaw status          # active sessions, claims, plans
brainclaw agent-board     # what each agent sees
brainclaw context         # current project memory
```

## Step 6: Start using brainclaw

### For agents with MCP (most agents)

This is the primary path. Your agent calls brainclaw tools directly during work:

| Tool | What it does |
|------|-------------|
| `bclaw_work(intent)` | Start a session, load context, claim scope — all in one call |
| `bclaw_coordinate(intent, agents)` | Assign work, consult, request review, open an ideation loop, reroute, or summarize |
| `bclaw_context(kind, path?)` | Read memory / execution / board / delta — narrow to a path when given |
| `bclaw_claim(scope)` | Claim a file/directory before editing (prevents conflicts) |
| `bclaw_write_note(text)` | Record an observation, decision, or trap during work |
| `bclaw_session_end(narrative)` | Close session, release claims, hand off cleanly |

The facades `bclaw_work` and `bclaw_coordinate` are the recommended entry points — they handle session setup, context loading, and claim management automatically. For entity reads and writes (plans, decisions, traps, handoffs, candidates, etc.), use the canonical grammar: `bclaw_find` / `bclaw_get` / `bclaw_create` / `bclaw_update` / `bclaw_remove` / `bclaw_transition`.

### For autonomous agents (no MCP)

Autonomous agents (OpenClaw, NanoClaw, NemoClaw, PicoClaw, ZeroClaw) operate from a SKILL.md file generated by brainclaw. For Tier B/C agents that have MCP but no hooks (Cursor, Cline, Windsurf, Copilot, Continue, Kilocode, Mistral Vibe, etc.), an opt-in `.live.md` companion (regenerated on session-end and handoff) carries plans, claims, traps, candidates, and handoffs as a parity backstop.

Regenerate when project memory changes:

```bash
brainclaw export --detect --write
```

### Human operators (CLI)

The CLI is for inspection, scripting, and fallback:

```bash
brainclaw plan create "Implement auth module" --priority high
brainclaw plan list
brainclaw claim list
brainclaw context --for src/auth/routes.ts
brainclaw export --detect --write    # regenerate the detected agent instruction file
brainclaw export --all               # regenerate all known instruction files
```

## Onboarding an existing project

If the repo already has code, brainclaw can extract context from it:

```bash
brainclaw bootstrap --json     # preview: CI patterns, ADRs, Docker, branches, tags
brainclaw bootstrap --apply    # import detected signals into memory
```

Or let your agent drive it:

```text
Call bclaw_bootstrap to detect project signals, then review what was found.
```

## Common scenarios

The same primitives serve multiple workflows. Pick the one that matches what you're doing — full walkthroughs in [`concepts/multi-agent-workflows.md`](concepts/multi-agent-workflows.md).

### Active orchestration — parallel lanes across agent instances

```text
brainclaw sequence create "feature-cycle" --items '[…]' --status active
bclaw_dispatch(intent="execute", agents=[…])
```

The dispatcher creates one worktree + claim per lane and routes inbox messages by `claim_id`. Lanes with `hard_after` unblock as predecessors finish.

### Agent switching — when an agent runs out of credits mid-task

```text
# On the outgoing agent:
bclaw_session_end(narrative="Did X. Need to finish Y.")

# On the next agent (same or different):
bclaw_work(intent="resume")
```

The new agent picks up the open plans, the latest handoff narrative, and the unfinished claims it can adopt. No re-explanation needed.

### Project recovery — returning after weeks away

```text
bclaw_work(intent="resume")
```

Returns active plans, decisions taken since you left, active constraints, known traps, and where the last session stopped. Use `bclaw_context(kind="memory", profile="briefing")` for a narrower scope-focused view.

### Team async — humans and agents sharing the same project

Capture decisions, constraints, and traps as you discover them — they propagate to every teammate's agent on the next context read:

```text
bclaw_create(entity="decision",   data={ text: "…", outcome: "approved" })
bclaw_create(entity="constraint", data={ text: "…", category: "security" })
bclaw_create(entity="trap",       data={ text: "…", severity: "high" })
```

Hand off work for review with `bclaw_coordinate(intent="review", scope="…")`. Reviewers pick it up via `bclaw_read_inbox()`.

### One rule across all four

Scope-level claim isolation is strict — only one active claim per scope at a time, regardless of agent type. That's how parallel work stays safe and async handoffs stay clean.

## Next reads

- [integrations/overview.md](integrations/overview.md) — how brainclaw adapts to each agent
- [integrations/mcp.md](integrations/mcp.md) — the MCP runtime path in detail
- [concepts/memory.md](concepts/memory.md) — what project memory includes
- [concepts/plans-and-claims.md](concepts/plans-and-claims.md) — coordination layer
- [cli.md](cli.md) — full CLI reference