Claude Code Integration¶
This guide covers how SecondBrain integrates with Claude Code — turning your vault into a live context layer inside every coding session.
What This Is¶
SecondBrain exposes its knowledge and workflows to Claude Code through five surfaces:
| Surface | Location | What it provides |
|---|---|---|
| MCP server | brain/mcp/cc_server.py |
Memory, grounded QA, decisions, meetings, and knowledge assimilation tools callable during any session |
| Skills | .claude/skills/ |
9 /slash-commands for common workflows |
| Agents | .claude/agents/ |
5 specialist subagents Claude delegates to |
| Hooks | .claude/settings.json |
Automatic actions on session/file events |
| Routines | brain/routines/templates/ |
7 scheduled/triggered cloud automations |
There is also an inbound HTTP channel (brain/serve/routers/inbound.py) and an Agent SDK wrapper (brain/agent_sdk/) for programmatic use.
Prerequisites¶
# MCP SDK — already in pyproject.toml
pip install mcp>=1.9.0
# Agent SDK
pip install claude-agent-sdk>=0.1.68
# Claude Code CLI
# https://code.claude.com — must be installed and authenticated
How to Activate¶
The .claude/settings.json in the repo root is read automatically when you run claude from the SecondBrain repo. Nothing to configure manually — open a session and it's live.
To verify everything is connected:
# Check MCP server starts and lists its tools
printf '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}\n' \
| .venv/bin/python -m brain.mcp.cc_server
# Check the status line works
bash .claude/statusline.sh
# Check routine templates load
sb routines templates list
MCP Tools¶
The secondbrain MCP server is auto-connected in every session. Claude Code can call these tools directly — you can also call them explicitly.
| Tool | What it does | When to use |
|---|---|---|
secondbrain_recall |
Hybrid vault search (vector + keyword) | Quick lookup — "what do I know about X?" |
secondbrain_ask |
Full DataAgent synthesis (SQL + retrieval + LLM) | Multi-source reasoning needed |
secondbrain_ingest |
Parse, chunk, embed, index a file | Add new content to vault |
secondbrain_pack |
Generate a ContextPack for an intent | Pre-load context before a complex task |
secondbrain_shravan_add |
Create source-aware knowledge intake | Preserve provenance before reflection |
secondbrain_manan_reflect |
Reflect on Shravan intake | Turn capture into claims, questions, and principles |
secondbrain_nididhyasan_implement |
Convert reflection into practice | Create a habit, task, rule, checklist, project, principle, or governed memory proposal |
secondbrain_knowledge_status |
Show maturity counts and recent records | Inspect whether knowledge is captured, reflected, or practiced |
secondbrain_knowledge_review |
Review pending assimilation work | Find intake needing Manan or reflections needing practice |
secondbrain_open_loops |
List TODO/OPENLOOP markers across vault | What's pending? |
secondbrain_decision_extract |
Extract DECISION blocks from text | Parse decisions before recording |
secondbrain_meeting_extract |
Run meeting copilot on a transcript | Get action items + risks + summary |
secondbrain_grounded_answer |
Multi-step closed-corpus evidence QA | Research-grade questions |
Skills¶
Type / in a Claude Code session to see all available skills. SecondBrain adds nine:
| Skill | Invoked by | Runs | Use when |
|---|---|---|---|
/sb-ask |
Claude auto + you | inline | Any knowledge question |
/sb-ingest |
You only | inline | Adding a file to the vault |
/sb-pack |
Claude auto + you | forked | Pre-loading context for a task |
/sb-open-loops |
You only | inline | Reviewing what's pending |
/sb-decision-extract |
Claude auto + you | forked | Parsing decisions from a doc |
/sb-meeting |
You only | inline | Processing a transcript |
/sb-weekly-review |
You only | forked | Weekly review brief |
/sb-grounded |
Claude auto + you | inline | Deep research questions |
/sb-data-agent |
Claude auto + you | inline | Analytical/data questions |
Skills marked "forked" run in an isolated subagent context and return a summary to the main conversation. Skills with live bash injection (sb-pack, sb-open-loops) run sb commands before Claude sees the content, so Claude receives real data rather than instructions to fetch it.
Agents¶
Five specialist subagents Claude can delegate to automatically:
| Agent | Model | Tools | Best for |
|---|---|---|---|
sb-researcher |
Haiku | Read, Glob, Grep, WebSearch, WebFetch | Vault + web research |
sb-decision-maker |
Sonnet | Read, Bash, Glob, Grep | Decision extraction and recording |
sb-meeting-copilot |
Sonnet | Bash, Read, Write | Meeting transcript processing |
sb-data-analyst |
Sonnet | Bash, Read | SQL and event log analysis |
sb-travel-planner |
Sonnet | Read, Glob, Grep, Bash, WebSearch, WebFetch | Trip planning |
sb-researcher uses Haiku deliberately — it's read-only retrieval work that doesn't need Sonnet quality.
Hooks¶
Five hooks fire automatically on Claude Code events:
| Event | When it fires | What happens |
|---|---|---|
SessionStart (startup) |
New session opens | System message injected: vault size + MCP tool inventory |
Stop |
Session ends | session_end event logged to EventLog (async) |
PostCompact |
Context window compacted | System message re-injected: MCP tools + skills list |
PostToolUse (Edit/Write) |
Claude edits any .md in vault/ |
File auto-ingested into vector store (async, non-blocking) |
PreToolUse (Bash) |
rm -rf * command |
Blocked with exit 2 per policy |
Hook scripts: brain/mcp/hooks/.
Output Styles¶
Four named output styles in .claude/output-styles/ that format Claude's responses for vault-readiness:
| Style | Use when |
|---|---|
decision-log |
Recording or presenting a decision — produces a structured block with key/rationale/alternatives ready to paste into vault |
meeting-notes |
After processing a transcript — action item table + decisions + risks in consistent format |
kb-entry |
Creating reference material — YAML frontmatter + summary + key points + open questions |
data-insight |
Answering analytical questions — transparent answer with data table, assumptions, confidence level, and mandatory caveats |
Routine Templates¶
Seven pre-built Claude Code Routine templates. Deploy them via /schedule in a Claude Code session or at claude.ai/code/routines.
sb routines templates list # see all templates
sb routines templates show <name> # full prompt + /schedule command
sb routines templates init <name> # output prompt text to file
| Template | Trigger | Schedule | Model |
|---|---|---|---|
daily-ingest-sweep |
Schedule | nightly 2am | Haiku |
open-loops-review |
Schedule | weekdays 8am | Haiku |
decision-quality-audit |
Schedule | Monday 9am | Haiku |
kb-link-health |
Schedule | Wednesday 9am | Haiku |
alert-triage |
API | on-demand | Sonnet |
meeting-followup |
API | on-demand | Sonnet |
pr-review |
GitHub PR opened | on event | Sonnet |
Maintenance routines use Haiku (cheap, read-only). Synthesis and triage routines use Sonnet (quality matters).
To deploy open-loops-review:
# In a Claude Code session:
/schedule weekdays at 8am, scan open loops and surface highest-priority items
Inbound Channels¶
When sb serve is running, external systems can push events via HTTP. Set SB_CHANNEL_TOKEN to enable.
# Health check (no auth)
curl http://localhost:8000/inbound/health
# Ingest a file
curl -X POST http://localhost:8000/inbound/ingest \
-H "Authorization: Bearer $SB_CHANNEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{"path": "/path/to/file.md"}'
# Triage an alert
curl -X POST http://localhost:8000/inbound/alert \
-H "Authorization: Bearer $SB_CHANNEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{"title": "DB latency spike", "body": "p99 > 2s for 5m", "severity": "high", "service": "postgres"}'
# Process a meeting transcript
curl -X POST http://localhost:8000/inbound/meeting \
-H "Authorization: Bearer $SB_CHANNEL_TOKEN" \
-H "Content-Type: application/json" \
-d '{"transcript": "...", "title": "Q2 planning"}'
Agent SDK¶
For programmatic use outside Claude Code sessions:
from brain.agent_sdk import SecondBrainRunner, readonly_config, research_config
# Default: research mode (vault + web + sb commands)
runner = SecondBrainRunner()
result = runner.run_sync("Summarise all open loops in the platform namespace")
print(result.text)
print(f"Cost: ${result.cost_usd:.4f} | Tokens: {result.input_tokens}in/{result.output_tokens}out")
# Read-only vault research
runner = SecondBrainRunner(options=readonly_config())
result = runner.run_sync("What do my notes say about the auth migration?")
CLI:
sb sdk run "research the Q2 platform decisions" --mode research
sb sdk run "find all open loops related to travel" --mode readonly
sb sdk configs # list available presets
Status Line¶
The status bar at the bottom of the Claude Code terminal shows:
vault:N— number of markdown files in the vaultloops:N— number of files containing TODO or OPENLOOP markers- last field — current git branch
Configured in .claude/settings.json → statusLine.command.