algometrix1k downloadsGrow your vault into a linked knowledge graph: select any word or phrase to generate detailed, wiki-linked explanation notes using Claude Code, Gemini, Codex, or a local Ollama model.
Features • Quick start • AI backends • Install • Note modes • Troubleshooting • FAQ • Report a bug
An Obsidian plugin that turns any topic into a folder of interlinked, deep-dive study notes: a generated index hub, mermaid concept maps, and wiki-links that light up the graph view. It also explains selections into linked notes and enhances text in place.
📚 A course from one promptType a topic. Get an index hub and 8 to 15 linked notes, ordered from foundations to advanced. |
💸 No extra AI billsNo API keys and no per-token billing. It runs on the Claude, Google, or ChatGPT plan you already have. |
🔒 Private when you need itPoint it at a local Ollama model. It costs nothing and your notes never leave your computer. |
One prompt ("why is the dollar the world's reserve currency?") produced this index hub and the 16 linked notes behind it:
|
🧠 Grow your vault
|
🪄 Improve what you have
|
|
🔌 Four AI backends behind one setting: Claude Code CLI • Gemini CLI • Codex CLI • Ollama |
|
| You want to | Run |
|---|---|
| Learn a whole subject from one prompt | Generate knowledge notes in folder |
| Turn a term in a note into its own linked note | Explain selection |
| Grow a folder of deep-dive notes under the current note | Create sub-note from selection |
| Improve text right where it is | Enhance selection |
| Get review questions or exercises for a finished note | Analyze current note |
| Start a subject with no note open | Generate notes from topic |
| Fill in empty stub notes you linked earlier | Fill empty note |
Give the plugin a topic, a pasted paragraph, or a whole article, pick a teaching mode and a target folder, and it builds a complete, interlinked mini-textbook. Run "Generate knowledge notes in folder with AI" from the command palette, or right-click a folder.
A few minutes later the folder contains the full series. Each note has YAML frontmatter, tags, and cross-links to its siblings:
folderDecompositionGuide that teaches the planner how to split topics in that domain, so the breakdown is not generic.[[wiki-link]] grouped logically with one-line descriptions, a recommended reading order with rationale, and a mermaid diagram (with subgraphs) mapping how the notes relate to each other.[[wiki-links]] where relevant. Notes use mermaid diagrams, tables, and Obsidian callouts throughout, and every one gets YAML frontmatter and consistent formatting via the plugin's output rules.Select a word or phrase, run "Explain selection with AI" (or right-click the selection), and pick one or more modes. The plugin creates a new note in the same folder, writes the AI output into it, and replaces your selection with a [[wiki-link]]. If a note with that name already exists, it links to it instead. Select several modes to generate multiple takes on the same topic.
Select text and run "Create sub-note from selection with AI", or right-click and choose Create sub-note. For example, select "Kafka, Redis, WebSocket Gateway" in a system design note to generate a linked Components folder in one step.
The modal asks for a sub-folder name and a note style, plus a topic list with one note topic per line. If the selection looks like a list ("Kafka, Redis, WebSocket Gateway"), the topics are prefilled from it. If it is prose ("US stopped redeeming dollars for gold"), it stays one line you can rewrite into the topics you want.
On submit, each topic becomes its own note inside the sub-folder under the current note's folder. The generated notes cross-link each other, link back to the parent note, and reuse wiki-links from the surrounding context. Topics taken from the selection replace it with links; rewritten topics keep your text and append the links after it. The sub-folder name is remembered for next time.
Run "Enhance selection with AI" to transform the selected text in place, or insert the result below it. All nine actions are also one right-click away under AI actions. Use inline actions to improve the note you are in, and note creation to grow the vault.
| Action | Use it when |
|---|---|
| Expand | A passage is too thin and needs more depth, without creating a new note |
| Simplify | The text is dense or jargon-heavy |
| Add Examples | An abstract explanation needs concrete cases |
| Add Diagram | A process or structure would be clearer as a mermaid diagram |
| Summarize | A long section needs a TL;DR |
| Challenge | You want counterarguments and weaknesses of the claims |
| Fix & Polish | Grammar, flow, and clarity need cleanup without changing meaning |
| ELI5 | You want a beginner-level restatement |
| Translate to Code | A described algorithm or process should become working code |
| Command | What it does | Use it when |
|---|---|---|
| Analyze current note with AI | Runs a full-note mode against the entire note and appends the result. The sample modes include Question Generator and Active Recall Prep | You finished a note and want study aids or a critique of the whole thing |
| Generate notes from topic with AI | Creates notes from a typed topic with no selection. It can split a broad topic into multiple linked notes | You are starting a new subject from nothing |
| Fill empty note with AI | Fills the note you are in, using its title and backlink context as the prompt | You created stub [[links]] earlier and want to flesh them out one by one |
| Insert scale estimation table | Inserts a back-of-envelope capacity estimation table at the cursor | You keep system design or interview prep notes |
| Scaffold system design workspace | Creates a linked workspace of section notes for a design exercise | You are starting a system design exercise |
| View note generation queue | Opens a live progress modal with elapsed time, retry, remove, and streaming output (CLI providers; Ollama output appears when generation completes) | You want to watch or manage running jobs |
| View logs | Shows recent plugin activity | You are debugging a problem |
All generation runs through a sequential background queue, so you can queue several notes and keep working. The status bar shows the current item and the queue length.
Four steps from zero to your first generated note.
1. Install the plugin. See Install for every option.
2. Set up one AI backend. The plugin generates nothing until this is done. The two easiest options:
npm install -g @anthropic-ai/claude-code, then run claude once to log in. Needs a Claude account.ollama pull llama3. No account or Node.js needed.3. Pick your provider. Open Settings > Second Brain Builder and set AI provider to the backend you set up (Claude is the default). The setup guide for that provider appears right below the option.
4. Generate your first note. Open any note, select a word or phrase, press Ctrl+P (macOS: Cmd+P), run "Explain selection with AI", and pick the Explain mode. A new linked note appears in the same folder.
Then try the headline feature: run "Generate knowledge notes in folder with AI", type any topic, and watch it build a whole linked series with an index and diagrams.
[!TIP] If the plugin says it cannot find the CLI, see Troubleshooting. It is almost always a PATH issue with a one-line fix.
Most AI note plugins ask for an API key and bill you per token, on top of whatever AI subscription you already pay for. This plugin takes a different approach: note generation should not cost you anything extra.
[!IMPORTANT] Generating notes still consumes tokens against your plan's limits, and batch features like folder generation can use a lot in one run. Watch your usage, especially with large selections or long series. Ollama has no limits since everything runs locally.
Pick one provider in Settings > Second Brain Builder > AI provider. All four work on Windows, macOS, and Linux.
| Provider | What it costs you | Note quality | Where your text goes | You need |
|---|---|---|---|---|
| Claude Code CLI (default) | Covered by your Claude plan | Best | Anthropic, under your account | Node.js + Claude account |
| Gemini CLI | Covered by your Google plan (has a free tier) | High | Google, under your account | Node.js + Google account |
| Codex CLI | Covered by your ChatGPT plan | High | OpenAI, under your account | Node.js + ChatGPT account |
| Ollama | Free | Depends on the model you pull | Nowhere, stays on your machine | Ollama installed |
npm install -g @anthropic-ai/claude-code
claude # run once in a terminal to log in
The plugin calls the CLI in read-only mode with file-modifying tools disabled. It uses the Sonnet model by default because the CLI's own default model burns through plan limits much faster. Set a different model in settings if you want.
[!NOTE] The plugin invokes
claude -p(print mode). Anthropic has announced (currently paused) plans to bill programmatic usage likeclaude -pseparately from Pro/Max subscription limits, as extra usage at API rates. If that change ships, plugin usage may no longer be covered by your plan.
npm install -g @google/gemini-cli
gemini # run once to log in
The plugin runs Gemini with --approval-mode plan, so it cannot modify files.
npm install -g @openai/codex
codex login
The plugin runs codex exec --sandbox read-only and reads the final message from a file in the plugin folder, since Codex interleaves progress logs on stdout.
Install Ollama from ollama.com (installers for all three OSes), then:
ollama pull llama3 # or any model you prefer
Keep Ollama running, set the provider to Ollama, and set the model name in settings. The default URL is http://localhost:11434.
Use Ollama when your notes must never leave your machine or you do not want a subscription. The cloud CLIs generally produce better notes; local quality depends on the model you pull.
You need the Obsidian desktop app on Windows, macOS, or Linux, plus one AI backend. The plugin does not work in the Obsidian mobile app because it needs to run local programs on your computer.
Node.js 16+ and npm are needed only for a CLI backend (Claude, Gemini, Codex) or to build from GitHub.
Once the plugin is available in the community directory:
git clone https://github.com/algometrix/second_brain_builder.git
cd second_brain_builder
Then run install.bat on Windows, or ./install.sh on macOS and Linux. Both build the plugin and auto-detect your vaults from Obsidian's config, with a manual path prompt as fallback. Requires Node.js 16+.
| File | What it is | |
|---|---|---|
| 📜 | main.js | The plugin |
| 🧾 | manifest.json | The plugin manifest |
| 🎨 | styles.css | The plugin styles |
Copy all three into .obsidian/plugins/second-brain-builder/ inside your vault:
| OS | Typical destination |
|---|---|
| Windows | C:\Users\<you>\Documents\MyVault\.obsidian\plugins\second-brain-builder\ |
| macOS | ~/Documents/MyVault/.obsidian/plugins/second-brain-builder/ |
| Linux | ~/Documents/MyVault/.obsidian/plugins/second-brain-builder/ |
Modes define the teaching styles offered in the note creation modal. The plugin ships 24 general-purpose modes, and you can add your own in the plugin settings without rebuilding. Those are stored in the vault's plugin data.
| Mode | Best for |
|---|---|
| Explain | Default detailed reference note |
| Deep Inquiry | Critical analysis, trade-offs, stress tests |
| Feynman Teacher | Intuition-first teaching with analogies |
| Book Summarizer | Chapter-by-chapter book notes |
| Researcher | Evidence, competing perspectives, open questions |
| Flashcard Maker | Q&A cards for spaced repetition |
| Compare & Contrast | Side-by-side comparison of options |
| Cheat Sheet | Condensed quick reference |
| Socratic Guide | Question-driven exploration |
| Cornell Notes | Cues, notes, and summary layout |
| Glossary Builder | Term definitions and relationships |
| Debate | Arguing all sides of a question |
| How-To Guide | Step-by-step practical instructions |
| Mind Map | Hierarchical concept map |
| ELI5 | Absolute-beginner explanation |
| Timeline | Chronological history of a concept |
| Devil's Advocate | Challenging assumptions |
| Project Breakdown | Phases, tasks, and milestones |
| Case Study | Real-world case analysis |
| Question Generator (full note) | Appending review questions to a finished note |
| Active Recall Prep (full note) | Fill-in-the-gap study exercises |
| Lesson | One scoped skill: minimal knowledge, retrieval practice, reference card |
| Deep Dive (General) | Long-form, evidence-based deep dives |
| Learning Path & Resources | Curated beginner-to-expert learning paths |
Modes live in modes.json, which is bundled into the plugin at build time. It is not committed to the repository. scripts/sync-modes.js resolves it before every build:
modes.config.json exists, its modesFile is copied to modes.json.modes.json is used as-is.modes.sample.json is copied to modes.json.A fresh clone builds with the sample modes and needs no setup. To maintain your own:
cp modes.sample.json modes.personal.json # then edit it
Create modes.config.json:
{
"modesFile": "modes.personal.json"
}
Rebuild. Both files are gitignored, so your prompts stay private.
| Field | Required | Meaning |
|---|---|---|
id |
yes | Unique identifier |
name |
yes | Shown in the mode picker |
icon |
yes | A Lucide icon name |
description |
yes | One-line summary shown in the picker |
prompt |
yes | The system prompt. {selection} and {context} are replaced at run time |
isDefault |
no | Preselect this mode |
fullNote |
no | Mode operates on the whole note (used by "Analyze current note") and {context} is the full note content |
folderDecompositionGuide |
no | Guides how folder generation splits the topic into notes |
analyzesExisting |
no | Mode analyzes existing content rather than generating new content |
| Setting | Description | Default |
|---|---|---|
| AI provider | claude, gemini, codex, or ollama |
claude |
| Claude CLI path | Path to the claude executable |
claude |
| Claude model | Model override (e.g. opus, claude-sonnet-4-6) |
sonnet |
| Gemini CLI path / model | Same, for Gemini | gemini / (default) |
| Codex CLI path / model | Same, for Codex | codex / (default) |
| Ollama server URL / model | Local API endpoint and model name | http://localhost:11434 / llama3 |
| Preferred mode | Mode preselected when you have not used one yet | (none) |
| Enable logging | Keep an in-memory log for "View logs" | on |
| Custom modes | Add or edit modes without rebuilding | (none) |
LLMs occasionally emit markdown that Obsidian renders badly, mostly around mermaid diagrams and callouts. The scripts/ folder has standalone fixers that scan every .md file in a vault, report problems, and optionally repair them.
Run fix-all.js without --fix after a large batch generation, or when a mermaid block shows a syntax error. Review the report, then re-run with --fix.
node scripts/fix-all.js "/path/to/YourVault" # detect only, all fixers
node scripts/fix-all.js "/path/to/YourVault" --fix # apply all fixes
node scripts/fix-mermaid-end.js "/path/to/YourVault" # run a single fixer
[!WARNING] Back up your vault (or commit it) before applying fixes in bulk.
The vault path comes from the first argument, the OBSIDIAN_VAULT environment variable, or an OBSIDIAN_VAULT= line in a gitignored .env file at the repo root. Scripts are detect-only unless you pass --fix.
| Script | Fixes |
|---|---|
fix-all.js |
Runs every fixer below in the correct order |
fix-callout-fences.js |
Code fences inside callouts missing the > prefix |
fix-currency-dollars.js |
Unescaped $ currency signs that Obsidian reads as LaTeX |
fix-mermaid-end.js |
Extra end keywords with no matching block opener |
fix-mermaid-missing-end.js |
Missing end keywords and closing fences not on their own line |
fix-split-end.js |
Words like "Send" split across lines by an old regex bug |
fix-mermaid-parens.js |
Unquoted mermaid node labels containing parentheses or slashes |
fix-mermaid-quotes.js |
Nested double quotes inside quoted mermaid labels |
fix-mermaid-list.js |
"Unsupported markdown: list" errors in mermaid labels |
fix-mermaid-sequence-note.js |
Sequence diagram notes that wrapped onto a list line, which cause got '1' parse errors |
Privacy. The selected text and surrounding note content go to whichever backend you configure. With Claude, Gemini, or Codex, that means the provider's cloud service, under your own account and their terms. With Ollama, everything stays on your machine. The plugin itself collects nothing.
Security. The plugin spawns the AI CLI you configure, which is why Obsidian shows a "shell execution" notice for it. The design limits what that process can do:
--disallowedTools (no file edits, no shell), Gemini with --approval-mode plan, Codex with --sandbox read-only.| Problem | Fix |
|---|---|
| "command not found" / spawn error | Put the absolute CLI path in settings. Find it with where claude (Windows) or which claude (macOS/Linux) |
| CLI works in terminal but not in Obsidian (macOS/Linux) | Apps launched from the dock do not inherit your shell PATH. Use the absolute path in settings, e.g. /usr/local/bin/claude or ~/.nvm/versions/node/<ver>/bin/claude |
| CLI path with extra words (macOS/Linux) | The path setting must be a single executable path. Commands like node /x/codex.js or FOO=1 claude are not run through a shell; wrap them in a small script with a shebang and point the setting at it |
| Windows path | npm installs usually land at C:\Users\<you>\AppData\Roaming\npm\claude.cmd |
| Empty or garbled output | Verify the CLI works standalone first, e.g. claude -p "hello" |
| Ollama errors | Check the server is running: curl http://localhost:11434 and that the model is pulled |
| Timeout | Large contexts are slow; select less text or use a faster model |
Build fails on modes.json |
Run node scripts/sync-modes.js, or check that the path in modes.config.json exists |
claude -p usage separately from Pro/Max limits.
Found a bug or want a feature? Open an issue. The View logs command shows recent plugin activity, which helps explain what went wrong.
[!IMPORTANT] Logs and examples can include your note text. Remove anything private before you post them.
You need Node.js 16+ and npm.
npm install
npm run dev # watch mode, rebuilds on save
npm run build # type-check and production bundle
npm run build produces main.js. Copy main.js, manifest.json, and styles.css into your vault as shown in Install. Use the Hot-Reload plugin for instant reloads in Obsidian.
src/
main.ts plugin class: commands, menus, generation queue, providers
types.ts shared interfaces, settings and defaults
inline-actions.ts the catalog of inline actions
output-rules.ts formatting rules appended to every prompt
fixers.ts post-processing for generated output
cli.ts typed boundary around spawning a CLI
logger.ts in-memory log behind the "Enable logging" setting
utils.ts filename sanitizing, JSON extraction, empty-note detection
ui.ts shared modal helpers
settings-tab.ts settings UI and per-provider setup guides
modals/ one file per modal family
scripts/ build helpers and vault fix scripts
modes.sample.json the sample note modes
styles.css modal and queue styles
Second Brain Builder is released under the MIT License.
If the plugin is useful to you, a ⭐ helps other people find it.