Skip to content
DizzyMiiPublic

About

A notebook for developers that checks every citation in an answer against the actual file and line, and checks again when you reopen it. Also runs as a Claude Code Stop hook, in CI and over MCP.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Lectern. Ask your docs and your code. Every citation checked against the file.

A notebook for developers. Pin the docs you trust, point it at your source folders, ask questions, and every citation gets checked against the actual file before you see it.
Reopen the answer a month later and they get checked again. A Claude Code Stop hook and lectern check in CI run the same checker.

Quick start · First notebook · How it checks · Demos · Settings · MCP · CLI · Changelog

CI status License: Apache 2.0 Node 20 or newer Version 1.0.0-rc.2

Lectern answering how to send a custom 400 when body validation fails: an answer with numbered citations, a receipt reading 11 verified, 0 moved, 1 unverified with a note that one quote was not found and is marked in red, and margin cards showing the cited source lines

Screen recording: a new question about app.close() is typed into the composer, the trail of files the model reads scrolls past, the answer streams in, then the citations stamp in as verified and the receipt counts up to 17 verified
One real ask. It took about 40 seconds and the clip runs 18: the waiting is sped up (8x while it reads files, 5x while the answer streams), the checking at the end runs at real speed. Full quality (MP4)

Quick start

Pick one.

Desktop app (Windows)

git clone https://github.com/DizzyMii/lectern.git
cd lectern
npm install
npm run build:exe

That leaves two files in dist/:

File What it is
Lectern Setup.exe Installs for your user, no admin needed. Starts in a couple of seconds. This is the one to hand to people.
Lectern.exe Portable, runs from anywhere. It unpacks itself on every launch so it takes about 30 seconds to open.

Neither needs Node on the machine it runs on. Neither is code signed yet either, so SmartScreen asks the first time (More info, Run anyway).

Closing the window leaves Lectern in the system tray (the Quit when the window closes switch in Settings turns that off). While it sits there it watches your code roots, and after a git pull or a save moves the citations in a saved answer you get a notification with the question number, click it to land on that answer.

Quick ask is off until you switch it on in Settings. With it on, Ctrl+Alt+Space in any app opens a small Lectern window with your clipboard text already in the palette. Enter asks your last-used notebook on the fast preset (Haiku, low effort), and Alt+Enter opens that question in the main window. Clipboard text is cut at 8,000 characters.

npm

Needs Node 20 or newer.

npm install -g @dizzymii/lectern
lectern serve --open

npx @dizzymii/lectern serve works too if you don't want it installed. Either way it's on http://127.0.0.1:4317.

From a clone

npm install
npm start        # the web app on http://127.0.0.1:4317
npm run app      # the same thing in the desktop window

docs/SETUP.md walks through a fresh machine step by step, including phone access over Tailscale and starting it at logon.

Your first notebook

  1. Add an API key. Click the cog in the top bar, paste a key from console.anthropic.com, Save. The engine label next to it turns green.
  2. Make a notebook. First run walks you through it, or try the ready-made one:
    lectern example node-docs
    
    That pulls three pages of the Node.js 22 API docs into a new notebook.
  3. Add sources. Press A. A page URL gets pinned as markdown, a folder or git repo becomes a code root the model can search.
  4. Ask. Press /, type, Enter. Click any [n] to open the file at that line.

What it does

  • Checked citations. Every [n] points at a file with a quote, a line range or both, and Lectern opens the file and looks. Code citations save the lines they cite and compare them again on every re-check. Each one comes back verified, moved (found elsewhere in the file, with the new line), unverified (the quote is gone, or the saved code lines were rewritten) or missing, and they get re-checked whenever you open an old conversation, so if the docs or the code changed under you, it shows. Each answer also records the git commit of every code root it read, so you can open the file as it was.
  • Checks in Claude Code and CI. lectern hook stop is a Claude Code Stop hook. When a citation in the agent's final message is broken it blocks the finish and sends the agent back to fix it (details). lectern check --fail-on unverified re-checks a whole notebook and exits 1 when a citation went unverified or missing, so CI goes red when a CLAUDE.md written from the notebook cites lines that have since changed (CLI). Neither calls a model.
  • Code roots. A notebook holds pinned docs (the shelf) plus code roots, which are folders or git repos on your disk. The model can search and read any text file under a root while it answers, so it quotes the real source of the library you're using.
  • Studio. 24 recipes that turn a notebook into a saved artifact (specs, code maps, a CLAUDE.md, flashcards, a diff review...) with the same citation checks.
  • MCP. lectern mcp lets Claude Code or Cursor search your notebook for free and ask it questions while they work.

