Obsidian Web Brain

A small, self-hosted, Obsidian-style markdown vault with a web UI and a built-in shared-memory MCP server, so Claude Code on all your devices can share one "brain". Notes stay plain .md files on disk and are backed up to a private git repository.

Independent, clean-room project, not affiliated with or endorsed by Obsidian (Obsidian is a trademark of Dynalist Inc.). No Obsidian code or assets are used. The behavior is designed to be compatible with Obsidian vault conventions, so the same folder also opens in Obsidian.

Live showcase: https://tabtq.github.io/obsidian-web-brain/ is an interactive tour of the architecture, data flows, editor and MCP tools. To view it offline, download docs/showcase/index.html and open it in a browser; it's a single self-contained file.

Features

Editor and notes

• Live-preview editor (CodeMirror 6). Markdown renders as you type, and syntax appears only where the cursor is:
  • per token for bold, italic, code, links and math;
  • per line for headings, tasks and rules;
  • per block for callouts, code fences and math blocks.
• Links: [[wikilinks]] with aliases, #heading and ^block references. Ambiguous names resolve the way Obsidian resolves them.
• Embeds: notes, headings, images (with size), audio, video and PDF.
• Renames update links everywhere: wikilinks, markdown links (URL-encoded) and frontmatter links.

Navigation and search

• Backlinks, outgoing links, outline, properties (YAML frontmatter) and a tag tree.
• Search operators: "phrase", OR, -exclude, file:, path:, content:, tag:, line:(), section:(), block:(), task-todo:, task-done:, [property:value], /regex/ and match-case:.
• Graph view (global and local; d3-force on canvas), quick switcher, command palette, daily notes and templates ({{title}}, {{date}}, {{time}}, {{date:FORMAT}}).
• KaTeX math and lazy-loaded Mermaid diagrams.

Git backup and sync

• Every save is committed, and pushes are debounced.
• Manual commit, sync and pull are available.
• Edits made on GitHub flow back into the vault.
• A per-file conflict resolver (keep vault, keep remote, or edit a merged version) means nothing is lost. Conflicts are detected with git merge-tree, so the working tree never contains conflict markers.

Safety

• Soft delete to .trash/, restorable from the UI.
• Stale-write protection: writes carry an etag, so concurrent edits are rejected with a clear error instead of silently overwriting.

MCP server at /mcp (Streamable HTTP, bearer token) with 25 tools:

• search, read, create, append, prepend and edit notes;
• replace lines, update, rename and delete;
• backlinks, outgoing links and outline;
• tags, properties and daily notes;
• unresolved links, orphans, dead-ends and templates.

Footprint: about 20–90 MB RAM at idle. The server is a single Node.js process with one runtime dependency (yaml), and ships as a ~400 KB bundle.

How it fits together

 Browser (any device on your tailnet) ─┐                ┌─> Claude Code (laptop, desktop, ...)
                                       │  HTTPS (real   │     MCP over HTTPS + bearer token
                       tailscale serve ┴─ certificate) ─┘
                                       │
                         127.0.0.1:8090 Node.js server (systemd)
                ┌──────────┬───────────┼─────────────┬──────────────┐
             REST API    MCP /mcp   live events     web UI      git sync
                └──────────┴─────┬─────┴─────────────┘              │
                       vault service + in-memory index              │
                   (links, backlinks, tags, properties, search)     │
                                 │                                  │
                      /var/lib/brain/vault/*.md  ── commits/pushes ─┴─> private GitHub repo

Repository layout

server/              Node.js + TypeScript backend: vault, index, search, git, REST API, MCP
web/                 Vite + TypeScript frontend (no framework): editor, panels, graph, settings
clients/claude-code/ CLAUDE.md section, SessionStart hook and 5 skills for Claude Code
deploy/              release packaging, systemd unit, installer, optional Proxmox LXC helper
docs/showcase/       self-contained interactive showcase page (open offline)

Run locally

npm install
npm test                                        # server test suite
BRAIN_DATA_DIR=.dev-data npm run dev:server     # API on http://127.0.0.1:8090
npm run dev:web                                 # UI on http://localhost:5173 (proxies /api and /mcp)

On first start the server prints a one-time setup code, which is also written to $BRAIN_DATA_DIR/setup-code.txt. Open the UI, enter the code and choose a password. The UI then shows your MCP token.

Deploy (any Debian/Ubuntu host or container)

1. Build a release on a machine with Node.js 22+:

   bash deploy/package.sh            # -> release/brain-<version>.tar.gz
   

2. Install on the target as root. This installs Node.js 24 (official tarball, checksum verified), git and the OpenSSH client, creates the brain user, and installs a hardened systemd unit listening on 127.0.0.1:8090 only.

   tar xzf brain-*.tar.gz && bash brain/install.sh
   

3. Expose it privately with Tailscale (recommended). You get HTTPS with a real certificate, reachable only from your tailnet:

   tailscale up --hostname brain
   tailscale serve --bg 8090         # -> https://brain.<your-tailnet>.ts.net
   

   Your tailnet needs MagicDNS and HTTPS certificates enabled.

This is the beginning of the README. Read the rest at the original. Read the full README ↗