SynaBun Documentation

Overview #

SynaBun is an open-source, self-hosted AI workspace and persistent memory MCP server: SynaBun Assistant coordinates Claude Code, Codex and OpenCode agents. Any MCP-compatible AI tool — Claude Code, Codex, Gemini, OpenCode, Cursor, Windsurf, or any other — can connect and retain knowledge across sessions. Everything comes together in SynApp, the workspace the app also calls the Neural Interface. Dedicated sidepanels ship for Claude Code, Codex, and OpenCode, and the SynaBun Assistant sits on top of them as a memory-aware orchestrator that dispatches work to those three CLIs.

Memories are stored in a single local SQLite database with keyword indexes and locally generated vector embeddings. recall uses hybrid retrieval — SQLite FTS5 keyword search, document embeddings and passage refinement, combined with reciprocal rank fusion — so it finds the right memory whether you remember an exact identifier or only the idea behind it.

Key Capabilities #

• 158 MCP tools — memory (8), loop (1), profile (1), choice (1), browser automation (46: 21 general tools incl. browser_batch, browser_console and browser_cheatsheet, plus 25 platform tools), BlueSky (15), Google Search Console (30), YouTube (11), SynaBun Assistant orchestration (12 agent_* tools plus whatsapp_send_file), computer use (4), Leonardo AI (5), whiteboard (5), cards (5), discord (8), git (1), image (1), style guide (1), MoreLogin (1), tictactoe (1)
• 500+ REST API endpoints — full HTTP API for external integrations and the Neural Interface
• SynaBun Assistant — a central orchestrator that thinks with a brain you pick (Claude Code, Codex, or OpenCode), recalls memories on every turn, and dispatches autonomous workers with model routing, clarification briefs, budgets, and token accounting. See SynaBun Assistant.
• Memory v2 engine — hybrid retrieval (FTS5 + embeddings + passage refinement), compact budgeted recall, revision history with undo, idempotent writes, and reversible maintenance. See Memory v2 Engine.
• Computer use (macOS) — the Assistant can operate your Mac through screenshots, mouse, keyboard, apps, and the accessibility tree, bounded by always-on guards and stop controls
• 3 dedicated sidepanels — Claude Code, Codex, and OpenCode with tool activity docks, per-agent abort, permission cards, TODO drawer, context gauge, session menu, new-session modal (project + branch picker), and Multi-CLI Resume with provider picker
• Automation Studio — user-created collapsible folders, per-template launch defaults (CLI / Model / Effort / MCP profile), first-class 4-CLI support (Claude Code, Codex, Gemini, OpenCode)
• Universal MCP Management — smart-paste add form (auto-detects 5 config formats), multi-platform sync across Claude Code / Codex / Gemini / OpenCode, centralized env vault with sensitive-value masking, auto profile registration, and one-click install from GitHub
• Recall Profile Presets — Quick / Balanced / Deep / Custom with 6 fine-tune controls and a live impact indicator (tokens/recall, memories reachable, session context)
• Claude Code hooks — 10 hook scripts with 11 registrations across 9 lifecycle events for automated recall, memory capture, subagent briefing, and context management
• SynaBun Rules — a short ruleset installed and kept up to date automatically for Claude Code, Codex, Gemini, and OpenCode when you connect a tool
• Style Guide — a per-project brand and design system written as DESIGN.md plus design tokens, handed to every agent through the style_guide tool
• Local embeddings — Transformers.js (all-MiniLM-L6-v2, 384 dimensions) with zero configuration; embedding inference never sends memory text to a cloud provider
• AI decisions (optional) — typed judgments from Jev (TypeSafe) replace regex heuristics for duplicates, relevance, staleness, and more; every surface falls back to a local heuristic when it is off
• WhatsApp Link — chat with the Assistant from your phone as a linked device, with permission levels enforced on your computer
• 3D Neural Interface — a memory map of your whole store at localhost:3344
• Multi-project support — memories are tagged by project, searchable across all or filtered per-project
• Hierarchical categories — parent/child category system with dynamic schema
• Modern code rendering — syntax highlighting, file path linkification, language labels, hover-only copy buttons, 30 fps throttled streaming, real-time thinking-block streaming
• Self-hosted, local-first — the database, embeddings, and retrieval all run on your machine

How It Works #

When your AI assistant calls remember, SynaBun embeds the content locally with Transformers.js (all-MiniLM-L6-v2, 384 dimensions) and writes it to SQLite with its metadata (category, project, importance, tags, kind, related files) and a first revision. Long documents are also split into source passages, so evidence late in a document stays findable.

When it calls recall, keyword search (SQLite FTS5) and document embeddings each nominate candidates, passage refinement sharpens them, and reciprocal rank fusion combines the rankings. Ranking scores are relevance signals, not confidence probabilities. An explicit project filter never widens to other projects, and format: "compact" returns budgeted excerpts instead of full memories. See Memory v2 Engine.

Quick Start #

Prerequisites #

• Node.js 22.5+ — for the MCP server, the SQLite database (via built-in node:sqlite), and the Neural Interface
• No API keys, no Docker — embeddings run locally via Transformers.js and the database is a single file
• Optional build tools — the embedded terminal uses node-pty, a native addon. Without build tools npm install warns and continues; everything else works. Install them with xcode-select --install (macOS), sudo apt install build-essential python3 (Linux), or VS Build Tools 2022 with "Desktop development with C++" (Windows).

Installation #

# Clone the repository
git clone --depth=1 https://github.com/danilokhury/Synabun.git
cd Synabun

# Start everything (installs deps, builds MCP, launches Neural Interface)
npm start

# Install globally via npm
npm install -g synabun

# Launch (installs deps, builds MCP, opens onboarding wizard)
synabun

What npm start does #

npm start and the synabun command run the same setup script:

1. Checks the data home (~/.synabun by default) and, for installs that kept their state inside the checkout, migrates it before anything else starts
2. Checks the Node.js version and installs dependencies for the Neural Interface and the MCP server
3. Installs the Playwright Chromium browser used for browser automation
4. Builds the MCP server (stdio and HTTP transports, compatible with all MCP clients)
5. Repairs existing SynaBun registrations in your AI tools so they point at the current build
6. Starts the Neural Interface on port 3344 and opens it in your browser — the onboarding wizard on first run

The SQLite database is created at ~/.synabun/mcp-data/memory.db, and the local embedding model (Xenova/all-MiniLM-L6-v2, about 90 MB of ONNX weights) is downloaded once and cached.

Connect to Claude Code #

The onboarding wizard and Settings → AI connections register SynaBun with Claude Code, Codex, Gemini, and OpenCode, and install the SynaBun Rules for each tool you connect. To register by hand, add SynaBun to your project's .mcp.json:

// .mcp.json
{
  "mcpServers": {
    "SynaBun": {
      "command": "node",
      "args": ["/path/to/Synabun/mcp-server/run.mjs"]
    }
  }
}

Or register it globally for all projects:

claude mcp add SynaBun node "/path/to/Synabun/mcp-server/run.mjs" -s user

Verify Installation #

# Check database exists
ls ~/.synabun/mcp-data/memory.db

# Inspect database, migration, client-registration, and backup health
synabun doctor

# Check Neural Interface API
curl http://localhost:3344/api/stats

# Open Neural Interface in browser
open http://localhost:3344

In Claude Code, restart and run /mcp — the SynaBun server should be listed with its tools. From a git checkout, run CLI subcommands as npm start -- doctor. See CLI Commands.

Architecture #

SynaBun follows a layered architecture: your AI assistant communicates via MCP, the MCP server handles tool dispatch, embeddings are generated locally, and memories are stored and searched in SQLite. Everything runs on your machine — no external services, no Docker, no API keys.

┌─────────────────────────────────────────────────────────────┐
│                     AI ASSISTANT                            │
│    (Claude Code, Codex, Gemini, OpenCode, Cursor, ...)      │
└───────────────────────┬─────────────────────────────────────┘
                        │  Model Context Protocol (stdio or HTTP)
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                  SYNABUN MCP SERVER                         │
│                                                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │ remember │  │  recall  │  │ reflect  │  │  forget  │     │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │ restore  │  │ memories │  │   sync   │  │ category │     │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘     │
│  + loop, profile, choice and 21 switchable tool groups      │
└─────────────┬───────────────────────┬───────────────────────┘
              │                       │
              ▼                       ▼
┌─────────────────────┐  ┌───────────────────────────────────┐
│  LOCAL EMBEDDINGS   │  │  SQLITE                           │
│                     │  │  ~/.synabun/mcp-data/memory.db    │
│  • Transformers.js  │  │                                   │
│  • all-MiniLM-L6-v2 │  │  Memories + revision history      │
│  • 384 dimensions   │  │  FTS5 keyword index               │
│  • Isolated worker  │  │  Vectors as Float32 BLOBs         │
│    process          │  │  Session evidence, trash          │
└─────────────────────┘  └───────────────────────────────────┘
                                        │
                                        ▼
                        ┌───────────────────────────────────┐
                        │    NEURAL INTERFACE               │
                        │    (Express REST API + 3D UI)     │
                        │    localhost:3344                 │
                        └───────────────────────────────────┘

Data Flow #

Writing a memory: AI calls remember(content, category, project) → well-known credential formats in the text are redacted → the content is embedded locally → the memory, its metadata, and its first revision are written to SQLite → the full UUID is returned.

Reading memories: AI calls recall(query) → FTS5 keyword search and embedding search each nominate candidates → passage refinement compares the best parent documents passage by passage → reciprocal rank fusion merges the rankings → results come back as full memories or as compact, token-budgeted excerpts.

Neural Interface: Browser connects to the Express REST API on port 3344 → loads memories → renders the 3D memory map with Three.js → allows search, trash, restore, backup, and sync operations.

Hybrid Retrieval #

Recall is no longer a single similarity score. The Memory v2 engine combines several signals:

• Keyword channel — SQLite FTS5 finds exact identifiers and evidence late in long documents
• Embedding channel — document vectors from the local MiniLM model find memories by meaning
• Passage refinement — up to 50 candidates per channel nominate at most 100 parent documents, whose passages are then compared. It refines candidates; it is not an exhaustive scan of every passage.
• Reciprocal rank fusion — merges the rankings into one list. min_score gates raw cosine similarity or keyword coverage before fusion.
• Fallback — if the embedding model is missing or fails, keyword recall stays available and new memories are saved with semantic indexing pending

Without a project filter, recall searches every project and boosts the current one; recency_boost shifts ranking toward recent memories (14-day half-life, 55% recency weight). The pre-2.0 retrieval path remains as a rollback: set SYNABUN_MEMORY_ENGINE=legacy for the server and restart it.

MCP Tools #

SynaBun exposes 158 tools via the Model Context Protocol. Eleven are always on — remember, recall, reflect, forget, restore, memories, category, sync, loop, profile, and choice — and the other 147 live in 21 tool groups that tool profiles switch on and off. The memory tools below are the core of the system; every other group is documented in its own section.

Tool Groups #

The remaining tools are grouped. A profile decides which groups a runtime sees; two groups are gated by who is calling instead of by profile.

remember #

Store a memory with content, category, project, and optional metadata. Returns the full UUID of the created memory.