Search, file reads, citation checks and the free MCP tools run on your machine, and the server only listens on 127.0.0.1. Your questions, the pinned docs and the files the model reads while it answers go to Anthropic (the full list is under What leaves your machine, further down).

How a citation gets checked

Behind every [n] is a file plus a short verbatim quote, a line range or both (docs mostly get a quote, code gets line numbers). A line-only citation also saves a copy of the lines it points at when the answer is saved. Lectern opens the file as it is on disk right now and looks, and does it again every time you open an old conversation.

flowchart LR
    A["[n] in the answer"] --> B{"File in the notebook,<br>2 MB or under?"}
    B -->|no| M["missing"]
    B -->|yes| Q{"Has a quote?"}
    Q -->|yes| F{"Where is<br>the quote?"}
    F -->|"at the cited lines"| V["verified"]
    F -->|"elsewhere in the file"| MV["moved<br>(new line given)"]
    F -->|"not in the file"| U["unverified"]
    Q -->|"no, lines only"| L{"Where are the<br>saved lines?"}
    L -->|"at the cited lines"| V
    L -->|"elsewhere in the file"| MV
    L -->|"rewritten or gone"| U
Loading
Status Means
verified The quote is within two lines of the cited range (anywhere in the file if no range was given), or the saved lines are still at the cited range. Whitespace and blank lines don't count as a change.
moved The quote or the saved lines are in the file at different lines. The card says where, like "Cited L9, found at L15".
unverified The quote isn't in the file, or the saved lines were rewritten. The hover card shows the saved lines over today's with the changed words marked.
missing No such file inside the notebook or its code roots, or it's over 2 MB.

Verified means the cited text is still in that file at those lines. The sentence it backs can still be wrong: on the 5 graded questions under How well it works, all 53 citations verified and the answers got 17.5 of 21 key facts.

When a code citation drifts, E in the drawer shows the file as it was at the answer's commit beside today's version, and D lists the commits since then that touched those lines. Answers saved before Lectern kept these copies get one the first time they're re-checked, and the card says so.

The source drawer on service/src/plugins/db.ts for citation 2, unverified, with Show as it was open: AS IT WAS (BA9F175, Oct 28) on the left and TODAY on the right, the cited line 12 banded on both sides, app.decorate('db', store) then and app.decorate('orders', store) today, line 9 changed too, and a banner on the answer saying 2 of 5 citations got worse
Question 006 (what the db plugin decorates) after two lines of db.ts were edited, the store now takes options and the decorator is called orders. Citation 2 cited line 12 and is now unverified ("lines rewritten since the answer"). E puts the file as it was at commit ba9f175 beside today's, with the cited line banded on both sides.

Demos

Every clip is the web UI on one notebook: the Fastify docs pinned (41 files), with the Fastify 5.12.7 source and an 11-file orders service as code roots. Each caption links the MP4 if the GIF is too soft.

Walk the claims, open the source

Screen recording: J and K move the claim cursor and the matching margin card highlights, hovering a citation shows an excerpt with the cited lines highlighted, O opens the source drawer at the line, and the bracket key steps to the next citation

J / K move the claim cursor and the matching margin card lights up. Hover a citation for the excerpt, O opens the drawer at the cited lines (here service/src/app.ts 14 to 16), ] steps to the next one. Full quality (MP4)

Proof ribbons

Screen recording: V on the app.db answer widens the margin and turns each citation card into an excerpt of its file, with ribbons running from each claim to its cited lines, J J K move the claim cursor and the ribbons for the other claims thin out, and Escape puts the margin back

