William Wasenmiller120 downloadsSee your vault as a 3D black hole. Notes orbit as stars grouped by folder, tag or links, and selecting a star opens the note.
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:
It is only the visual. It has no note-taking app, AI or sync built in.
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.
The plugin shows your vault as the black hole in an Obsidian tab. Desktop only (Windows, Mac and Linux).
Or open its page in the Obsidian community directory and select Add to Obsidian.
Open Settings → Second Brain Black Hole:
Templates.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.
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.
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 system when you run npm: type npm.cmd instead of npm, for example npm.cmd install --omit=dev."C:\My Notes", not "C:\My Notes\". Shift + right-click a folder → Copy as path gives you a quoted path..bat: Windows warns about any downloaded script. Click More info → Run anyway. You can open the .bat in Notepad first to read it; it's short.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.
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:
.md file 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: in front matter ([a, b], a, b, or a - a list) and #tags in the text (not inside code).title: or updated: in front matter, or the first # Heading. File dates are used otherwise.Options:
--owner "Name" sets the name under the heading.--open opens the map in your browser when it's done.--cluster auto|folders|tags|links picks how notes are grouped (default auto, described above). It prints which one it used.--out file.html sets the output file (default my-brain.html).--max 500 caps 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.json also saves the graph data.--help shows all of this with examples.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.
None of this is needed to use the map.
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 lint checks the code with the same rules as Obsidian's plugin review.npm run test:plugin writes test vaults to test-vaults/ (open them in Obsidian to try things by hand) and builds test-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 example npx http-server test-vaults.npm version 0.2.0 (it updates manifest.json and versions.json too), then push the tag with git push origin 0.2.0. A GitHub Action builds the plugin and attaches main.js, manifest.json and styles.css to 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.
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.
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]]
}
regions are the clusters; names must match each node's region. About six reads best.edges are pairs of node indexes. degree is each node's link count.html is inserted as HTML, so escape or sanitize it first.ideas is optional: the headings inside the note.MIT. See LICENSE.