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

guides

Troubleshooting — common pitfalls and how to recover

The 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.

If you’re running brainclaw in production, you’ll hit one of these eventually. Each has a specific recovery path — none require nuking .brainclaw/ and starting over.

”An agent left a claim active and walked away”

Symptom: bclaw_find entity=claim filter={status: "active"} shows a claim that’s been open for hours; no recent agent_run events; the worktree directory still exists.

Recovery:

# Inspect what was happening
brainclaw doctor --dispatch       # surfaces stale claims, orphan agent_runs

# Release the claim (you become the actor on the audit log;
# in 1.10, ownership override is automatic for trusted+ callers — no flag needed)
brainclaw release-claim <claim_id>
# Optionally transition the linked plan in the same call:
brainclaw release-claim <claim_id> --plan-status done
# or via MCP:
bclaw_release_claim id=<claim_id>

The handoff that should have been written is missing — capture what you know about the work via brainclaw handoff (the CLI) so the next agent picks up the context anyway.

”I dispatched work and nothing happened”

Symptom: bclaw_coordinate intent=assign targetAgents=[...] task="..." returned ok but the target agent never picks up the brief.

Diagnose in this order:

  1. Did the message land? bclaw_read_inbox from the target agent’s identity, or bclaw_get_thread thread_id=<id> if you have one. If nothing — check that the target agent’s name matches the registered identity (bclaw_find entity=agent_run to see what brainclaw thinks the agents are).
  2. Was auto-spawn enabled? Default is on, but cross-project dispatch (with project=…) force-disables it. Check FacadeResponse.warnings for auto-spawn disabled. If yes, the target agent will pick the brief up the next time it runs bclaw_work — this is the inbox-only model and it’s intentional.
  3. Is the target agent CLI on PATH? validateAgentForDispatch rejects with binary_missing if the agent’s invoke_binary (e.g. codex, claude, cline) is not on PATH. Visible in the dispatch warnings array.
  4. Did the target agent’s session actually start? bclaw_find entity=agent_run filter={status: "launching"} — if the agent_run is stuck in launching, the spawn happened but the agent never reached the handshake. Check brainclaw doctor --dispatch for the stale-launch reconciler output.

”bclaw_context returns empty / stale memory”

Symptom: a feature you’re working on has known traps, but bclaw_context kind=memory path="..." returns nothing related.

Possible causes:

  • Provenance filtering — by default, bclaw_find and the memory context exclude provenance.kind="legacy" records and auto_reflect records below 0.6 confidence. Pass filter={includeLegacy: true, minAutoReflectConfidence: 0.3} to widen.
  • Scope path mismatch — the memory ranker scores items by path overlap. path="src/auth/" matches items tagged with auth or src/auth/..., not items tagged with authentication. Try bclaw_search query="authentication" to find them by full-text.
  • Cross-project reads — if the trap lives in a linked project, pass project=<name> to read its store. Without that param the call hits the current project only.

”Merge wiped my node_modules”

Resolved as of pln#498 in v1.5.0 — detachWorktreeJunctions runs before git worktree remove on Windows so git’s recursive rm can’t follow the node_modules junction back into the main repo. If you see this on v1.4.x or older, upgrade.

”trp#36 — Cloudflare adapter post-build crash”

Resolved as of v1.5.3 site-side: scripts/build.mjs recognizes the known cloudflare adapter post-build hook crash, accepts the non-zero exit, and emits the sitemap manually via scripts/emit-sitemap.mjs. The HTML is intact; the worker bundle stays broken until the Astro 6 + cloudflare 13 upgrade ships (Linux/macOS investigation pending). Full details: trp#36 in project memory.

”I can’t find an agent in the registry”

Symptom: bclaw_create entity=plan data={author: "claude-code"} works, but bclaw_coordinate intent=assign targetAgents=[claude-code] says unknown_profile.

Cause: agent profile (built-in capability descriptor) ≠ registered agent identity (project-local). The dispatch validator uses profiles. Fix:

brainclaw register-agent claude-code --kind agent
brainclaw enable-agent claude-code      # writes the agent's native instruction file

Whitelisted agents for dispatch: claude-code, codex, github-copilot. Other names (gemini, antigravity, sonnet, opus) are off-limits per project policy.

”I lost track of who’s working on what”

bclaw_context kind=board                 # active claims, assignments, plans across the workspace
bclaw_context kind=board_summary         # lightweight counts only
brainclaw doctor                         # health check + repair candidates
brainclaw stale list                     # plans/traps/handoffs/candidates that look stale

bclaw_context kind=delta since=<prior_session_id> is the closest thing to “what changed since I last checked”.

When in doubt — read the audit log

Every state mutation writes to .brainclaw/audit.log (JSONL). It’s the source of truth for “what actually happened, who did it, and when”. Tail it with tail -f .brainclaw/audit.log while you reproduce; the entry just before the failure is usually the smoking gun.