# Agent Integration

## The problem brainclaw solves for agents

Coding agents are stateless. Each session starts from zero. They don't know:

- what other agents have been working on
- what files are being actively edited by someone else
- what decisions were made last week and why
- what traps to avoid in a specific part of the codebase

Brainclaw gives every agent access to this shared context through a combination of surfaces adapted to what each agent can handle.

## Multiple points of contact

No single mechanism is enough. Agents don't always obey a single instruction file. They sometimes skip MCP calls. They forget between prompts.

That's why brainclaw uses every available surface:

1. **Instruction files** set the frame — "this project uses brainclaw, here's how"
2. **Hooks** inject context automatically — the agent sees plans and claims without asking
3. **MCP tools** provide on-demand access — the agent calls brainclaw when it needs more detail
4. **Auto-approve** removes friction — no popup confirmation for each tool call
5. **Skills/commands** give the developer a manual override — force a context refresh when needed

The more surfaces are active, the more reliably the agent uses brainclaw.

## What the instruction file contains

The instruction file (CLAUDE.md, .cursor/rules/, AGENTS.md, etc.) is the agent's first contact with brainclaw. Its content depends on the agent's capabilities:

### For agents with MCP and hooks (Claude Code)

Short and focused:
- Why brainclaw matters for this project
- The session protocol (hooks handle the rest)
- Active constraints and instructions
- Version check reminder

### For agents with MCP but no hooks (Cursor, Codex, Cline, Copilot, Windsurf, Continue, Kilocode, OpenCode, Roo, Mistral Vibe, Gemini CLI, etc.)

More directive:
- Same core sections as above, with stronger language ("REQUIRED", "MUST")
- The top 5 most critical traps (the agent won't see them otherwise)
- Explicit step-by-step protocol with all MCP calls listed
- For Tier B/C agents that lack hooks, an opt-in `.live.md` companion (regenerated on session-end and handoff) carries plans, claims, traps, candidates, and handoffs as a parity backstop — write with `brainclaw export --include-live --write`

### For agents without MCP (autonomous agents only)

Full static context via SKILL.md:
- All of the above
- Active plans with status and assignees
- All shared traps
- Recent architectural decisions

### For autonomous agents (OpenClaw, NanoClaw, NemoClaw, PicoClaw, ZeroClaw)

Skill-based integration via `skills/<agent>/SKILL.md`:
- Compact brainclaw usage instructions adapted to the agent's workflow
- Uses `--profile compact` by default (short sessions, constrained resources)
- Supports task-based and scheduled workflow models

## Setting up agent integration

### Automatic (recommended)

```bash
brainclaw setup-machine   # machine-level: detects agents, creates global configs
brainclaw init            # project-level: creates or refreshes .brainclaw/, writes agent files
```

Or ask your coding agent to do it:

```
"Inspect this package, explain what brainclaw does, then install it and initialize or join this project"
```

The agent can use `bclaw_setup` to walk through the process interactively.

### Per-agent manual setup

```bash
brainclaw enable-agent claude-code
brainclaw enable-agent cursor
brainclaw export --format claude-md --write
brainclaw export --detect --write          # auto-detect and write the current agent format
```

### Regenerating after changes

When brainclaw memory changes (new constraints, resolved traps, updated plans), regenerate instruction files:

```bash
brainclaw export --all              # all known agent formats at once (17 targets today)
brainclaw export --detect --write   # only the detected agent
```

For agents without MCP (autonomous agents), this is especially important — the instruction file or SKILL.md is their only source of project context.

## Generated files are local

Agent config files generated by brainclaw are **not committed to Git**. Each developer regenerates them locally from the shared `.brainclaw/` store.

This ensures:
- No machine-specific traps leak into the shared repo
- Each developer's agent sees instructions tailored to their setup
- Instructions stay in sync with current memory, not a stale committed version

brainclaw adds all generated files to `.gitignore` automatically during init.

Exception: use `--shared` if you intentionally want the main instruction file (e.g., CLAUDE.md) versioned for the whole team.

## Multi-project workspaces

When a workspace contains multiple brainclaw-initialized child projects, agents need to target the correct project store. There are three mechanisms (from most to least ergonomic):

### 1. `brainclaw switch` (persistent)

An operator or agent sets the active project once, and all subsequent commands resolve against it:

```bash
brainclaw switch apps/lodestar         # set active project
brainclaw plan list                    # targets lodestar
bclaw_context(kind="memory")           # MCP also targets lodestar
brainclaw switch --clear               # back to workspace root
```

### 2. `BRAINCLAW_PROJECT` environment variable

Set in the shell or agent configuration. Useful for CI/CD or when the agent can control its environment:

```bash
export BRAINCLAW_PROJECT=lodestar
```

### 3. `--cwd` flag (one-off override)

For a single command without changing the active project:

```bash
brainclaw --cwd apps/lodestar plan list
```

**Priority**: `--cwd` > `BRAINCLAW_PROJECT` > active project > shell cwd.

**Discovery**: use `brainclaw switch --list` to see all available projects in the workspace.

## Session lifecycle

### Starting work

```
bclaw_work(intent="execute", scope="src/auth/")          → start session, load context, claim scope in one call
bclaw_context(kind="execution")                          → check local tooling and brainclaw updates
```

### During work

```
bclaw_write_note("Found a race condition in AuthService")            → record observations
bclaw_create(entity="plan", data={ text: "Fix race condition", estimated_effort: 30 })  → track work
```

### Finishing work

```
bclaw_session_end(auto_release: true) → release claims, update plans
```

### Plans and estimation

Always estimate duration in minutes when creating a plan or step. When completing, report actual effort. This builds a calibration history that helps improve future estimates — agents are typically poor at estimation, and this feedback loop helps.

## Version awareness

Agents should call `bclaw_context(kind="execution")` at session start (or `bclaw_work` which loads it implicitly). If a newer brainclaw version is available, it tells the agent, who can then inform the developer and suggest updating. Updates may include new features, new MCP tools, and improved coordination.