README file from
GithubSecond Brain Black Hole
A 3D map of your notes. One black hole sits in the middle, your notes orbit it as stars, and light bends around it. It runs on the GPU, fully on your computer: no server, no tracking, no network requests.
There are two ways to use it:
- Use it in Obsidian: a plugin in Obsidian's community plugin list that shows your vault as the black hole in its own tab. No terminal needed.
- Use it with any notes folder: turn a folder of Markdown files into one HTML file you can open in a browser.
It is only the visual. It has no note-taking app, AI or sync built in.
Try the demo
Live demo: https://williamwasen.github.io/second-brain-black-hole/
It shows 14 made-up notes. Drag to rotate, scroll to zoom, click a star to read it. To run it offline, open docs/index.html in Chrome, Edge, Safari or Firefox.
Use it in Obsidian
The plugin shows your vault as the black hole in an Obsidian tab. Desktop only (Windows, Mac and Linux).
Install
- In Obsidian, open Settings → Community plugins. If asked, select Turn on community plugins.
- Select Browse, search for Second Brain Black Hole, then select Install and Enable.
- Select the orbit icon in the left sidebar, or open the command palette (Ctrl+P, or Cmd+P on Mac) and run Open black hole map.
Or open its page in the Obsidian community directory and select Add to Obsidian.
Using it
- Drag to rotate, scroll to zoom. Point at a star to see its note's name.
- Select a star to open the note. Ctrl-click (Cmd-click on Mac) opens it in a new tab.
- Select a group's name to fly to that group. To go back out, select ← All groups (top left) or press Esc.
- Select Home (top left) or the black hole to open the dashboard: note, idea and link counts, notes updated per day, ideas by group and your most connected notes. Select a group or note there to jump to it. Press Esc, select ×, or select Home again to close it.
- To change the chart color, select the palette icon next to × on the dashboard. Drag in the color square and hue slider, type a hex code, or pick a swatch (the half-filled one uses your theme's accent color). Select Save changes to keep it, or Revert to undo.
- The map updates by itself when you add, rename, link or delete notes, so there's nothing to schedule or rebuild.
Settings
Open Settings → Second Brain Black Hole:
- Group notes by: Automatic uses your top-level folders if you have two or more, then tags if at least half your notes have one, then groups of notes that link to each other. You can also pick Top-level folders, Tags or Groups of linked notes. At most six groups are shown: the five biggest plus "Other".
- Maximum notes: big vaults show only the most connected notes (default 500). Lower it if the map feels slow.
- Excluded folders: one folder per line, for example
Templates. - Show unlinked notes: turn off to hide notes with no links.
- Reset camera: moves open maps back to the starting view.
Privacy
Everything stays on your computer. The plugin reads Obsidian's own index of your vault (note names, links, tags and headings) to draw the map. It makes no network requests, has no telemetry, and never changes your notes. Its settings are saved in the plugin's own data.json.
Use it with any notes folder
Easiest way: if you have Claude Code or the Claude desktop app (they can run commands on your computer), paste this:
Install the 3D notes viewer from https://github.com/williamwasen/second-brain-black-hole and build it from my notes. First ask me two things: my computer type (Windows, Mac or Linux) and the full path to my notes folder. Then install Node.js 18 or newer if it's missing (ask me first), download the repo, run npm install, and run the importer on my folder with --open. Only read my notes: never modify, move or delete them. Explain each step in plain words. When it's done, tell me where my-brain.html is, and remind me it contains the full text of my notes, so I shouldn't upload or share it.
Or do it yourself. You need Node.js 18 or newer. The LTS download is fine.
Windows
- Install the LTS version of Node.js from nodejs.org with the default options.
- On this repo's GitHub page, click Code → Download ZIP. No git needed. Right-click the ZIP → Extract All.
- In the unzipped folder, double-click
Build My Brain (Windows).bat. Pick your notes folder, type a name, and the map opens in your browser.
Prefer typing? Open PowerShell in the unzipped folder (right-click the folder → Open in Terminal) and run:
npm install --omit=dev
node scripts\import-markdown.mjs "C:\Users\You\Documents\Notes" --owner "Your Name" --open
If something goes wrong:
'node' is not recognized: Node.js isn't installed, or the window was opened before you installed it. Install the LTS version, then close and reopen PowerShell (or sign out of Windows and back in).running scripts is disabled on this systemwhen you runnpm: typenpm.cmdinstead ofnpm, for examplenpm.cmd install --omit=dev.- Paths with spaces: put the whole path in double quotes and don't end it with a backslash:
"C:\My Notes", not"C:\My Notes\". Shift + right-click a folder → Copy as path gives you a quoted path. - "Windows protected your PC" when you open the
.bat: Windows warns about any downloaded script. Click More info → Run anyway. You can open the.batin Notepad first to read it; it's short.
Mac and Linux
git clone https://github.com/williamwasen/second-brain-black-hole.git
cd second-brain-black-hole
npm install --omit=dev
npm run import -- ~/Documents/Notes --owner "Your Name" --open
No git? Code → Download ZIP works here too.
What you get
The importer writes my-brain.html in the repo folder. --open opens it in your browser; otherwise double-click it.
It contains the full text of your notes. It is git-ignored here, but don't upload or share it unless you want your notes public.
What the importer understands:
- Every
.mdfile in the folder, including subfolders. Hidden folders (like.obsidian) are skipped, and so are folders it doesn't have permission to read. [[wiki links]],[[Note|alias]], and normal relative links between notes. Each link becomes a connection.- Tags:
tags:in front matter ([a, b],a, b, or a- alist) and#tagsin the text (not inside code). - Clusters: if your notes are in two or more top-level folders, the folders become the clusters. Otherwise it groups by tags (if at least half your notes are tagged), then by groups of linked notes. If there are more than six clusters, the five biggest stay and the rest are grouped as "Other".
- A
title:orupdated:in front matter, or the first# Heading. File dates are used otherwise. - Raw HTML in notes is shown as plain text, never run.
Options:
--owner "Name"sets the name under the heading.--openopens the map in your browser when it's done.--cluster auto|folders|tags|linkspicks how notes are grouped (defaultauto, described above). It prints which one it used.--out file.htmlsets the output file (defaultmy-brain.html).--max 500caps how many notes are drawn (default 500, keeping the most connected). Large vaults are untested for speed, so lower this if it feels slow.--json graph.jsonalso saves the graph data.--helpshows all of this with examples.
Automate it (notes-folder version only)
Using Obsidian? Skip this section. The plugin already updates the map by itself whenever you add, rename, link or delete notes. This section is only for the notes-folder version, which makes a fixed file you have to rebuild.
Want it to refresh nightly, pull from Notion, Apple Notes, Google Drive or chat exports, or have an AI link and summarize your notes? That part depends on your setup, so it isn't included. PROMPT.md has a prompt you can paste into Claude to build it for you, step by step.
Notes
- The sky and stars are generated by shaders at startup. No photo is used.
- Lensing is physically inspired, not an exact relativistic simulation.
- The HTML version remembers your last visit and recent pages in your browser's local storage so new notes can glow.
- Needs a browser with WebGL2.
For developers
None of this is needed to use the map.
Build the plugin yourself
npm install
npm run build:plugin
That type-checks the plugin and writes main.js and styles.css to the repo folder. To try it, copy them with manifest.json into <your vault>/.obsidian/plugins/second-brain-black-hole/, or link this folder there and run npm run dev:plugin, which rebuilds on every change.
npm run lintchecks the code with the same rules as Obsidian's plugin review.npm run test:pluginwrites test vaults totest-vaults/(open them in Obsidian to try things by hand) and buildstest-vaults/harness.html, which runs the plugin against a stand-in for Obsidian's API in a browser. Open it through a local web server, for examplenpx http-server test-vaults.- Releases: run
npm version 0.2.0(it updatesmanifest.jsonandversions.jsontoo), then push the tag withgit push origin 0.2.0. A GitHub Action builds the plugin and attachesmain.js,manifest.jsonandstyles.cssto a draft release for you to publish. Obsidian picks up each published release and reviews it automatically.
Code layout: the visual lives in src/ (blackhole.js and the WebGL files it uses), shared by the HTML page (src/prototype.html and src/app.mjs) and the plugin (obsidian/). src/graph.js holds the grouping rules both use.
Use the map in your own page
src/blackhole.js is an ES module:
import { createBlackHole } from './src/blackhole.js';
const map = createBlackHole(element, graph, {
onSelect: (node, { event }) => { /* a star was clicked; node is null for empty space */ },
readingPanel: false, // false: clicks only call onSelect, so you show notes your own way
});
map.update(newGraph); // new data, same WebGL contexts
map.resize();
map.destroy(); // frees every WebGL context, animation frame and listener
Include src/blackhole.css. graph uses the format below; see src/blackhole.d.ts for every option and method.
Data format
You can skip the importer and write the graph yourself. See data/sample-graph.json, then:
node scripts/build.mjs path/to/graph.json out.html
{
"owner": "Your Name",
"regions": { "Projects": { "center": [x, y, z], "spread": [x, y, z], "density": 850 } },
"nodes": [
{ "title": "...", "category": "Note", "region": "Projects", "path": "...", "url": "#",
"status": "unknown", "updated": "2026-11-01", "modified": 1793500000000,
"html": "<p>Page text as safe HTML</p>", "ideas": ["Section title"],
"position": [x, y, z], "degree": 3 }
],
"edges": [[0, 1], [1, 2]]
}
regionsare the clusters; names must match each node'sregion. About six reads best.edgesare pairs of node indexes.degreeis each node's link count.htmlis inserted as HTML, so escape or sanitize it first.ideasis optional: the headings inside the note.
License
MIT. See LICENSE.