// Store a bug fix
remember({
  content: "Fixed race condition in auth middleware by adding mutex lock around token refresh logic. Root cause was concurrent requests hitting the token expiry check simultaneously.",
  category: "bug-fixes",
  project: "my-app",
  importance: 8,
  tags: ["auth", "race-condition", "middleware"],
  kind: "issue",
  source: "self-discovered",
  related_files: ["src/middleware/auth.ts"],
  idempotency_key: "fix:auth-race"
})

category and project are required on every call. kind is one of note (default), decision, issue, preference, fact, or session. The source field accepts user-told, self-discovered, or auto-saved. Importance ranges from 1 (trivial) to 10 (foundational) and defaults to 5.

idempotency_key makes retries safe: within a project and category, the same key and content returns the existing UUID instead of writing a copy. source_ref records a session or event identifier. Well-known credential formats (API keys, tokens, private-key blocks) are redacted before the memory is embedded and stored.

recall #

Search stored memories with hybrid retrieval. It finds relevant memories by meaning even when the words don't match, and by exact keyword when they do.

// Compact, budgeted discovery with filters
recall({
  query: "authentication issues token refresh",
  project: "my-app",
  tags: ["auth", "middleware"],
  tag_match: "all",
  after: "2026-09-01T00:00:00Z",
  format: "compact",
  token_budget: 1500,
  explain: true
})

All filter parameters are optional. Omitting project searches across everything, with a boost for the current project. Prefer format: "compact" for discovery, then fetch full originals with memories action get or get-batch.

reflect #

Update an existing memory. Provide only the fields you want to change. If content is updated, the embedding vector is regenerated automatically.

// Update importance and add a tag, only if nothing changed since revision 3
reflect({
  memory_id: "8f7cab3b-644e-4cea-8662-de0ca695bdf2",
  importance: 9,
  add_tags: ["critical"],
  subcategory: "auth",
  expected_revision: 3
})

// Mark this memory as the replacement for an older one
reflect({
  memory_id: "8f7cab3b-644e-4cea-8662-de0ca695bdf2",
  supersedes: "2c1d7e90-5b1a-4f6e-9a3c-7d2e8f4b6a10"
})

expected_revision rejects the update if the memory changed since that revision. supersedes explicitly links this memory as the replacement for another live memory in the same project; cycles are rejected, and a superseded memory is left out of current-state recall.

forget / restore #

forget moves a memory to trash (soft delete). restore brings it back. Trashed memories can also be managed from the Neural Interface trash panel.

// Soft-delete
forget({ memory_id: "8f7cab3b-644e-4cea-8662-de0ca695bdf2" })

// Restore from trash
restore({ memory_id: "8f7cab3b-644e-4cea-8662-de0ca695bdf2" })

memories #

Browse memories, fetch one in full, review revisions, and control maintenance. List actions truncate content to 150 characters; get returns it untruncated.

// Get recent memories
memories({ action: "recent", limit: 10 })

// Fetch one memory in full
memories({ action: "get", id: "8f7cab3b-644e-4cea-8662-de0ca695bdf2" })

// Project briefing without a search query
memories({ action: "context", project: "my-app", token_budget: 1500 })

// Review revisions, then roll back to revision 2
memories({ action: "history", id: "8f7cab3b-644e-4cea-8662-de0ca695bdf2" })
memories({ action: "undo", id: "8f7cab3b-644e-4cea-8662-de0ca695bdf2", revision: 2, expected_revision: 4 })

sync #

Detects memories whose related_files have changed since the memory was last updated. Compares SHA-256 file hashes against stored checksums and returns a compact list (IDs and changed files, no content). Pass categories to scope the scan; the default limit is 50 (maximum 1000).

// Check one project, scoped to two categories
sync({ project: "my-app", categories: ["my-app-architecture", "my-app-bugs"] })

// Raise the limit for a narrow category
sync({ categories: ["my-app-config"], limit: 200 })

category #

One tool manages the category taxonomy; the action parameter selects create, update, delete, or list. Categories can have parent/child relationships. Creating or updating a category triggers a dynamic schema refresh so the tool descriptions update immediately.

// Create a parent category
category({
  action: "create",
  name: "myproject",
  description: "All knowledge for My Project",
  is_parent: true,
  color: "#3b82f6"
})

// Create a child category
category({
  action: "create",
  name: "myproject-bugs",
  description: "Bug fixes and known issues",
  parent: "myproject"
})

// Rename a category
category({ action: "update", name: "myproject-bugs", new_name: "myproject-issues" })

// Delete, reassigning memories to another category
category({ action: "delete", name: "myproject-issues", reassign_to: "myproject-notes" })

// List all categories as a tree
category({ action: "list", format: "tree" })

list accepts format tree (default), flat, or parents-only. When deleting a parent, reassign_children_to moves its children to another parent.

profile #

The always-available capability router. action: "get" returns the current profile, its active groups, and the presets; action: "set" switches this runtime only and refreshes the host's tool list. A switch never changes other sessions or the default for future sessions.

// Inspect this runtime
profile({ action: "get" })

// Switch to a preset, or pass comma-separated groups
profile({ action: "set", profile: "linkedin" })
profile({ action: "set", profile: "git,image,browser,gsc" })

• Claude Code always runs the full profile: it loads tool schemas on demand, so it needs no restriction.
• Codex sidepanels advertise the complete catalog as deferred tools from the start of each turn, so a profile there is a focus selection and needs no reload.
• The agents and computer groups are never part of a preset. profile set can neither reveal them nor hide them.
• Profiles you add in the Neural Interface appear next to the built-in presets. From a shell, synabun profile list, synabun profile get, and synabun profile set <name> show the profiles and change the stored default profile.

choice #

A blocking multiple-choice prompt for hosts without a native question tool, such as Codex in Default mode. It sends one to three questions through MCP form elicitation; each question has two to four mutually exclusive options, and an "Other" free-text answer is always offered. If the host reports that elicitation is unsupported, the assistant asks the same numbered choices once in plain text.

choice({
  questions: [{
    id: "scope",
    header: "Scope",
    question: "Which memories should the audit cover?",
    options: [
      { label: "This project", description: "Only memories tagged with the current project" },
      { label: "Everything", description: "All projects and categories" }
    ]
  }]
})

Memory v2 Engine #

SynaBun 2.0.0 moves every memory surface — the MCP tools, Neural Interface search, the Claude Code hooks, session indexing, and the terminal UI — onto one shared local engine. Existing tool names, required arguments, UUIDs, project labels, and stored content keep working.

Hybrid Retrieval #

Hybrid retrieval is the default. It combines SQLite FTS5, document embeddings, and passage refinement using reciprocal rank fusion.

• Explicit project filters never widen to other projects. Registered project aliases and case differences resolve without relabelling stored records.
• Tags match any value by default; tag_match: "all" requires every value.
• Long documents get tokenizer-checked source passages and an aggregate document vector, so exact identifiers and late evidence in long documents are found.
• Up to 50 candidates per retrieval channel nominate at most 100 parent documents for passage refinement.
• Ranking scores are relevance signals, not confidence probabilities.

Compact Recall and Context #

The original output format and your configured recall limits remain supported. Agents can ask for concise evidence instead:

{
  "query": "SQLite backup checkpoint policy",
  "project": "synabun",
  "format": "compact",
  "token_budget": 1500,
  "include_sessions": true
}

• The compact budget includes metadata and uses a local UTF-8 estimate. Fetch the original evidence with memories action get, or get-batch with up to 50 UUIDs.
• memories action context, with an explicit project, returns a bounded, extractive briefing of recent decisions, issues, preferences, and notes without embedding a query. It preserves source IDs and does not invent a narrative.
• Automatic memory injection for Claude Code uses a 600-token estimated ceiling. Repeated evidence is suppressed only for the same caller, session, memory revision, and context generation; explicit recalls stay repeatable.

Revisions, Undo, and Supersession #

• remember — optional kind, source_ref, and idempotency_key. Retry keys are scoped to project and category.
• reflect — expected_revision rejects a stale update. supersedes explicitly links a replacement to another live memory in the same project.
• memories — history lists revisions; undo needs id, revision, and expected_revision, and creates a new revision. feedback accepts useful, irrelevant, or incorrect.
• Memory cards expose revision history and restore controls. Content edits keep an unsaved draft if a revision conflict occurs.
• Source checks — file checksum checks run asynchronously after retrieval; a changed or missing related file flags the memory as needing a recheck.

Reversible Maintenance #

Maintenance runs locally in bounded jobs and can be paused, resumed, or retried in Settings → Memory & backups → Maintenance or with memories action maintenance. It indexes passages, groups exact copies within compatible project, category, source, and tag boundaries, and proposes similar or potentially conflicting records for review. Similarity and negation heuristics only create review suggestions; they never rewrite or supersede a fact on their own. With AI decisions enabled, a confident judgment can mark a memory as replaced, and every such replacement is listed with Undo and Keep.

Session Intake #

Managed Claude Code and Codex transcript files enter a resumable, bounded JSONL reader, and OpenCode's history is normalized into the same intake. New transcript intake creates session evidence rather than duplicate memories. Internal reasoning and system injections are excluded, and the original transcripts are never edited. An unsupported client has to expose its transcript before automatic capture can work — MCP alone does not reveal a conversation.

Migration and Rollback #

• The first database open creates a consistent memory.db.pre-v2-*.bak snapshot for a populated store, then migrates the schema additively; a failure rolls the schema work back. A later schema upgrade takes its own memory.db.pre-v3-*.bak snapshot.
• Restart the Neural Interface and connected MCP processes after upgrading so they load the same engine.
• For a retrieval rollback, set SYNABUN_MEMORY_ENGINE=legacy for the server and restart it. This keeps the v2 database and all new writes.
• If the embedding model is not cached yet, install its assets once after building:

npm --prefix mcp-server run setup:embeddings

Further reading: Self-Hosted AI Memory: Why Local Beats Cloud for Coding Agents

Recall Profile Presets #

Control how much context flows into each recall call. Configure from Settings → Memory & backups in the Neural Interface.

4 Presets #

6 Fine-Tune Controls #

• Number of results — default limit per recall.
• Similarity threshold — minimum cosine-similarity score.
• Tag filter intensity — how aggressively tag matches re-rank results.
• Session chunk inclusion — include conversation transcript chunks.
• Importance floor — filter out memories below a minimum importance.
• Temporal bias — shift weighting toward recency vs. semantic similarity.

Impact Indicator #

The settings panel shows a live estimate of tokens per recall, memories reachable, and session context size so you can budget context windows intentionally. The /api/recall-impact endpoint powers the calculation (using avg_tags_len, avg_files_len, and per-project session stats).

Server-Side Defaults #

Configure the baseline recall shape globally via getRecallDefaults(). Every CLI follows the server-side defaults unless the tool call explicitly overrides them.

Category System #

Categories are the primary organizational axis in SynaBun. Each memory belongs to exactly one category. Categories support a parent/child hierarchy, custom colors, and descriptions that appear in the recall tool's schema hints.

Hierarchy #

