@brainmcp/brainmcp

Safely configure brain / brainmcp guidance and MCP connections for agent clients.

Requires Node.js 22 or newer. The recommended command runs the latest published CLI directly, so there is no permanent global package to maintain.

Full client walkthroughs: Quickstart · Claude Code · Cursor · Codex · VS Code · GitHub Copilot CLI · Antigravity

Quickstart — all projects, supported agents

Preview one combined user-scope change for Claude Code, Cursor, Codex, VS Code, GitHub Copilot CLI, and Antigravity, then confirm once:

npx --yes @brainmcp/brainmcp@latest init --all --scope user

The --yes before the package name belongs to npx: it suppresses npm's package-download prompt. It does not skip BrainMCP's file preview or confirmation. To automate both prompts only after reviewing the targets, add a second --yes at the very end.

Only pin a workspace at user scope when that same workspace should be the default in every project. Otherwise omit it and use the OAuth authorization default or a project-scope override:

npx --yes @brainmcp/brainmcp@latest init --all --workspace <workspace-uuid> --scope user

After setup:

1. Sign in to the brain dashboard and create one workspace for the project if it does not exist yet. Start with Review required.

2. Restart every configured client you plan to use. Installation only writes the MCP endpoint and guidance; it does not log the client in.

3. Log each client in to brain:

   • Codex: run codex mcp login brain and finish the browser flow. Generated TOML pins Brain's stable public codex OAuth client and canonical resource so re-login recovers the same logical connection rather than registering another DCR identity.
   • Claude Code: start a session, run /mcp, select brain, then choose Authenticate.
   • Cursor: open Settings → Tools & MCP, select brain, then connect/authorize it.
   • VS Code (Copilot Chat): start brain from MCP: List Servers or its mcp.json CodeLens, choose Auth, and complete browser sign-in.
   • GitHub Copilot CLI: run copilot, open /mcp, and authenticate brain. If it shows needs-auth, run /mcp auth brain.
   • Antigravity: in the IDE open Settings → Customizations and Authenticate brain (or … → MCP Servers to confirm it is listed). In agy, run /mcp, select brain, and finish OAuth. Paste an authorization code back into settings if prompted.

4. On the brain consent screen, review the scopes, select every workspace that connection may reach, and choose its default workspace.

5. In the project, ask: Use brain to give me an overview of this workspace. Confirm the dashboard Connect view changes from waiting for first call to Agent seen ... ago.

6. If the overview says the workspace is empty, copy and paste this second command into the connected agent:

   Use brain to bootstrap this project now. Inspect the repository comprehensively and propose the
   most detailed durable initial graph that fits one valid brain_change_propose. Use Cores as stable
   concepts; parent a focused Neuron when a broader Core genuinely owns it, while allowing honest
   standalone flat Neurons. Add described cross-Core links. Report the proposal ID/status, coverage,
   remaining gaps, and whether it was auto-applied or awaits Review. Do not claim the workspace is
   populated until it is applied.

   The dashboard's Context map → Bootstrap with your agent control provides the full canonical version, including coverage, safety, modeling, and deduplication requirements. The CLI also prints that full prompt after installation.

7. Follow the returned status. If the proposal awaits Review, approve, edit, or reject it. The workspace is not populated until the proposal is applied.

8. Leave the generated guidance enabled. It tells agents to orient and retrieve context before non-trivial work, follow workspace Rules/Skills/Workflows, and propose only genuinely new durable project knowledge afterward.

No API keys or OAuth secrets are written to config files.

Guidance included in the current release

Version 0.1.29 bundles guidance 2026.10.04 (unchanged since 0.1.27): knowledge classes, workspace inference (pick an authorized workspace and continue instead of asking which one), Context Paths (save an explanation only when asked, and only when brain_context_path_create is advertised), proactive proposals during authorized work, explicit Rule/account-library write limits, and customer-agent processing responsibility. It also retains sector discovery/filtering, Neuron brain_remember / brain_amend selection, advanced brain_change_propose operations, and capability-aware fallback for older MCP servers. Branch, targetRef, and activeRef guidance was removed because brain no longer has branches. The CLI installs the compact managed instruction block; generated plugin/shared Skills and the MCP handshake carry the full authoring workflow. Every graph change still uses the audited proposal pipeline. Sectors classify Cores/Neurons across hierarchy; Unassigned means no effective primary, including nodes with secondary memberships.

