dotfiles/claude-obsidian

claude-obsidian — Claude conversations → Obsidian notes

Summarizes every Claude conversation into one searchable Obsidian note: what happened, what was decided and why, the facts and gotchas worth remembering, and what was left open.

• Claude Code sessions sync automatically and incrementally (hourly timer).
• claude.ai chats import from a data export (claude.ai has no API, so each export is manual).

Notes are written through the Obsidian Local REST API plugin, so the vault can live anywhere the plugin is reachable. The same plugin exposes a built-in MCP server (/mcp/), which is how Claude reads the notes back — no separate MCP process.

~/.claude/projects/*/*.jsonl ─┐                                          ┌─ Claude/Code/2026/…md
claude.ai export .zip ────────┼─ condense → redact → summarize → PUT ────┼─ Claude/Web/2026/…md
                              └─ (headless claude -p, no transcript)     └─ Claude/Index.md

Install

1. In Obsidian, install Local REST API, enable its HTTP server, and make it reachable from this machine. Put the API key in ~/.config/claude-obsidian/api-key (chmod 600).

2. ./install.sh — links the binary into ~/.local/bin, enables the hourly user timer, and creates ~/.config/claude-obsidian/config.env from config.env.example if absent.

3. Edit config.env (at minimum OBSIDIAN_API_URL), then preview one note:

   claude-obsidian-sync stats                       # sizes, no network
   claude-obsidian-sync sync --dry-run --limit 1    # prints the note, writes nothing
   

Use

claude-obsidian-sync sync                          # what the timer runs
claude-obsidian-sync sync --session <session-id>   # one session, now, ignoring the settle window
claude-obsidian-sync import-claude-ai ~/Downloads/data-2026-09-13.zip

Claude reads the vault through the plugin's MCP server:

claude mcp add --scope user --transport http obsidian http://<host>:27123/mcp/ \
  --header "Authorization: Bearer $(cat ~/.config/claude-obsidian/api-key)"

How it behaves — and why

• Summaries run on your own Claude plan via headless claude -p (LLM_BACKEND=claude-cli). No API key to manage. An OpenAI-compatible backend (LLM_BACKEND=openai) exists for local models. Note a LiteLLM gateway that fronts Claude by passing through the caller's subscription has no key of its own, so a background job cannot use its claude-* models.
• --no-session-persistence is load-bearing. Without it every summary writes a new transcript into ~/.claude/projects, and the next run summarizes its own summarizing.
• It shares your plan's usage limits. A first backfill of ~100 sessions in parallel hit a session limit within minutes — which also limits interactive use. So: one job at a time, MAX_PER_RUN sessions per run (newest first), and the run stops at the first usage-limit error (exit 75, which the systemd unit treats as success) instead of failing the rest of the queue. The next hourly run resumes. A 100-session backlog drains in about ten hours.
• Secrets are redacted before anything leaves the machine, and again in the note: private keys, bearer tokens, password=-style assignments, JWTs, provider tokens, ≥48-char hex, and random mixed-case strings. It over-redacts on purpose; git SHAs, md5s and paths survive. The summarizer is also told never to reproduce secrets.
• Incremental and idempotent. State (~/.local/state/claude-obsidian/state.json) records each session's size+mtime. A resumed session is re-summarized into the same note path. A session is left alone until idle for SETTLE_MINUTES, so a live conversation isn't summarized mid-flight. Empty sessions are recorded and skipped.
• Condensed, not truncated. Tool output is dropped and each tool call becomes one line; prose is kept. Typical compression is ~60× (271 MB of transcripts → 4.4 MB). Sessions over 300 KB condensed are summarized in parts, then combined.
• Subagent transcripts (<session>/subagents/**) are part of their parent session and are not synced separately.

Note format

type: claude-conversation
source: claude-code            # or claude-ai
session_id: 3f9c2a1e-…
title: Fix flaky CI cache after runner upgrade
project: my-service            # basename of the working directory
branch: …
started / ended: …
prompts: 1                     # user prompts, not tool-loop records
summarized_by: claude-haiku-4-5-20251001
tags: [claude, claude-code, ci, caching, …]

followed by a summary callout and Outcomes / Decisions / Facts & gotchas / Open threads, and a claude --resume <id> line. Claude/Index.md lists every note, newest first.