Categories can have a parent, forming a tree structure. Parent categories act as top-level organizational branches. Child categories provide fine-grained routing within a branch. When routing a memory, use the most specific applicable category.

myproject (parent)
├── myproject-bugs        # Bug fixes and known issues
├── myproject-arch        # Architecture decisions
├── myproject-api         # API design notes
└── myproject-deploy      # Deployment and infrastructure

Routing Descriptions #

The description field of each category is surfaced in the MCP tool schema as a hint to AI assistants. A good description should explain what belongs here in routing language:

Good: "Bug fixes, known issues, and error resolutions for My Project"
Good: "Architecture decisions, system design patterns, and rationale"

Bad: "Bugs"
Bad: "My stuff"

Dynamic Schema Refresh #

When you create, rename, or update a category, SynaBun automatically refreshes the MCP tool schema and sends notifications/tools/list_changed. Your AI tool re-fetches the tool list and sees the updated category descriptions — no server restart required.

Default Categories #

Categories are user-defined. A new installation is seeded with a few that the hooks and tools rely on, and each registered project gets a parent category with four children:

Local Embeddings #

SynaBun generates embeddings locally with Transformers.js. There is no provider to choose, no API key, and no network dependency after the first model download.

• One stateless worker process per server owns native ONNX inference, with a bounded priority queue and 256 cached query and document embeddings. Interactive requests take priority over background work.
• Embedding inference uses cached files only and never sends memory text to a cloud provider.
• If the embedding model is missing or fails, keyword recall remains available and new memories are saved with semantic indexing pending.

Further reading: Using all-MiniLM-L6-v2 for Local Vector Memory in MCP Servers

AI Decisions (Jev) #

SynaBun can ask Jev (TypeSafe System One) for a typed judgment wherever a regex or a similarity constant used to stand in for a semantic decision. The layer is optional: every call site keeps a working heuristic fallback, and Settings → AI decisions controls all of it at runtime.

How It Works #

• Typed answers — a judgment is a choice with a confidence, a yes/no probability, or a score. SynaBun's code applies a threshold to it; the judgment never acts on its own.
• Always a fallback — with no key, the layer switched off, a disabled surface, a timeout, or a rate limit, the call returns nothing and the surface runs its local heuristic exactly as before.
• Configuration — the API key is TYPESAFE_API_KEY in ~/.synabun/.env. The master switch, each surface's switch, timeouts, and thresholds live in Settings and apply within seconds, with no rebuild or restart.
• Kill switch — SYNABUN_TYPESAFE=off stops every outbound call and wins over everything else.
• Judgment log — one row per call (surface, model, latency, tokens, what the caller did with the answer), newest 20,000 rows, with a credential-redacted preview.

What It Decides #

Advisory by Design #

• In the browser and on the desktop Jev never drives anything: it answers typed questions about a minimized description of what is visible, and the tools print that answer beside their normal output.
• Typed text, drafts, form values, cookies, and storage are never sent. Page and screen text is treated as untrusted data and reaches Jev only as state, never inside an instruction.
• Candidate credential values are masked before the secret gate sends them.
• The two features that would act on a judgment — safe auto-heal for a failed browser_click and press-by-intent for computer_ax — ship off and stay locked until a benchmark passes for the exact running configuration.

SynaBun Assistant #

The Assistant is the central, memory-aware orchestrator of the Neural Interface. It thinks with a brain you pick (Claude Code, Codex, or OpenCode), recalls SynaBun memories on every turn, does small things itself — operating your Mac, browsing with the SynaBun browser, small edits and shell commands, memory, loops, and schedules — and delegates heavier work to the three AI sidepanels as autonomous worker runs that it tracks, steers, and summarizes.

The brain is the planner: it decides where each actionable request runs, on its own model or on a worker model, and SynaBun enforces the session's route mode, asking you which model to use when the mode says so.

Opening It #

The terminal tab and the sidepanel mount the same component, so every control, card, and slash command exists in both. A session lives in one place at a time, and Esc inside the Assistant aborts a running turn.

Brains, Modes, and Accounts #

• Provider — Claude Code (Agent SDK), Codex (app-server), or OpenCode (an isolated opencode serve). Switching provider starts a fresh server session in the same tab.
• Model and effort (Claude, Codex) or agent (OpenCode), project (the working directory, which also sets the memory project), MCP profile, and permission mode (ask before tools, or autonomous).
• Plan — a separate switch for all three providers. While Plan is on, code changes are blocked and everything else (shell commands, the browser, computer use, other tools) runs under the session's approval mode. Approving the plan ends plan mode.
• Accounts (Claude and Codex) — pick, add, rename, or remove a saved account. Claude accounts are separate config directories (~/.claude-accounts/<id> with CLAUDE_CONFIG_DIR); Codex accounts use ~/.codex-accounts.
• Hidden models — switch off any model of any provider under ⋯ → Models… or with /models. A hidden model never reaches route cards, the catalog, the model menus, or the brain.

Memory on Every Turn #

• Every non-trivial user turn triggers a token-budgeted recall with the same engine the Claude Code hooks use. Recalled memories show as chips above the transcript.
• After every completed worker run the Assistant is expected to remember the outcome, with the run id as source_ref. If nothing was stored, the server auto-stores an agent-runs memory.
• A session is one continuing conversation, not a fresh context per prompt. The provider's session or thread id is kept on the session record, so the conversation resumes after an idle period or a server restart.

Clarification Briefs #

Most requests are clear enough to act on. When one is materially ambiguous — two plausible readings with different results, an unclear target, destructive or irreversible scope, spend, or memories that conflict with it — the brain asks first, once, before it routes.

• The card — Before I start shows 1–3 questions (2–4 options each, recommended first) and, below them, the assumptions the brain will make for everything it does not ask. Pick an option, type your own answer, or skip and go with the assumptions.
• Waiting — agent_clarify waits up to 45 seconds by default. After that the brain ends its turn and your answers arrive later as a mailbox event; the card stays open until it is answered.
• Dependent work waits — while questions are open, agent_route answers clarifying and agent_dispatch is refused with CLARIFICATION_PENDING. Work that does not depend on the answers goes ahead.
• The brief — your original request, your answers, the constraints, and the assumptions form the session's brief (brief_id). Every worker of that request reads it as a USER BRIEF section; answers and constraints override the task text where they conflict, and assumptions are marked unconfirmed.
• Settings — clarify.enabled and clarify.waitSeconds in ~/.synabun/data/assistant-config.json.

Slash Commands #

/dispatch <claude|codex|opencode> [--model m] [--effort e] [--agent a] [--project p] [--mcp profile] [--account id] [--ask] <task>
/agents   /stop [runId|all]   /recall <query>   /remember <text>   /model   /project
/routes [always|unsure|never]   /computer [on|off]   /budget   /models
/new   /resume   /compact   /clear   /help

agent_* Tools #

The brain sees the agents tool group only when its MCP session carries the assistant role. Dispatched workers never get it, so a worker cannot dispatch further workers. Calls are made one at a time.

Model Routing #

The brain calls agent_route once before any actionable task with a task class, a one-line summary, its confidence (0–1), and 1–3 proposals: direct (here, on its own model) or dispatch (a worker provider and model). The route mode toggle in the Assistant toolbar decides what happens next.

Route Modes #

• Route cards wait up to 45 seconds inside the tool call. After that the brain ends its turn and your later pick arrives as a mailbox event.
• Picking here on another model of the brain's provider runs a one-turn continuation on that model in the same conversation; the next turn is back on the session model.
• Models are validated against the catalog. Failed or blocked runs carry a one-tier escalation, shown on the run card as Escalate to ‹model›. With AI decisions on, a transient failure (timeout, rate limit, outage) offers a retry on the same model instead, and a run that needs access or your input offers no escalation.
• Settings live in ~/.synabun/data/assistant-config.json under routing, and in the Model routes editor (⋯ → Model routes…, or /routes).

Task Classes #

chat, quick, code, complex, review, research, browser, computer, automation, design, image_gen, and video_gen. Three of them have capability rules:

• Image creation (image_gen) and Video creation (video_gen) always run on a worker whose model generates the medium itself. With no capable model, agent_route declines with no_capable_model. SynaBun copies the generated files to ~/.synabun/data/media/<runId>/ and shows them on the run card.
• Design (design) always runs on one worker whose model can see. The worker gets SynaBun's design rules — overridable in ~/.synabun/data/playbooks/design.md — and the project's Style Guide block, and captures screenshots at 375 / 768 / 1440 px in the SynaBun browser.
• A stock setup has no model that generates video: Codex and Claude cannot. The Video creation row in Model routes says so until a provider whose models output video is connected.

The Route Gate #

Every brain turn starts unrouted. Until the brain calls agent_route in that turn, every tool outside a small exempt set — the memory tools, the agent_* tools, the question tools, profile, image_staged, computer_status, ToolSearch, and TodoWrite — is refused before it runs, with a tool error that tells the model what to do next. After 8 refusals in one turn the turn is aborted. Dispatched workers, the Claude Code / Codex / OpenCode sidepanels, and CLI sessions have no gate.

Workers and Dispatch #

Ask in natural language ("write docs for the hooks with Codex, then have Claude review them") or use /dispatch. Each dispatch becomes a task run: one provider conversation that executes the task, ends with a ## Result block (status, summary, changes, follow_ups, an optional question, and media for image, video, and design runs), then stays warm for follow-ups until the Assistant completes it or the idle timeout fires.

The run attaches as an automation tab in the matching sidepanel without stealing focus. The Agents dock under the transcript lists runs with provider, model, account, status, elapsed time, and cost, plus Focus / Stop / Read and Stop all.

// Dispatch a worker on an approved route
agent_dispatch({
  assistant_session_id: "<assistant-session-id>",
  route_id: "<route-id>",
  task: "Write reference docs for the hooks in docs/hooks.md. End with a ## Result block.",
  cwd: "/Users/me/my-project",
  capability: "workspace",
  max_minutes: 30,
  budget_usd: 3,
  title: "Hooks docs"
})

// Block until it goes idle, then read the parsed result
agent_wait({ run_id: "<run-id>", until: "idle", timeout_seconds: 50 })
agent_read({ run_id: "<run-id>", format: "result" })

agent_dispatch Parameters #

Rails and Limits #

Defaults, editable in ~/.synabun/data/assistant-config.json under limits and read live:

• Concurrency per provider — Claude 3, Codex 4 total (2 per account), OpenCode 3
• Per session — 6 running and 20 queued runs, fan-out 6
• Time — run cap 45 minutes, idle timeout 20 minutes, permission timeout 10 minutes, question timeout 30 minutes
• Follow-ups — 6 follow-up turns per run

Runs that read the browser or untrusted content must be read-only or workspace unless tagged user-authorized-full.

Mailbox and Results #

Lifecycle events from runs — result, needs input, permission request, failed, stalled, budget warning, hard cap reached — are batched and delivered to the brain as one [SynaBun Mailbox] turn when it is idle, and rendered as chips in the transcript. agent_wait and agent_status give the brain slim run views (per-turn status and a short summary); agent_read with format: "text" returns the full text.

Browser Policy #

