Skip to content

Claude Code integration with LifeOS vault

  • Date: 2026-03-09
  • Status: Accepted
  • Tags: workflow tooling

Context

Claude Code is used as the primary AI interface for managing the LifeOS Obsidian vault — creating notes, processing the inbox, writing session logs, surfacing tasks, and building project context. Without explicit configuration, Claude has no awareness of the vault's PARA structure, frontmatter conventions, project tags, or the session lifecycle (start/save/promote).

The integration needed to encode:

  1. Vault path and folder conventions in persistent CLAUDE.md rules
  2. A session workflow (resume → work → save → promote)
  3. Token-efficient vault search (avoid reading hundreds of irrelevant files)
  4. Obsidian-aware operations via MCP for the subset of ops that require them
  5. Slash-command skills for recurring vault tasks

Decision

Configure Claude Code with two layers of CLAUDE.md rules and a set of vault skills:

Rules layer

  • ~/.claude/CLAUDE.md (global): Vault path, session workflow summary, skill index, tool strategy (filesystem-first, MCP only for move/tag ops)
  • LifeOs/CLAUDE.md (vault-level): Full PARA structure, frontmatter standards, active project list, ai-grep usage, PeriodicPARA tag conventions, MCP tool strategy, maintenance rules

Skills layer

Seven skills in ~/.claude/commands/ cover the full session lifecycle:

Skill File Purpose
/resume resume.md Load CLAUDE.md + recent session logs
/compress compress.md Archive current session to Session-Logs/ (now ~/sandbox/ai_logs, see 0041)
/preserve preserve.md Promote learnings to LifeOs/CLAUDE.md
/daily-note daily-note.md Create/open today's daily note
/meeting-note meeting-note.md Structure a meeting transcript
/inbox-process inbox-process.md File -1. Capture/ items to PARA
/weekly-review weekly-review.md Generate weekly summary

MCP layer

obsidian-mcp is registered in ~/.claude/settings.json for the three operations that require Obsidian to be aware of the change: move-note, add-tags, rename-tag. All other vault operations use filesystem tools.

See obsidian/decisions/0001-mcp-local-rest-api-integration.md for the full MCP rationale and hang-recovery procedure.

Search layer

ai-grep installed at ~/tools/ai-grep/ provides token-efficient vault search. Query the index first; read only the files that match.

See obsidian/decisions/0002-lifeos-vault-structure-and-ai-grep.md.

Alternatives Considered

Option Why Rejected
Single global CLAUDE.md with all vault context Too long; Claude reads it on every request in every project, not just vault sessions
No persistent rules — rely on /resume each session /resume supplements; it doesn't replace always-loaded rules
Cursor or Windsurf for vault management Claude Code's filesystem tools and skill system are the best fit for markdown-heavy vault ops
Obsidian AI plugins (Copilot, Smart Connections) Good for in-app use but can't be orchestrated from Claude Code sessions

Consequences

Positive:

  • Claude has full vault context on every session without manual priming
  • Session lifecycle is repeatable and encoded — no institutional knowledge lost
  • Filesystem-first strategy means vault ops work even when MCP is unavailable
  • Skills are discoverable and documented; no need to remember ad-hoc prompts

Negative / Trade-offs:

  • LifeOs/CLAUDE.md can grow large; requires periodic pruning via /preserve
  • Skills live in ~/.claude/commands/ — not version-controlled in this repo (tracked as a known gap)
  • Active project list in CLAUDE.md must be manually maintained

Ongoing obligations:

  • Run /compress at session end; run /preserve after significant learnings
  • Keep active project list in LifeOs/CLAUDE.md current
  • When skill files change, reflect updates in claude/skills/ index

ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.