galaxybrain-mcp

MCP server for GalaxyBrain — an information operating system powered by local files. Lets AI agents read, write, search, and monitor your GalaxyBrain workspace.

• Website: https://galaxybrain.com
• About GalaxyBrain: https://galaxybrain.com/docs/galaxybrain/
• MCP documentation: https://galaxybrain.com/docs/mcp/
• API documentation: https://galaxybrain.com/docs/api/

Prerequisites

• Bun runtime installed
• GalaxyBrain open in a Chromium-based browser (Chrome or Edge)

Setup

Ask your AI assistant to install the GalaxyBrain MCP server (package: galaxybrain-mcp). Most AI tools can configure MCP servers automatically.

Or install manually. Add to your tool's MCP settings:

{
  "mcpServers": {
    "galaxybrain": {
      "command": "npx",
      "args": ["-y", "galaxybrain-mcp"]
    }
  }
}

Port override

{
  "mcpServers": {
    "galaxybrain": {
      "command": "npx",
      "args": ["-y", "galaxybrain-mcp"],
      "env": { "GB_API_PORT": "3000" }
    }
  }
}

If you override the port, also pass ?gb_port=3000 in the GalaxyBrain browser URL.

Tools

| Tool | Description | |------|-------------| | galaxybrain_status | Check connectivity and list connected browser tabs | | galaxybrain_project | List, open, and close projects | | galaxybrain_orient | Get a structural overview of the open project | | galaxybrain_read_pages | Read full page content by ID or by open tabs | | galaxybrain_query | Search and filter pages with sorting and pagination | | galaxybrain_traverse | Build recursive page-link trees (up or down) | | galaxybrain_write_pages | Create, update, or delete pages and templates | | galaxybrain_create_from_template | Create a page from a template | | galaxybrain_items | Push or pop items from specific blocks | | galaxybrain_workspace | Read or write the workspace tab layout | | galaxybrain_watch | Watch for real-time events with filtering and hooks | | galaxybrain_help | Look up detailed documentation on any topic | | galaxybrain_update | Warm the npx cache for galaxybrain-mcp@latest |

GalaxyBrain MCP

The GalaxyBrain MCP server lets AI agents read, write, search, and monitor your GalaxyBrain workspace. It connects tools like Claude Code, Cursor, and Windsurf to GalaxyBrain so an AI assistant can work with your pages, templates, and workspace layout.

Table of Contents

• Setup
• How It Works
• Tools Overview
  • galaxybrain_status
  • galaxybrain_project
  • galaxybrain_orient
  • galaxybrain_read_pages
  • galaxybrain_query
  • galaxybrain_traverse
  • galaxybrain_write_pages
  • galaxybrain_create_from_template
  • galaxybrain_items
  • galaxybrain_workspace
  • galaxybrain_watch
  • galaxybrain_help
  • galaxybrain_update
• Typical Workflow
• Data Model
  • Pages
  • Blocks
  • Items
  • Units
  • Templates
• Writing Content
  • Creating a Page
  • Updating a Page
  • Surgical Updates
  • Push and Pop
• Output Modes
• Instances
• Versions and Conflict Detection
• Event Watching
  • Event Types
  • Content Filters
  • Hooks
• Error Reference
• Troubleshooting
• Further Reading

Setup

Prerequisites

• Bun runtime installed
• GalaxyBrain open in a Chromium-based browser (Chrome or Edge) — either at app.galaxybrain.com or as a local offline .html file

Install

Ask your AI assistant to install the GalaxyBrain MCP server (package: galaxybrain-mcp). Most AI tools can configure MCP servers automatically.

Or install manually. Add to your tool's MCP settings:

{
  "mcpServers": {
    "galaxybrain": {
      "command": "npx",
      "args": ["-y", "galaxybrain-mcp"]
    }
  }
}

The MCP server starts a local API server automatically if one isn't already running. It communicates with GalaxyBrain browser tabs over a local WebSocket connection (default port 1924).

Port override

Set the GB_API_PORT environment variable to use a different port:

