Second Brain OS: Build a Self-Organizing Knowledge Base with Claude Code

Who It's For

• For anyone who wants to use Claude Code to build a self-organizing knowledge base: you collect articles and notes and want them to be automatically extracted, cross-linked, and kept tidy — instead of piling up into a heap of files nobody revisits.
• It provides a complete guide, an initial vault, agent skills, and scripts, running on markdown files, wikilinks, and SKILL.md; it also works with any agent that reads files. Obsidian is just a graph viewer, not a dependency.
• When it's not a fit: if you want an out-of-the-box graphical note-taking app and aren't willing to clone a repo, copy directories, and run an agent in a terminal, this workflow isn't for you. The official evidence doesn't state which clients beyond the specific agents mentioned it supports, which text languages it supports, or whether there are restrictions beyond being free and requiring no account — it's free and requires no registration, but other boundaries are unknown.

Your First Try in 3 Minutes

The official main path is to install locally to ~/brain in a terminal, then launch Claude Code in that directory:

1. Prerequisites: git and Claude Code (the agent) installed; Obsidian is recommended as well so you can view the graph.
2. Run the official installation commands in the terminal to copy the initial vault along with the skills, commands, and agents into ~/brain/.claude:

git clone https://github.com/undefined-ui/second-brain-os.git
cp -r second-brain-os/vault-template ~/brain

mkdir -p ~/brain/.claude
cp -r second-brain-os/skills   ~/brain/.claude/skills
cp -r second-brain-os/commands ~/brain/.claude/commands
cp -r second-brain-os/agents   ~/brain/.claude/agents

cd ~/brain && claude

1. Side effects and checkpoints: the commands above create ~/brain in your home directory and write files there; if the target already exists, check first whether you want to overwrite it.
2. Trigger a low-risk first task: save or clip an article as a file in the raw/ directory, then type /ingest in Claude Code. This is the official core workflow: the agent ingests, extracts, builds links, and cleans up the raw material, organizing it into an interlinked wiki. It reads and writes the markdown files inside the vault; whether it executes commands or accesses the network is not stated in the official evidence and should be treated as unknown. If the article contains sensitive content, redact it before putting it in raw/.
3. Success signal: the article in raw/ gets organized into note pages with wikilinks inside the vault; the official rule is "Nothing is ingested until it is linked" — if linking isn't completed in the same round, ingestion isn't finished. So check whether the new page actually contains links pointing to other notes; that's the criterion for whether the /ingest round is complete. The official evidence doesn't state which check passes /ingest performs internally or whether there are different flows for different text types — do not assume.

Use Cases

Case 1: Archiving collected articles. You clip articles in your browser but never look at them again. Scenario: clip an article and save it to ~/brain/raw/, then run /ingest in Claude Code. It follows the official ingest workflow — extracting key points, linking to existing notes, and cleaning up. Expected outcome: the raw file is turned into a linked wiki page; if you find the new page lacks links, per the official rule the round counts as incomplete and you can ask the agent to add the missing links.

Case 2: Viewing the knowledge graph in Obsidian. Scenario: after a few ingests, you want to verify the connections between notes. How to: open ~/brain as a vault in Obsidian (Obsidian is the officially stated graph viewer) and browse the graph formed by notes and wikilinks. What you can confirm: the vault is pure markdown and wikilinks, and Obsidian can open it directly and display the graph; the official documentation doesn't describe any deeper automation or sync behavior, so don't expect integration beyond a viewer.

Boundaries of Use

• File access: installation and running create and modify local markdown files (~/brain, raw/, and the .claude directory); this is core to the workflow, not an optional side effect.
• Commands and network: the official evidence only provides the shell installation commands above; whether the agent executes other commands or accesses the network during ingest is not stated in the evidence and is unknown.
• Checkpoints: review sensitive material yourself before putting it in raw/; confirm yourself before overwriting an existing ~/brain.
• Runtime environment: requires a local terminal, git, and an agent that reads files (the official main path uses Claude Code); Obsidian is needed to see the graph view, but it is not a dependency. Beyond this, the official documentation lists no other runtime restrictions.
• Unverified key information: whether the list of supported agents is limited to Claude Code (the official docs only say it works with Claude Code and any agent that reads files), which text languages are supported, and which commands besides /ingest are available — none of these have evidence. Before use, you can check the actual files in the skills and commands directories yourself to confirm.