The brain and the workers it dispatches look at pages — public web and localhost alike — only through SynaBun's browser_* tools, which open the browser configured in SynaBun. They do not run their own Playwright, Puppeteer, or Selenium code, launch browser binaries, take headless screenshots, or use web search and fetch tools of their own. Visual checks go through browser_screenshot and page errors through browser_console. When the SynaBun browser cannot do something, they stop and report it instead of switching tools. Running a project's own automated test suite stays allowed.

Further reading: External Models as Agents, SynaBun Memory as the Bus

Budget #

⋯ → Budget… (also /budget, or a click on the spend chip) sets the money caps. They are stored in assistant-config.json and apply without a restart.

Every amount is between $0.10 and $1000, with default ≤ largest ≤ hard cap, warning < hard cap, and brain cap ≤ hard cap. A save that breaks these rules is refused.

Enforcement #

• A new run gets at most what the hard cap leaves after the session's spend and the reservations of live runs. With nothing left the dispatch is refused with BUDGET_EXCEEDED.
• A run that reaches its own cap stops, and a follow-up to it is refused.
• At the session hard cap every live, queued, and held run of the session stops, new dispatches and follow-ups are refused, and brain turns are refused until the cap is raised.
• The caps fail closed on a model with no known price: such a model is not dispatched (BUDGET_UNPRICED).

How Each Provider Is Metered #

• Claude reports its own cost. The run's cap is passed to the CLI at launch and checked between model calls, so one call can pass it.
• OpenCode reports cost per assistant message. The run stops at the first step past its cap, so one step can pass it.
• Codex reports tokens only, priced at list price. The caps are checked after each turn, so one turn can pass them.
• No cap can stop a model call that is already in flight. The brain is checked before each turn; a turn in progress finishes.

Token Usage #

The Assistant counts every token of a session from what each provider reports and shows the running total in a gauge above the composer: the whole session, with input and output apart and the dollars at list price. The dollar caps in Budget are separate — they meter money, this counts tokens.

Sessions, Tasks, and Runs #

• A task is one message from you plus everything it sets off: the brain's turns, the runs it dispatches, those runs' sub-agents, helper-model calls, and AI-decision judgments.
• The session total is the sum of its tasks. A follow-up prompt starts a new task at zero and adds to the session; it never restarts the headline.
• The total is built from an append-only ledger at ~/.synabun/data/assistant-usage/<sessionId>.jsonl, so reloading the page or restarting the server shows the same number.

Token Classes #

Every count is split into five classes that never overlap: input (uncached), cache write, cache read, output (visible), and reasoning. Each provider's numbers are converted to these classes, and every tokens object also carries inputTotal (input + cache write + cache read), outputTotal (output + reasoning), and total.

Statuses #

"Exact" means equal to what each provider reports; it is not an independent measurement. Dollars are at API list prices, and each model row says how its figure is known: reported by the CLI, a list-price equivalent, free, or no list price.

Reading It #

// Session totals plus the current task
agent_usage({ assistant_session_id: "<assistant-session-id>" })

// Every task of the session, narrowed to one run
agent_usage({ assistant_session_id: "<assistant-session-id>", task: "all", run_id: "<run-id>" })

The same data is available at GET /api/assistant/sessions/:id/usage. agent_usage only reads, so the brain may call it in a turn that has no route yet.

Computer Use #

On macOS the Assistant can operate your Mac the way a person does: it takes screenshots, moves and clicks the mouse, types, presses shortcuts, opens and focuses apps, and reads an app's accessibility tree. It is fully autonomous — there are no per-action approval prompts — and it is bounded by guards that always stay on and by stop controls you can hit at any moment.

Only the Assistant's own brain and worker runs it dispatches with uses_computer: true get the tools. Computer use requires macOS 14 or newer; other platforms report unsupported.

One-Time Setup #

1. Build the helper. SynaBun compiles a small native Swift helper with the Xcode Command Line Tools. If swiftc is missing, the setup tray offers to install it (xcode-select --install).
2. Grant permissions. macOS attaches Screen Recording and Accessibility to the app that launched SynaBun, usually your terminal. Enable that app in System Settings, then check again.
3. Ready. New Assistant sessions default the Computer toggle to on. Turn it off per session with the toggle or /computer off.

Tools #

// Read the frontmost app's controls, then press one by ref
computer_ax({ action: "snapshot" })
computer_ax({ action: "press", snapshot_id: "s7", ref: "e12" })

// Click a coordinate of the latest screenshot
computer({ action: "left_click", coordinate: [640, 400] })

Coordinates are pixels of the latest screenshot. A coordinate action needs fresh evidence — a screenshot taken after the last action, within two minutes, with no user input or display change since — otherwise it is refused with STALE_SCREENSHOT and a fresh screenshot is attached.

Guards #

Stop Controls #

Stop with the red Stop · Esc button, Esc (system-wide while an agent holds the desktop), by slamming the pointer into the top-left corner of the main display, or with POST /api/desktop/stop. Stop aborts the action, releases held keys, interrupts the Assistant's turn, and stops computer-use workers. Computer use then stays latched off until you press Resume — agents cannot resume themselves.

WhatsApp Link #

Chat with the SynaBun Assistant from WhatsApp. You write in a WhatsApp chat on your phone; the message reaches the Assistant running on your computer, and its answers, questions, and approvals come back as WhatsApp messages. Everything is set up and controlled in Settings → Messages → WhatsApp.

SynaBun links to WhatsApp the way WhatsApp Web does, as a linked device of an account, through Baileys (an unofficial client). No Meta developer account, phone number rental, or public webhook is involved, and no SynaBun server sits in between. Your computer has to be on and SynaBun running.

Two Ways to Chat #

In Message yourself mode SynaBun reads only your own "Message yourself" chat; every other chat, group, and contact is ignored. With a second number, whoever sends the one-time claim code first becomes the owner, and nobody else is ever answered.

Permission Levels #

Settings → Messages → WhatsApp → Safety decides what a message from the phone may make the Assistant do. The level is enforced on your computer, by the Assistant runtime, its dispatcher, and the brain's hooks — not by the phone.

• Ask and Autonomous need a Claude brain. On a Codex or OpenCode brain the conversation runs Read-only, whatever the level says.
• Computer use from WhatsApp is off unless you turn on its switch in Settings, on the computer. No message from the phone can turn it on.
• At every level, commands and paths that reach credentials, the WhatsApp session itself, persistence points, or browser profiles are refused. This denylist is a speed bump, not a sandbox.
• Pause now stops SynaBun acting on WhatsApp messages at once; the phone cannot undo a pause made on the computer.

Commands #

Levels, models, and settings never change from the phone. Text and pictures are read (4 pictures per message, 5 MB each); voice, video, documents, and stickers are not read yet. Incoming messages are limited to 20 a minute and 300 a day.

When you ask for it, the Assistant of a WhatsApp conversation can also send you a file from your computer as a WhatsApp attachment, with whatsapp_send_file. Sensitive places such as keys, credentials and app data are refused, and a delivery it cannot confirm is never retried on its own.

Neural Interface #

The Neural Interface, the workspace that opens as SynApp, is a 3D memory map of your store at localhost:3344, and the control room for everything else: categories, hooks, skills, MCP registration, the sidepanels, and the SynaBun Assistant.

Core Features #

• 3D memory map — every memory is one point. Categories are islands grouped into continents by their parent category, and inside an island positions come from a UMAP of the memories' embeddings, so similar memories sit side by side. Newer memories float higher, and brighter means more recent.
• Labels that follow the zoom — continents, then islands, then named regions, then memory titles. Click a memory to open it and see lines to its closest memories anywhere on the map.
• 2D alternative — a 2D view of the same memories for performance-focused workflows.
• Semantic search — press / to focus the search bar. Hits light up and everything else dims.
• Memory inspector — open any memory to see full content, metadata, related files, and tags. Memory cards expose revision history and restore controls.
• Category sidebar — filtering, hierarchy editing, and custom logos for parent categories.
• Trash panel — view, restore, or permanently purge trashed memories without leaving the browser.
• Sync panel — detect stale memories whose source files have changed (SHA-256 hash comparison).
• Backup & restore — export and import verified database snapshots.
• Category export — download all memories in a category as Markdown.
• OpenClaw Bridge — a read-only integration that overlays OpenClaw workspace memories on the map.
• Workspace tour — the ? button in the title bar opens a hand-drawn tour of the workspace: a welcome and 14 steps in six chapters, in English and Brazilian Portuguese.

IDE Features #

• SynaBun Assistant — the central orchestrator, as a terminal tab or its own sidepanel. See SynaBun Assistant.
• Sidepanels for Claude Code, Codex, and OpenCode — three dedicated chat panels with per-agent abort, tool activity dock, permission cards, TODO drawer, context gauge (with 1M context activation), session menu, new-session modal (project + branch picker), and Multi-CLI Resume. See Sidepanels.
• Skills Studio — browse, create, edit, import/export skills and agents. Multi-file support, icon upload, validation, and install/uninstall management. /synabun and /leonardo run on both Claude Code and Codex; /synabun changelog is a quick-action button inside the OpenCode sidepanel.
• Style Guide panel — edit a project's brand and design system with light/dark previews, imports, history, and agent proposals. See Style Guide.
• Automation Studio — visual template editor for loops and agents with user-created collapsible folders (drag/drop, icons, colors), per-template launch defaults (CLI / Model / Thinking effort / MCP profile), and first-class 4-CLI support (Claude Code, Codex, Gemini, OpenCode). See Automation Studio.
• MCP Management — Universal Add Form with smart paste (auto-detects 5 config formats), multi-platform sync across the 4 CLIs, centralized env vault with sensitive-value masking, auto profile registration, and one-click install from GitHub. See MCP Management.
• Multi-tab terminal — PTY-backed terminal on a single xterm.js surface with ANSI color support (256-color + truecolor), git branch tracking, command history, session lock, split view, Windows ConPTY hints, and unified CLI update commands via npm install -g for all 4 CLIs.
• File explorer — project file tree with custom folder colors, sort options, and collapsible sections.
• Whiteboard canvas — shared drawing surface for AI and human collaboration. Free-form pen, text, shapes, arrows, images, and wireframe sections with undo/redo.
• Floating memory cards — open memories as draggable, pinnable cards. Compact mode (220×120px mini-cards), persistent positioning, and workspace screenshots.
• Cost widget — Claude API cost tracking with per-session breakdowns and model cost awareness. Collapsible and dockable.
• Statistics dashboard — memory count by category/project, importance distribution, age distribution, and health checks (stale memories, orphaned categories).

Settings and Customization #

• Settings — eleven task pages: AI connections, Memory & backups, AI decisions, Projects, Browser, Connected tools, Tool access, Automations, Messages, Notifications, and Appearance. A search field at the top of the Settings sidebar (Cmd+F / Ctrl+F) finds any page, section, or control.
• Languages — English and Brazilian Portuguese, selected in Settings → Appearance → Language.
• Custom skins — upload custom CSS themes for the entire interface.
• Keybinds — bindable actions (toggle panels, launch tools, navigation, search) with import/export of keybind configurations.
• Workspaces — save and restore panel layouts, sidebar state, and terminal positions. Layout presets per variant (2D/3D).
• Custom file icons — per-extension or per-filename icons with PNG/SVG support.
• Guest access — generate 24-hour invite links with feature-level permission control. Cloudflare tunnel proxy support for remote access.

