second_brain_builder: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

An Obsidian plugin ("Second Brain Builder") that generates detailed explanation notes using Claude Code CLI, Gemini CLI, Codex CLI, or a local Ollama server. Users select text in a note, pick a teaching style (mode), and the plugin spawns the CLI to produce a new note or inline enhancement. Desktop only; supports Windows, macOS, and Linux.

Beauty Review

This is a TypeScript codebase. When reviewing code here (/code-review, or any request to review, critique, or audit changes), invoke the global ts-js-beauty-reviewer agent alongside any other reviewers. It judges intent, scope, type-level contracts, async/error handling, tests, and measured performance — not just lint. Run it on the changed .ts files; treat its correctness and security findings as must-fix and its taste notes as suggestions.

Build Commands

npm install          # install dependencies
npm run build        # type-check (tsc -noEmit) + production bundle
npm run dev          # esbuild watch mode (rebuilds on save)

The build produces main.js (CJS bundle) from the single entry point main.ts via esbuild. Use the Hot-Reload plugin in Obsidian for live dev.

Project Structure

Source lives in src/, bundled to a single root main.js by esbuild (entry point src/main.ts).

• src/main.ts -- ClaudeExplainerPlugin: commands, context menus, the generation queue, CLI/Ollama providers, note orchestration
• src/types.ts -- shared interfaces: modes, inline actions, queue items, settings (+ defaults), provider labels
• src/inline-actions.ts -- the INLINE_ACTIONS catalog (expand, simplify, add diagram, ...)
• src/output-rules.ts -- formatting rules appended to every prompt (getOutputRules, inline/append variants)
• src/cli.ts -- typed child_process.spawn boundary (SpawnedCliProcess, spawnCli)
• src/logger.ts -- in-memory ring logger behind the "Enable logging" setting
• src/utils.ts -- filename sanitizing, JSON array extraction, empty-note detection
• src/ui.ts -- shared modal helpers (title, mode cards, searchable mode grid)
• src/fixers.ts -- output post-processing fixers (code fences, mermaid, callouts, dataview, currency)
• src/modals/ -- one file per modal family: generation.ts, folder.ts, analysis.ts, queue.ts, system-design.ts
• src/settings-tab.ts -- the settings UI, including per-provider setup guides
• modes.json -- note generation modes loaded as BUILTIN_MODES at build time. Gitignored; resolved before every build by scripts/sync-modes.js (from modes.config.json's modesFile if present, else an existing modes.json, else modes.sample.json)
• modes.sample.json -- committed sample set of general-purpose modes (Explain, Deep Inquiry, Feynman, etc.); the default build input for fresh clones
• modes.config.json -- optional, gitignored; { "modesFile": "<path>" } points the build at a personal modes file (conventionally modes.personal.json, also gitignored)
• styles.css -- modal and queue UI styles
• manifest.json -- Obsidian plugin manifest (id: second-brain-builder)
• scripts/ -- build helpers and vault fix scripts:
  • sync-modes.js -- prepares modes.json before builds (see above); wired into npm run build and npm run dev
  • vault-root.js -- shared vault path resolution for the fix scripts (first non-flag CLI argument, OBSIDIAN_VAULT env var, or OBSIDIAN_VAULT= in a gitignored repo-root .env)
  • fix-all.js -- unified runner that executes all fix scripts below in order
  • fix-callout-fences.js -- fixes callout code fences missing the > prefix on closing ``` or content lines
  • fix-currency-dollars.js -- escapes unescaped $ currency signs that Obsidian misinterprets as LaTeX
  • fix-mermaid-end.js -- strips extra end keywords with no matching block opener (subgraph, or sequence-diagram par/alt/opt/loop/rect/critical/break/box) and inserts zero-width space into "end" inside larger words
  • fix-mermaid-missing-end.js -- re-inserts missing end keywords (indentation-based placement) and puts the closing ``` fence on its own line
  • fix-split-end.js -- rejoins lines corrupted by an old regex that split words like "Send" into "S\nend"
  • fix-mermaid-parens.js -- quotes unquoted mermaid node labels containing parentheses or slashes
  • fix-mermaid-quotes.js -- strips nested double quotes inside already-quoted mermaid labels (inner " to ')
  • fix-mermaid-list.js -- fixes "Unsupported markdown: list" errors by converting N./N) to N: in labels and joining - item lines with <br/>
  • fix-mermaid-sequence-note.js -- in sequenceDiagram blocks, folds a note/message whose text wrapped onto a following list line (1./1)/-/*) back into the preceding line joined with <br/> (converts N./N) to N:, strips bullets); fixes got '1' parse errors from lines starting with a bare number