V on the app.db answer widens the margin and turns every citation card into an excerpt of its file, with a ribbon from each claim to its lines. J, J, K move the cursor and the ribbons for the other claims thin out, Esc puts the margin back. Full quality (MP4)

When the files change under an answer

Screen recording after the files changed: the app.close() answer is open with a banner saying 3 of 17 citations got worse, then the app.db answer is reopened from history, its receipt has a Written line and a Today line, changed marks stamp in, a citation to Plugins.md rolls from L9 to L13, hovering the unverified db.ts citation shows the saved lines L8 to L14 over today's L8 to L11 with the changed words marked and a history row, and a banner reads 5 of 10 citations got worse since 08:06

db.ts got shorter and Plugins.md grew four lines at the top. The clip opens on the app.close() answer (its banner already says 3 of 17 citations got worse), then reopens the app.db answer from history. Its receipt has a Written line (08:06, 10 verified) over a Today line (5 verified, 4 moved, 1 unverified), the changed marks stamp in, and the Plugins.md mark rolls from L9 to L13. Hovering citation 1 shows Saved L8-14 over Now L8-11 with the changed words marked, above a History row of earlier checks. The banner reads 5 of 10 citations got worse since 08:06. Full quality (MP4)

Where a file is cited from

service/src/plugins/db.ts open in the source drawer with status glyphs in the gutter at lines 4, 8, 9, 10, 12 and 13 and a stem down lines 4 to 6 and 8 to 14, and the Cited in this file list open over the code with 16 entries such as Sheet 06 node DbOptions, Q001 [1] and Q004 [13], each verified with its line range

db.ts in the drawer. Every cited line is marked in the gutter: a status glyph where a range starts (lines 4, 8, 9, 10, 12 and 13) and a stem down the rest. Cited by 5 (16 citations) in the header opens the list: the orders-service code map, the flashcards sheet and questions 001, 004 and 006, each row with its status and lines.

What the trail read

The opened trail map under the question Where does Fastify actually run onRequest hooks in its source. The Fastify row has two marks with citations 9 and 10 under them. The fastify row has a square for the fastify/lib folder it searched, then a mark for route.js with citations 1, 2, 3, 4 and 8 under it and a mark for hooks.js with 5, 6 and 7, joined by one line

L opens the trail on the onRequest answer, map on top, one row per source. On the fastify row (the code root) the square is fastify/lib, grepped twice (first for onRequest, then for hookIterator and runPreParsing), and the line runs on to route.js (read at lines 490 to 619) and hooks.js (read at lines 225 to 284). Citations 1, 2, 3, 4 and 8 are in route.js and 5, 6 and 7 in hooks.js (7 and 8 sit past where the reads ended, the second grep found them). The two marks on the Fastify row (the pinned docs) are Lifecycle.md and Hooks.md, cited as 9 and 10.

Studio

Screen recording of Studio: the sheet index with 24 recipes, the printed code map for the orders service with 39 verified citations, the all-nodes graph zoomed in, a search for db plugin, and Open at line landing in db.ts at line 8

P opens the sheet index (24 recipes, 3 printed in this notebook). The code map has 39 verified citations and 36 nodes, search finds the db plugin node, and Open at line drops you in db.ts at line 8. Full quality (MP4)

Screen recording of a 40-card flashcards sheet: card 1 is flipped and marked Got it, card 2 is flipped and marked Again, then card 3 is flipped and hovering its citation shows the verified quote from Plugins.md
Flashcards on plugins and encapsulation, 40 cards with 44 verified citations. Flip, then Got it or Again, and hover a citation to see the quote. Full quality (MP4)
The sequence sheet for POST /v1/orders through Fastify lifecycle hooks: 27 verified citations, nine actors, step 3 selected with its two verified citations in the side panel
Sequence diagram of POST /v1/orders through Fastify's lifecycle hooks: 9 actors, 26 steps, 27 verified citations. Step 3 is selected and shows its two.