REST API #

The Neural Interface runs an Express server with 500+ REST endpoints. The UI, the hooks, and external integrations all use it:

# List all memories
GET http://localhost:3344/api/memories

# Hybrid search
POST http://localhost:3344/api/search
{ "query": "auth bug", "limit": 5 }

# Get, update, or trash a specific memory
GET    http://localhost:3344/api/memory/:id
PATCH  http://localhost:3344/api/memory/:id
DELETE http://localhost:3344/api/memory/:id

# Revision history and undo
GET  http://localhost:3344/api/memory/:id/history
POST http://localhost:3344/api/memory/:id/undo

# Trash
GET  http://localhost:3344/api/trash
POST http://localhost:3344/api/trash/:id/restore

# Categories and stats
GET http://localhost:3344/api/categories
GET http://localhost:3344/api/stats

# Download a verified full system backup (ZIP)
GET http://localhost:3344/api/system/backup

The same server mounts the MCP endpoint over HTTP at /mcp — see Multi-Client Support.

Sidepanels (Claude, Codex, OpenCode) #

SynaBun ships three dedicated chat sidepanels that dock to the side of your editor and talk to the same memory backend. They share a common visual language and feature set while exposing each CLI's native capabilities.

Feature Matrix #

Code Rendering #

• Syntax highlighting for fenced code blocks.
• File path linkification — path/to/file.ts:42 becomes a clickable link that jumps to the file explorer.
• Language labels shown in the code header, plus a hover-only copy button.
• Throttled streaming at 30 fps to keep long-token streams smooth without thrashing the DOM.
• Real-time thinking blocks rendered progressively as the model streams reasoning (for the CLIs that emit it).

Temporary Chat (Claude Code) #

A new Claude Code tab's empty state has a Temporary chat button. Click it before the first message for a conversation with nothing saved and memory still readable.

• Nothing is saved — no transcript on disk, no saved tab, no entry in the session list. It ends when the tab is closed, the page is reloaded, or the server restarts.
• Memory is readable, not writable — recall and the other reading tools work, and related memories are still added to your prompt. remember, reflect, forget, restore, and sync are not in the session.
• The hooks stand aside — the SynaBun hooks register nothing, never hold a stop back for a memory, capture nothing at compaction, and store no plan.
• Tools that act outside SynaBun — the browser, git, Discord, and so on — work as usual, and whatever they create stays where it was made.

Sub-Agent Panels (OpenCode) #

• Every sub-agent of the session in the main panel has its own pill, in the order they were started, and its own panel with its transcript, compose box, queue, and permission and question cards.
• A pill shows a running dot, an amber mark while the sub-agent waits for a permission or an answer, a green check when it is done, and a red mark when it failed.
• Nothing opens by itself: a new sub-agent is a pill and a toast. A click on a pill shows that sub-agent's panel where the main panel was.
• Minimize hides the panel and keeps the pill; Close removes both. Neither deletes or stops the sub-agent session.

Keyboard Shortcuts #

• Esc — abort the current turn (works panel-wide, not only when the input has focus).
• Ctrl/Cmd+Shift+A — toggle the OpenCode Tool Activity Dock.
• Enter — submit from the new-session modal; Esc skips.

Further reading: We Skinned Claude Code. It Took 6 Days and Our Sanity.

Automation Studio #

A visual template editor for autonomous loops and agents. Build once, launch across CLIs.

Collapsible Folders #

• Organize custom templates into user-created folders; presets stay in hard-coded categories (Social / Productivity / Monitoring).
• Drag templates onto a folder header to move them; drag folder headers to reorder.
• Per-folder icon (13-icon set + social platform icons), color (8-swatch palette), name, and collapsed state.
• Right-click menus on templates (Move to folder ▸ / Delete) and folder headers (Rename/Recolor, Collapse/Expand, Delete).
• Collapsed state persists per device in localStorage; the server collapsed flag is the first-run default.
• Full backup/restore coverage via loop-folders.json; export/import bumps to version: 2 with an explicit folders array.

Per-Template Launch Defaults #

• Save CLI (Claude Code, Codex, Gemini, OpenCode), Model, Thinking effort (Claude only), and MCP profile (Codex / Gemini / OpenCode) per template.
• The Launch Configuration modal opens pre-filled with the template's saved choices and still lets the user override before kicking off the loop.
• Runtime Card uses native <select> elements so long MCP profile names (e.g. "memory-full — 40 tools") don't truncate.
• Legacy templates without the fields render sensible defaults (Claude Code / default model / effort off / MCP "full").

4-CLI Support #

• Loop mode runs on all four CLIs. cat <taskfile> | opencode run --model <m> is the non-interactive equivalent of codex exec for OpenCode.
• Agent mode is Claude-exclusive (deep subagent integration). Agent mode is automatically disabled and the UI force-reverts to loop mode when a non-Claude CLI is selected.
• Think / effort chips hide for OpenCode (no reasoning flag in opencode run). MCP Profile section auto-shows for non-Claude CLIs.
• A template can append the selected project's Style Guide to its prompt.

MCP Management #

One screen to install, configure, and sync every MCP server you use — across every CLI.

Universal Add Form (Smart Paste) #

• Auto-detects 5 config formats: stdio JSON, HTTP URL, OpenCode TOML, Claude mcp add command, and plain JSON.
• Tag-style arg chips, env var rows, and platform checkboxes with auto-detection.
• Sensitive values (tokens, API keys) are masked in the form and stored through the env vault.

Multi-Platform Sync #

A single MCP server entry syncs to Claude Code, Codex, Gemini, and OpenCode with one click. REST endpoints:

# List platforms SynaBun can sync to
GET http://localhost:3344/api/mcp/platforms

# Sync the selected server to every targeted platform
POST http://localhost:3344/api/mcp/sync
{ "serverId": "...", "platforms": ["claude-code", "codex", "gemini", "opencode"] }

# Remove the sync (per platform)
DELETE http://localhost:3344/api/mcp/sync?serverId=...&platform=codex

Env Vault & Auto Profile Registration #

• Secrets are stored once in the centralized env vault and referenced by name across MCP servers.
• Sensitive variables are masked in the add form and in settings screens.
• Newly added servers are auto-registered with profiles so they can be toggled by group via the profile MCP tool.
• Streamlined install from GitHub — paste a repo URL, SynaBun clones, builds, and registers the server.
• The data/mcp/ folder scaffold gives user-installed servers a predictable layout.

Style Guide #

Each project can have a Style Guide: colors in light and dark with 11-step palettes, type, spacing, shape, motion, icons, logo files, imagery direction, component specs, and rules. It is kept in one place and handed to every agent that works on the project. Saving it writes the files agents and build tools already read:

The Panel #

• Open Style Guide from the Neural Interface Skills menu and select a registered project.
• The panel edits all fourteen sections with autosave, light/dark component previews, import diffs, exports, history, and agent proposals.
• Eight presets — SynaBun Default, Minimal SaaS, Dark Developer, Editorial, Playful, Enterprise, Fintech Precision, and Warm Organic.
• Imports — from a DESIGN.md, a W3C design-tokens file, CSS custom properties (including a Tailwind v4 @theme or shadcn-style variables), a Tailwind theme as JSON, the project's own code, or the community DESIGN.md collection. A preview returns the resulting guide and a diff without saving.
• History — every saved revision is kept, newest first, 30 at most. Restoring a revision brings its design back as a new revision.

The style_guide Tool #

Pass projectPath — the project root or any path inside it. The default is the server's working directory, which is usually not the caller's project.

// The compact brand block
style_guide({ action: "summary", projectPath: "/Users/me/my-project" })

// Tokens as CSS custom properties
style_guide({ action: "tokens", projectPath: "/Users/me/my-project", format: "css" })

// Check contrast for two colors or aliases
style_guide({ action: "contrast", projectPath: "/Users/me/my-project", fg: "{semantic.text}", bg: "{primary.500}" })

// Propose a change for the user to review
style_guide({
  action: "propose",
  projectPath: "/Users/me/my-project",
  changes: { colors: { status: { danger: "#dc2626" } } },
  reason: "The current danger red fails AA on the dark surface"
})

What Agents Receive #

• Workers the Assistant dispatches for coding, complex engineering, design, image, and video work find a STYLE GUIDE block in their brief: 300 to 500 tokens for a filled-in guide, never more than 600.
• The SynaBun Rules tell every connected tool to read DESIGN.md before UI, design, copy, or creative work, and Automation Studio can append the selected project's guide to a template's prompt.
• Agents never write the guide. Their only write is a proposal — a JSON merge patch and a reason — and nothing changes until you accept it in the panel. At most 200 proposals may be pending.
• Contrast is checked against WCAG 2.2 AA by default: 4.5:1 for text, 3:1 for large text and UI.
• The style_guide tool is in the styleguide group, part of the core, standard, codex-browser, browser, and full profile presets.

Claude Code Hooks #

SynaBun ships 10 hook scripts for Claude Code, registered as 11 handlers across 9 lifecycle events. They recall context at session start, brief subagents with memory before they launch, and enforce memory capture after work is done.

Installing Hooks #

Install hooks from the Neural Interface: Settings → Projects → Workspaces → Enable for a single project, or Settings → Automations → Automation behavior → Hooks for every project. This writes the hook configuration into the matching .claude/settings.json.

SessionStart hook #

Runs when Claude Code starts a new session. Injects the full category tree, project detection rules, 5 binding directives (session start recall, auto-remember, recall before decisions, compaction auto-store, user learning), and compaction recovery context. It adds one line when the working directory has a DESIGN.md. This is prepended to the session before the user types anything.

UserPromptSubmit hook #

Intercepts each user message before it reaches Claude. Analyzes the prompt against a multi-tier trigger system — unstored edits from an earlier task, conversation-recall phrases, must / should / consider recall tiers, non-English detection, and a quiet user-learning nudge after a configurable number of interactions — and injects context-aware nudges. Automatic memory injection stays within 3 memories and 600 tokens. With AI decisions on, a judged urgency replaces the regex tiers.

PreCompact hook #

Fires before context compaction occurs. Captures the session transcript path and metadata, sets a pending-compact flag that the Stop hook will enforce — ensuring the compacted session gets indexed in memory before Claude can proceed.

Stop hook #

Runs after Claude completes a response. Enforces two requirements: (1) if a pending-compact flag exists, blocks Claude until the session is indexed via remember with category "conversations", and (2) if edits were made that are not stored yet, blocks until the work is remembered. Max 3 retries per flag to prevent infinite loops. The Stop hook also drives autonomous loop iterations.

PostToolUse hook (post-remember) #

Matches Edit, Write, NotebookEdit, and the SynaBun remember, reflect, and recall tools. Tracks edit count and clears enforcement flags when memories are stored — the conversations category clears the compact flag, other categories reset the remember counter. A successful explicit recall records a receipt that the subagent gate reads.

PreToolUse hook (pre-websearch) #

