version
2.2.0
GitHub stars
13

Install

/plugin install second-brain@pickled-claude-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add technicalpickles/pickled-claude-plugins.

Contents

Discovered from source

Skills 10

Capture

Write a note into the vault from a source the user hands you. One arc, six steps: open (search, fetch, ask why) -> read the primary source -> create through sb -> leave it in the inbox -> link connections -> fold in follow-ups. "Read this and make a note" means all six; the connect step won't happen unless this skill runs it.

Two requests take a different path through the same skill. Decide which one you have before Step 1:

The user wantsPath
A source written up as a new noteSteps 1-6 below
To know what the vault already holds ("do we have notes on X", "find notes about X")Lookup only
Something added to a note that already exists ("add this to the X note", "pull up the note for X", or a "yes, extend it" to Step 1)Extend an existing note

Note shape: references/note-format.md. sb commands: ../obsidian/references/sb-cli.md.

Step 0: Locate the vault

npx @techpickles/sb vault info
npx @techpickles/sb config qmd-collection

Read the vault's own CLAUDE.md if you haven't this session. Its policy (destinations, status vocabulary, disambiguation) overrides the defaults here.

Step 1: Open - search, start the fetch, ask why

Do these in order, then end the turn. Nothing is written yet.

  1. Start reading the source in the background (Bash with run_in_background), using the first rung of references/fetch-ladder.md. Step 2 collects the result.

  2. Search the vault while it runs, through the qmd MCP tools (shelling out to qmd hits Metal-init failures under the sandbox):

    mcp__qmd__query
      searches: [{type: 'lex', query: '<one distinctive term>'},
                 {type: 'lex', query: '<another term>'},
                 {type: 'vec', query: '<what the note would say>'}]
      collections: [<from sb config qmd-collection>]
      intent: '<why you are searching>'
      rerank: false
    

    Each lex is one or two terms, because lex ANDs its terms. Also Glob today's inbox captures (*/11 Inbox*/<YYYYMMDD>*.md), since the qmd index lags same-day notes.

  3. Send one message with: the hits (path + snippet + why each looks strong or weak; qmd scores are only ranks), the question "what made you grab this?", and on a strong match "extend or start a new one?".

  4. End the turn.

Then, keyed to what you observe:

  • The request already states a reason: skip the why question and carry on.
  • The fetch has failed when you send the message: say so there, in one line, and ask the same questions. The why question and the hits don't wait on the fetch.
  • The fetch finishes before a reply: write with **Why I saved this:** TODO.
  • A strong-match question is open: wait for the reply, then write.
  • qmd tools aren't loaded yet: use Grep, say it was keyword-only, and run qmd before writing.
  • A qmd path starts with second-brain/: strip that prefix to get the path on disk.
  • The thing's name is unfamiliar: let the fetch land before the vec query.
  • A search misses, or the user says "that isn't the one": references/search-recovery.md.

Step 2: Read the actual primary source

Never write from search snippets. If Josh names a fetch method, use it or say why you can't.

A few sites have their own playbook. Match the host; anything else goes down the ladder in references/fetch-ladder.md (lightpanda first, WebFetch last):

SourcePlaybook
x.com, twitter.comreferences/sites/x.md
youtube.com, youtu.bereferences/sites/youtube.md
reddit.com, redd.itreferences/sites/reddit.md
Any other URL, PDF, connector sourcereferences/sites/web.md, which points at the ladder

Each playbook also names frontmatter fields to add beside source in Step 3; carry them into the note. New site: add references/sites/<site>.md and one row here.

If you cannot reach the source, or cannot find the thing the user described, stop and say so. No URL you did not load, no title you inferred, no details from background knowledge. "I couldn't find anything matching this" beats a plausible note that is wrong.

Step 3: Create the note through sb

npx @techpickles/sb note create --source auto --title "<title>"   # returns JSON with the path

Then replace the whole file at that path with this skeleton, filled in. Keep captured from sb's scaffold; everything else in the scaffold goes. Add any site fields from the playbook to the frontmatter beside source (see references/note-format.md).

---
status: seedling
tags: [topic-tag, another-tag]
created: YYYY-MM-DD
captured: <from sb's scaffold>
source: <the URL or file path you read>
---

# <Title, in the source's own framing>

<What it is, in a sentence or two, with an inline link to the source.>

**Why I saved this:** <the user's reason, in their words - or TODO>

<The content: 3+ parallel items become bullets with a bold lead-in; every named tool, project,
paper, or doc gets its link from the source; every sentence restates the source.>

## Related

- [[<note a search returned>]] - <why it relates>

Each slot's rules, with a worked example: references/note-format.md. sb owns the path (inbox, timestamp, slug); hand-rolled Write paths once orphaned 46 notes.

Step 4: Leave it in the inbox for process-inbox

The note stays where sb put it: don't ask about routing, don't route it, don't mention that it needs routing. This overrides the vault's "file rough, move on" guidance, which governs notes the user files by hand. Agent-written note on request -> inbox.

The exception is a destination the user named in the conversation ("put it in 66"). Resolve it as route does: sb vault structure, match the phrase to a real destination, then sb note move --from "{note-path}" --to "{destination}/". Never build the path from the user's words alone.

Step 5: Link connections, append the daily breadcrumb

Connection discovery doesn't fire on its own. Run it every time, using the Step 1 results plus a fresh search from the finished note's content. Only the note you just created changes on its own:

  • Confident - add it to the new note, don't ask. The existing note is the same subject (same tool/person/project/event, not a shared theme) or is named in the source. Add it under ## Related with a few words on why, check the target's basename exists first, and say Linked to <note>. in your summary.
  • Everything else is a proposal, never an action. If you can't write the "why" without the words "theme" or "similar", it's a proposal.

Then append the daily breadcrumb yourself, with no yes/no:

npx @techpickles/sb daily append --section "Links" --content "- [[<note>]] - <one-line why>"

sb creates today's daily note from the vault's template when needed and matches the existing ## Links heading. Keep it to the link line, and don't pre-check, hand-copy the template, restructure the daily note, or verify where the line landed. Report it in one line (Added breadcrumb to today's daily note.); if the append fails, say so. A "created": true response means the note was seeded verbatim from the template, so leave any placeholder in it alone.

Closing proposals

End the summary with one line per proposal, in exactly this shape:

- [high|medium|low] <action in plain words> - <reason> (<path of the existing note>)

Actions: Add a link to this note from <note>, Make a note for <thing the source cites>, Add this to <hub or list note>, Merge with <note>?, Link <note> too?.

Confidence is how sure you are Josh would say yes, with the reason as proof. Every target is a note a search found, named by path. Skip the block when there is nothing to propose. For deeper backlink weaving, hand off to the connect skill.

Step 6: Fold in follow-up research on the note you just wrote

If right after capture the user asks about the thing the note covers ("is there a release date yet?"), answer and then update the note with the answer, rather than leaving it stale in chat. Say what you added in one line. This stops at a genuinely new note or source.

Lookup only: "do we have notes on X"

The user wants to know what's in the vault, not to write anything. Run Step 0 and the Step 1 search (qmd, today's inbox Glob), and skip the fetch and the why question, since there is no source.

  1. Show the hits in one message: path + snippet, and a few words on why each looks strong or weak. qmd scores are only ranks, so don't quote them as relevance.
  2. Then offer, one line: "Extend ?" when a hit is on the subject, "Want me to start one?" when nothing is. A miss follows references/search-recovery.md first.
  3. Stop. Nothing is written, no breadcrumb, no closing proposals. Never suggest a new folder, hub, or note beyond the one the user asked about.

If they say yes, you're on the new-note arc (Steps 1-6, reusing these hits) or the extend path.

Extend an existing note