Screen recording of the sequence sheet for POST /v1/orders: Follow code is ticked, Play starts from step 1 and a packet travels along the first arrows, then the source drawer follows each step through route.js, orders.ts and route.js again, and Escape stops it

Same sheet with Follow code ticked. Play starts at step 1, a packet runs along the first arrows, then the drawer follows each cited step (route.js 561 and 573, orders.ts 7 and 8, route.js 656 and 658). Esc stops it. The drawer covers the right-hand lanes at this window width. Full quality (MP4)

Asked before

Screen recording: a new question about app.db being undefined is typed into the composer and a hint appears under the typed text, Asked before: Question 001, 10 citations, all still verified, with an Open button that Tab moves to

Type "Why is app.db undefined in my orders routes after I decorate it in one plugin?" into a new question and a hint shows up under the text: Asked before, Question 001, 10 citations, all still verified. Tab lands on its Open button (Enter there would open Question 001). Nothing gets submitted in the clip. Full quality (MP4)

Command palette

Screen recording: Ctrl+K opens the command palette, typing orders filters questions, files and sheets as it goes, and Enter opens orders-store.ts in the source drawer

Ctrl+K, type orders, and files, questions and sheets filter as you type. Four Down presses and Enter open orders-store.ts in the drawer. Full quality (MP4)

How well it works

Measured on one notebook (NeoForge 1.21.1: 18 docs, 68 files, 3 code roots, about 350k tokens of pinned shelf). Yours will be different.

Result
5 graded questions 53 of 53 citations verified, 17.5 of 21 key facts
Fast ask through MCP about 2 cents, 8 seconds
Deep ask about 43 cents, 30 seconds
New conversation on Opus, shelf cached about 30 cents
Cold shelf load about $3

Warning

That $3 is the one to watch. The first ask per notebook and model loads the whole shelf into the cache and pays for it, after that it stays warm as long as you ask something within the hour (on the API engine that's a one-hour cache entry, which costs 2x input to write and a twentieth to read). Use fast mode (Haiku) for the "where is X" kind of lookups.

Settings

The cog in the top bar (or the engine label, or Settings in the Ctrl+K palette). Everything saves to settings.json in the home folder and applies straight away, except the two marked restart.

Setting Env var What it's for
Anthropic API key ANTHROPIC_API_KEY What Lectern answers with. Only ever shown back as its last four characters.
Workspace id ANTHROPIC_WORKSPACE_ID Only for a key made outside a workspace (starts with wrkspc_). Without it those keys get a 400.
Claude Code binary CLAUDE_BIN Path to claude when it isn't on PATH. Restart.
Projects folder LECTERN_PROJECTS_DIR Where the first-run screen looks for projects. Your home folder when empty.
Clone size cap (MB) LECTERN_CLONE_MAX_MB A git checkout over this gets deleted again. 1024 when empty.
Allow private URLs LECTERN_ALLOW_PRIVATE_URLS Lets Add URL fetch intranet and localhost pages.
Port PORT 4317 when empty. Restart.
Use my Claude Code login LECTERN_PREFER_CLAUDE_CODE Off by default. Answers questions asked on this machine through the claude you're already signed in to, on your own account. Questions from another device use the API key.
Quit when the window closes LECTERN_QUIT_ON_CLOSE Desktop app. Off means closing the window leaves Lectern in the tray, watching your code roots.
Quick ask hotkey LECTERN_QUICK_ASK Desktop app. Ctrl+Alt+Space from any app. Off by default because another app may already own that shortcut.

Each one is also an environment variable, and a value saved in Settings wins over the environment. Clear the field and the environment's value comes back. Over Tailscale the page can show settings but only the machine Lectern runs on can change them.

Engines

API key. This is how you run Lectern. It calls the Anthropic API directly and you pay per token on your own key. It answers from every device that can reach it, including a phone over Tailscale.

Your Claude Code login (off by default). If you use Claude Code yourself, you can switch on Use my Claude Code login in Settings (or set LECTERN_PREFER_CLAUDE_CODE=1) and Lectern drives your own unmodified claude -p headless for the questions you ask on this machine. It runs on your account under your plan's terms, so check those. Lectern starts the claude you already signed in to and never reads or stores Claude credentials. It only answers on this machine: a question from another device (a phone over Tailscale, say) uses the API key, and a conversation that started on the login refuses follow-ups from there with a 403. The login is never picked for you, with no API key and no switch Lectern has no engine and asks for a key. A hook keeps claude's Read, Grep and Glob inside the notebook and its code roots.

With the switch on, this machine uses the login and everything else uses the API key. With it off, a set key is used everywhere. --engine api or --engine claude-code on the CLI picks one and errors out if it isn't set up, and lectern mcp follows the switch. A follow-up stays on the engine its conversation started on.

Use it from Claude Code or Cursor (MCP)

Install globally first so lectern is on your PATH.

Tip

Installed the desktop app with Lectern Setup.exe? Settings has a Connect Claude Code and a Connect Cursor button that register lectern mcp to run through the installed exe, so you don't need Node or npm. Connect Cursor shows what it will add to mcp.json before writing it and keeps the old file as mcp.json.bak. The portable Lectern.exe can't do this because it unpacks to a new temp folder on every start, so Settings shows the npm commands to copy instead.

Claude Code:

claude mcp add lectern --scope user -- lectern mcp

Cursor, in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "lectern": { "command": "lectern", "args": ["mcp"] }
  }
}

