bl

BrainLift Plugin for Claude Code

A Claude Code plugin that helps you build and maintain BrainLifts — structured knowledge artifacts for developing real expertise in any domain.

The plugin handles the bookkeeping that kills knowledge bases: extracting facts, generating summaries, tracking evidence chains, flagging stale content, and keeping everything organized. You focus on the curation decisions that actually build expertise — what to include, what challenges your thinking, what patterns you see across sources.

Inspired by Karpathy's LLM Wiki pattern: the LLM maintains the knowledge base, you direct the analysis.

What's a BrainLift?

A BrainLift is a structured markdown file where you develop expertise on a focused topic. It organizes knowledge in layers:

Purpose (what's in/out of scope)
DOK4 - SPOVs (your expert positions — "spiky points of view")
DOK3 - Insights (surprising patterns you've found across sources)
────── your expertise is above / external information is below ──────
Experts (people worth following)
Knowledge Tree
  └─ Sources
      ├─ DOK2 - Summaries (patterns synthesized from a source's facts)
      ├─ DOK1 - Facts (specific, verifiable details extracted from the source)
      └─ Link to original content

Each layer is supported by the one below it. Your SPOVs are backed by insights, which are backed by facts extracted from real sources. No unsupported claims.

Prerequisites

• Claude Code installed and working
• One or more BrainLift .md files in a directory (use the BrainLift template to get started, or run /new-brainlift if you have the full BrainLifting project)

Install

In any Claude Code session, run these two commands:

/plugin marketplace add srbdp/brainlift-plugin
/plugin install bl@srbdp-brainlift

The first command adds the plugin marketplace from GitHub. The second installs the bl plugin from it. After that, the slash commands (/bl:init, /bl:update, /bl:query, /bl:lint) are available in every Claude Code session.

To update the plugin later, Claude Code will check for updates automatically. You can also force an update by re-running the install command.

---

Getting Started

1. Set up your workspace

Navigate to the folder where you want to keep your BrainLifts and run /bl:init:

cd ~/brainlifts    # or wherever you want
/bl:init

This creates:

~/brainlifts/
├── CLAUDE.md       # Workspace config (Claude Code loads this automatically)
├── index.md        # Auto-generated catalog, evidence graph, source registry
├── lifts/          # Your BrainLift .md files go here
├── logs/           # Change logs (auto-managed by the plugin)
└── sources/        # Raw source content (optional, for URL rot insurance)

It also saves a pointer at ~/.brainlift so the plugin can find your workspace from any Claude Code session — you don't have to be in the BrainLift folder to use the commands.

If you have existing BrainLift files, /bl:init will detect them and offer to move them into lifts/ (and any companion .log.md files into logs/).

2. Why this structure?

• lifts/ keeps BrainLift files separate from logs, READMEs, and other markdown. ls lifts/ shows exactly your BrainLifts — nothing else.
• logs/ tracks how each BrainLift evolves over time without doubling the file count in your working directory.
• sources/ is for future use — the plugin will optionally save fetched source content here so you have a local copy if URLs break.
• CLAUDE.md serves double duty: it tells Claude Code about your workspace (loaded as project instructions when you cd in), and it contains a marker (<!-- brainlift-root -->) that the plugin uses to find your BrainLifts automatically.
• index.md is auto-generated — the plugin writes it, you read it. It catalogs all your BrainLifts, maps the evidence graph (which SPOVs are supported by which Insights, which draw from which Sources), and lists every source across all BrainLifts. The plugin reads this first for fast navigation. If you use Obsidian, the wikilinks in index.md light up the graph view.

3. How discovery works

The plugin finds your BrainLifts automatically through a three-step cascade:

1. If you're in your BrainLift folder (or a subfolder): the plugin detects CLAUDE.md and finds lifts/ directly.
2. If you're in a different project: the plugin reads ~/.brainlift to find your workspace.
3. If neither exists: the plugin asks you once and offers to save the location for next time.

You never have to re-specify the path after initial setup.

---

Commands

/bl:update — Add a source to your BrainLift

The core workflow. Paste a URL and get guided through adding it to your BrainLift.