{
  "mcpServers": {
    "galaxybrain": {
      "command": "npx",
      "args": ["-y", "galaxybrain-mcp"],
      "env": { "GB_API_PORT": "3000" }
    }
  }
}

If you override the port, also pass ?gb_port=3000 in the GalaxyBrain browser URL so the app connects to the same server.

How It Works

AI Tool (Claude Code, Cursor, etc.)
  ↕  MCP protocol (stdio)
GalaxyBrain MCP Server
  ↕  WebSocket (localhost:1924)
GalaxyBrain API Server
  ↕  WebSocket
GalaxyBrain Browser Tab(s)

The MCP server is a thin translation layer. It receives tool calls from your AI assistant, converts them to WebSocket commands, sends them to the API server, and formats the responses. The API server routes commands to the correct browser tab where the actual data lives.

Multiple MCP server processes can connect simultaneously. The API server is started automatically if not already running. When the MCP session that spawned the API server exits, it terminates the API server. Other connected MCP sessions will automatically re-spawn it on their next command.

Version Checking

The MCP server performs two version checks:

1. Protocol compatibility — Before connecting to an API server, the MCP server checks the API server's protocol version (from the HTTP health check response "GalaxyBrain API Server/{version}"). If the versions don't match, it returns an error with instructions to stop the old server. This also applies after spawning a new API server, as a belt-and-suspenders check for npm dependency mismatches.

2. npm update check — On startup, the MCP server checks the npm registry for newer versions of galaxybrain-mcp. If an update is available, it logs a warning to stderr and prepends the update notice to galaxybrain_status, galaxybrain_orient, and galaxybrain_help responses. The raw galaxybrain_status output also exposes a structured mcp.updateState field so agents can detect the update programmatically and call galaxybrain_update to warm the npx cache.

Tools Overview

The MCP server provides 13 tools. AI agents discover basic parameters from tool schemas automatically, but some tools accept complex nested payloads (page bodies, operations, workspace layouts) that aren't fully described in the schema. Use galaxybrain_help to look up detailed schemas for these — topics like page_body, surgical_update, anchor_offset, and workspace cover the nested structures.

galaxybrain_status

Check whether the API server is running and list connected GalaxyBrain browser tabs. Shows each tab's state (picker, folder, or demo), what project is open, and connection details.

Use this first to confirm connectivity and see what's available.

Unlike other tools, the raw output of galaxybrain_status is MCP-enriched (not a pure pass-through of the API response). Two top-level blocks are injected:

• mcp — { version, updateState }. updateState is one of "checking", "up-to-date", "available", or "failed". When the state is "available", the block also includes latestKnown (the newer version) and updateAvailable: true.
• api — { protocolVersion, port }. The MCP ↔ API protocol version in use and the bound port.

Agents can gate offers of galaxybrain_update on mcp.updateAvailable === true.

galaxybrain_project

Manage the project lifecycle:

• list — list available folders (recent projects) and demos
• open_folder — open a folder-backed project by ID
• open_demo — open a demo project by name
• close — close the current project
• remove_folder — remove a folder from the recents list

A project must be open before most other tools will work.

galaxybrain_orient

Get a structural overview of the open project — how many pages and templates exist, the hub structure (pages organized by their link hierarchy), and which tabs are currently open in the workspace.

Call this after opening a project to understand what you're working with.

galaxybrain_read_pages

Read the full serialized content of specific pages or templates. You can select pages by ID or read all currently open tabs at once.

Control which fields are returned with boolean flags: icon, title, subtitle, blocks (all default to true). Set blocks: false for lightweight reads when you only need titles. Use blockIds to read specific blocks within a page.

Works with both regular pages (scope: "pages", the default) and templates (scope: "templates").

galaxybrain_query

Search and filter pages with text search, error search, references search, graph filters (which pages link to which), count filters (by outbound/inbound page link counts and inbound reference counts), field projection, sorting, and pagination.

Returns lightweight results — by default only kind and pageId. Use the fields parameter to include additional data like title, subtitle, blocks, counts, vars, timestamps, and link information. Use galaxybrain_read_pages to get full serialized content.