Intercepts WebSearch and WebFetch tool calls. Checks if a SynaBun browser session is active or if the current loop uses the browser — if so, blocks the tool and injects a message telling Claude to use the SynaBun browser tools instead. Falls through gracefully if the Neural Interface is unreachable.

PreToolUse and PostToolBatch hooks (pre-task) #

Recall before subagents. Before composing Task or Agent prompts, the orchestrator must complete a task-focused recall and fold exact paths, prior fixes, and constraints into the prompt. As a backstop, the first unbriefed dispatch triggers one recall request for up to 5 memories and 1200 tokens; relevant memory blocks that first batch once and hands the brief back, and parallel dispatches share the result. PostToolBatch then releases the denied dispatches so the retry is immediate.

PostToolUse hook (post-plan) #

Fires when Claude enters or exits plan mode. When a plan is approved via ExitPlanMode, it stores the finalized plan as a memory in the plans category, so architectural decisions and implementation strategies are captured without manual intervention.

SubagentStart and SubagentStop hooks #

subagent-start.mjs adds routine memory context to a worker when the host supplies its task text, using the same 3-memory / 600-token budget. subagent-stop.mjs reminds a worker to save useful findings before finishing; it runs only when the subagentRemember flag is on.

Claude Code Integration #

SynaBun ships a single slash command — /synabun — that serves as the entry point for all memory-powered capabilities. It runs on both Claude Code and Codex, and the OpenCode sidepanel exposes a dedicated /synabun changelog quick-action button. Type it in your CLI and an interactive menu appears:

/synabun — Command Hub #

The /synabun command presents a paginated interactive menu — three options and a navigation slot per page. Passing an argument routes straight to an option and skips the menu.

/synabun
/synabun audit auth module
/synabun search how did we handle token refresh

Interactive Prompts per Runtime #

The menu is an interactive option card, not plain text. The skill uses each runtime's own question tool:

• Claude Code — AskUserQuestion
• OpenCode — the native question tool
• Codex — request_user_input
• Other runtimes — a concise plain-text multiple-choice question when no interactive tool exists

SynaBun Rules #

Your AI tool needs a short set of rules to use memory well: recall before substantial work, remember after each task, call SynaBun tools one at a time. SynaBun installs those rules when you connect a tool and keeps them up to date. There is nothing to paste.

• Connecting a tool installs its rules and disconnecting removes them. If you connected a tool before the installer existed, SynaBun asks once and installs nothing until you answer.
• Updates are automatic for a copy you have not edited. Edit the copy and SynaBun stops updating it; delete it and SynaBun does not put it back.
• Your edits are safe — SynaBun never removes rules you edited on its own. Disconnecting a tool leaves an edited copy in place, and Remove in Settings asks first and keeps a backup.
• Every file is backed up before SynaBun changes it, under ~/.synabun/backups/rulesets/.
• Older pasted copies in a project's CLAUDE.md, AGENTS.md, or GEMINI.md are listed in Settings. SynaBun removes one only when you ask, and only when it is an unedited copy.
• Codex — when a Codex home holds an AGENTS.override.md, Codex reads that file instead of AGENTS.md. Setup then shows the rules as Shadowed.

Settings → AI connections → SynaBun rules shows the state per tool with Install, Update, Replace, Remove, View, and Copy.

Multi-Client Support #

SynaBun is one MCP server for every AI tool on your machine. Claude Code, Codex, OpenCode, and generic MCP clients use the same tools and the same memory, so a decision stored from one tool is recalled in another.

Transports and Caller Context #

• stdio — the client launches mcp-server/run.mjs. Project context comes from SYNABUN_PROJECT and the terminal or session environment.
• HTTP — the Neural Interface mounts the MCP server at http://localhost:3344/mcp; a keyed path, /mcp/<key>, is used for tunnel access. Caller context can be supplied with the X-Synabun-Project, X-Synabun-Memory-Session, and X-Synabun-Context-Generation headers.
• A client that advertises one standard MCP filesystem root supplies project context automatically. Explicit tool project arguments take precedence, and multiple roots require an explicit project instead of guessing.

Per-Runtime Tool Profiles #

Each MCP runtime owns its live tool profile, so switching profile in one sidepanel, loop, or schedule never changes another. MCP Management syncs one server entry across Claude Code, Codex, Gemini, and OpenCode, and SynaBun Rules keeps each tool's instructions current.

Further reading: OpenCode + Ollama: Local AI Coding Without the Setup Tax

Whiteboard Tools #

SynaBun includes a shared visual canvas that your AI can see, draw on, and use for architecture diagrams, planning, and collaborative sketching. 5 MCP tools control the whiteboard.

Element Types #

• text — Text boxes with configurable font size and color
• list — Bulleted or numbered lists
• shape — Rectangles, pills, circles, triangles, and drawn circles
• arrow — Connectors with 2+ points whose ends can snap to other elements (startAnchor, endAnchor)
• pen — Free-form drawing strokes with configurable width
• image — Images served by the Neural Interface, embedded on the canvas
• section — Wireframe blocks (navbar, hero, sidebar, content, footer, card, form, image-placeholder, button, text-block, grid, modal)

// Add two shapes side by side with auto-layout
whiteboard_add({
  elements: [
    { type: "text", content: "Auth Flow", fontSize: 24 },
    { type: "shape", id: "login", shape: "rect" },
    { type: "shape", id: "token", shape: "pill" }
  ],
  layout: "row"
})

// Connect them: anchored ends snap to the target's edge
whiteboard_add({
  elements: [
    { type: "arrow", points: [[30, 50], [70, 50]], startAnchor: "login", endAnchor: "token" }
  ],
  coordMode: "pct"
})

Card Tools #

Memory cards are floating panels in the Neural Interface that display memory content. Your AI can open, arrange, pin, and screenshot cards to build visual workspaces for research, investigations, or reference material.

// Open a memory as a compact card
card_open({
  memoryId: "8f7cab3b-644e-4cea-8662-de0ca695bdf2",
  left: 50,
  top: 10,
  coordMode: "pct",
  compact: true
})

Discord Tools #

8 MCP tools for full Discord server management. Requires a DISCORD_BOT_TOKEN in ~/.synabun/.env. Set DISCORD_GUILD_ID for a default server.

// Send a message
discord_message({
  action: "send",
  channel: "general",
  content: "Deployment complete! v2.1.0 is live."
})

// Create a role
discord_role({
  action: "create",
  name: "Beta Tester",
  color: "#3b82f6",
  mentionable: true
})

Further reading: Making Claude Code Live in Discord

Autonomous Loops #

The loop tool enables autonomous iteration — your AI can run long-running tasks with up to 50 iterations (default 10) and a configurable time cap of up to 480 minutes (default 60). Progress is tracked via a journal across context compactions.

// Start a monitoring loop
loop({
  action: "start",
  task: "Check the deploy status every iteration and report any failures",
  iterations: 20,
  max_minutes: 120
})

Further reading: Loops and Agents From Hell: Making AI Run Itself Without Imploding

Git Tool #

The git MCP tool provides version control operations directly through the MCP protocol — status, diff, commit, log, and branch management.

// Check repo status
git({
  action: "status",
  path: "/Users/me/my-project"
})

// Commit specific files
git({
  action: "commit",
  path: "/Users/me/my-project",
  message: "Fix auth middleware race condition",
  files: ["src/middleware/auth.ts"]
})

Browser Automation #

SynaBun integrates Playwright to give your AI assistant its own browser with persistent sessions. Your AI can navigate websites, interact with elements, fill forms, take screenshots, read the console, execute JavaScript, and extract structured data — all through natural language commands via MCP.

How It Works #

Sessions run in the browser configured in Settings → Browser: a SynaBun-managed browser profile, your real Chrome, or a MoreLogin profile. Sessions maintain their own cookies, login state, and local storage across AI conversations — your AI stays logged into platforms without re-authenticating each time. Each caller works in its own tab: tab ownership checks keep one agent from acting on another caller's tab.

Browser Tools (21) #

• browser_navigate — Open any URL in the AI's browser
• browser_click — Click elements by snapshot ref, CSS selector, text content, ARIA role, or data-testid. A textHint lets a brittle locator recover when a site tweaks its DOM.
• browser_fill — Clear and fill input fields and textareas
• browser_type — Type text character-by-character (for contenteditable elements like social media composers)
• browser_snapshot — Observe the page structure and element refs as text (token-efficient alternative to screenshots). Modes: ai (default; compact output with [ref=eN] element refs to pass to click, fill, and type), interactive, landmarks, and full. Scope it with selector and depth, and use snapshot IDs and diffs to see only what changed.
• browser_screenshot — Capture the page as an image: the viewport as JPEG, downscaled to 1024 px wide, by default. width / height emulate a breakpoint for that capture only, fullPage captures the whole page, and save or path writes a full-resolution file.
• browser_console NEW — Read the current tab's console messages and uncaught page errors (the last 200), localhost pages included. Filter with level, since, and limit; clear empties the buffer after reading.
• browser_content — Extract page content as text (default) or markdown for LLM-optimized output with headings and links preserved. selector limits it to one element's subtree.
• browser_evaluate — Execute arbitrary JavaScript in the page context
• browser_hover — Hover over page elements
• browser_select — Select dropdown options
• browser_press — Press keyboard keys and shortcuts
• browser_wait — Wait for elements to appear, page load states, or timeouts
• browser_scroll — Scroll the page or specific elements
• browser_go_back — Navigate to the previous page
• browser_go_forward — Navigate to the next page
• browser_reload — Refresh the current page
• browser_upload — Upload files through form inputs
• browser_session — Create, list, or close browser sessions. Sessions are isolated between the CLI and the Neural Interface sidepanels/loops, so agents don't fight each other over the same browser.
• browser_cheatsheet — Curated selector cheatsheet with stable selectors per platform (twitter, facebook, tiktok, whatsapp, instagram, linkedin, bluesky), optionally filtered to one action.
• browser_batch NEW — Run up to 10 known browser steps sequentially on one tab and return one final snapshot. Part of Browser V2.

Browser V2 #

Browser V2 is the faster execution path. It is on by default; no opt-in variable is needed.

• browser_batch — accepts 1–10 {tool, args, observe?} steps for one session and tab. It validates every step before acting, runs the existing guarded tools in order, stops on the first failure, and returns the outcomes completed so far. The final snapshot is full (default), diff, or none. Steps cannot change routing or run arbitrary JavaScript.
• Snapshot IDs and diffs — browser_snapshot returns a compact snapshot ID and accepts baselineId. A diff needs a compatible delivered snapshot from the same caller and page; force: true requests a full view.
• Bounded automatic snapshots — the observation after a click defaults to 6,000 characters, after navigation and scroll to 12,000, and explicit snapshots to 30,000. Truncation ends at complete lines.
• Paged extraction — browser_extract_* tools accept optional fields and maxChars, deduplicate items by identity, and report why they stopped.
• Social write pacing — social engagement writes keep a randomized 30–90-second spacing, serialized within each browser session.
• Cancellation — cancelling a tool call stops pending requests and prevents later batch steps. Never replay a whole batch or an uncertain click; inspect the current state first.
• Rollback — set SYNABUN_BROWSER_V2=0 for both the Neural Interface and its MCP processes, then restart them.

// Selectors and sequence are already known: one call, one final diff
browser_batch({
  steps: [
    { tool: "browser_fill", args: { selector: "#email", value: "fixture@example.invalid" } },
    { tool: "browser_click", args: { selector: "#save" } }
  ],
  snapshot: "diff"
})

Screenshots and Console for Visual QA #

// Full-page capture at a mobile breakpoint, saved as a file
browser_screenshot({ width: 375, fullPage: true, save: true })

// Only the errors since the last read
browser_console({ level: "error", clear: true })

A saved screenshot lands in ~/.synabun/data/media/screenshots/<date>/ by default. An explicit path must be absolute, end in .png, .jpg, or .jpeg, and lie inside a registered project or the screenshots folder.

Jev Assistance (Advisory) #

With AI decisions on, the browser tools add a typed reading of the page to their normal output. It is text only and never part of the control flow: with it off, every tool answers exactly as before.

• browser_navigate accepts an optional intent. One line may follow the snapshot, such as Jev assessment: authentication_required (94%) — pause for human sign-in. A blocker means stop and hand over to the human; a consent dialog is never dismissed automatically.
• browser_snapshot accepts an optional intent and may append a Jev target: line naming the best ref from that same snapshot. It never clicks.
• A failed or ambiguous click, fill, type, hover, select, or upload returns its usual hints, reordered when a confident match was found.
• Inside browser_batch there is no assistance; a batch that navigated gets one assessment of its final page after it ends.

MoreLogin #

MoreLogin is an anti-detect, multi-account browser. SynaBun can manage its profiles with the morelogin tool and use one of them as the default AI browser, so that every browser_* tool drives that profile.

// Find a profile, then make it the default AI browser
morelogin({ action: "list" })
morelogin({ action: "use_default", envId: "<env-id>" })

MoreLogin as the Default Browser #

• While Settings → Browser names MoreLogin as the default, every loop, schedule, dispatched run, recovery, and interactive session drives the default MoreLogin profile.
• If MoreLogin cannot be reached, the run fails and its log carries the reason. Nothing falls back to Chrome.
• Page tools refuse a session that does not serve the default browser, so an agent never acts on a page in the wrong browser.
• Localhost pages open in the MoreLogin profile like any other page. MoreLogin's per-profile Port scan protection decides which local ports load: list your dev-server ports under Edit profile → Advanced settings → Port scan protection, then restart the profile. A blocked navigation fails with a message that names the port.

Social Media Automation #

Beyond the general browser tools, SynaBun includes 25 platform tools for Twitter/X, Facebook, TikTok, WhatsApp, Instagram, and LinkedIn: 22 extraction tools that parse content into structured JSON, two read-only compose-state probes, and the fb_groups directory tool. They are faster and more reliable than using browser_snapshot because they use platform-specific parsing. Platform tools always run in the default browser.

Twitter / X #

• browser_extract_tweets — Parses all visible tweets: author, handle, text, timestamp, URL, replies, reposts, likes, and view counts. Works on timelines, search results, and profile pages.
• browser_x_compose_state NEW — Inspects the compose surface in one read-only call: composer text, character count and over-limit flag, the quote card type (quote, link, or none), the submit button and its selector, and a recommendedAction (submit, type, open-composer, fix-quote-url, trim-text, or unknown). Check it before publishing: a quote is safe to post only when the card type is quote.

TikTok #

• browser_extract_tiktok_videos — Extract feed videos with handle, video URL, caption, likes, comments, saves, shares, and music info
• browser_extract_tiktok_search — Parse search results with video URLs, handles, captions, and view counts
• browser_extract_tiktok_profile — Extract profile info: name, handle, bio, followers, following, likes, plus video grid with URLs and views
• browser_extract_tiktok_studio — Parse TikTok Studio content list: title, URL, date, privacy setting, and performance stats

Facebook #

• browser_extract_fb_posts — Parse visible posts: author, author URL, text, timestamp, post URL, and reactions. Works on news feeds, group feeds, and business Pages.
• browser_fb_composer_state NEW — Inspects the posting surface in one read-only call: the open posting dialog, the composers on the page (comment boxes are flagged and never treated as post composers), the submit button, the submission state (visible-post, pending-approval, posting-failed, composer-open, or unknown), a recommendedAction, and boostRisk, which flags paid Boost / Promote controls that must never be clicked. Locale-tolerant across PT, EN, TR, FR, ES, and DE.
• browser_extract_fb_groups NEW — Extract all joined groups from the joins page as a region-sorted index. Auto-scrolls the virtualized list and dedupes by URL in one call; each group carries its name, URL, member count, region, language, and currency.
• fb_groups NEW — A structured, SQLite-backed group directory and per-group posting checklist. See the actions below.

WhatsApp #

• browser_extract_wa_chats — Parse the WhatsApp Web sidebar: chat name, last message, time, unread count, muted/pinned status
• browser_extract_wa_messages — Extract messages from an open conversation: sender, time, date, direction (in/out), and text content

These tools read WhatsApp Web in the browser. To chat with the Assistant from your phone, see WhatsApp Link.

Instagram #

• browser_extract_ig_feed — Parse feed posts: username, caption, likes, comments, and timestamp
• browser_extract_ig_profile — Extract profile data: bio, follower/following stats, post grid, and story highlights
• browser_extract_ig_post — Single post with full comments (supports pagination)
• browser_extract_ig_reels — Extract reels with engagement metrics and audio name/URL
• browser_extract_ig_search — Parse explore and hashtag search results

LinkedIn #

• browser_extract_li_feed — Feed posts with author, headline, text, reactions, comments, and article links
• browser_extract_li_profile — Profile data: headline, location, connections, experience, education, and skills
• browser_extract_li_post — Single post with full comments (supports pagination)
• browser_extract_li_notifications — Notifications with text, timestamp, and read status
• browser_extract_li_messages — Messaging conversations and active thread messages
• browser_extract_li_search_people — People search results with headline and location
• browser_extract_li_network — Network connections and connection suggestions
• browser_extract_li_jobs — Job listings from search results and homepage recommendations (title, company, location, salary, posted date)

Other Platforms #

BlueSky and YouTube have dedicated tool groups — see BlueSky Tools and YouTube Tools. The general browser automation tools can interact with any web-based platform — Reddit, Pinterest, or any site that opens in the browser. Use browser_navigate, browser_click, browser_type, and browser_content to automate interactions on any website.

Further reading: AI social media automation with SynaBun

BlueSky Tools #

SynaBun ships 15 BlueSky tools that call the AT Protocol API directly from the logged-in bsky.app tab instead of scraping the page. Log into bsky.app once in the SynaBun browser: the tools reuse that session and renew an expired access token themselves.

// Confirm the session, search, publish, and engage
bluesky_session({})
bluesky_search_posts({ q: "mcp server", sort: "latest", maxItems: 20 })
bluesky_post({ text: "Notes on wiring persistent memory into a coding agent: https://synabun.ai/docs" })
bluesky_action({ action: "follow", target: "alice.bsky.social" })

• The read tools return compact JSON and a cursor; pass maxItems to auto-paginate.
• A whole call has one 48-second deadline. A request that does not answer in time is reported as possibly finished and is never retried — check before repeating a write.
• Enable the group with the bluesky profile preset (git, image, browser, and the BlueSky tools); it is also part of browser and full.

YouTube Tools #

SynaBun ships 11 YouTube tools for an end-to-end game trailer pipeline: discover, download, publish, and analyze. Browser automation drives YouTube Studio directly through your signed-in Google session, which avoids the Data API's private lock on unaudited projects and its small daily upload quota. Sourcing and analytics delegate to the Neural Interface API.

Discovery & Download (2) #

• youtube_source — Discover game trailer candidates via IGDB (metadata, Steam app id, YouTube trailer ids) and the Steam Storefront (direct MP4 URLs). Supports genre, platform, and hype filters and lookback windows.
• youtube_download — Download a trailer to disk. Prefers Steam publisher MP4s over direct HTTPS; falls back to yt-dlp for YouTube-only trailers.

Studio Publishing (7) #

• youtube_navigate — Open a YouTube Studio section (dashboard, content, analytics, playlists, comments, subtitles, copyright, earn, customization). Auto-resolves the signed-in channel.
• youtube_upload mutating — Upload a local video through the Create → Upload dialog: title, description, tags, made-for-kids, then Details → Video elements → Checks → Visibility.
• youtube_metadata mutating — Edit an existing video's title, description, tags, category, and made-for-kids flag.
• youtube_thumbnail mutating — Upload a custom thumbnail image to a video.
• youtube_schedule mutating — Set a future publish time or immediate visibility. Accepts ISO or YYYY-MM-DD HH:MM.
• youtube_playlist mutating — Create playlists, add videos, or list existing playlists.
• youtube_endscreen mutating — Apply an end-screen template to a video.

Analytics (2) #

• youtube_analytics — Read-only YouTube Analytics via the YouTube Analytics API (OAuth): views, watch time, likes, and subscribers gained, channel-wide or per video.
• youtube_channel — Channel info, or a list of recent uploads for deduplication.

Leonardo.ai Tools #

SynaBun includes 5 browser-based Leonardo.ai MCP tools for AI-powered image and video generation. These tools automate the Leonardo.ai web UI directly via Playwright — no API key needed. Use generic browser tools to configure settings (model, style, dimensions, motion controls), then use the Leonardo tools to generate and retrieve results.

Browser Tools (5) #

• leonardo_browser_navigate — Navigate to specific Leonardo.ai pages (home, library, image editor, video, upscaler, blueprints, realtime canvas, models).
• leonardo_browser_generate — Fill the prompt and click Generate. Configure all UI settings (model, style, dimensions, motion controls) beforehand using generic browser tools (browser_click, browser_fill, browser_snapshot).
• leonardo_browser_library — Browse or search the generation library through the web interface.
• leonardo_browser_download — Capture the current Leonardo.ai page as a screenshot to see generation results.
• leonardo_browser_reference — Upload and attach reference images to the next generation. Accepts filePaths and a type: image_ref, style_ref, content_ref, character_ref, or image_to_image for images; start_frame or end_frame for video.

Google Search Console Tools #

SynaBun ships 30 browser-based Google Search Console MCP tools that drive the GSC web UI directly via Playwright — no API key, no quota, no service-account JSON. Your AI uses your own authenticated Google session in the SynaBun-managed browser. Selectors are locale-tolerant (URL paths, material-icon ligatures, and aria roles instead of translated UI strings), so the tools work regardless of GSC's display language.

Navigation & Property (2) #

• gsc_navigate — Open any GSC section (overview, performance_search/discover/news, inspect, pages, videos, sitemaps, removals, cwv_mobile/desktop, https, security, manual_actions, links, achievements, settings, crawl_stats, users, change_address, associations, disavow, shopping, merchant, plus 17 enhancement reports). Preserves the active property.
• gsc_property — List, select, read, or add a property (domain or URL-prefix).

URL Inspection (4) #

