Fastest way to scaffold your LLM powered personal knowledge base - Obsidian, Claude Code, qmd, Github
JavaScript aiampclaude-codecodexcursorgithubknowledge-baseknowledge-graphknowledge-managementllmobsidianobsidian-vaultqmdsecond-brain
feat: auto-register qmd collections + add CLI reference docs
jessepinkman99002c717d71ce08
diff --git a/.github/workflows/pack-test.yml b/.github/workflows/pack-test.ymlindex 94ec7c5..969470d 100644--- a/.github/workflows/pack-test.yml+++ b/.github/workflows/pack-test.yml@@ -75,6 +75,7 @@ jobs:check "~/.claude/skills/brain-ingest/.csb-version" "$HOME/.claude/skills/brain-ingest/.csb-version"check "~/.claude/skills/brain-search/.csb-version" "$HOME/.claude/skills/brain-search/.csb-version"check "~/.claude/skills/brain-refresh/.csb-version" "$HOME/.claude/skills/brain-refresh/.csb-version"+ check ".qmd/index.sqlite (created by auto qmd:setup)" "$VAULT/.qmd/index.sqlite"grep_check() {local label="$1"diff --git a/bin/create.js b/bin/create.jsold mode 100644new mode 100755index 449d570..3303a74--- a/bin/create.js+++ b/bin/create.js@@ -687,6 +687,28 @@ async function createBrain(initialName) {if (pnpmOk) spin.stop("dependencies installed")else spin.stop("pnpm install failed — run it manually inside your vault", 1)+ // Register qmd collections + contexts. Skip reindex — first reindex downloads+ // ~2GB of GGUF models; user runs it explicitly when ready.+ if (pnpmOk) {+ let doQmdSetup = true+ if (isInteractive) {+ const ok = await p.confirm({+ message: "Register qmd collections now? (wiki + raw-sources)",+ initialValue: true,+ })+ if (p.isCancel(ok)) { p.cancel("Setup cancelled."); process.exit(0) }+ doQmdSetup = ok+ }+ if (doQmdSetup) {+ spin.start("Registering qmd collections (wiki, raw-sources)")+ const qmdOk = run(["mise", "exec", "--", "pnpm", "qmd:setup"], targetDir)+ if (qmdOk) spin.stop("qmd collections registered")+ else spin.stop("pnpm qmd:setup failed — run it manually inside your vault", 1)+ } else {+ p.log.info("Skipped qmd:setup — run `pnpm qmd:setup` from the vault root when ready.")+ }+ }+// Install global skills (version-aware — prompts to update when versions differ)spin.start("Installing global Claude skills")const skillResult = await installGlobalSkills({ isInteractive })@@ -777,7 +799,8 @@ async function createBrain(initialName) {const nextSteps = [`${pc.cyan(`cd ${brainDisplayPath}`)}`,- `${pc.cyan("claude")} open Claude Code, then run ${pc.bold("/setup")}`,+ `${pc.cyan("pnpm qmd:reindex")} ${pc.dim("# first run downloads ~2GB of embedding models")}`,+ `${pc.cyan("claude")} open Claude Code and start ingesting sources`,...remoteSteps,].join("\n")diff --git a/docs/pages/cli.mdx b/docs/pages/cli.mdxnew file mode 100644index 0000000..b0dced7--- /dev/null+++ b/docs/pages/cli.mdx@@ -0,0 +1,92 @@+# CLI Reference++The `claude-second-brain` CLI creates and manages brains registered in `~/.claude-second-brain/config.toml`. Run it via `npx claude-second-brain`, `pnpm dlx claude-second-brain`, or — if installed globally with `npm i -g claude-second-brain` — the shorter `csb` alias.++All examples below use `claude-second-brain`; substitute `csb` if you've installed it globally.++## Commands++| Command | Description |+|---|---|+| `claude-second-brain` | Create a new brain (interactive). |+| `claude-second-brain <name>` | Create a new brain named `<name>`, skipping the name prompt. |+| `claude-second-brain ls` | List all registered brains. The default brain is marked with `*`. |+| `claude-second-brain rm <name>` | Delete a brain directory and remove its entry from `config.toml`. |+| `claude-second-brain path [flags]` | Print the path of the default (or named) brain. |+| `claude-second-brain qmd [flags] -- …` | Run `qmd` against the default (or named) brain. |+| `claude-second-brain help` | Show usage. |++`ls` is also available as `list`, and `rm` as `remove`.++## Create a brain++```bash+npx claude-second-brain # interactive — prompts for name + remote+npx claude-second-brain my-brain # skip the name prompt+```++Creates the brain at `~/.claude-second-brain/<name>/`, runs `mise install`, `pnpm install`, `pnpm qmd:setup`, `git init`, and registers it in `~/.claude-second-brain/config.toml`. The first brain created is set as the default.++During the interactive flow the CLI asks:++- **Brain name** — defaults to `my-brain`.+- **Git remote** — `GitHub`, `Cloudflare Artifacts`, or `Skip`. See [GitHub](/remotes/github) and [Cloudflare Artifacts](/remotes/cloudflare-artifacts).+- **Repo name** — only shown when a remote is selected; defaults to the brain name.+- **Artifacts namespace** — only shown for Cloudflare; defaults to `default`.+- **Register qmd collections now?** — confirms running `pnpm qmd:setup`.++## List brains++```bash+npx claude-second-brain ls+```++Prints each registered brain with its path, creation date, and git remote. The default brain is shown in bold with a `*` marker.++## Remove a brain++```bash+npx claude-second-brain rm my-brain # prompts for confirmation+npx claude-second-brain rm my-brain --yes # skip the confirmation+npx claude-second-brain rm # interactive — pick from a list+```++Deletes the brain's directory under `~/.claude-second-brain/` and removes its entry from `config.toml`. If you remove the default brain and others remain, the first remaining brain becomes the new default.++Flags:++- `-y`, `--yes` — skip the confirmation prompt.++## Print a path++```bash+npx claude-second-brain path # default brain root+npx claude-second-brain path --qmd # default brain's qmd index+npx claude-second-brain path --config # ~/.claude-second-brain/config.toml+npx claude-second-brain path --brain work --qmd # a specific brain's qmd index+```++Flags:++- `--root` *(default)* — the brain's directory (e.g. `~/.claude-second-brain/my-brain`).+- `--qmd` — the brain's qmd SQLite index (e.g. `~/.claude-second-brain/my-brain/.qmd/index.sqlite`).+- `--config` — the central config path. Ignores `--brain`.+- `--brain <name>` — target a specific brain instead of the default.++Used by the global skills (`/brain-ingest`, `/brain-search`, `/brain-refresh`) to resolve paths at call time so they work from any working directory.++## Run qmd against a brain++```bash+npx claude-second-brain qmd -- query -c wiki "distributed systems"+npx claude-second-brain qmd --brain work -- search -c wiki "kafka"+```++Forwards all arguments after `--` to `npx @tobilu/qmd`, with `INDEX_PATH` set to the resolved brain's qmd index. Flags:++- `--brain <name>` — target a specific brain instead of the default.+- `--` — end of CLI flags; everything after is passed to qmd verbatim.++## Exit status++Every command exits non-zero on failure (invalid brain name, missing config, etc.) and writes the error to stderr.diff --git a/docs/pages/getting-started.mdx b/docs/pages/getting-started.mdxindex 6007443..92a1eed 100644--- a/docs/pages/getting-started.mdx+++ b/docs/pages/getting-started.mdx@@ -57,6 +57,8 @@ Open `~/.claude-second-brain/my-brain/` as a vault in Obsidian — the folder isRun `npx claude-second-brain` (or `csb` if installed globally) again to create additional brains. Each gets its own folder under `~/.claude-second-brain/` and its own isolated qmd index. The global skills (`/brain-ingest`, `/brain-search`, `/brain-refresh`) always operate on the **default brain** in `~/.claude-second-brain/config.toml`. The first brain created is set as the default automatically.+See the [CLI Reference](/cli) for `ls`, `rm`, `path`, and `qmd` subcommands that manage and target specific brains.+## Access from anywhere**Edit anywhere — Claude Code on desktop or mobile.** Claude Code's GitHub integration lets you open the repo and work from anywhere — ingest a source, run a query, or update a page from your phone.diff --git a/template/.claude/skills/setup/SKILL.md b/template/.claude/skills/setup/SKILL.mdindex 029487f..2d0b98e 100644--- a/template/.claude/skills/setup/SKILL.md+++ b/template/.claude/skills/setup/SKILL.md@@ -7,8 +7,8 @@ argument-hint: "Optional: 'reindex' to skip registration and only re-index files# Vault Setup## When to Use-- First-time setup after cloning-- Re-registering qmd collections (e.g., after config changes)+- First-time indexing (collections are already registered by `npx claude-second-brain`)+- Re-registering qmd collections after manual config changes- Re-indexing after a bulk wiki ingest session (run step 2 only)## Procedure@@ -17,14 +17,14 @@ All commands run from the vault root.### Full Setup (first time)-**Step 1 — Register collections and contexts**+**Step 1 — Register collections and contexts** *(already done by the scaffold — re-run only if needed)*Run:```bashpnpm qmd:setup```-Registers the two core qmd collections (`wiki`, `raw-sources`) and their path-level context descriptions. Idempotent — safe to re-run.+Registers the two core qmd collections (`wiki`, `raw-sources`) and their path-level context descriptions. Idempotent — safe to re-run. `npx claude-second-brain` runs this automatically after `pnpm install`, so a fresh vault already has collections registered.**Step 2 — Index files and generate embeddings**diff --git a/vocs.config.ts b/vocs.config.tsindex 53aad7a..0340a1f 100644--- a/vocs.config.ts+++ b/vocs.config.ts@@ -37,6 +37,7 @@ export default defineConfig({sidebar: [{ text: 'Introduction', link: '/' },{ text: 'Getting Started', link: '/getting-started' },+ { text: 'CLI Reference', link: '/cli' },{text: 'Concepts',items: [