Supports sorting by title, timestamps, link counts, and transitive page reach. Graph filters let you find pages that link to or are reachable from specific pages. Call galaxybrain_help("query") for full filter documentation.

References search — search: { references: <target>, sections?: ["subtitle","blocks"] } finds structural references to a single target across subtitles, block items, var formulas, and block linkOrder keys. Targets:

• { imageId: "<64hex>" } or { imageId: "<64hex>.<ext>" } — image items only
• { varName: "...", prefix?: true } — var defs + V refs + PLCV refs + linkOrder keys (V refs use live name lookup, so renames change which refs match; prefix: true enables trailing-* match)
• { metaRef: { head, pageId?, blockId?, varId?, type?, derivation?, varName?, format? } } — head must be "CT", "CA", "UA", "V", "PLCV", or "M"; only fields valid for that head are accepted
• { pageLink: { pageId } } — both standalone page link items and inline pageLink units
• { webLinkUrl: "..." } — exact URL match on webLink units

Mutually exclusive with text and errors variants. matchCount counts structural occurrences (one per matching unit/item/linkOrder key).

galaxybrain_traverse

Build a recursive page-link tree starting from a root page:

• down (MAP) — what does this page link to, and what do those pages link to? limits is optional (null for auto, [] for leaf).
• up (ANCESTORS) — what pages link to this page, and what links to them? limits is required (e.g. [10, 5, 3] for per-layer budgets).

Optionally include subtitle text and block text previews.

galaxybrain_write_pages

Create, update, or delete pages or templates:

• create — create new pages from a full page body
• update — replace or surgically modify existing pages
• delete — delete pages by ID

Supports surgical updates (modify specific blocks without replacing everything) and image uploads via a base64 image map. See Writing Content for details.

galaxybrain_create_from_template

Create a new page from a template. The template's content is cloned with template values automatically resolved:

• nextNumber — increments based on existing page links in the source block
• nextDay — advances one day from the most recent date in neighboring links
• dateToday — current date

A page link to the newly created page is inserted into the specified source block.

galaxybrain_items

Push (insert) or pop (remove) items from specific blocks. More precise than updating an entire page — useful for appending a task to a list, inserting a page link, or removing items.

Position is controlled by anchor (top or bottom) and offset. See Push and Pop.

galaxybrain_workspace

Read or write the workspace tab layout — which tabs are open, their widths, scroll positions, and navigation paths.

Supports optimistic concurrency via readVersion to prevent conflicting writes.

galaxybrain_watch

Start watching for real-time events. Returns a shell command to run with your AI tool's process monitoring feature (e.g., Claude Code's Monitor tool). Each matching event produces a notification that wakes the agent.

Supports event-type filters, content-derived filters (detect checkbox changes, variable value changes, page link additions, etc.), and hooks for custom pre-output logic. See Event Watching.

galaxybrain_update

Warm the npx cache for galaxybrain-mcp@latest so the next MCP host restart picks up the new version. Input schema is empty — no parameters.

Check galaxybrain_status.mcp.updateAvailable first; offer this tool when it is true. On success, the tool returns a message like Updated galaxybrain-mcp: v0.6.0 → v0.7.0. Restart your MCP host .... If the running version already matches the registry, it returns galaxybrain-mcp is already current at v<version>. No restart needed.

This tool is a no-op for non-npx installs (local dist/, globally-installed package). In that case the user must update manually. Process timeout is 120 seconds; on timeout or non-zero exit, the tool returns an error message with a trimmed stderr snippet.

galaxybrain_help

Look up detailed documentation on a specific topic, directly within a tool call. Available topics:

| Topic | Description | |-------|-------------| | commands | Overview of all tools and workflow guidance | | query | Search filters, fields, sorting, pagination | | meta_refs | Meta reference format strings (CT, CA, UA, V, PLCV, M) | | styles | Text item style values | | link_order | Link order format, direction, sort keys | | units | Unit types, fields, and context restrictions | | images | Image ID format, images map, imageId vs imageFile | | versions | Page versions, workspace version, readVersion, snapshotSeq | | instances | Instance states, routing | | templates | Template pages, template value types, creation | | workspace | Workspace layout, tabs, paths, validation rules | | anchor_offset | Push/pop anchor and offset semantics | | page_body | Full page body schema | | surgical_update | Surgical update fields and behavior | | read_shapes | Serialized page/block/item/unit schemas from read commands | | watch | Watch system: events, content filters, hooks, examples | | errors | Common error codes and their meanings | | troubleshooting | Version mismatches, updating, common errors, npx caching | | docs | Links to full online documentation |

This is the go-to tool when you need precise schema details or parameter documentation during a session.

Typical Workflow

1. galaxybrain_status        →  check connectivity, see open instances
2. galaxybrain_orient        →  understand the project structure
3. galaxybrain_read_pages    →  read content
   galaxybrain_query         →  search and filter
   galaxybrain_traverse      →  explore link structure
4. galaxybrain_write_pages   →  create/update/delete pages
   galaxybrain_items         →  insert/remove items
   galaxybrain_create_from_template  →  create from template

If no project is open, use galaxybrain_project to list and open one first. Most of the time, a project is already open in the browser.

Data Model

GalaxyBrain organizes content in a hierarchy: Pages → Blocks → Items → Units.

Pages

A page is the primary document unit. Every page has:

| Field | Description | |-------|-------------| | pageId | 20-character alphanumeric ID (e.g. AbcDef1234567890GhIj) | | icon | Single emoji | | title | Array of title units (text and template values only) | | subtitle | Array of units (all types) | | blocks | Array of blocks |

Pages also have read-only fields: blockOrder, createdAt, updatedAt, templateValues, and counts.

Blocks

A block is a container within a page that holds items. Blocks have:

| Field | Description | |-------|-------------| | blockId | Non-negative integer, unique within the page | | items | Non-empty array of items | | linkOrder | Optional sort rule for page-link items (e.g. A.M.tt for title A-Z) |

Items

An item is a single piece of content within a block. There are four item types:

| Type | Description | |------|-------------| | text | Styled text content. Has a style (body, heading, bullet, checkbox, ordered list) and content (array of units). | | var | A named variable with a formula that evaluates to a value. | | image | An image, referenced by content-addressed ID. | | pageLink | A standalone link to another page. |

Text item styles:

| Style | Meaning | |-------|---------| | "" | Body text | | "#" | Heading 1 | | "##" | Heading 2 | | "###" | Heading 3 | | "*" | Bullet list | | "[ ]" | Unchecked checkbox | | "[X]" | Checked checkbox | | "ol" | Ordered list |

Text items also support indentLevel (0-8) for nesting.

Units

Units are the atomic content pieces within text items, subtitles, and formulas:

| Type | Description | |------|-------------| | text | Plain or styled text (unitStyle: bold, italic, boldItalic) | | webLink | Hyperlink with display text and URL | | pageLink | Inline reference to another page | | metaRef | Live computed value (timestamps, word counts, variable values, etc.) | | templateValue | Placeholder resolved when creating from a template |

Context restrictions: Titles only allow unstyled text and templateValue units. Formulas only allow text, metaRef, and templateValue. Subtitles and text item content allow all types.

Templates

Templates are special pages that serve as blueprints. They use the same structure as regular pages but can contain templateValue units that are resolved when a new page is created from the template. Access templates by passing scope: "templates" to read, write, and items tools.

Writing Content

Creating a Page

Pass a full page body to galaxybrain_write_pages with action: "create":

{
  "action": "create",
  "pages": [{
    "icon": "📝",
    "title": [{ "type": "text", "text": "My Page" }],
    "subtitle": [],
    "blocks": [{
      "blockId": 0,
      "items": [
        {
          "type": "text",
          "style": "",
          "content": [{ "type": "text", "text": "Hello world" }]
        }
      ]
    }]
  }]
}

Pass null in the pages array to create a default blank page.

Updating a Page

For a full replacement, pass the complete page body with a pageId:

{
  "action": "update",
  "pages": [{
    "pageId": "AbcDef1234567890GhIj",
    "icon": "🔥",
    "title": [{ "type": "text", "text": "Updated Title" }],
    "subtitle": [],
    "blocks": [{
      "blockId": 0,
      "items": [{
        "type": "text",
        "style": "",
        "content": [{ "type": "text", "text": "New content" }]
      }]
    }]
  }]
}