The right move is often to edit a note that's already there (a stub, or a note on the same subject), not to mint a second one. Skip Steps 3 and 4; the rest of the arc applies.

  • Read the existing note first, and the real source (Step 2 still applies).

  • Edit in place with Edit, not sb. sb only creates. The note keeps its path and folder: don't move it, don't rename it, don't touch status or its frontmatter beyond what the new content needs.

  • Put the content where it belongs. Under an existing heading that fits, else a new ## section before ## Related. Add only what the source says, with the same links and no-invention rules as references/note-format.md. Leave what's already there alone, and don't add a second **Why I saved this:**.

  • Confident links follow Step 5: same subject or named in the source, under the note's ## Related, skipping any already there.

  • Breadcrumb as in Step 5, but with updated so the daily note doesn't read like a new note:

    npx @techpickles/sb daily append --section "Links" --content "- [[<note>]] - updated: <what you added>"
    
  • Closing proposals use the same block as Step 5. "Merge with ?" and "Add this to " don't apply to the note you just extended; a second existing note that also fits is a proposal, not an edit.

  • Several candidate notes? Edit the strongest one and propose the rest, unless the user said to cover them all.

Capturing several sources at once

For a batch of 3+ sources, dispatch one subagent per note, then do the cross-linking and closing proposals yourself. How: references/batch.md.

Constraints

  • Only the new note (or the one you were asked to extend) changes without a yes. Confident links go inside it and the breadcrumb is automatic. A lookup changes nothing. Every other note edit and every new side note is a closing proposal, unless the user's phrasing already covers the whole batch.
  • Never fabricate. No invented URLs, no unverified [[links]], no filled-in details.
  • One note, one idea. If the source carries several distinct ideas, say so and offer to split.

Connect Stage

Find related notes via semantic search (qmd) and weave forward/backward links.

See ../obsidian/references/pipeline.md for stage definitions and status flow. See ../obsidian/references/connecting.md for the connection discovery algorithm.

Input

A routed note with status: routed.

Process

  1. Check qmd availability: the mcp__qmd__query tool if it is loaded, else which qmd. If neither is available, log "Skipped connections: qmd not available", set status: connected, and return.

  2. Extract query terms from the note's title and body

  3. Run semantic search with reranking off, through mcp__qmd__query (collections, limit: 15, rerank: false) or the CLI:

    qmd query "{terms}" -c {collection} -n 15 --json --no-rerank
    
  4. Filter and rank per ../obsidian/references/connecting.md:

    • Remove self
    • Remove already-linked notes
    • Remove daily notes
    • Remove weak matches, judged from the snippet (qmd scores are ranks, not a relevance scale)
  5. If candidates found, present to human (when called by orchestrator):

    • Show each candidate with its snippet and a few words on why it looks like a strong or weak match
    • Let user multi-select which to connect
  6. For selected connections:

    • Add ## Related section to the note with wiki-links
    • Offer backlink weaving for notes that have See Also/Related/TK sections
  7. Update status to connected

Output

  • Note with ## Related section added (if connections found)
  • status: connected

