better bear

Let Claude read, search, create, and edit your Bear notes. Also works as a standalone CLI. Powered by CloudKit.

Set Up with Claude CLI Only GitHub

Context Library

Curated, synced context for LLMs. Index-first retrieval.

MCP Server

34 tools for Claude Desktop and Claude Code.

CLI

Create, search, edit, tag, and attach files from the terminal.

CloudKit

Same API as Bear Web. Syncs to all devices.

Context Library

Background: Andrej Karpathy's LLM Knowledge Base pattern (April 2026) showed that the best way to give an LLM project knowledge isn't RAG or vector databases — it's a curated folder of markdown files with an index the model reads first. The LLM acts as a "research librarian," reading the index to find what's relevant, then loading only those files. Better Bear implements this pattern directly on top of your Bear notes.

A context library is a synced, curated folder of Bear notes (plus external files) that Claude can navigate and query. Tag notes with #context in Bear, sync, and Claude uses index-first retrieval to find answers without loading everything.

~/.bear-context/ ├── index.md ← Claude reads this first ├── bear/ ← synced from Bear (source of truth) │ ├── project-plan.md │ └── meeting-notes.md ├── external/ ← PDFs, exports, shared docs, etc. │ └── syllabus.md └── inbox/ ← drop zone for untriaged files

How it works

Tag any Bear note with #context (or #context/research, #context/work, etc.) and it enters the library on next sync. Remove the tag and it's cleaned up. Bear is always the source of truth for bear/ files — local edits are overwritten on sync.

External files from other systems (Google Docs exports, PDFs, email threads) live in external/ and are never overwritten by sync. Drop new files into inbox/ for Claude to triage.

Setup

Tell Claude: "Set up a context library" — or from the terminal:

bcli context init
bcli context sync

Example: study notes

Tag your lecture notes and readings with #context/bio101. Claude reviews the index and pulls only the notes relevant to your question.

You:   "Sync my context and tell me what's there"
Claude: Synced 14 notes (~52,000 tokens). 2 updated, 1 new.
        Your library has 8 lecture notes, 4 reading summaries, 2 lab reports.

You:   "Explain the difference between innate and adaptive immunity
        using my notes"
Claude: [reads index → fetches lecture-12-immunity.md + reading-adaptive.md]
        Based on your lecture notes from March 20 and the assigned
        reading: innate immunity is non-specific and immediate, while
        adaptive immunity targets specific pathogens and builds memory...

Example: shared family or team notes

You:   "Add our vacation planning note to context"
Claude: Tagged "Summer Trip Planning" with #context. Synced.

Partner (in their own Claude Desktop):
        "What hotels are we considering for the trip?"
Claude: [fetches summer-trip-planning.md]
        You're comparing three options from your planning note: ...

Index-first retrieval: Claude reads index.md first (a compact table of contents with file paths, titles, and token estimates), identifies which files are relevant to your question, then fetches only those. This follows the same pattern as Karpathy's index.md manifest and llms.txt: give the model a map, not a dump.

See all context CLI commands and context MCP tools in the full reference.

Claude Desktop

Quick install (recommended)

If you have the bcli binary installed (see below), run:

bcli mcp install --desktop-only

This downloads the .mcpb bundle and opens it in Claude Desktop. Confirm the install in the dialog that appears.

Manual install

Download the latest .mcpb bundle from GitHub Releases and double-click to install. Or edit your config directly (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "better-bear": {
      "command": "npx",
      "args": ["-y", "better-bear"]
    }
  }
}

Restart Claude Desktop after saving. Use bcli mcp install --json to write this config automatically.

Manage

bcli mcp status      # check what's configured
bcli mcp uninstall   # remove from Claude Desktop and Claude Code
bcli mcp reinstall   # clean uninstall + install

Use --desktop-only or --code-only with install/uninstall to target one client.

Requires Node.js 18+ and the bcli binary (see CLI Install).

Claude Code

Using the CLI:

bcli mcp install --code-only

Or add it directly:

claude mcp add better-bear -- npx -y better-bear

CLI Install & Upgrade

The bcli binary is required by both the MCP server and the terminal CLI.

curl -sL https://raw.githubusercontent.com/KuvopLLC/better-bear/main/install.sh | bash
bcli auth

The installer will offer to configure the MCP server for Claude Desktop. Or pass --mcp to set it up automatically.

Upgrade

bcli upgrade         # download latest
bcli upgrade --check # check only

Run hash -r after upgrading. Restart Claude Desktop if using MCP. Need to build from source? See full reference.

Use Cases

Study with your notes

Tag lecture notes and readings with #context/bio101. Claude becomes a study partner that knows your actual course material.

You:   "Quiz me on the immune system based on my notes"
Claude: [fetches lecture-12-immunity.md + reading-innate-vs-adaptive.md]
        Here are 5 questions based on your lecture notes and the assigned
        reading. Let's start: What are the two main branches of the
        adaptive immune system, and how do they differ?

Research and writing

Collect sources in Bear, tag them #context/research. Ask Claude to compare, synthesize, or help you draft — grounded in your actual sources, not hallucinations.

You:   "Compare the three articles on urban heat islands in my context"
Claude: [fetches zhang-2024.md, patel-2025.md, nakamura-2023.md]
        All three agree that green infrastructure reduces surface temps
        by 2-4°C. Zhang and Patel diverge on whether cool roofs are
        cost-effective at scale. Here's a comparison table...

Meeting and project notes

Tag meeting notes, project plans, and decisions with #context. Ask Claude what happened, what's pending, and what to do next.

You:   "What did we decide about the budget in last week's meeting?"
Claude: [fetches meeting-apr-7.md]
        In Monday's meeting you agreed to cap the marketing spend at $5k
        for Q2 and revisit after the May metrics review. Sarah owns the
        vendor shortlist — that's still marked as a TODO.

Weekly review

Claude checks what you worked on, surfaces open TODOs, and helps you plan the week ahead.

You:   "What did I work on this week?"
Claude: [searches context + recent notes]
        This week you finished the grant proposal draft, added 3 new
        sources to your literature review, and have 4 open TODOs across
        your project notes. Want me to prioritize them?

Shared knowledge base

A team, study group, or family all tag shared notes with #context in Bear. Everyone syncs the same library. Claude gives consistent answers because everyone's working from the same material.

Terminal power users

Everything Claude does via MCP also works from the command line.

# Sync and check health
bcli context sync && bcli context status

# Tag all notes about a topic
bcli search "machine learning" --json | jq -r '.[].id' | while read id; do
  bcli context add "$id" --subtag ml
done

# Quick lookup
bcli context search "deadlines" --json

How It Works

Same CloudKit REST API as Bear Web. Notes live in your iCloud private database. Does not touch Bear's local SQLite — safe to use with Bear open on any device.

Full Documentation →

All CLI commands, MCP tools, scripts, and build instructions.