Surgical Updates

Modify specific blocks without replacing the entire page. Use updateBlocks, insertBlocks, deleteBlockIds, and blockOrder instead of blocks:

{
  "action": "update",
  "pages": [{
    "pageId": "AbcDef1234567890GhIj",
    "title": [{ "type": "text", "text": "New Title" }],
    "updateBlocks": [{
      "blockId": 0,
      "items": [{
        "type": "text",
        "style": "[X]",
        "content": [{ "type": "text", "text": "Done!" }]
      }]
    }],
    "insertBlocks": [{
      "blockId": 5,
      "items": [{
        "type": "text",
        "style": "",
        "content": [{ "type": "text", "text": "A new block" }]
      }]
    }],
    "deleteBlockIds": [2, 3]
  }]
}

blocks (full replacement) and surgical fields are mutually exclusive.

Push and Pop

Use galaxybrain_items for targeted insertions and removals:

Push — insert items into a block at a specific position:

{
  "action": "push",
  "operations": [{
    "pageId": "AbcDef1234567890GhIj",
    "blockId": 0,
    "anchor": "bottom",
    "offset": 0,
    "items": [{
      "type": "text",
      "style": "[ ]",
      "content": [{ "type": "text", "text": "New task" }]
    }]
  }]
}

Pop — remove items from a block:

{
  "action": "pop",
  "operations": [{
    "pageId": "AbcDef1234567890GhIj",
    "blockId": 0,
    "anchor": "bottom",
    "offset": 0,
    "count": 1
  }]
}

Position reference:

• anchor: "top", offset: 0 — beginning of the block
• anchor: "bottom", offset: 0 — end of the block
• anchor: "top", offset: 2 — after the second item
• anchor: "bottom", offset: 1 — before the last item

Batch Semantics

Create, update, delete, push, and pop all accept arrays. Each entry succeeds or fails independently — one failure does not roll back others. Responses include a results array aligned to input order.

Note: if the entire payload is malformed (e.g. missing required fields, wrong types), the command fails with a top-level PARSE_ERROR before any entries are processed.

Normalization

Written content is normalized automatically:

• Adjacent compatible text and web-link units are merged.
• A lone pageLink unit inside an unstyled text item is promoted to a standalone pageLink item.
• Content may look different on read than what was written — this is expected.

Output Modes

Most tools accept an outputMode parameter:

| Mode | Description | |------|-------------| | summary | Human-readable formatted text | | raw | Full JSON response from the API | | full | Summary text with raw JSON appended |

Defaults by tool:

• summary: galaxybrain_status, galaxybrain_orient, galaxybrain_query, galaxybrain_traverse
• full: galaxybrain_read_pages, galaxybrain_write_pages, galaxybrain_create_from_template, galaxybrain_items, galaxybrain_workspace, galaxybrain_project

The galaxybrain_help and galaxybrain_watch tools do not use output modes.

Instances

A GalaxyBrain instance is a browser tab connected to the API server. Instances can be in one of three states:

| State | Description | |-------|-------------| | picker | No project is open | | folder | A folder-backed project is open | | demo | A demo project is open |

Routing rules:

• One instance connected — the instance parameter is optional; commands are auto-routed.
• Multiple instances — instance is required. Use galaxybrain_status to see available instances.
• No instances — commands fail with a NO_INSTANCES error. Open GalaxyBrain in a browser.

Versions and Conflict Detection

Each page has an independent integer version that increments on every mutation. You receive it from read and write responses.

To prevent concurrent writes from colliding, pass readVersion alongside the mutation:

• Match — mutation proceeds.
• Mismatch — CONFLICT error. Re-read the page and retry.
• Omitted — conflict check is skipped.

Where readVersion goes depends on the command:

• Page updates — inside each page update object in the pages array (e.g. { "pageId": "...", "readVersion": 3, ... })
• Push/pop operations — inside each operation object in the operations array
• Workspace writes — top-level readVersion parameter on galaxybrain_workspace
• Create and delete — do not use readVersion

The workspace has its own independent version with the same semantics.

Event Watching

The galaxybrain_watch tool sets up real-time event monitoring. It returns a shell command that you run with your AI tool's process monitor (e.g., Claude Code's Monitor tool). Each matching event prints a line to stdout, which becomes a notification that wakes the agent.

Event Types

Page events:

| Event | Description | Filters | |-------|-------------|---------| | pages_created | Pages were created | templateId, titlePattern | | pages_deleted | Pages were deleted | — | | pages_updated | Page content changed | pageIds, scope, role, source |

Workspace events:

| Event | Description | Filters | |-------|-------------|---------| | workspace_tab_opened | A tab was opened | pageId | | workspace_tab_closed | A tab was closed | pageId | | workspace_tab_navigated | A tab changed pages | newPageId | | workspace_tab_resized | A tab was resized | — | | workspace_scrolled | Workspace was scrolled | pageId | | workspace_changed | Layout changed structurally | — |

Project and system events:

| Event | Description | |-------|-------------| | project_opened | A project was opened | | project_closed | A project was closed | | concurrent_access_detected | Concurrent file access detected |

File events:

| Event | Description | |-------|-------------| | files_changed | Filesystem change inside a watched folder |

Global source filter: Use source: ["user", "api", "system"] to limit which event sources pass through. The pages_updated event can override this with its own per-event source filter.

File Watching

File watching lets you drive agents off filesystem activity inside your GalaxyBrain project folder, not just app-internal mutations. It's a thin wrapper around Chromium's FileSystemObserver, exposed through the same galaxybrain_watch monitor.

Typical uses:

• Inbox processing. Drop a PDF into inbox/, have the agent OCR it, write a page, move the file to inbox/processed/.
• External edit sync. Watch a subfolder you also edit outside GalaxyBrain and reconcile changes back into pages.
• Attachment pipelines. React when images, audio, or exports land in a known drop folder — transcribe voice memos, tag screenshots, thumbnail photos.
• Cleanup / audit. Alert on unexpected deletions or moves inside critical folders.

Pass files_subscriptions to galaxybrain_watch to start one or more folder watches when the monitor connects. Each entry fires a FILES_WATCH against the open instance before the monitor subscribes to the event stream:

{
  "files_subscriptions": [
    { "subpath": "inbox", "recursive": true }
  ]
}

subpath is forward-slash-delimited and must resolve to an existing directory under the project root. Leading /, backslashes, Windows-absolute paths, .., ., and empty segments are rejected. recursive defaults to false — without it you only see direct children of the folder.

Each change produces one files_changed stdout line carrying subscriptionId, subpath, recursive, changeType, path (array, relative to subpath), and movedFrom (array on moved, null otherwise). Change types mirror the platform API:

| changeType | Meaning | |---|---| | appeared | A file or directory was created or moved into the watched subtree. | | disappeared | A file or directory was removed from the watched subtree. | | modified | A file's contents or metadata changed. | | moved | A file or directory was renamed within the same directory. movedFrom carries the previous path. | | unknown | The OS dropped events — state may have diverged; rescan if correctness matters. | | errored | The observation is dead. GalaxyBrain removes the subscription automatically; issue files_subscriptions again on the next monitor run. |

Use files_change_types to narrow the stream to the records you care about:

{
  "files_subscriptions": [{ "subpath": "inbox", "recursive": true }],
  "files_change_types": ["appeared", "moved"]
}

File watches fail with specific wire errors you may need to handle:

• FOLDER_UNAVAILABLE — the open project is a demo / in-memory, so there's no real folder to observe.
• UNSUPPORTED_BROWSER — the browser doesn't expose FileSystemObserver (currently Chromium-only).
• FOLDER_NOT_FOUND — the subpath doesn't resolve to an existing directory under the project root.
• NO_PROJECT — no project is open.

Lifetime: Subscriptions live on the GalaxyBrain instance (the open browser tab), not on the MCP monitor. The monitor performs best-effort FILES_UNWATCH on graceful exit and on reconnect (so duplicates don't accumulate). A hard kill leaves watches running on the instance until the project is closed, the folder is switched, the app is reloaded, or Chrome emits an errored record.

Built-in filter: files_changed events whose last path segment is .DS_Store are dropped before emission — macOS metadata noise is never forwarded to the agent.

Other sharp edges:

• Windows reports cross-directory moves as a disappeared + appeared pair rather than a single moved record.
• File events are not file-readiness events. A large file copy produces appeared (and possibly modified) before the writer has finished — use temp-then-rename or wait for size/mtime stability.
• Per-origin observation limit is OS-dependent and surfaces as errored.

Content Filters

Content filters detect specific changes within pages_updated events by comparing before/after state. They fire when a relevant count or value changes. At least one event subscription or content filter must be specified when calling galaxybrain_watch.

Each content filter is an object with a required type field and optional scoping fields.

Block-level filters (support pageIds and blockId scoping):

| Filter | What it detects | Extra fields | |--------|-----------------|-------------| | block_changed | Any modification to a block's content | — | | checkbox_count_changed | Total checkbox count changed | — | | checked_count_changed | Checked checkbox count changed | — | | image_count_changed | Image item count changed | — | | page_link_item_count_changed | Standalone page link count changed | targetPageId (optional) | | item_style_changed | Text item style changed | — | | web_link_unit_added | Web link unit added | — | | web_link_unit_removed | Web link unit removed | — | | meta_ref_unit_added | Meta reference unit added | — | | meta_ref_unit_removed | Meta reference unit removed | — |

Page-level filters (support pageIds scoping):

| Filter | What it detects | Extra fields | |--------|-----------------|-------------| | page_link_unit_added | Inline page link unit added | targetPageId (optional) | | page_link_unit_removed | Inline page link unit removed | targetPageId (optional) | | var_value_changed | Variable value changed | pageId (required), varId (optional) | | var_added | Variable item added | — | | var_removed | Variable item removed | — | | title_changed | Page title changed | — | | subtitle_changed | Page subtitle changed | — | | icon_changed | Page icon changed | — | | block_created | A new block was created | — | | block_deleted | A block was deleted | — |

Content filter output includes full before/after data by default. Set include_diffs: false to reduce token usage and only receive change metadata.

Hooks

Hooks are optional JavaScript/TypeScript modules that run on each matched event before it reaches the agent. They can perform side effects (API calls), suppress events (return false), or replace the output with a custom message (return a string).

// update-subtitle-hook.ts
export default async function(match, context) {
  if (match.output.filter === "checked_count_changed"
      && match.output.afterChecked > match.output.beforeChecked) {
    // Perform a side effect
    await context.sendCommand("UPDATE_PAGES", {
      pages: [{
        pageId: match.output.pageId,
        subtitle: [{ type: "text", text: "Processing..." }]
      }]
    });
  }
  // Return nothing to let the event through to the agent
}

Return values:

• undefined — event passes through normally
• false — event is suppressed (agent is not woken)
• string — replaces the default output (agent sees your string)

Important: When your hook sends API commands, use source: ["user"] in your filter spec to prevent infinite loops. Commands sent via context.sendCommand have source "api", so they won't re-trigger filters restricted to "user".

Use hook_debug: true for verbose tracing of all hook calls.

Error Reference

Routing errors (returned when the command can't reach an instance):

| Code | Meaning | |------|---------| | NO_INSTANCES | No GalaxyBrain browser tabs connected | | INSTANCE_REQUIRED | Multiple tabs connected; specify instance | | UNKNOWN_INSTANCE | Specified instance ID not found |

Command errors (returned in responses):

| Code | Meaning | |------|---------| | NO_PROJECT | Command requires an open project | | CONFLICT | readVersion mismatch — re-read and retry | | PARSE_ERROR | Invalid payload shape or field types | | PAGE_NOT_FOUND | Page or template does not exist | | TEMPLATE_PAGE | Regular-page command sent to a template | | NOT_TEMPLATE_PAGE | Template command sent to a regular page | | LAST_PAGE | Cannot delete the last remaining page | | NO_REMAINING_ITEMS | Pop would remove every item from a block | | SELF_LINK | Page link points to the page being written | | PERMISSION_REQUIRED | Browser requires user gesture before folder can be opened | | BLOCK_NOT_FOUND | Block ID doesn't exist (surgical update) | | BLOCK_ALREADY_EXISTS | Inserted block ID already exists (surgical update) | | NO_UPDATES | Surgical update contained no actual changes | | DUPLICATE_BLOCK_OP | Same block appears in multiple surgical operations | | BLOCK_ORDER_MISMATCH | blockOrder doesn't match the final block set | | UNEXPECTED_ITEM_TYPE | Pop expectedItemType doesn't match items in range | | INVALID_TEMPLATE_ID | Template ID doesn't exist (create from template) | | NO_ITEMS | Empty items array in a block or push operation | | DUPLICATE_VAR_ID | Duplicate variable ID within a page |

Troubleshooting

Prerequisites

GalaxyBrain MCP requires Bun. Install:

• macOS/Linux: curl -fsSL https://bun.sh/install | bash
• Windows: powershell -c "irm bun.sh/install.ps1 | iex"

After installing, fully quit your MCP host and relaunch it from a fresh terminal where bun --version works — the host inherits PATH from the terminal that launched it, not from ~/.zshrc or ~/.bashrc.

If Bun is installed at an unusual path, set GB_BUN_PATH to its absolute path in the host's environment.

Recommended Setup

Configure your MCP client with:

{
  "command": "npx",
  "args": ["-y", "galaxybrain-mcp"]
}

The -y flag auto-confirms the install prompt. Without it, npx may hang waiting for confirmation since MCP servers have no interactive terminal.

Updating

The MCP server checks for updates on startup and re-checks lazily during long sessions. When an update is available, the notice is prepended to galaxybrain_status, galaxybrain_orient, and galaxybrain_help output; agents can also detect it programmatically via galaxybrain_status raw output (mcp.updateAvailable === true).

Agents should prefer calling galaxybrain_update — it warms the npx cache without requiring the user to drop to a shell. After it reports success, the user must restart their MCP host for the new version to take effect. The shell equivalent is:

npx -y galaxybrain-mcp@latest

To update the API server:

npx -y galaxybrain-api@latest

If an old API server is still running, stop it first:

lsof -ti :1924 | xargs kill

npx Caching

npx caches packages locally. Running npx -y galaxybrain-mcp uses the cached version without checking for updates — this keeps startup fast. To force an update, run npx -y galaxybrain-mcp@latest once. Subsequent runs use the updated cache.

Do not use @latest in your MCP client configuration — it causes a network request to the npm registry on every startup, adding latency.

Version Mismatches

The browser app, API server, and MCP server share a protocol version. When versions don't match:

• MCP ↔ API server — The MCP server checks protocol compatibility before connecting. Incompatible versions produce a clear error with update instructions.
• Browser app ↔ API server — The app checks on WebSocket connect. Incompatible versions show a warning toast with update instructions.

Common Errors

| Error | Cause | Fix | |-------|-------|-----| | GalaxyBrain MCP requires Bun | Bun not installed or not findable from the MCP host's PATH | Install Bun (see Prerequisites above); if already installed, relaunch the host from a terminal where bun --version works | | env: bun: No such file or directory | Host launched from a shell without Bun on PATH | Quit the host, open a fresh terminal where bun --version works, relaunch the host from there | | "incompatible version" | MCP/API protocol versions don't match | Update both: npx -y galaxybrain-api@latest and npx -y galaxybrain-mcp@latest | | "Port in use by another process" | Non-GalaxyBrain process on port 1924 | Stop it: lsof -ti :1924 \| xargs kill | | "No GalaxyBrain browser tabs connected" | No browser tab connected to the API server | Open GalaxyBrain in Chrome, or check for version mismatch | | "No project is open" | Browser tab is on the folder picker | Open a folder or demo via galaxybrain_project |

Further Reading

• GalaxyBrain API docs — full WebSocket API reference with transport details, data model schemas, and all command specifications.
• galaxybrain_help tool — call it from your AI tool for detailed, contextual documentation on any topic during a session.