list_notebooks, recall, search, read_source, verify, list_artifacts, get_artifact, check_notebook and submit_artifact never call a model and come back in well under a second. ask and generate do and cost money. recall looks through the answers, notes and sheets you already saved, in every notebook, so Claude Code can check them before it pays for an ask. The 24 Studio recipes are also slash commands in Claude Code (/mcp__lectern__diff-review): the agent reads the notebook with the free tools and writes the sheet, and submit_artifact checks it and saves it, so it costs nothing. The web server doesn't need to be running. Arguments and protocol details are in docs/mcp.md.

Check Claude Code's citations

lectern hook stop is a Claude Code Stop hook. When Claude Code finishes a turn it reads the final message, finds every [[path#L12]], [[path#L12-L20]] and [[path|"quote"]] in it, and checks each one against the notebook whose folder or code root contains the working directory. If one fails, the finish is blocked with a reason like [[src/Foo.java#L40]] is past the end of src/java/Foo.java (32 lines), and Claude fixes it before you read it. No model is called and no file text leaves your machine.

lectern hook install            # prints the settings for this repo
lectern hook install --write    # merges them into .claude/settings.local.json

It goes in settings.local.json because the command has this machine's node and lectern paths in it. --write keeps everything else in the file and replaces an earlier Lectern entry, and it refuses a file it can't merge into. Claude only writes these citations when it is asked to, so add a line about them to your CLAUDE.md.

What the hook checks, and its limits
  • Only the final message is checked. Fenced code, inline code, wiki links like [[Some note]] and C++ attributes like [[nodiscard]] are skipped.
  • A citation fails when it comes back unverified or missing. moved passes, because the quote is still in the file.
  • A line-only citation fails only when the range is past the end of the file or the file isn't there. The hook can't know what a line says.
  • A block gives Claude one retry per stop. If the citations are still bad after that, you get a notice and the finish goes through.
  • Anything odd (bad input, no matching notebook, an error in Lectern) lets Claude stop. The hook never traps a session.
  • The repo has to sit inside a notebook folder or one of its code roots. Add it with lectern add <notebook> <folder>.
  • It needs the npm install of Lectern on this machine. The command points at bin/lectern.mjs, and the portable exe unpacks to a new temp folder every launch.
  • On Windows without Git Bash, Claude Code runs hooks through PowerShell and the quoted command doesn't parse. Change the entry to the exec form there: command is the node path and args is ["<path to bin/lectern.mjs>", "hook", "stop"].

Lectern's own claude -p runs skip the hook.

CLI

lectern serve [--port n] [--open]
lectern ask <notebook> "<question>" [--json] [--fast | --deep] [--continue <conversationId>]
            [--model opus|sonnet|haiku] [--effort e] [--max-turns n] [--engine api|claude-code]
lectern mcp
lectern hook stop | install [--dir folder] [--write]
lectern list [--json]
lectern show <notebook> <conversationId|artifactId> [--json]
lectern check <notebook> [files...] [--fail-on moved|unverified] [--json]
lectern new <id> [--title t] [--dir folder]
lectern add <notebook> <url|path|git-url> [--name n] [--branch b] [--subdir d]
lectern example [name] [--dir folder] [--code]
lectern --version | --help
  • --fast is Haiku at low effort with at most 4 rounds, --deep is Opus at high effort with at most 12. Without either it's Opus with at most 12. A round is one model request, every batch of tool calls costs another, and hitting the cap gives an error that says so.

  • add works out what you gave it. A git URL (or a plain github, gitlab or codeberg link) gets cloned as a code root, any other http URL is fetched as a doc, a folder becomes a code root and a file gets copied in.

  • show re-checks the saved citations against the files as they are now.

  • check does that for the whole notebook: every conversation, every Studio sheet and every note, plus the Lectern footnotes ([^1]: path:12-14 "quote" (verified)) in any markdown files you name. It lists what got worse since it was written, grouped by the cited file, and never calls a model or writes to disk. A citation that was already moved, unverified or missing when it was saved is counted separately and doesn't fail anything.

    --fail-on moved exits 1 when any citation got worse, --fail-on unverified only when one is now unverified or missing. Without the flag it always exits 0. A bad flag value, an unknown notebook or a file that isn't there exits 2. For CI, register the committed notebook folder (lectern new ci --dir ./notebook leaves an existing notebook.json alone) and run lectern check ci --fail-on unverified. Commit notebook.json, conversations/ and artifacts/, and give code roots as relative paths in notebook.json. As a pre-commit hook it is the same one line. A Lectern-written CLAUDE.md has no footnotes in it, so check reports the sheet that wrote it, and names the file the sheet was written to. One limit: footnotes in notes and in files you name carry no copy of the cited lines, so a code line footnote only goes bad when the file shrinks past them or disappears. Quote footnotes drift properly.

  • example with no name lists the ready-made notebooks. neoforge is the big one, add --code to also pull the NeoForge and GeckoLib sources.

The web app's HTTP API is internal and can change between versions, script against the CLI or MCP.

Studio recipes

Open Studio with P. Each recipe asks for a couple of inputs and saves an artifact into the notebook.

Group Recipes
Plan Product requirements, Tech spec, Implementation plan, Decision record, Test plan
Visual Code map, Concept map, Flow diagram, Sequence diagram, Dependency graph
Agent CLAUDE.md, AGENTS.md, Agent skill, Agent quiz
Learn Onboarding guide, Cheat sheet, Porting guide, Gotchas, Glossary, Flashcards
Code Gap report, Diff review, How would I build..., Release notes

Code map, CLAUDE.md, Glossary and Product requirements make a LOT of tool calls and are the likeliest to hit the 4-round cap in fast mode. Run those in deep.

Keyboard shortcuts

? opens the full sheet in the app.

Key Does
Ctrl+K command palette
/ focus the composer
N or Alt+N new conversation
J / K next / previous claim
1 to 9 open citation n
[ / ] previous / next citation
O open the current citation in the source drawer at the line
V proof ribbons: the cited files open in the margin with a ribbon from each claim to its lines
E / D in the drawer: the code as it was, and the commits that changed those lines
C copy the answer with citations
X challenge the claim under the cursor
W ask "what could make this wrong?"
H focus history
Shift+H toggle claim bands
L toggle the trail log
P Studio
A add a source
Ctrl+B toggle the rail
Ctrl+1 / 2 / 3 focus rail / page / margin
Ctrl+Shift+F search the notebook
Ctrl+Shift+L toggle theme
Esc close the top layer, then clear the claim cursor
Ctrl+Alt+Space quick ask from any app (desktop app, once it's on in Settings)

Inside Studio artifacts, flashcards flip with Space and rate with the arrow keys, graphs zoom with + - 0, sequence diagrams step with J / K and play with Space, and Ctrl+S saves an edited file.

What leaves your machine
  • Your question, the pinned docs and whatever files the model reads go to Anthropic, through the API or through Claude Code. The first ask in a conversation sends the whole shelf, follow-ups send the conversation so far, and tool calls send back the file contents the model asked for.
  • Adding a URL fetches that page (user-agent lectern/1.0) and saves it as markdown. Loopback, private and link-local addresses are refused, redirects included, unless you turn on Allow private URLs.
  • Adding a git URL runs git clone --depth 1 (sparse when you give a subfolder). https:// or git@ only, symlinks come out as plain files, hooks and LFS downloads are off, and a checkout over the size cap gets deleted again.
  • Quick ask reads your clipboard when you press its hotkey and shows it in its own window. Nothing is sent until you press Enter, and then it goes out as an ordinary question.
  • lectern example downloads that example's sources from GitHub.
  • On the Claude Code engine, Claude Code's own telemetry settings apply to that process. Lectern leaves them alone.

That's the whole list. No telemetry, no update check, and the fonts and scripts are bundled so nothing loads from a CDN. Search, file reads, citation checks and the free MCP tools never touch the network. The page sends a Content-Security-Policy that blocks loads from any other host, so an answer can't smuggle in an image tag that phones home.

Everything under a code root can end up in front of the model. In a git repo Lectern indexes what git ls-files lists (so .gitignore applies), outside one it skips the usual build and dependency folders. Don't add a folder with secrets in it.

Where your stuff lives

A notebook is a folder with a notebook.json in it, anywhere on disk:

notebook.json     title, pinned docs, code roots
sources/          docs you added (fetched pages, copied files)
corpus/           git repos you added
conversations/    every conversation, as JSON
notes/            notes, as markdown
artifacts/        Studio output

Per-user state goes in the Lectern home folder: the notebook list (registry.json), cached base sessions (bases.json), settings.json, and the desktop app's window profile. It's picked in this order:

  1. the LECTERN_HOME environment variable
  2. "home" in ~/.lectern.json, like {"home": "C:/lectern-home"}
  3. ~/.lectern

The config file is handy when your home drive is full.

Limits and rough edges

  • Every number above comes from one NeoForge notebook. I haven't measured anything else yet.
  • I use it daily on Windows. CI runs the tests on Ubuntu, macOS and Windows (Node 20 and 22), and the desktop build is Windows only for now.
  • Files are picked by extension. The list leans toward what I use (Java, Kotlin, Gradle, JSON, JS, TS, Python, shaders, markdown) and also covers Go, Rust, C and C++, C#, Ruby, PHP, Swift, Lua, SQL, Vue and Svelte. Anything else gets skipped.
  • Files over 2 MB count as missing for search, reads and citations.
  • On the API engine a follow-up sends the earlier turns back whole, files the model read included, and most of that comes from cache. If you add a source or a code root mid-conversation it has to fall back to the answers as plain text, so the model forgets what it read and that follow-up re-pays the cache.
  • The packaged desktop app can't be used as the CLI. Use lectern from npm or node bin/lectern.mjs for that. The Connect buttons in Settings are the one exception, they register lectern mcp with Claude Code and Cursor.
  • The tray watcher only watches code roots, pinned docs are left alone. It runs while the app is open or in the tray. A pull made with Lectern closed shows up as the drift badge when you open the answer, or in the first notification after the next change in that root, whichever comes first.
  • This is a release candidate, things will still move before 1.0.0.

Design

The colours, type, spacing and the benchmark mark are written down in docs/design/DESIGN.md, with the screens in SCREENS.md.

License

Apache 2.0, so you can build on it at work or in a product of your own. Hand out LICENSE and NOTICE with any copy you ship. The full text in LICENSE is what counts.

Copyright 2026 Kade Heglin.

Built by Kade Heglin. I'm open to work on AI developer tooling, you can find me at github.com/DizzyMii.

About

A notebook for developers that checks every citation in an answer against the actual file and line, and checks again when you reopen it. Also runs as a Claude Code Stop hook, in CI and over MCP.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages