brainbridge

Connect your AI tools (Claude Code, OpenCode, Cursor) to a structured knowledge base. Set up an Obsidian vault or a plain markdown folder as a shared brain in one command.

Status: v0.3.0. The CLI works; it just isn't published to npm yet, so npx brainbridge won't resolve until it ships there. Until then, run it from source (requires Bun):

git clone https://github.com/PedroMosquera/brainbridge
cd brainbridge
bun install
bun run dev            # the interactive wizard (brainbridge init)

What it does

brainbridge init runs an interactive wizard that:

1. Scaffolds a vault directory with a curated folder layout (00-inbox, 01-ideas/{apps,portfolio,business,technical}, 02-projects, 03-implemented, 04-decisions, 05-sessions, 06-resources, templates).
2. Drops in four note templates (idea, session, decision, project), a README, and a conventions doc.
3. Wires the vault to your AI tools:
   • Claude Code — ~/.claude/mcp/filesystem.json + bounded section in ~/.claude/CLAUDE.md
   • OpenCode — deep-merge into ~/.config/opencode/opencode.json + bounded section in ~/.config/opencode/AGENTS.md
   • Cursor — deep-merge into ~/.cursor/mcp.json
4. Optionally initializes a git repository and creates a private GitHub repo via the gh CLI.
5. Runs an automatic health check at the end so you immediately know whether everything wired up correctly.

All three AI runtimes are instructed to use the filesystem MCP tools (search_files, read_text_file) to look up prior notes before proposing anything new.

Backends

Backend	Best for
obsidian	You want graph view, plugins, and the Obsidian mobile apps. Includes .obsidian/ stub and a tuned .gitignore.
local	Plain markdown folder. Works with any editor (VS Code, Cursor, vim). No Obsidian dependency.

Sync

Option	Notes
Git + GitHub	Creates a private repo via gh repo create. Requires gh to be installed and authenticated.
None	Skip sync; you can wire it up later.

Safety

• Idempotent: re-running on a configured setup detects existing state and only fills gaps.
• Atomic writes: every file is written to <path>.tmp and renamed.
• Bounded patches: CLAUDE.md modifications are wrapped in <!-- brainbridge: managed v1 --> markers; user content outside the markers is preserved.
• Backup before patch: CLAUDE.md.bak is written before any modification.
• Rollback: a transaction log under .brainbridge/transaction.log allows the runner to undo writes if a step fails.
• Dry run: brainbridge init --dry-run prints the planned operations without touching disk.

Requirements

• Node.js 18 or newer (works under Bun too)
• gh CLI 2.x (only if you choose Git+GitHub sync)
• Obsidian (only if you choose the Obsidian backend; the vault is plain markdown either way)

Vault structure

your-vault/
  00-inbox/              # quick captures, unsorted
  00-meta/
    conventions.md       # storage rules and frontmatter conventions
  01-ideas/
    apps/                # app product ideas
    portfolio/           # portfolio project concepts
    business/            # startup / company ideas
    technical/           # technical experiments and patterns
  02-projects/
    active/              # in-progress
    backlog/             # planned but not started
  03-implemented/        # shipped or completed work
  04-decisions/          # ADRs (YYYY-MM-DD-title.md)
  05-sessions/           # AI session summaries (YYYY-MM-DD-topic.md)
  06-resources/          # references and links
  templates/
    idea.md
    session.md
    decision.md
    project.md
  README.md
  .gitignore
  .obsidian/app.json     # obsidian backend only

Commands

brainbridge init                       # interactive wizard (default command)
brainbridge init --dry-run             # print plan without writing anything
brainbridge init --no-doctor           # skip the post-init health check

brainbridge capture "<text>"           # quick-capture an idea into 00-inbox/
brainbridge capture --type idea "..."  # use a specific template (idea | session | decision | project)
brainbridge capture --vault <path>     # explicit vault path

brainbridge new <type> <name>          # scaffold a new note from a template
brainbridge new idea "graph search" --category technical
brainbridge new project knowledge-cli
brainbridge new decision "use ripgrep"
brainbridge new session "vault retrieval"

brainbridge doctor                     # read-only health check across all integrations
brainbridge doctor --vault <path>      # check a specific vault

brainbridge grep <query>               # search the vault (ripgrep, with grep fallback)
brainbridge grep -i <query>            # case-insensitive
brainbridge grep --vault <path>        # search a specific vault

brainbridge --version                  # print package version
brainbridge --help                     # show usage

Non-interactive init (scriptable for CI / dotfiles)

When all required flags are supplied, init skips every prompt:

brainbridge init \
  --backend obsidian \
  --vault ~/Projects/knowledge-graph \
  --integrations claude-code,opencode,cursor \
  --sync none \
  --no-doctor

Partial flags also work — the wizard treats them as defaults and prompts only for missing fields.

capture

Writes a timestamped note (YYYY-MM-DD-HHmm-<slug>.md) into the vault's 00-inbox/. With --type, it renders the matching template. Without --type, it writes a freeform note with status: raw frontmatter.

new

Scaffolds a structured note into the type-specific folder:

Type	Destination	Filename
idea	01-ideas/<category>/ (default technical)	<slug>.md
project	02-projects/active/	<slug>.md
decision	04-decisions/	YYYY-MM-DD-<slug>.md
session	05-sessions/	YYYY-MM-DD-<slug>.md

Refuses to overwrite an existing file.

doctor

Reports a checklist of statuses for: vault path, vault marker, Claude Code (MCP + CLAUDE.md), OpenCode (MCP + AGENTS.md), Cursor (MCP), and git repo + origin (live git ls-remote with 5s timeout). Exits 0 if all OK, exits 1 if any FAIL. WARN and SKIP rows do not affect the exit code. Pure read-only — never writes.

grep

Wraps ripgrep when present, falls back to grep -rIn --include="*.md" otherwise. Forwards the underlying tool's exit code (0 on match, 1 on no match).

License

MIT. See LICENSE.