0.1.19 (published 2026-10-02) adds companion dead-grant handling (see Credential storage and safety boundaries). 0.1.20 (published 2026-10-02) also makes brainmcp login exit after success. 0.1.21 (published 2026-10-02) gives SessionStart orientation a 2.5-second budget instead of a fixed 800 ms per request inside 1 second, so a slow or cold API no longer drops it; rerun init so VS Code/Copilot hooks get the longer host timeout. 0.1.22 (published 2026-10-02) refreshes an expired access token before the request instead of after a 401, and reuses the token endpoint found at login, so a session that starts with an expired token makes two requests instead of four. 0.1.23 (published 2026-10-02) raises the SessionStart budget to 4 seconds (VS Code/Copilot host timeout 6 seconds) so the first orientation after the API has been idle still loads; rerun init after upgrading. Published versions cannot be reused.

0.1.24 (published 2026-10-03): failures use the documented exit codes instead of always 1, and brainmcp whoami exits 3 when signed out or when the sign-in must be renewed (it exited 0 through 0.1.23). capture now reports a refused sign-in (3) or permission (4) instead of a network error. Only whoami changes between zero and non-zero; a script that ran it while signed out and expected 0 must read the exit code or the JSON status.

0.1.25 (published 2026-10-04) fixes brainmcp login for an authorization that covers two or more workspaces (the default now comes from the account's defaultWorkspaceId; earlier versions refused the login), trims digests to both the server's 14,000-character and 14,336-byte limits, checked before and after the server's redaction (earlier versions could queue a digest the server rejected for good), makes capture now exit 6 when another BrainMCP process holds the capture-queue lock, keeps the SessionEnd hook inside its process deadline, and resolves absolute hook paths correctly on Windows. Rerun init after upgrading so hooks use the new runtime.

0.1.26 (published 2026-10-04, guidance 2026.09.30): invalid JSON in local files (credentials, queue, session, preferences, agent MCP configs) is reported as "not valid JSON (position N)" without echoing any file content, so a corrupted credentials file can no longer print part of a token; runtime log rotation keeps only whole lines, never writes padding, and skips a rotation that races a concurrent write; doctor validates credentials with the same schema the CLI stores and reports vault service credentials correctly. Rerun init after upgrading.

0.1.27 (published 2026-10-04): guidance 2026.10.04 drops the branch, targetRef, and activeRef instructions, because brain no longer has branches, and session orientation no longer prints an active ref. It works with servers before and after the branch removal. Rerun init after upgrading so installed instructions and hooks carry the new guidance.

0.1.28 (published 2026-10-04, npm latest, guidance 2026.10.04): --workspace must be the workspace UUID on every command (a slug or name exits 2), and doctor fails an existing slug binding with a fix to rerun init --workspace <workspace-uuid>. --store-service-token without --service-token-stdin exits 2 instead of being ignored. Capture gives slow Git commands a per-trigger time budget inside the hook deadline and leaves out diffStats when they time out instead of reporting a clean tree; queue items with an unknown status or trigger are skipped instead of resent. Rerun init after upgrading.

0.1.29 (not yet published; publish after the API deploy that ships the matching digest changes):

• capture now reports what happened to the current session slice instead of always "nothing new": already delivered (0), queued for the next lifecycle hook as an automatic capture (6), refused earlier (1, 3, or 4 by cause), cancelled (4), or no local delivery record (1). JSON adds alreadyDelivered, digestId, status, and failureClass.
• capture now also resends this sign-in's other undelivered manual captures (same workspace and consent revision) and reports them as retriedEarlier / earlierOutcomes. A full queue no longer blocks a slice that is already queued; when it is full, earlier manual items are sent first.
• The last successful delivery is kept in capture-status.json (owner-only), so capture status still shows it after local retention prunes delivered items. purge-local keeps that file.
• The latest ledger is chosen by modification time (up to 1,000 scanned). Digests keep the newest 10 prompts and 50 paths. A server 409 pending_digest_cap_reached is retried later instead of failing the item for good.
• remove never edits, backs up, or deletes a hook file that has no BrainMCP entry, deletes a file only when what is left is what BrainMCP created, and treats a blank hook or MCP file as empty.
• doctor gives each network probe an 8-second deadline (body included) and rejects redirects.
• --help/-h and --version/-v work anywhere; a positional action such as now on a command other than capture exits 2. init previews the hook runtime as one line (path, size, SHA-256).
• Hooks keep working when the session's working directory was deleted; read-only tool calls are classified by name (the mcp__<server>__ prefix is stripped, and a tool with a write verb counts as a write); digest secrets are redacted with the same patterns the API uses.
• Session orientation says so when Brain Rules could not be loaded, instead of implying there are none.

Rerun init after upgrading so hooks use the new runtime.

Publication and server deployment are separate: @latest downloads the published npm version, not unpublished repository source. After the release is published, rerun the setup command below and restart/reconnect your clients to load refreshed guidance. Keep capture opt-in: upgrading instructions does not authorize digest capture or grant companion OAuth consent.

Rerun to upgrade or repair

Run the same init command again after upgrading the package or whenever Brain configuration or instructions may have been damaged. Every run previews the repair before writing:

• The reserved brain MCP server entry is rewritten to the selected client’s exact defaults for the installed release, even if an older client shape or valid-but-corrupted value is present.
• The Codex [mcp_servers.brain] table is restored even if its generated markers were removed.
• BrainMCP-managed instruction regions are replaced with current guidance. Existing workspace bindings survive unless --workspace supplies a replacement. Dedicated Cursor, VS Code, and Antigravity project-rule headers are refreshed; files without managed blocks restore defaults.
• Unrelated MCP servers, TOML tables, and text outside valid managed instruction blocks are kept. Changed existing files receive backups, and the write is atomic.

Syntactically invalid JSON/JSONC, a non-object server map, unmatched/duplicated markers, or another ambiguous structure still fails closed instead of guessing across unrelated user content. Use a server name other than brain for a separately maintained custom connection.

doctor compares the complete managed instruction block with the guidance bundled in the CLI being run. A current version marker alone is insufficient: altered content and missing/duplicate end markers are reported too. Without --workspace, an existing explicit workspace binding is preserved for comparison; a binding to a workspace slug or name (from installs before --workspace required a UUID) fails the check, with a fix to rerun init --workspace <workspace-uuid>. Diagnosis is read-only; valid stale content can be repaired by rerunning init, while ambiguous shared markers must be resolved before the installer can safely proceed. This does not query npm for a newer release or prove authenticated MCP access. Setup prints a read-only agent verification prompt for that final check.

The guidance teaches agents to reuse fresh context, recover omitted Rules, stop retrieving once the task is grounded, amend existing concepts, and distinguish applied proposals from pending review.

Answer grounding is part of every installed managed block and the MCP workflow. Agents must connect material claims to sources they actually read, separate direct source statements from inferences, assumptions, and unknowns, and state when Brain does not supply the answer. A related search hit is not evidence for an outcome. Quotations, delivery receipts, saved explanations, and applied proposals do not independently verify factual truth or an earlier agent's motivation. Context Paths must not pad steps or sources, invent requirements, or turn expected benefits into measured results.

Companion orientation is a bounded packet. It identifies workspace ids, labels Rule excerpts and omitted context, and reports failed or mismatched workspace responses. Grounding and recovery instructions survive the shared 2,400-character cap; up to eight workspace packets share the remaining budget, with additional omissions disclosed. Agents still read overview for full binding context. Read-only or unknown companion grants do not receive write-back instructions; host MCP permissions are checked independently. These instructions are intended to reduce unsupported claims. Delivery regressions verify their presence; actual model behavior requires separate evaluation.

Check one client's exact schema and placement, managed guidance, canonical and compatibility OAuth metadata, PKCE/DCR/refresh capabilities, and strict scoped 401 challenge. For Cursor, VS Code, GitHub Copilot CLI, and Antigravity, doctor also fails when the reserved brain entry exists in both project and user MCP config scopes:

npx --yes @brainmcp/brainmcp@latest doctor --client cursor --scope user

--all intentionally excludes generic: an unknown client has no universal global config path. Keep each named host's brain MCP server in either project or user scope, not both. Prefer a maintained plugin when Claude Code or Cursor offers one; use the CLI when you want reviewable filesystem configuration or no plugin is available.

Project-local alternative

For a single repository only, omit --scope user (or pass --scope project) and run from that repo root:

npx --yes @brainmcp/brainmcp@latest init --client claude-code

Optional persistent CLI

If you prefer a brainmcp binary on your PATH for repeated administration, install it globally:

npm install --global @brainmcp/brainmcp@latest
brainmcp init --all --scope user

The setup result is the same. The npx path avoids global package permissions and version drift; the global path makes later doctor, print, and remove commands shorter.

Commands

| Command | What it does | | --- | --- | | init | Preview and restore current MCP config + instruction defaults for a client; installs lifecycle hooks by default | | init --all | Preview one combined change for Claude Code, Cursor, Codex, VS Code, GitHub Copilot CLI, and Antigravity after duplicate-scope preflight | | doctor | Check host schema, placement, duplicate scopes, managed markers, full OAuth discovery, and strict auth challenge (each network probe has an 8-second deadline) | | print | Print the canonical config and guidance without writing | | remove | Preview and remove BrainMCP-managed blocks and hooks; files without a BrainMCP entry are left alone | | login | Interactive companion OAuth sign-in with browser consent; OS vault first, file fallback only with --allow-file-credentials | | logout | Revoke the companion grant when possible and clear local credentials | | whoami | Show the current companion identity without echoing tokens | | capture | Manage affirmative session digest capture (enable, disable, status, now, purge-local) |

Every mutation shows a diff and asks for confirmation unless you append a trailing CLI --yes.

brainmcp init [--client <client>] [--workspace <uuid>] [--scope project|user] [--no-hooks] [--write-back-nudge] [--yes]
brainmcp init --all [--workspace <uuid>] [--scope project|user] [--no-hooks] [--write-back-nudge] [--yes]
brainmcp doctor [--client <client>] [--workspace <uuid>] [--scope project|user]
brainmcp print [--client <client>] [--workspace <uuid>] [--scope project|user]
brainmcp remove [--client <client>] [--scope project|user] [--yes]
brainmcp login [--capture-digests] [--allow-file-credentials] [--service-token-stdin] [--store-service-token] [--force] [--json]
brainmcp logout
brainmcp whoami [--json]
brainmcp capture [enable|disable|status|now|purge-local] [--dry-run] [--workspace <uuid>] [--include-prompts] [--yes] [--json]
brainmcp --help | -h
brainmcp --version | -v | version

--help wins over every other argument and exits 0. Positional actions are accepted only by capture.

Exit codes

| Code | Meaning | Typical causes | | --- | --- | --- | | 0 | Success | Command completed; --help / --version; whoami has a usable sign-in; capture now was delivered, or the slice was already delivered (JSON alreadyDelivered: true) | | 1 | General error | Unclassified failure, a declined preview, a manual capture the server rejected for good (now or earlier), an automatic slice that ran out of retries, no local delivery record for the slice, or a full capture queue | | 2 | Usage error | Unknown command or option, conflicting or misplaced flags (including --store-service-token without --service-token-stdin), a --workspace that is not a workspace UUID, a positional action on a command other than capture | | 3 | Authentication required | whoami is signed out or its sign-in expired or was revoked (JSON status unauthenticated / reauth_required); HTTP 401; capture needs brainmcp login --capture-digests, including a slice refused earlier for that reason | | 4 | Permission denied | HTTP 403, missing digests:write, a workspace outside the grant, or capture disabled by consent, project policy, or the server (now or for a slice refused earlier); a slice cancelled before delivery | | 5 | Configuration error | doctor found issues; a host config file cannot be parsed (a blank file counts as empty); conflicting managed markers or a manual brain entry; Brain already configured in the other scope; missing hook runtime; no capture ledger or workspace | | 6 | Network error (retryable) | Connection failure or request timeout; capture now left the digest queued after a transport, 429, 5xx, or 409 pending_digest_cap_reached failure, or a manual slice failed after 8 attempts (rerun to resend); the slice is an automatic capture waiting for the next lifecycle hook; a local BrainMCP lock was busy |

brainmcp hook always exits 0 and prints {} when it cannot help, so a hook never fails the host agent.

Clients

| --client | User-scope paths (--scope user) | Project-scope paths (default) | | --- | --- | --- | | claude-code | ~/.claude.json, ~/.claude/CLAUDE.md | .mcp.json, CLAUDE.md | | cursor | ~/.cursor/mcp.json, ~/.cursor/rules/brainmcp-workspace.mdc | .cursor/mcp.json, .cursor/rules/brainmcp-workspace.mdc | | codex | $CODEX_HOME/config.toml, $CODEX_HOME/AGENTS.md (default ~/.codex) | .codex/config.toml, AGENTS.md | | vscode | Default VS Code profile mcp.json; ~/.copilot/instructions/brainmcp.instructions.md | .vscode/mcp.json, AGENTS.md | | copilot | ~/.copilot/mcp-config.json; shared ~/.copilot/instructions/brainmcp.instructions.md | portable .mcp.json, .github/copilot-instructions.md | | antigravity | ~/.gemini/config/mcp_config.json, ~/.gemini/GEMINI.md | .agents/mcp_config.json, .agents/rules/brainmcp.md | | generic | Conventional ~/.mcp.json, ~/AGENTS.md (only when your host recognizes them) | .mcp.json, AGENTS.md |

If you omit --client, the CLI detects a single obvious client from the project. Multiple matches require an explicit --client. Copilot is detected from .github/copilot-instructions.md; its portable project .mcp.json is also a Claude Code location, so choose --client copilot explicitly when needed. Antigravity is detected from .agents/mcp_config.json or .agents/rules, not from a shared .agents/skills directory. VS Code user scope targets the platform’s default local profile; named profiles, Insiders, remote SSH, WSL, and dev containers need their own setup in that environment.

Shared artifacts are reference-safe on removal: the user-level VS Code/Copilot instruction remains until neither config uses Brain, and the portable project .mcp.json entry remains while either the managed Claude Code or Copilot CLI setup still uses it.

Scope

• user — write to the selected host’s supported per-user locations so brain is available across that host’s projects
• project (default) — write only under the current repository

Cursor, Codex, VS Code, GitHub Copilot CLI, and Antigravity must keep brain in exactly one of these scopes. init refuses to create a competing entry and tells you which remove command resolves it; doctor reports both paths when an older setup already contains a duplicate.

Workspace

--workspace <uuid> embeds the workspace UUID in the managed guidance block so agents orient to that workspace. It must be the UUID, not the workspace slug or name: MCP tools accept only the UUID, so every command rejects any other value with exit code 2. Prefer this at project scope. At user scope it affects every project for that host, so use it only for a genuinely global default. Without it, brain_workspace_overview may use the authorization’s default workspace; agents call brain_workspaces_list, infer the best authorized match from the task and repository, state the assumption, verify it with overview, and continue even when several candidates fit. Workspace descriptions help matching; they do not override instructions.

Examples

# Cursor for all projects
npx --yes @brainmcp/brainmcp@latest init --client cursor --scope user

# Antigravity for all projects
npx --yes @brainmcp/brainmcp@latest init --client antigravity --scope user

# Standalone GitHub Copilot CLI for all projects
npx --yes @brainmcp/brainmcp@latest init --client copilot --scope user

# Codex user-scope with workspace pin
npx --yes @brainmcp/brainmcp@latest init --client codex --workspace <workspace-uuid> --scope user

# Single-repo only
npx --yes @brainmcp/brainmcp@latest init --client vscode

# Preview / remove
npx --yes @brainmcp/brainmcp@latest print --client vscode --scope user
npx --yes @brainmcp/brainmcp@latest remove --client cursor --scope user

# Companion CLI login (two-phase OAuth companion access)
brainmcp login

# Inspect companion credentials and access
brainmcp whoami --json

# Session digest capture (affirmative opt-in)
brainmcp capture enable --workspace 11111111-1111-4111-8111-111111111111
brainmcp capture now
brainmcp capture now --dry-run
brainmcp capture status --json
brainmcp capture disable
brainmcp capture purge-local

Companion OAuth and Lifecycle Hooks

BrainMCP supports a two-phase connection workflow:

1. Authorize the host agent (Claude Code, Cursor, Codex, etc.) over MCP OAuth to enable tool calls. In Cursor, use Settings → Tools & MCP, select brain, and connect. A successful brainmcp login does not attach brain_* tools to the IDE agent.
2. Authorize the companion CLI via brainmcp login. Reuses your existing browser session with prefilled Continue when eligible. Companion grants are non-billable, independent of the host grant, and held under the scope ceiling graph:read skills:read workflows:read offline_access (never changes:write).

Companion REST calls go to https://api.brainmcp.ai (BRAINMCP_API_URL). OAuth discovery uses https://mcp.brainmcp.ai (BRAINMCP_OAUTH_ISSUER). Do not point BRAINMCP_API_URL at the MCP host: /api/mcp/workspaces is not served there. Self-hosted layouts that split those roles should set both variables independently.

Credential storage and safety boundaries

• Credentials prefer the OS vault, with one item per Brain account. If it is unavailable, brainmcp login --allow-file-credentials stores tokens in owner-only files under ~/.brainmcp/accounts/<accountId>/ (directory 0700, file 0600, no symlinks, atomic write). Capture consent, queues, and session ledgers are namespaced the same way so switching accounts cannot reuse the previous identity's local state.
• Vault reads require a marker in the selected Brain home; a fresh BRAINMCP_HOME does not adopt a machine-wide credential. Existing file credentials remain readable if a vault later becomes available. Legacy flat state migrates only when its previous account owner is known; unowned state is retained without assigning it to a replacement login.
• Service token fallback uses BRAINMCP_SERVICE_TOKEN or brainmcp login --service-token-stdin (process-only unless --store-service-token, which is valid only with --service-token-stdin). It cannot call /orient or enable automatic capture. Do not pass the token as a command-line argument.
• Default orientation hooks fail open, send no prompt text, and do not treat prompts as /orient queries. Hooks use a project binding, authorization default, or sole authorized workspace; when unresolved, they hand selection to the host agent's inference workflow. Companion login is independent of host MCP access. --no-hooks skips hook install; --write-back-nudge is off by default.
• capture now and its dry run select the latest ledger for the current project. Delivery also requires the same workspace and capture-consent revision. Older ledgers without a project binding need fresh hook activity before manual capture. A nudge-only ledger stores counters, never prompts, summaries, edited paths, or model labels.
• capture now resends only manual captures; an automatic slice waits for the next lifecycle hook. Hooks never send manual items. The last successful delivery time is kept in capture-status.json (0600) next to the queue.
• Capture retries reserve a delivery lease and reuse the same digest ID. Concurrent hooks cannot enqueue the same session slice twice or send a manual item in the background. Consent and authorization are checked again immediately before sending, including after token refresh.
• API and OAuth requests enforce deadlines through refresh and response-body reads, reject redirects, and keep remote error bodies out of diagnostics. Stored OAuth takes precedence over the service-token environment fallback; replacing a login verifies the newly issued token explicitly.
• Once a refresh request is sent, the companion waits for the response and stores the rotated tokens even after the calling hook's deadline, so a refresh token the server already rotated is never discarded. When the token endpoint rejects the grant (invalid_grant, invalid_client, or unauthorized_client), the companion marks it for re-login: hooks stop sending requests, SessionStart tells the agent to orient through the host brain_* tools and to ask the user to run brainmcp login (no --force needed for a rejected grant), and whoami and doctor report it. Other orientation failures name their cause (timeout, forbidden, http_<status>, network) in the packet and in orient_fetch_failed diagnostics. A lapsed hourly access token with a refresh token is healthy.
• Cloud environments (e.g. Cursor Cloud Agents, GitHub Codespaces without a local browser) do not share this machine's ~/.brainmcp state; configure service tokens or dashboard connections for those environments.

What gets written

• Canonical MCP endpoint: https://mcp.brainmcp.ai/mcp (server name brain)
• Managed instruction markers (brainmcp:managed:start / end) so later init / remove can update safely
• Task-first guidance: disclose connection/auth failures honestly, orient, start with a bounded search working set, escalate to exact or broader reads only when needed, and apply recent review feedback
• Empty-workspace guidance: never silently omit bootstrap; after explicit authorization, study the project comprehensively and propose detailed concept Cores, focused Neurons with honest conceptual parenting (or legitimate flat placement), and described links; report whether the proposal was auto-applied or awaits Review
• Selective write-back guidance: propose only new durable project knowledge, never store secrets/raw transcripts/temporary output, correct exact duplicate creates instead of retrying, report proposal status, and abstain when nothing reusable changed
• Context Path guidance: save only on request and when advertised; cite nodes, Rules, Skills, direct instructions, and labeled assumptions; distinguish delivery evidence from reported influence; retry unchanged payloads with the same key and use a new key only for repaired payloads after definitive rejection
• Backups for changed files; existing modes and symlinked dotfiles are preserved, and stale previews are refused
• No embedded OAuth secrets — tokens come from the browser consent flow

Local package verification

corepack pnpm --filter @brainmcp/brainmcp test first bundles dist/runtime/brainmcp-hook-runtime.mjs, because init tests install that packaged hook runtime; nothing else in dist/ is needed. When running one test file directly, run node scripts/bundle-hook-runtime.mjs from packages/cli first.

From this repository, run corepack pnpm --filter @brainmcp/brainmcp test:package. It packs through the prepack build, then checks the extracted package in disposable project and home directories for all six hosts, including installed guidance, the bundled Skill renderer, hooks, repeat initialization, and removal. It does not install into your home or publish to npm. npm pack and source-directory publication both rebuild the bundled guidance through prepack; do not use --ignore-scripts to prepare a release.

Requirements

• Node.js 22+
• A brain account and workspace for OAuth
• A client version that supports remote HTTP MCP and browser OAuth

License

MIT