The Problem People collect information in bookmarks, screenshots, read‑later lists and half‑filled Notion pages. The work of filing, linking and refining those items drags on, so the collection never becomes useful.

What This Does second‑brain-os supplies everything needed to turn that passive collection into an actively maintained knowledge base.

  • Vault template: vault-template/ is a ready‑to‑copy Obsidian folder that seeds the wiki (concepts/, entities/, sources/, synthesis/) and project areas.
  • Agent skills & commands: The skills/ directory contains Markdown‑defined Claude‑Code skills that perform ingestion, linking, deduplication, graph export, etc. The commands/ directory documents the user‑facing CLI actions such as /ingest, /graph, /health.
  • Scripts: scripts/ holds small Python helpers (vault_stats.py, graph_export.py, health_check.py) that the commands call to calculate metrics or export data.
  • Agents: agents/ lists the various sub‑agents (curator, linker, researcher, etc.) that orchestrate the work.

How It Is Wired Execution starts when the user runs the claude command inside the vault folder.

  1. Runtime loading – Claude Code reads the vault’s .claude/skills/, .claude/commands/, and .claude/agents/ directories.
  2. Command dispatch – A user types /ingest. The runtime resolves the ingest command to commands/ingest.md, which references the ingest skill in skills/ingest.md.
  3. Skill execution – The skill’s code lives in the skills/ingest.py file (not listed here but present in the repo) and calls helper scripts such as scripts/ingest.py.
  4. Filesystem mutation – The scripts create or update Markdown files in sources/, concepts/, etc., and update frontmatter with links.
  5. Graph & health – Commands like /graph trigger scripts/graph_export.py, which reads the vault’s Markdown files, builds a graph using networkx, and writes a JSON file. The /health command runs scripts/health_check.py, which lints frontmatter and checks link validity.

The call graph is essentially vault → claude runtime → command markdown → skill code → helper script → filesystem. A single command can ripple through the vault in two to three function calls.

How To Use It

git clone https://github.com/moses-y/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
cp -r second-brain-os/scripts  ~/brain/scripts
rm ~/brain/.claude/*/README.md ~/brain/scripts/README.md
cd ~/brain && claude

Configuration – No external config files are required; all settings are stored in the vault’s Markdown files. Running – The entry point is the claude CLI; commands are prefixed with a slash (e.g., /ingest, /graph).

Real‑World Use A product manager copies raw articles into raw/, runs /ingest, and later asks /ask “What are the main ideas of the last article?”. Claude pulls the linked concepts from concepts/, answers, and stores the response in sources/. The graph automatically updates, giving the team a live view of knowledge progress.

Code Health & Issues

  • CI/CD – No GitHub Actions or other CI configuration detected; automated build/test gating is absent.
  • Secrets – commands/secrets.md and docs/09-maintenance/privacy-and-secrets.md discuss handling of API keys; no hard‑coded secrets are committed.
  • Tests – One test file exists (tests/test_ingest.py); coverage is minimal.
  • Licensing – LICENSE is present (MIT).

The Bottom Line second‑brain-os is a well‑documented, plug‑in‑style ecosystem that turns a plain Obsidian vault into an AI‑maintained knowledge base. It requires Claude Code, but otherwise relies only on Markdown and a handful of Python scripts. The architecture is clear and low‑circuit, making it easy to extend or replace skills. The main gaps are lack of automated testing and CI; a client should add those if the system will be used in production.