• gsc_inspect_url — Inspect a URL, polls up to 30s for the result panel, returns structured JSON (indexingState, canonicals, lastCrawl, sitemap, robots, enhancements, etc.).
• gsc_inspect_test_live — Click "Test live URL" and poll up to 90s for live test results (Google's own timeout).
• gsc_inspect_request_indexing mutating — Submit URL to Google's indexing queue.
• gsc_inspect_view_crawled — Open the View Crawled Page panel — switch between html / screenshot / http_response / more_info tabs.

Performance (3) #

• gsc_performance_query — Query a Performance report — searchType, dateRange (preset or custom), dimension (query/page/country/device/searchAppearance/date), filter chips, comparison toggle. Auto-scrolls grid up to limit rows and returns totals + table JSON.
• gsc_performance_export — Trigger the report Export menu (CSV / Excel / Google Sheets).
• gsc_performance_chart_screenshot — Screenshot the current performance chart.

Indexing & Coverage (6) #

• gsc_pages_report — Read the Pages (Coverage) report — totals, per-reason buckets, optional drill-down to URL examples.
• gsc_pages_validate_fix mutating — Start a Validate Fix run for a chosen reason bucket.
• gsc_videos_report — Read the Video Indexing report (same shape as gsc_pages_report).
• gsc_sitemap — List, submit, delete, or view errors for sitemaps.
• gsc_removals — List or create URL-removal requests (temporary 6-month, outdated content, SafeSearch).
• gsc_removals_cancel mutating — Cancel a pending temporary removal.

Experience & Issues (5) #

• gsc_cwv_report — Core Web Vitals (mobile / desktop) — poor / needs-improvement / good URL counts and per-issue groups.
• gsc_https_report — HTTPS coverage and non-HTTPS URL reasons.
• gsc_security_issues — Read security issues; optionally request a review.
• gsc_manual_actions — Read manual actions; optionally submit a reconsideration request with custom body text.
• gsc_enhancements — Read any structured-data Enhancements report (breadcrumbs, faq, sitelinks, videos, products, recipes, review, events, jobposting, speakable, qa, logos, sitenames, dataset, practice, math, merchant).

Links (2) #

• gsc_links_report — Top linked pages / linking sites / linking text / internally linked. Auto-paginates.
• gsc_links_export — Trigger Links report Export menu.

Settings & Misc (8) #

• gsc_settings — Read settings page (ownership, verification, users); change address.
• gsc_crawl_stats — Crawl Stats — totals (requests, bytes, response time) plus host / response-code / file-type / Googlebot-type breakdowns.
• gsc_users — List, add, remove, change-role for property users.
• gsc_associations — List, add, remove associations (Analytics, Merchant Center, Ads, Play, YouTube, Actions, Chrome Web Store).
• gsc_disavow mutating — Download / upload / delete the Disavow Links file.
• gsc_shopping — Read the Shopping / Merchant Listings report.
• gsc_extract_table — Generic GSC grid → JSON extractor when no specific tool covers a panel.
• gsc_screenshot — Full-page screenshot of the active GSC tab.

Vibe Coding with SynaBun #

Vibe coding is a development style where you collaborate with AI assistants conversationally — describing what you want in natural language while the AI writes, refactors, and debugs code. Tools like Claude Code, Cursor, and Windsurf have made vibe coding mainstream.

The Problem: AI Amnesia #

Without persistent memory, every AI coding session starts from zero. Your AI forgets architecture decisions, bug fixes you already resolved, coding conventions you established, and project context. You end up re-explaining the same things every session, wasting time and losing continuity.

How SynaBun Fixes It #

SynaBun gives your AI persistent memory that survives across sessions:

• Automatic memory capture — Claude Code hooks automatically store important decisions, bug fixes, and patterns after each task
• Semantic recall — Your AI finds relevant context by meaning, not exact keywords. Ask "how did we handle auth?" and it finds the memory about "JWT token refresh flow"
• Drift detection — When source files change, SynaBun flags memories that reference those files as potentially stale
• Multi-project isolation — Each project gets its own memory space, with cross-project search when needed
• Session continuity — Conversation memory indexing captures session context at compaction events for cross-session recall

Beyond Memory: Complete AI Toolkit #

SynaBun provides 158 MCP tools that transform any compatible AI editor into a full development environment:

• SynaBun Assistant — A memory-aware orchestrator that routes each task to the right model and dispatches Claude Code, Codex, and OpenCode workers with budgets and token accounting
• AI image & video generation — Create images and videos via Leonardo.ai with style stacking, motion controls, and reference-image attachment
• Browser automation — Test web apps, scrape data, and check pages at any breakpoint through a real browser; browser_batch runs known sequences in one call and browser_console surfaces page errors
• Computer use — On macOS the Assistant can operate desktop apps, bounded by always-on guards and stop controls
• Style Guide — A per-project DESIGN.md and design tokens that every agent reads before UI work
• Visual whiteboard — Architecture diagrams, flowcharts, and collaborative planning on a shared canvas
• Floating cards — Pin research notes, investigations, and decisions to a visual workspace
• Automation Studio — Visual template editor with user-created folders, per-template launch defaults, and Claude Code / Codex / Gemini / OpenCode support
• Autonomous loops — Long-running AI tasks with configurable intervals across any of the four CLIs
• Sidepanels — Claude Code, Codex, and OpenCode dedicated sidepanels with per-agent abort, tool activity dock, permission cards, and Multi-CLI Resume
• Skills studio — Build reusable AI workflows and custom commands; /synabun and /leonardo run on both Claude Code and Codex
• Social media tools — Interact with Twitter/X, TikTok, Facebook, Instagram, LinkedIn, WhatsApp, BlueSky, and YouTube

Further reading: SynaBun for vibe coding

Configuration #

SynaBun works with zero configuration. Every setting is an optional environment variable, set in ~/.synabun/.env or in the environment that launches SynaBun.

Data Home #

Mutable user state lives outside the application, under ~/.synabun by default, so updating the code never touches your data:

~/.synabun/
├── .env            # optional settings and API keys
├── mcp-data/
│   └── memory.db   # the SQLite database: memories, vectors, revisions
├── data/           # Neural Interface state: assistant config and sessions, media, audit logs
└── backups/        # verified backups and ruleset backups

Installs that kept their state inside the checkout can preview a safe move with synabun migrate-data and apply it with synabun migrate-data --apply.

Storage #

# Root for mutable user state (default: ~/.synabun)
# SYNABUN_DATA_HOME=/custom/synabun

# Database file path (default: ~/.synabun/mcp-data/memory.db)
# SQLITE_DB_PATH=/custom/path/to/memory.db

# Data directory for MCP runtime files (default: ~/.synabun/mcp-data/)
# MEMORY_DATA_DIR=/custom/data/dir

# SQLite runs embedded in Node.js via node:sqlite
# No port, no API key, no external process needed

Server and Integrations #

# Neural Interface server port (default: 3344)
# NEURAL_PORT=3344

# Setup wizard completion flag
# SETUP_COMPLETE=true

# Discord bot token for the Discord tools
# DISCORD_BOT_TOKEN=your-token-here

# TypeSafe API key for AI decisions (optional)
# TYPESAFE_API_KEY=your-key-here

Feature Switches #

CLI Commands #

The synabun command is installed by npm install -g synabun. From a git checkout, npm start is the same entry point, and subcommands are passed after --.

npm Scripts #

# From a checkout: setup + launch (same as the synabun command)
npm start

# Run a CLI subcommand from a checkout
npm start -- doctor

# Start only the Neural Interface server
npm run server

# Rebuild the MCP server after changing its source
npm run mcp:build

# Install the local embedding model assets
npm --prefix mcp-server run setup:embeddings

# Migrate an older Qdrant-based installation into SQLite
npm --prefix mcp-server run migrate

Updating #

• npm — npm install -g synabun@latest keeps user state outside the package. The in-app updater creates a verified pre-update snapshot before replacing code, and a manual npm update performs the same verification on first launch.
• git — run git pull --ff-only, then launch SynaBun once. The first launch migrates checkout-local state before normal startup; do not run git clean -fdx until that launch has completed.
• Conflicting roots — SynaBun never merges two populated data roots automatically. Run synabun doctor, then choose explicitly with synabun migrate-data --choose external or --choose legacy. Both copies are preserved before the choice is activated.

Self-Hosting #

SynaBun is designed to be self-hosted. All data lives in your SQLite database and your local filesystem, and no account is required.

Database Management #

SynaBun uses SQLite via Node.js built-in node:sqlite (requires Node.js 22.5+). The database is a single file at ~/.synabun/mcp-data/memory.db by default — no Docker, no separate process, no network port.

# Database location
ls ~/.synabun/mcp-data/memory.db

# Inspect database, migration, client-registration, and backup health
synabun doctor

Backup & Restore #

Use Settings → Memory & backups → Backups for a WAL-consistent, checksum-verified backup, or download one from the API. Scheduled backups are immutable, timestamped ZIP files with manifest checksums and a consistent SQLite snapshot.

# Download a verified full system backup
curl -o synabun-backup.zip http://localhost:3344/api/system/backup

# Verify a backup (dry run)
synabun restore-backup --from ./synabun-backup.zip

# Restore it, with SynaBun's MCP and server processes stopped
synabun restore-backup --from ./synabun-backup.zip --apply

The default retention keeps every backup for 24 hours, one per day for 30 days, and one per week for 12 weeks, capped at 10 GB.

Multi-Instance Support #

You can keep separate stores — for example one per environment — by launching each instance with its own data home and port:

SYNABUN_DATA_HOME=/srv/synabun-a NEURAL_PORT=3344 synabun
SYNABUN_DATA_HOME=/srv/synabun-b NEURAL_PORT=3345 synabun

Production Deployment #

For production deployments, run SynaBun as a Node.js process with a process manager like PM2. The SQLite database and local embeddings run on the same machine — no external services needed:

# Start with PM2
pm2 start npm --name synabun -- start

# Running on this machine:
# - SQLite database (~/.synabun/mcp-data/memory.db)
# - MCP server + Neural Interface (:3344)

See CLI Commands for updating an existing installation safely.

Further reading: Claude Code and Linux Were Made for Each Other

Contributing #

SynaBun is open source under the Apache 2.0 license. We welcome bug reports and feature requests. Pull requests are not accepted — the codebase is maintained solely by the SynaBun authors.

• Bug reports: Open an issue on GitHub Issues with reproduction steps
• Feature requests: Open an issue on GitHub Issues describing the problem and proposed solution
• Forking: You are free to fork and modify SynaBun under Apache 2.0. Forks must use a different name (trademark policy).

See the full CONTRIBUTING.md for details, development setup, and the forking guide.

Related Guides #

Where to go from here: how SynaBun fits a workflow, how it compares with other AI memory tools, and the posts that explain how it was built.

Workflows #

• Agentic coding with SynaBun — persistent context, the Assistant and worker agents, browser testing
• Vibe coding with SynaBun — memory that carries across sessions and tools
• Social media automation — the browser-based platform tools

Comparisons #

• Compare AI memory tools — SynaBun next to Mem0, Letta, Zep and others
• SynaBun vs Mem0
• SynaBun vs Letta
• MCP Memory Servers: SynaBun vs mem0 vs Letta vs Zep

Project #

• Changelog — the notes of every release
• Blog — engineering notes and war stories
• About SynaBun — who maintains it and how it started