VS Code Extension

See the lessons attached to your code, right where the code lives. The SourceBrain extension surfaces anchored lessons inline: gutter markers, hover-to-read, one click to capture a new lesson from a selection, a warning when a lesson has gone stale, and a search command to jump to any lesson.

ℹ️

The extension isn't on the VS Code Marketplace yet. It lives in the repository at editor/vscode/ and you run it from there (see Install).

What it does

It's a thin client over the sourcebrain CLI: it calls sourcebrain refs <file> --json to find what's anchored to the open file and sourcebrain show <lesson> --json to read it. Because it goes through the CLI, it works against whatever backend the CLI is configured for: a local .sourcebrain/ repo or a cloud workspace.

Feature	What you get
Gutter markers	A marker in the gutter on every line that has a lesson anchored to it. Workspace lessons show a filled indigo marker; your personal (My Lessons) lessons show a distinct outlined-violet one.
Hover to read	Hover a marked line to see the lesson(s) there: a preview, plus a link to open the full lesson. Personal lessons are tagged as such.
Open in code	Each lesson in the hover lists the files it documents; click one to jump to that file at the anchored symbol or line range.
Stale-lesson warnings	When the code a lesson documents has changed since the lesson was written, its gutter marker turns amber and the hover shows a “may be out of date” note, the same staleness signal as sourcebrain doctor, surfaced right where you read the code.
Search lessons	Command Palette → “SourceBrain: Search lessons”: type a query, pick from the ranked results (with the relevance score on Pro), and open the lesson, without leaving the editor.
Add lesson from selection	Select code, right-click → a markdown draft opens, anchored to those exact lines. Write it yourself, or press Draft with AI (Pro) to fill the same draft, edit it in place, and save. Capturing by hand is free.
Add personal lesson from selection	Command Palette → “SourceBrain: Add personal lesson from selection” runs the same flow but saves privately to your personal space. The default right-click flow stays workspace-only.

Install

The extension is built from the repository; there's no Marketplace install yet. From a clone of the SourceBrain repo:

Build the extension

cd editor/vscode
npm install
npm run compile      # or: npm run watch

2
Launch the Extension Development Host
Open the editor/vscode folder in VS Code and press F5. That opens a second VS Code window (the Extension Development Host) with SourceBrain loaded. Open one of your SourceBrain repositories in that window.
3
Make sure the CLI is reachable
The extension shells out to sourcebrain, so the CLI must be installed and on your PATH (or point sourcebrain.path at it; see Settings). Open a SourceBrain project: a local repo (sourcebrain init), or, in cloud mode, any git checkout with a workspace selected (sourcebrain workspace use).

Commands

All commands are under the SourceBrain category in the Command Palette; the capture command is also on the editor right-click menu when you have a selection.

Command	What it does
`SourceBrain: Refresh anchors`	Re-query the current file for anchors. Also runs automatically on save.
`SourceBrain: Search lessons…`	Search the knowledge base by relevance and open a result, a Quick Pick without leaving the editor.
`SourceBrain: Add lesson from selection…`	Prompt for a path, then open a markdown draft anchored to the selected lines. Save with the Save lesson button or Ctrl+Alt+S.
`SourceBrain: Draft lesson with AI (Pro)`	While a draft is open: fill it with an AI-written lesson for the selected code (also the notification button, or Ctrl+Alt+G). Asks before replacing anything you typed.
`SourceBrain: Save lesson draft`	While a draft is open: save it as the lesson (also Ctrl+Alt+S).

Drafting with AI: the Pro flow

Inside the capture flow, Draft with AI sends the selected code to the server, which calls a configured AI model and fills your draft with the result, in the same editor tab, so you edit it exactly like a hand-written one. Nothing is saved until you save the draft. It's a Pro feature and is metered (Free accounts get a small trial quota); see Lesson suggestion in the AI guide for how it works and what's required server-side.

Settings

Setting	Default	Description
`sourcebrain.path`	`sourcebrain`	Path to the sourcebrain executable. Leave as the default to use the one on your PATH.
`sourcebrain.enableGutter`	true	Show gutter markers on lines that have lessons anchored to them.
`sourcebrain.staleWarnings`	true	Flag lessons whose anchored code has changed since they were written with an amber gutter marker and a hover warning.

💡

If the extension can't find the CLI it shows a one-time warning with a shortcut to the sourcebrain.path setting. Set it to the absolute path of your binary if it isn't on PATH.

How anchors work

A lesson declares what it points at with a refs: list in its frontmatter. The extension reads those refs to place markers:

a lesson's frontmatter

---
refs:
  - internal/auth/token.go            # whole file  → marker on line 1
  - internal/auth/token.go#SignToken  # a symbol    → marker at the symbol
  - internal/auth/token.go:40-58      # a line range → marker on the range
---

Symbol anchors are resolved to their current location through VS Code's language server, so a marker follows a function even after it moves within the file. Several lessons anchored to the same line collapse into one marker that lists them all on hover. See sourcebrain refs and the CLI reference for the anchor syntax and the refs command the extension is built on.