Constraints

  • Graceful skip if qmd unavailable (always log that it was skipped)
  • The note being processed won't be in qmd's index yet. Search FROM its content, not for it.
  • Don't add connections the user didn't approve
  • Backlink weaving is optional (offer, don't force)

Devlog

Overview

Devlog is continuous, point-in-time work commentary: what happened, why, and anything surprising, captured as it happens instead of reconstructed from memory at the end of a session. One narrative session note accumulates every entry from the current session — no separate "learnings" system, no til/cursed split, everything worth remembering goes in the same place.

Processing (routing, connecting, daily-linking) happens later via /second-brain:process-inbox. This skill only ever appends to the inbox.

Write the entry now, in the same turn as whatever triggered it. Don't ask "should I log this?" and don't offer to — just write it. Asking is exactly the failure mode that made the old distill-conversation flow get skipped: by the time a session ends, you're mentally done, and a skip-able step gets skipped.

When to write

  • Finished a feature or fixed a notable bug
  • Wrapping up a work session
  • Discovered something non-obvious: a gotcha, undocumented behavior, a workaround that took several tries, a constraint you only noticed after hitting it

When not to write

  • Routing, connecting, or moving existing notes — that's /second-brain:process-inbox
  • Reading an external source and writing it up — that's second-brain:capture
  • Trivially obvious or one-off details you'd never reach for again
  • A bare project-specific fact (a config value, a repo convention) with no story behind it — that belongs in Claude Code's own memory system alone, not the vault

Step 1: Load Configuration

Don't preflight-check sb availability — just run it:

npx @techpickles/sb config default && npx @techpickles/sb config vaults

If this fails, run ${CLAUDE_PLUGIN_ROOT}/scripts/diagnose-sb.sh and follow its guidance rather than re-deriving the checks by hand.

Then pick the vault for this session's note:

${CLAUDE_PLUGIN_ROOT}/scripts/resolve-vault.sh

It prints a vault name, or nothing. Use that name as --vault <name> on every sb call below that takes it (note create, vault obsidian, inbox list). When it prints nothing, omit --vault and let sb use its default. The name comes from SB_NOTE_VAULT if set (a per-project override), else from whichever registered vault contains the working directory. Never write a session's note to a different vault than the one the session is working in or for: a vault can have rules about what may be written to it.

If no default vault is configured:

Second brain not configured. Run /second-brain:setup first.

Step 2: Find or create this session's devlog note

Every entry from the current session lands in ONE note. Never create a second devlog note for a session that already has one.

  1. Collect session context:
    • Current repo and branch, if in a worktree
    • Current work item, if any (see Work items below)
    • Short session id (first 8 characters of the session UUID)
    • Source string format: claude-code session {short-id} ({repo}, branch {branch}, {tracker} {id}) (omit fields that don't apply)

Work items

This plugin doesn't know or assume an issue tracker. If your context names a tracked work item for this session (a ticket, issue, or task ID), record it; otherwise leave it out. It can arrive two ways:

  • Your instructions (CLAUDE.md, the user's own words) say what tracker they use and which item is current.
  • A hook injects candidates when this skill loads, in this shape:
    Work items this session ({tracker}):
    - {id} ({status}): {title}
    
    A PreToolUse hook on the Skill tool can emit this as additionalContext for second-brain:devlog.

If there are several candidates, pick the one(s) this entry is actually about. A follow-up item filed during the session is usually not what the session was about. If none fit, or nothing names a work item, omit it. Don't guess one from the branch name.

  1. Check your own memory first. If you already created or appended to this session's devlog note earlier in this same conversation, you already have its path in context — go straight to Step 2a and append. No CLI search needed: this is the same mechanism second-brain:insight uses for its own accumulating session note ("if the session file already exists, was created in an earlier call in this same conversation, append").

  2. If this is the first devlog entry this session, go to Step 2b to create the note, and keep its path in mind for the rest of the session.

  3. Fallback, only if you've genuinely lost track of the note's path (e.g. a context compaction wiped your memory of this session) — resolve a real path instead of guessing:

    • npx @techpickles/sb vault obsidian (add --vault <name> when step 1 picked one) — parse the JSON for the top-level inbox field (the inbox subfolder name, e.g. 📫 Inbox). This is the precomputed field sb note create itself resolves the inbox folder from — don't parse app.newFileFolderPath directly, since that skips the Zettelkasten Prefixer plugin's folder override (inbox is zkPrefixer?.folder ?? app?.newFileFolderPath) and can point at the wrong folder.
    • npx @techpickles/sb inbox list --detail — parse the JSON, look for the entry with type: session-notes whose source field contains the current short session id, and take its filename
    • Combine: ~/.claude/vaults/{vault-name}/{inbox}/{filename} is the real, readable/editable path. inbox list --detail only ever returns a bare filename, never a resolvable path on its own.
    • With the resolved path in hand, go to Step 2a and append. If the inbox list --detail search finds no entry matching the current session id (genuinely nothing to recover), fall through to Step 2b and create the note instead.

Step 2a: Append to the existing note

Read the note, append one new bullet to the end of its body (format below) using the Edit tool. Don't touch its frontmatter.

Step 2b: Create the note

Staged and written in one Bash call:

VAULT={vault name from resolve-vault.sh, or empty}
STAGE=$(mktemp)
cat > "$STAGE" <<'EOF'
- {HH:MM} {entry}
EOF
npx @techpickles/sb note create \
  ${VAULT:+--vault "$VAULT"} \
  --title "Session: {topic}" \
  --source "claude-code session {short-id} ({repo}, branch {branch}, {tracker} {id})" \
  --content "$(cat "$STAGE")"
rm -f "$STAGE"

Run it sandboxed first. It works sandboxed when the vault's real path is in the sandbox's allowWrite (for example ~/Vaults/<vault>/**/*.md). Name the real directory, not a symlink to it: the sandbox matches the resolved path. If the call fails with Operation not permitted on the vault path, the vault isn't allowlisted. Re-run the whole call with the Bash tool's dangerouslyDisableSandbox: true, not just the sb line: $TMPDIR resolves to a different path unsandboxed, so staging and reading have to happen in the same call under the same mode or the read can miss the file. Either way, the staged file must be a fresh mktemp path, not a fixed filename: $TMPDIR is shared across every Claude Code session on the machine, and a fixed-name file can be overwritten or read by a stale write from a different session.

sb note create prints JSON with a path field. If stdout has anything before the { (e.g. a stray npm warn ... line from the caller's own .npmrc), extract the JSON substring starting at the first { rather than parsing the whole stdout blob.

sb note create only ever writes captured, source, repo, branch, commit to frontmatter — it has no --type/--status flag, and repo/ branch come out as the literal none/none (devlog's --source format doesn't match sb's own conversation:repo=...,branch=... parsing convention). Read the file back at the path just parsed to preserve the exact frontmatter sb wrote, then Edit it:

  • add status: raw
  • add type: session-notes
  • replace the repo: none line sb wrote with repo: {repo-name} (from git context if available) — don't add a second repo: line
  • replace the branch: none line sb wrote with branch: {branch-name} (from git context if available) — don't add a second branch: line
  • add issue: {id} if there's a current work item (see Work items); a YAML list if the entry covers several. Omit the line entirely otherwise
  • keep source as sb wrote it — the claude-code session ... string already covers provenance for devlog's format
  • keep captured as sb wrote it

Without this fixup, the note is invisible both to this skill's own "check memory / find existing note" logic (Step 2, above) and to process-inbox's stage 3a filter, which requires exactly status: raw + type: session-notes to ever pick the note up.

Entry format

One bullet per entry, each with a wall-clock timestamp:

- {HH:MM} {what happened, why, anything surprising — one to three
  sentences, standalone enough to make sense without the surrounding
  conversation}

Prose, not a title. Write it like a short journal line, not a commit message.

Also saved somewhere else?

A record somewhere else doesn't replace the devlog entry. Claude Code's memory is what future sessions act on, an issue or ticket is the tracked work, and the devlog is the vault's record of what happened. When the discovery was also saved to one of those, write the entry anyway and say where it went:

- 14:05 The VM's guest DNS drifts off its DHCP lease after the host
  sleeps, so image pulls time out until it's reset. Saved as a memory
  (`~/.claude/projects/<project>/memory/reference_vm_dns_drift.md`).

Point at it, don't paste it: one or two sentences of what happened, then the pointer. The other record holds the details. Which trackers count beyond memory (and how to cite them) is up to your own instructions or the hook that nudged you here; this skill doesn't assume any.

Constraints

  • One note per session — append, never create a second one for the same session.
  • Never ask before writing, never present a summary and wait for a selection.
  • Don't route, connect, move the note, or touch the daily note. That's entirely process-inbox's job, later.
  • Frontmatter stays status: raw, type: session-notes for the life of the session. process-inbox owns every status transition after that.

Distill Rules

Review accumulated routing corrections in .routing-memory.md and propose updates to the vault's CLAUDE.md routing rules.

See ../obsidian/references/routing-memory.md for correction format and learning loop.

Process

  1. Read .routing-memory.md from vault root

  2. Read vault CLAUDE.md

  3. Analyze corrections for patterns:

    • Group corrections by destination
    • Identify repeated corrections (same type of note going to same destination)
    • Look for corrections that contradict existing CLAUDE.md rules
  4. Propose updates:

    • New edge case mappings for disambiguation sections
    • New category table entries
    • New learned patterns for .routing-memory.md
    • Corrections to existing rules that have been consistently overridden
  5. Present proposals to user:

    Found {n} patterns in {m} corrections:
    
    1. Add edge case: "{scenario}" -> {destination}
       Based on: {n} corrections over {date range}
    
    2. Add to category table: "{tool}" under {area}
       Based on: {n} corrections
    
    3. Update rule: "{old rule}" -> "{new rule}"
       Based on: consistently overridden {n} times
    
    Apply these updates?
    (A) Apply all
    (B) Review individually
    (C) Skip for now
    
  6. Apply selected updates:

    • Edit vault CLAUDE.md with new rules
    • Move applied corrections to an ## Archived section in .routing-memory.md
    • Promote stable patterns to ## Patterns Learned

Constraints

  • Never auto-apply. Always present proposals for approval.
  • Preserve existing CLAUDE.md structure and formatting
  • Archive corrections, don't delete them (audit trail)
  • Only propose rules backed by multiple corrections (minimum 2)

Enrich Stage

Turn an ingested insight note into a proper zettelkasten note with a clean title, well-written prose, and complete frontmatter.

See ../obsidian/references/pipeline.md for stage definitions and status flow. See ../obsidian/references/note-patterns.md for the Insight Note template. See ../obsidian/references/zettelkasten.md for naming conventions.

Input

An insight note in the inbox with status: ingested and type: insight.

Process

  1. Read the ingested note
  2. Rewrite the body as clean prose (1-3 paragraphs) using the Insight Note pattern from ../obsidian/references/note-patterns.md
  3. Improve the title if needed (should be descriptive and specific)
  4. Add a ## Context section with brief description of what session produced this
  5. Update status to enriched in frontmatter
  6. Write the updated note using the Write tool (read first, then rewrite)

Output

The same file, now with:

  • Clean, well-written prose body
  • Descriptive title
  • Context section
  • status: enriched

Constraints

  • Don't create a new file. Enrich in place.
  • Preserve all existing frontmatter fields (provenance, source-session, etc.)
  • The note should be useful months later to someone with no context
  • Keep it concise. 1-3 paragraphs, not an essay.

Ingest Stage

Turn a raw session notes file (type: session-notes) into an ingested insight, ready for the enrich stage. Defaults to keeping it as one note — see "Exception" below for when to split.

See ../obsidian/references/pipeline.md for stage definitions and status flow.

Input

A session notes file in the inbox with status: raw and type: session-notes.

If the note names a Claude Code session (source: claude-code session <id> ... or a session/session-id key) and that session's transcript isn't on this machine, leave the note untouched and say so: it was written on another machine and waits for that one. process-inbox finds these in its survey; when you're run on a single note, check with ls ~/.claude/projects/*/<id>*.jsonl (each CLAUDE_CONFIG_DIR entry in place of ~/.claude when it is set).

Default: enrich whole

Most session notes — including every devlog-produced one — are already well-organized: one session, one provenance (repo/branch/issue), a handful of related bullets. Splitting them into N separate notes mints near-duplicate notes that mostly route to the same destination anyway — a real run against 32 session notes would have exploded into 120-140 near-duplicates that mostly filed to the same destination.

Default behavior: keep the session note as ONE note. Change its frontmatter in place, using the Edit tool:

  • status: raw → status: ingested
  • type: session-notes → type: insight

Don't create any new files. Don't touch the body — enrich handles prose cleanup next.

Exception: split when bullets genuinely diverge

Check for a real cross-topic signal before splitting — not a bullet count. Read the note's bullets:

  • If every bullet shares the same repo/branch/issue context (the common case, and always true for a single devlog session), keep it whole.

  • If bullets explicitly reference different repos, branches, or issues within the same file (only possible in hand-authored or legacy multi-topic session notes — devlog output never does this), split those bullets into separate notes instead:

    There's no structured per-bullet frontmatter for this — repo/branch/issue only ever exist once, at the file level. Infer divergence from what the bullet text itself says (e.g. a bullet's prose names a different repo than the file's own frontmatter, or than another bullet). Older notes may carry bean: instead of issue:; treat them the same, and copy whichever key the source note used.

    1. For each insight, create a new note via sb note create --source auto --title "{insight title}" with status: ingested, type: insight, source-session: {original session filename}, and that bullet's own repo/branch/issue.
    2. Write the note body (the bullet text, cleaned into a sentence or short paragraph) using the Write tool.
    3. Update the original session file's status to ingested using the Edit tool — it stays in the inbox as a record, not processed further.
    4. Skip empty or trivial bullets when splitting (single words, fragments).

Output

Either:

  • The same note, now status: ingested and type: insight (default case), or
  • N new insight notes with status: ingested, plus the original session file updated to status: ingested (split case)

Constraints

  • Default to whole. Splitting is the exception, not the rule.
  • Preserve all provenance metadata.
  • Each split-out note gets its own zettelkasten timestamp (via sb).

Link Daily Stage

Add an entry for the processed note to today's daily note.

See ../obsidian/references/pipeline.md for stage definitions and status flow. See ../obsidian/references/daily-linking.md for linking mechanics.

Input

A note with status: connected. (The connect skill sets this even when qmd is unavailable and connections are skipped.)

Process

  1. Link to daily note:

    npx @techpickles/sb daily append \
      --section "Links" \
      --content "- [[{filename without .md}]] - {brief description}"
    
  2. Update status to complete

If daily note linking fails (sb returns error), log the error but don't fail. The note is already processed. Set status to complete anyway.

Output

  • Entry added to today's daily note
  • status: complete

Constraints

  • Don't fail the pipeline if daily linking fails
  • Use the note's title for the brief description
  • sb handles daily note creation if it doesn't exist

Obsidian Skill

Tool-specific mechanics for working with Obsidian vaults.

Vault Detection

A directory is an Obsidian vault if it contains .obsidian/ folder.

Wiki Links

Syntax: [[Note Title]] or [[path/Note Title]]

  • Obsidian resolves by title match
  • Can include path for disambiguation
  • Aliases: [[Note Title|display text]]

.obsidian/ Configuration

Obsidian stores settings in .obsidian/ at vault root:

FilePurpose
daily-notes.jsonDaily note folder and template
templates.jsonTemplates folder location
zk-prefixer.jsonZettelkasten/inbox settings
app.jsonGeneral settings (new file location, attachments)
plugins/Installed plugin data

Parsing Config

// daily-notes.json
{
  "folder": "Fleeting",
  "template": "Templates/daily"
}

// templates.json
{"folder": "Templates"}

// zk-prefixer.json
{
  "folder": "📫 Inbox",
  "template": "Templates/frontmatter"
}

// app.json
{
  "newFileFolderPath": "📫 Inbox",
  "attachmentFolderPath": "🖇 Attachments"
}

Daily Notes

Finding today's note:

  1. Read .obsidian/daily-notes.json for folder
  2. Use format YYYY-MM-DD.md (Obsidian default)
  3. Path: {folder}/{YYYY-MM-DD}.md

Template application:

  • Obsidian applies template on note creation
  • Template path from daily-notes.json

Glossary Integration

If Glossary.md exists at vault root:

  • Contains known transcription corrections
  • Maps common errors to correct terms
  • Used by process-daily command

Vault CLAUDE.md

Vaults should have a CLAUDE.md at root describing:

  • Folder structure
  • Routing rules
  • Naming conventions
  • References to methodology (PARA, Zettelkasten)
  • Disambiguation rules for semantically similar areas

See ../../templates/vault-claude-md.md for template.

Disambiguation Rules

When a vault has areas with semantic overlap (e.g., "tool sharpening" vs "software engineering"), the vault CLAUDE.md can include ### Disambiguation: sections that guide routing decisions.

The routing algorithm checks for:

  • Key questions - Decision heuristics for each area
  • Category tables - Lists of tools/topics per area
  • Edge case mappings - Explicit rules for ambiguous cases

See references/routing.md for the full disambiguation format and how to build custom rules.

References

For methodology (tool-agnostic):

  • references/para.md - PARA organizational system
  • references/zettelkasten.md - Naming conventions
  • references/note-patterns.md - Note templates
  • references/routing.md - Routing algorithm with disambiguation support
  • references/daily-linking.md - Linking captured notes to daily note
  • references/pipeline.md - Processing pipeline stages and status flow
  • references/routing-memory.md - Routing correction and learning loop

Process Inbox

Process accumulated inbox notes through the full pipeline: ingest, enrich, route, connect, link to daily note.

See ../obsidian/references/pipeline.md for stage definitions and status flow.

Step 1: Load Configuration

npx @techpickles/sb config default
npx @techpickles/sb config vaults

If no vault configured:

Second brain not configured. Run /second-brain:setup first.

Load skill references:

  • second-brain:obsidian for tool mechanics
  • ../obsidian/references/pipeline.md for stage definitions
  • ../obsidian/references/routing-memory.md for learning loop
  • ../obsidian/references/routing.md for scoring algorithm
  • ../obsidian/references/connecting.md for connection discovery
  • ../obsidian/references/daily-linking.md for daily note linking
  • ../obsidian/references/sb-cli.md for sb command reference

Step 2: Survey Inbox

${CLAUDE_PLUGIN_ROOT}/scripts/survey-inbox.py

It reads every note in the default vault's inbox and prints JSON. Each note is in exactly one bucket of next:

BucketNotesWhat happens
ingest, enrich, route, connect, link-dailyPipeline status (raw session notes, ingested, enriched or pending-review, routed, connected)That stage in Step 3
kept-recordA session note ingest split up, kept as a recordNothing
route-keep-statusA vault status (seedling, filed, active, ...) or no status on a note that isn't a session note: a finished note sitting in the inboxStep 3c, keeping its status
emptyTitle only, no bodyAsk: delete or fill in. Never process
session-not-on-diskRaw session note naming a Claude Code session whose transcript isn't on this machine, or whose session id is malformedLeave it untouched
unknown-statusA status in none of the vocabularies, or raw on a note that isn't a session noteAsk, after checking the vault CLAUDE.md's status vocabulary

stale lists notes captured more than 14 days ago. near_duplicates lists pairs of notes where one title's words all appear in the other's.

Why the status buckets: status carries pipeline state, zettelkasten maturity and vault lifecycle in one key. See "Status Values" in ../obsidian/references/pipeline.md.

Present summary:

Inbox: {total} notes
  {n} to ingest (session notes)
  {n} to enrich
  {n} to route ({k} pipeline, {m} finished notes keeping their status)
  {n} to connect
  {n} to link to the daily note

{If session-not-on-disk:}
  Holding {n} session notes whose sessions aren't on this machine
  ({repos}). Process them on the machine that wrote them, or after syncing.
{If empty:}
  {n} empty notes: {filenames}. Delete, or leave for you to fill in?
{If near_duplicates:}
  Possible duplicates: {each pair}. Compare before routing?
{If unknown-status:}
  {n} notes with a status I don't recognize: {filename: status}.
{If stale:}
  Heads up: {n} notes have been in the inbox for over 2 weeks.

Ask the empty-note and duplicate questions in this one message and wait for the answers before Step 3. Delete the empty notes the user says to delete; the rest stay out of Step 3. Merge the duplicates the user says to merge: keep the fuller note, fold the other's unique content into it, and delete the other. Duplicates the user keeps apart go through Step 3 as usual.

If inbox is empty:

Inbox is empty. Nothing to process.

If the route and route-keep-status buckets hold more than about 20 notes between them, use Large backlogs for the rest of the run.

Step 3: Process by Stage

Work through notes in pipeline order. Each stage picks up notes at its expected input status.

3a: Ingest raw session notes

For each note in the ingest bucket:

  • Follow the ingest skill (keeps the note whole by default, only splits on a real cross-topic signal)
  • Report: Ingested: {session filename} (default case), or Ingested: {session filename} -> {n} insights (split) (exception case)

3b: Enrich ingested insights

For each note with status: ingested and type: insight:

  • Follow the enrich skill to create proper zettelkasten notes
  • Report: Enriched: {filename}

3c: Route enriched notes and finished notes

For each note in the route and route-keep-status buckets:

  • Follow the route skill. For a route-keep-status note, route never writes routed or pending-review: it moves the note or leaves it, and its status stays as it is.
  • If auto-routed: Routed: {filename} -> {destination}
  • If pending-review: pause and present suggestions to user
    • Show the note title, top destinations with scores, and reasoning
    • Let user pick destination or leave in inbox
    • If user overrides, capture correction per ../obsidian/references/routing-memory.md
    • After user decides, continue to next note

Also process any pre-existing pending-review notes from previous runs.

3d: Connect routed notes

For each note with status: routed, plus each route-keep-status note this run moved that has no ## Related section yet (capture already connected the ones that do):

  • Follow the connect skill, without writing a status to the route-keep-status notes
  • If qmd unavailable: Skipped connections: qmd not available (once, not per note)
  • If connections found: present batch summary, let user multi-select
  • If no connections: skip silently

3e: Link to daily note

For each note with status: connected, plus the route-keep-status notes this run moved:

  • Follow the link-daily skill, without writing a status to the route-keep-status notes
  • Batch all links into a single sb daily append call when possible
  • Report: Linked {n} notes to daily note

Step 4: Summary

Pipeline complete:
  {n} session notes ingested ({s} kept whole, {m} insights extracted from splits)
  {n} insights enriched
  {n} notes routed ({auto} auto, {manual} manual)
  {n} notes connected ({links} links added)
  {n} notes linked to daily note
  {n} notes still pending review
  {n} session notes held (sessions not on this machine)
  {n} empty notes deleted, {n} left

Large backlogs

The per-note questions in Step 3 stop working past a couple dozen notes. Switch to this mode when the survey's route and route-keep-status buckets hold more than about 20 notes between them, or when the user asks to clear a big backlog:

  1. Work in chunks of about 20 notes, in the survey's order (oldest first). Status is written per note, so a run can stop after any chunk and the next run picks up where it left off. Say how many are left after each chunk.
  2. Route by cluster, not by note. Group the chunk's routing candidates by their top destination. Auto-route what clears the threshold as usual, then ask once per cluster: "These 6 look like 67 Dev tools: {titles}. Route them all there?" with "route all", "pick some", and "leave in inbox". A cluster answer that overrides the suggestion is one correction in .routing-memory.md, not one per note.
  3. Connect without asking per note. Add confident links (same subject, or named in the note) the way capture does, and list the weaker candidates in the chunk summary instead of asking about each one.
  4. Summarize each chunk in a few lines: routed where, links added, what is still pending. Ask only what blocks the next chunk.

Constraints

  • Process stages in order (ingest before enrich, enrich before route, etc.)
  • Pause for human input only on low-confidence routing and connection selection, and on the survey's empty-note and duplicate questions
  • Never write a pipeline status over a vault status. See "Status Values" in ../obsidian/references/pipeline.md
  • Don't fail the pipeline if one stage errors on a note. Log the error and continue.
  • Batch operations where possible (daily linking)
  • One vault at a time (uses default vault)

Route Stage

Analyze an enriched note against routing memory, vault rules, and generic signals. Move to destination or mark for review.

See ../obsidian/references/pipeline.md for stage definitions and status flow. See ../obsidian/references/routing.md for the scoring algorithm. See ../obsidian/references/para.md and ../obsidian/references/johnny-decimal.md for the two folder systems a vault may use (often both, mid-migration). See ../obsidian/references/routing-memory.md for the correction and learning loop.

Input

An enriched note in the inbox with status: enriched, or a finished note with a vault status (seedling, filed, ...) or none. For a finished note, skip every status write below: move it or leave it, and its status stays. See "Status Values" in ../obsidian/references/pipeline.md.

Process

  1. Load routing context:

    • Read .routing-memory.md from vault root (create with defaults if missing)
    • Read vault CLAUDE.md for disambiguation rules
    • Run sb vault structure for available destinations
    • Run sb note context --note "{note-path}" for keywords and signals
  2. Score destinations (priority order): a. Check .routing-memory.md corrections for matching topics/keywords b. Check .routing-memory.md learned patterns c. Apply vault CLAUDE.md disambiguation rules d. Apply generic signal scoring (per ../obsidian/references/routing.md)

    Each destination from sb vault structure carries a type. For Johnny Decimal destinations (type: 'jd') also use area and code when scoring: match the note's topic to the area, and prefer an ID code (e.g. 67.01) for a specific note or its parent category code (e.g. 67) for a loose note. See ../obsidian/references/johnny-decimal.md.

  3. Apply threshold:

    • Score >= auto-route-threshold: auto-route, move file, set status: routed
    • Score < threshold: set status: pending-review, return without moving
  4. Before moving, Glob the destination for a note on the same subject (its title's words all in the other's, at least two words unless the titles match exactly). If one is there, don't move: present it like a pending-review note, with "merge into {existing}" as the first option.

  5. If auto-routing, move the file:

    npx @techpickles/sb note move --from "{note-path}" --to "{destination}/"
    

    Update frontmatter: status: routed

  6. If pending-review, present suggestions to human (when called by orchestrator):

    • Show top 2-3 destinations with scores and reasoning
    • Include "Leave in inbox" option
    • If user overrides suggestion, capture correction to .routing-memory.md

Capturing Corrections

When the user picks a destination different from the top suggestion:

  1. Ask: "Quick note on why {chosen} over {suggested}?"
  2. Append to ## Corrections in .routing-memory.md:
    - {YYYY-MM-DD}: "{note title}" routed to "{suggested}", corrected to "{chosen}"
      Reason: {user's reason}
    
    For Johnny Decimal destinations, key the correction on the JD code (e.g. "corrected to 67.01") so the learning loop can match by number, not just folder name.

Output

  • Note moved to destination with status: routed, OR
  • Note marked status: pending-review for human input

Constraints

  • Only suggest destinations from sb vault structure output
  • Always include "Leave in inbox" for pending-review notes
  • Show reasoning for all suggestions
  • Capture corrections on every override (this is how routing improves)

Commands 7

Connect Notes

Connect a note to related notes in your vault, or discover connection opportunities across the vault.

Step 1: Load Configuration

Read ~/.claude/second-brain.md for vault name and path.

If missing:

Second brain not configured. Run /second-brain:setup first.

Use the symlink path ~/.claude/vaults/{name} to access the vault (e.g., ~/.claude/vaults/primary).

Load skill references:

  • second-brain:obsidian for tool mechanics
  • ../skills/obsidian/references/connecting.md for connection discovery algorithm

Step 2: Check Prerequisites

Follow ../skills/obsidian/references/connecting.md prerequisites: the qmd MCP tools if they are loaded, else the qmd CLI (which qmd).

If neither is available:

qmd is not installed. Connection discovery requires qmd for semantic search.
Install via: bun add -g qmd
Then configure: qmd collection add ~/path/to/vault --name second-brain

Verify collection exists:

qmd collection list

Load collection name from ~/.claude/second-brain.md (qmd_collection setting). Default: second-brain.

Step 3: Determine Mode

If argument provided (note path): Go to Step 4 (Connect Specific Note) If no argument: Go to Step 7 (Connection Gardening)


Connect Specific Note

Step 4: Load Target Note

Resolve the path. Accept:

  • Vault-relative path: Areas/gusto/202501121430 kafka-consumer-groups.md
  • Absolute path: ~/Vaults/pickled-knowledge/.../file.md
  • Just the filename: 202501121430 kafka-consumer-groups.md (search for it)

If just a filename, find it:

find "{vault}" -name "{filename}" -type f 2>/dev/null

Read the note content.

If note not found:

Note not found: {path}
Check the path and try again.

Step 5: Run Connection Discovery

Follow the full ../skills/obsidian/references/connecting.md algorithm:

  1. Extract query terms from the note's title and body
  2. Run the semantic search from its Step 2 (qmd MCP tool or CLI, reranking off)
  3. Filter noise (self, already-linked, daily notes, and weak matches judged from the snippet; qmd scores are ranks, not a relevance scale)
  4. Enrich candidates (check for See Also, Related, TK sections)
  5. Rank by connection value
  6. Present candidates for multi-select

Step 6: Apply Connections

Based on user selection:

  1. Add forward links (## Related section) to the target note
  2. Offer backlink weaving for selected notes
  3. Confirm what was connected

Done. Skip to Step 10.


Connection Gardening (No-Arg Mode)

Step 7: Find Connection Opportunities

Scan the vault for notes that might benefit from connections:

Priority 1: Recent inbox notes without connections

npx @techpickles/sb inbox list --detail

Keep the ones captured in the last 30 days.

For each, check if it has a ## Related section. Notes without one are candidates.

Priority 2: Notes with TK placeholders Search for notes containing TK in See Also or Related sections:

qmd query "TK see also related" -c {collection} -n 10 --json

Or use grep if qmd doesn't help here:

find "{vault}" -name "*.md" -exec grep -l "TK" {} \; 2>/dev/null | head -20

Priority 3: Recently captured notes with no outgoing wiki-links

# Recently modified notes
find "{vault}" -name "*.md" -type f -mtime -7 2>/dev/null | head -20

For each, check if it has any [[wiki-links]] in the body.

Step 8: Present Opportunities

Connection gardening: found {N} notes that could use connections:

Inbox notes without connections:
1. **{title}** - captured {date}, no Related section
2. **{title}** - captured {date}, no Related section

Notes waiting for connections (TK):
3. **{title}** - has TK in See Also section
4. **{title}** - has TK placeholder

Recent notes with no outgoing links:
5. **{title}** - modified {date}, no wiki-links

Use AskUserQuestion: Question: "Which note would you like to connect?" Options: Top 3-4 candidates, plus "None, I'm done gardening"

Step 9: Connect Selected Note

When user picks a note, run the same flow as Steps 4-6 (Connect Specific Note):

  1. Read the selected note
  2. Run connection discovery
  3. Present candidates
  4. Apply connections

After connecting, offer to continue gardening:

Want to connect another note?
(A) Yes, show me more opportunities
(B) Done for now

If (A), loop back to Step 7 with already-connected notes excluded.


Step 10: Summary

After all connections are done:

Connection session complete:
- {N} notes connected
- {M} forward links added
- {K} backlinks woven

Run /second-brain:connect again anytime to tend the garden.

Constraints

  • User always chooses - Present candidates, never auto-connect
  • Best-effort - Skip gracefully if qmd fails or returns nothing
  • Wiki-link format - Use [[filename]] not [text](path)
  • Descriptive links - Always include relationship description
  • Respect structure - Append to existing sections, don't reorganize
  • Gardening is optional - If no opportunities found, say so and exit

Capture Insight

Capture an insight from the current conversation to your Obsidian vault inbox.

This command captures raw insights quickly. Processing, routing, and connection discovery happen later via /second-brain:process-inbox.

Step 1: Load Configuration

Load configuration using sb CLI:

npx @techpickles/sb config default    # Get default vault name
npx @techpickles/sb config vaults     # List all configured vaults

If sb is not available, inform user:

sb CLI is required but not available. Install Node.js and npm, then try again.
Or install globally for faster execution: npm i -g @techpickles/sb

If no vaults are configured, inform user:

Second brain not configured. Run /second-brain:setup first.

Use the symlink path ~/.claude/vaults/{name} to access the vault for reading CLAUDE.md (e.g., ~/.claude/vaults/primary).

Read vault's CLAUDE.md for structure rules.

Load skill references:

  • second-brain:obsidian for tool mechanics
  • ../skills/obsidian/references/sb-cli.md for sb invocation details
  • ../skills/obsidian/references/zettelkasten.md for naming

Step 2: Identify the Insight

If argument provided: Use the argument as the insight to capture.

If no argument: Ask: "What insight would you like to capture?"

Also review recent conversation context to suggest what might be worth capturing.

Step 3: Create or Append to Session Notes

Session notes files collect all insights from a conversation in one place, with cheap metadata attached at capture time.

Check if session file already exists in this conversation.

If this is the first /insight command in this conversation:

  1. Create a new session notes file using sb CLI:
npx @techpickles/sb note create \
  --source auto \
  --title "{session context}"

Generate the title from conversation context: repo name, current branch, work item ID if your context names one, and what you're working on (e.g., "Debugging auth timeout in zenpayroll").

The file is created with frontmatter. Read the created file to preserve the exact frontmatter sb wrote.

Add type: session-notes to the frontmatter if not present. The frontmatter should include:

  • status: raw
  • type: session-notes
  • source-session: {topic}
  • repo: {repo-name} (from git context if available)
  • branch: {branch-name} (from git context if available)
  • issue: {id} (only if your context names a current work item, e.g. via your instructions or a hook; omit otherwise)
  • captured: {ISO timestamp}

Then write the note structure:

---
status: raw
type: session-notes
source-session: {topic}
repo: {repo-name}
branch: {branch-name}
issue: {id}
captured: {ISO timestamp}
---

# Session: {Session Title}

- {Insight bullet 1}

Use Write tool with the file content.

If session file already exists (was created in an earlier /insight call in this same conversation):

  1. Append the new insight as a bullet using Edit tool
  2. Insert under the bulleted list in the session notes file
  3. Write the insight as clean prose (1-3 words to a sentence, not raw conversation)

Example:

- Redis TTL per-key is better than Memcached for sessions
- Auth timeout varies by environment: 30s prod, 2m staging, 10m dev

Confirm Capture

After creating or appending, confirm with one line:

Captured to inbox: {filename}

That's it. No routing, no connecting, no daily linking. Those happen later via /second-brain:process-inbox.

Constraints

  • Always write to inbox - Inbox capture only, no routing
  • Use sb CLI for note creation - sb handles timestamps, frontmatter, vault structure
  • Capture cheap metadata - repo, branch from git/provenance context, plus a work item ID only if your context names one
  • Clean prose for bullets - Each insight is a polished sentence or short phrase
  • No routing, connecting, or linking - Processing moves to the separate process-inbox skill

Link Project to Vault

Create a symlink from current repo to a folder in your vault.

Step 1: Check Configuration

Read ~/.claude/second-brain.md for vault names and paths.

If missing:

Second brain not configured. Run /second-brain:setup first.

Use the symlink path ~/.claude/vaults/{name} to access vaults.

Step 2: Select Vault

If multiple vaults configured, ask which one:

Use AskUserQuestion: Question: "Which vault should this project connect to?" Options: List configured vaults

If only one vault, use it automatically.

Step 3: Browse Vault Structure

Show top-level folders in vault:

ls -d {vault}/*/ | head -10

Ask user to select or specify path:

"Which folder in your vault? (or type a path)"

Options:

  1. Areas/
  2. Projects/
  3. Resources/
  4. (type custom path)

May need to drill down into subfolders.

Step 4: Determine Local Path

Suggest default based on vault folder name:

Vault folder: Areas/gusto/ASYNC/
Suggested local path: docs/ASYNC/

Use this path? [Yes] [Custom path]

Step 5: Create Symlink

# Create parent directory if needed
mkdir -p {local_parent}

# Create symlink
ln -s "{vault_path}" "{local_path}"

# Verify
ls -la "{local_path}"

Step 6: Write Local Config

Create .claude/second-brain.local.md:

# Second Brain Connection

Vault: {vault_name}

Symlinks:
- {local_path}/ → {vault_relative_path}/

If file exists, append new symlink to list.

Step 7: Check Gitignore

git check-ignore .claude/second-brain.local.md

If not ignored (exit code 1):

⚠ .claude/second-brain.local.md is not gitignored.

This file contains host-specific paths and shouldn't be committed.

Options:
1. Add to .git/info/exclude (this repo only)
2. Add to global gitignore (~/.config/git/ignore)
3. Skip (I'll handle it)

If option 1:

echo ".claude/second-brain.local.md" >> .git/info/exclude

If option 2:

mkdir -p ~/.config/git
echo ".claude/second-brain.local.md" >> ~/.config/git/ignore

Step 8: Confirm

✓ Project linked to vault!

Symlink: {local_path}/ → {vault_path}/
Config: .claude/second-brain.local.md

Files in {local_path}/ are now synced with your vault.

Listing Existing Links

If .claude/second-brain.local.md exists, show current links first:

Current links:
- docs/jira/ASYNC/ → Areas/gusto/ASYNC/
- docs/interviews/ → Areas/gusto/interviews/

Add another link? [Yes] [No]

Process Daily Note

Clean up voice transcriptions in a daily note. Works in phases with confirmation between each.

Prerequisite: Vault Context Check

This command only works inside a vault.

Check if current directory is a vault:

ls -d .obsidian 2>/dev/null

If .obsidian/ not found in current directory or parents:

⚠ /second-brain:process-daily only works inside a vault.

You're currently in: {cwd}

Options:
1. Open your vault via symlink: ~/.claude/vaults/{name}
2. Use /second-brain:insight to capture from here
3. devlog captures notable moments automatically — nothing to invoke

Stop execution - do not continue.

Overview (when in vault)

  1. Load context (daily note, glossary, vault conventions)
  2. Identify & confirm transcription corrections (batched by category)
  3. Clean prose (preview before applying)
  4. Restructure to daily note template (preview before applying)
  5. Suggest extractions (optional)

Phase 1: Load Context

Step 1.1: Read Vault CLAUDE.md

Read CLAUDE.md at vault root for:

  • Daily note location
  • Template reference
  • Structure conventions

Step 1.2: Find the Daily Note

Get the daily note path using sb:

npx @techpickles/sb daily path

If argument provided: Pass the date to sb:

npx @techpickles/sb daily path --date "{YYYY-MM-DD}"

sb returns the full path to the daily note based on .obsidian config.

If file doesn't exist, inform user and stop.

Step 1.3: Load Glossary

Read Glossary.md if it exists at vault root.

Parse correction mappings by category.

Step 1.4: Assess Content

Read daily note. Report:

Loaded: Fleeting/2026-01-21.md
Glossary: Found ({N} known corrections)
Content: ~{N} words, {structured|unstructured}

Ready to process. Continue? [Yes] [Cancel]

Phase 2: Identify & Confirm Corrections

Present corrections in batches by category:

### Tools & Software (Batch 1 of 4)

| # | Found | → Correction | Context |
|---|-------|--------------|---------|
| 1 | me's | mise | "started using me's" |
| 2 | Claude MT | CLAUDE.md | "added Claude MT" |

✓ Accept all | Enter numbers to reject | ? for more context

Categories:

  1. Known corrections (from Glossary) - batch accept
  2. Tool/product names
  3. People names
  4. Technical terms
  5. Uncertain - need user input

After all batches, offer glossary update for new corrections.

Phase 3: Clean Prose

Remove filler words, false starts, run-on sentences.

Preserve: conversational tone, first-person voice, meaning.

Show before/after preview for representative sections.

Phase 4: Restructure (if needed)

If note lacks structure, propose restructuring to match daily template:

## Action Items    ← Top: high visibility
## Extracted Notes ← Links to permanent notes
## Log             ← Structured events
## Quick Notes     ← Bottom: append zone

Phase 5: Suggest Extractions

Identify content substantial enough for permanent notes.

Criteria: substantial, reusable, standalone, reference-worthy.

Offer extraction with routing.

Constraints

  • Vault-only - Must be run from inside vault
  • Interactive - Always preview before applying
  • Batch confirmations - Group similar items
  • Preserve meaning - Never change what was said
  • Follow skill references - Use vault conventions
  • Phases skippable - User can skip any phase

Route Notes

Route notes from inbox to appropriate destinations in your vault.

Step 1: Load Configuration

Load configuration directly - don't preflight-check sb availability first:

npx @techpickles/sb config default
npx @techpickles/sb config vaults

If this fails, run ${CLAUDE_PLUGIN_ROOT}/scripts/diagnose-sb.sh for a one-shot diagnosis rather than re-deriving the checks by hand.

If no vault configured:

Second brain not configured. Run /second-brain:setup first.

Use the symlink path ~/.claude/vaults/{name} to Read vault files (e.g., ~/.claude/vaults/primary/CLAUDE.md).

Load skill references:

  • second-brain:obsidian for tool mechanics
  • ../skills/obsidian/references/routing.md for routing algorithm
  • ../skills/obsidian/references/sb-cli.md for sb command reference
  • ../skills/obsidian/references/routing-memory.md for routing correction format

Step 2: Identify Notes to Route

If argument is a filename: Look for that file in inbox. If not found, search vault.

If argument is "all": List all files in inbox for batch routing.

If no argument: List inbox contents and let user select:

npx @techpickles/sb inbox list

Example output:

{
  "notes": [
    {
      "filename": "202601251430 redis-session-caching.md",
      "timestamp": "202601251430",
      "title": "redis-session-caching"
    },
    {
      "filename": "202601251445 claude-code-hooks.md",
      "timestamp": "202601251445",
      "title": "claude-code-hooks"
    }
  ]
}

Present to user:

Notes in inbox:
1. 202601251430 redis-session-caching.md
2. 202601251445 claude-code-hooks.md
3. 202601251500 debugging-approach.md

Which note(s) would you like to route?

Use AskUserQuestion with multi-select to let user choose.

Step 3: Discover Vault Structure

npx @techpickles/sb vault structure

Example output:

{
  "areas": [
    "Areas/AI/agentic development",
    "Areas/tool sharpening"
  ],
  "resources": [
    "Resources/software engineering",
    "Resources/mental models"
  ],
  "projects": [
    "Projects/pickletown",
    "Projects/claude-plugins"
  ]
}

Build destination map from returned paths only.

Step 4: Load Disambiguation Rules

Read the vault's CLAUDE.md via symlink (e.g., ~/.claude/vaults/primary/CLAUDE.md) and look for ### Disambiguation: sections.

If found, extract:

  • Key questions - Decision heuristics for each area
  • Category tables - Lists of tools/topics that belong in each area
  • Edge case mappings - Explicit routing rules for ambiguous cases

These rules override generic matching for semantically similar areas.

Step 4b: Load Routing Memory

Read .routing-memory.md from vault root (via symlink path, e.g. ~/.claude/vaults/primary/.routing-memory.md). If it doesn't exist, skip this step (no corrections yet).

If the file exists, parse:

  • auto-route-threshold from frontmatter
  • ## Corrections entries with:
    • Date, original suggestion, user's correction, and reason
    • Extract patterns: what topics have been corrected before
  • ## Patterns Learned entries:
    • Stable routing rules distilled from corrections
    • Pattern → destination mappings

Store this context for Step 5 scoring.

Step 5: Analyze and Score

For each selected note, follow ../skills/obsidian/references/routing.md algorithm:

  1. Extract signals using sb:
npx @techpickles/sb note context --note "inbox/202601251430 redis-session-caching.md"

Example output:

{
  "keywords": ["redis", "session", "caching"],
  "category": "architecture",
  "relatedNotes": [
    {
      "path": "Areas/AI/agentic development/Redis patterns.md",
      "similarity": 0.85
    }
  ],
  "sourceContext": {
    "origin": "slack",
    "thread": "https://..."
  }
}
  1. Apply routing memory (if loaded in Step 4b):

    • Check if any correction matches this note's topic/keywords (exact or close match). If so, strongly favor the corrected destination (+40% to that destination).
    • Check if any learned pattern matches the note's topic/keywords. If so, boost that destination (+20%).
    • These take precedence over generic signals but come after exact topic matches from corrections.
  2. Apply disambiguation rules (if loaded):

    • Check edge case mappings first (explicit rules)
    • Apply key question matches (+25% boost)
    • Apply category table matches (+15% boost)
    • Apply disambiguation mismatch penalty (-20%)
  3. Score with generic signals:

    • Keyword match in folder name (40%)
    • Related notes exist in folder (30%)
    • PARA category fit (20%)
    • Recency of folder activity (10%)
  4. Calculate confidence:

    • High (80-100%): Strong match, often with disambiguation support
    • Medium (50-79%): Partial match
    • Low (20-49%): Weak signals
    • None (<20%): Leave in inbox

Step 6: Present Recommendations

For single note:

Routing suggestions for "202601251430 redis-session-caching.md":

1. **Areas/AI/agentic development/** (85% - High)
   → Matches keywords: "caching", "session"
   → Related note exists: "Redis patterns.md"

2. **Resources/software engineering/** (48% - Low)
   → Generic architecture fit

3. **Leave in Inbox** (Safe default)

When disambiguation rules influenced the result:

1. **Areas/tool sharpening/** (95% - High)
   → Vault rule: "tmux config syntax" → tool sharpening
   → Key question: "Is this about MY machine?" → YES

Use AskUserQuestion with options from discovered paths.

For multiple notes:

| Note | Suggested Destination | Confidence | Rule Applied |
|------|----------------------|------------|--------------|
| "redis-session-caching" | Areas/AI/agentic development/ | High (85%) | - |
| "tmux-comma-parsing" | Areas/tool sharpening/ | High (95%) | edge case |
| "debugging-approach" | (leave in inbox) | None | - |

Use AskUserQuestion:

  1. Route all as suggested (Recommended)
  2. Route individually
  3. Leave all in inbox

Step 7: Execute Moves

For each note being routed:

npx @techpickles/sb note move --from "inbox/202601251430 redis-session-caching.md" --to "Areas/AI/agentic development/"

sb handles the filesystem operation and returns confirmation.

Step 8: Report Success

✓ Moved "redis-session-caching.md" → Areas/AI/agentic development/
✓ Moved "claude-code-hooks.md" → Areas/AI/agentic development/
○ Left "debugging-approach.md" in inbox (no clear destination)

3 notes processed: 2 routed, 1 remaining in inbox

Step 8b: Capture Corrections

For each note where the user chose a destination different from the top suggestion:

  1. Read .routing-memory.md from vault root. If it doesn't exist, create it with defaults:

    ---
    auto-route-threshold: 70
    ---
    
    ## Corrections
    
    ## Patterns Learned
    
  2. Ask: "Quick note on why {chosen} over {suggested}?" (keep it to one sentence)

  3. Append the correction to ## Corrections:

    - {YYYY-MM-DD}: "{note title}" routed to "{suggested}", corrected to "{chosen}"
      Reason: {user's reason}
    
  4. Write/Edit the updated file using the Edit tool

Example correction entry:

- 2026-03-31: "tmux conditional parsing" routed to "Resources/software engineering/", corrected to "Areas/tool sharpening/"
  Reason: tmux is a personal tool config, not a programming pattern

This correction becomes available in Step 4b of future routing operations, feeding the learning loop.

Examples

# Route a specific note
/second-brain:route redis-session-caching

# Route all inbox notes
/second-brain:route all

# Interactive: list inbox and select
/second-brain:route

Constraints

  • Never suggest non-existent paths - Only use vault structure output
  • Always include inbox option - Safe default for uncertain cases
  • Show reasoning - Users should understand why
  • Preserve filenames - Don't rename when moving
  • Two-level depth max - Don't suggest deeply nested paths
  • Respect emoji prefixes - Use exact folder names from filesystem

Search Second Brain

Search your Obsidian vault using qmd's semantic search (combines BM25 + vector similarity + reranking).

Prerequisites

  • qmd must be installed and available in PATH
  • A qmd collection must be configured for your vault

Step 1: Check Prerequisites

Verify qmd is available:

which qmd

If not found, inform user:

qmd is not installed. Install it via:
  bun add -g qmd
Then configure a collection:
  qmd collection add ~/path/to/vault --name second-brain

Step 2: Load Configuration

Get the qmd collection name via sb:

npx @techpickles/sb config qmd-collection

This returns the configured collection name (defaults to second-brain if not set).

Verify the collection exists:

qmd collection list

If collection doesn't exist, inform user which collections are available and suggest adding one.

Step 3: Execute Search

If no argument provided: Ask: "What would you like to search for?"

Run the search:

qmd query "{query}" -c {collection} -n 10 --json

Step 4: Present Results

Parse JSON output. Each result has:

  • file: qmd://{collection}/{path} - strip the qmd://{collection}/ prefix
  • score: orders the results; it is a rank, not a relevance scale, so don't quote it
  • title: document title from frontmatter or first heading
  • snippet: matching content with diff-like context markers (strip @@ ... @@ lines)

Present results clearly:

## Search Results for "{query}"

1. **{title}**
   `{path relative to vault}`
   > {cleaned snippet preview, 2-3 lines max}

2. **{title}**
   ...

Include:

  • Title from the result
  • A few words on why the hit looks strong or weak, judged from the snippet
  • File path relative to vault (strip qmd://collection/ prefix)
  • Snippet preview (clean up diff markers, show meaningful content)

If no results, suggest:

  • Try different keywords
  • Check if vault has been indexed (qmd update && qmd embed)

Step 5: Offer Follow-up Actions

After showing results, offer to:

  • Read a result - Use qmd get "qmd://{collection}/{path}" to retrieve full content
  • Search again - Try different or refined terms

If user wants to read a result:

qmd get "qmd://{collection}/{path}" -l 100

This returns the document content with optional line limit.

Constraints

  • Query required - Don't search without a query
  • Collection must exist - Check before searching
  • Explain each hit - why it looks strong or weak, not a score
  • Respect limits - Default to 10 results, don't overwhelm

Second Brain Setup

Configure vault paths and scaffold vault CLAUDE.md.

For sb CLI details, see references/sb-cli.md.

Step 1: Check Existing Config

Check if vaults are already configured:

npx @techpickles/sb config vaults

This returns JSON with configured vaults.

If this fails, run ${CLAUDE_PLUGIN_ROOT}/scripts/diagnose-sb.sh for a one-shot diagnosis rather than re-deriving the checks by hand.

If vaults exist, show current and ask:

  • Add another vault?
  • Reconfigure existing vault?
  • Cancel

Step 2: Get Vault Path

Ask user for vault path. No assumed locations, just ask directly:

"Where is your Obsidian vault located? (full path)"

Step 3: Validate Vault

Check the path exists:

ls -d "{path}" 2>/dev/null

Parse .obsidian config (if present):

npx @techpickles/sb vault obsidian --path "{path}"

This outputs JSON with:

  • Daily notes folder and template
  • Templates folder
  • Inbox/new notes folder
  • Attachments folder

If .obsidian/ missing, sb will indicate this in the output:

  • Might not be an Obsidian vault
  • Offer to continue anyway (for plain markdown repos)
  • Or user can open folder in Obsidian first to initialize

Step 4: Confirm Settings

Show detected settings from the sb output:

Detected from .obsidian/:
- Daily notes: Fleeting/ (template: Templates/daily)
- Templates: Templates/
- Inbox: 📫 Inbox/
- Attachments: 🖇 Attachments/

Does this look right? [Yes] [Adjust]

Step 5: Name the Vault

Ask for short identifier:

"What should I call this vault? (e.g., primary, work, personal)"

Suggest "primary" if this is the first vault.

Step 6: Initialize Configuration

Create or update ~/.claude/second-brain.md:

npx @techpickles/sb init --name "{name}" --path "{path}"

Add --scaffold flag if user wants to create vault CLAUDE.md:

npx @techpickles/sb init --name "{name}" --path "{path}" --scaffold

This command:

  • Writes the vault configuration to ~/.claude/second-brain.md
  • Optionally creates {vault}/CLAUDE.md with detected settings

Step 7: Create Vault Symlink

Create a symlink at ~/.claude/vaults/{name} pointing to the actual vault:

# Create vaults directory if needed
mkdir -p ~/.claude/vaults

# Create symlink (use -n to not follow existing symlink, -f to force replace)
ln -sfn "{actual_vault_path}" ~/.claude/vaults/{name}

# Verify
ls -la ~/.claude/vaults/{name}

This symlink provides a well-known path for permissions and access.

Step 8: Show Permissions

Generate permission entries for Claude Code settings:

npx @techpickles/sb permissions --vault "{name}"

This outputs the exact permission strings needed for:

  • Read/Write on the vault path
  • Read/Write on CLAUDE.md
  • Read on .obsidian config

Step 9: Confirm Complete

✓ Second brain configured!

Vault: {name} → {path}
Symlink: ~/.claude/vaults/{name}
Config: ~/.claude/second-brain.md

Add these permissions to your Claude Code settings:
{output from sb permissions}

Next steps:
- Use /second-brain:insight to capture from any repo
- Use /second-brain:link-project to connect a repo to your vault
- Run Claude inside your vault for /second-brain:process-daily

Adding Additional Vaults

If vaults already exist (shown in Step 1):

  1. Show current vaults from npx @techpickles/sb config vaults
  2. Ask for new vault path
  3. Follow same validation/detection flow (Steps 2-4)
  4. Run npx @techpickles/sb init --name "{name}" --path "{path}" (appends to config)
  5. Create symlink for new vault (Step 7)
  6. Generate and show permissions (Step 8)
  7. Ask if this should be the new default

Sponsors

Details

Marketplace
technicalpickles/pickled-claude-plugins
Source
plugins/second-brain
Category
Community

More from technicalpickles/pickled-claude-plugins

All 26