Claude Code integration with LifeOS vault¶
- Date: 2026-03-09
- Status: Accepted
- Tags:
workflowtooling
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:
- Vault path and folder conventions in persistent CLAUDE.md rules
- A session workflow (resume → work → save → promote)
- Token-efficient vault search (avoid reading hundreds of irrelevant files)
- Obsidian-aware operations via MCP for the subset of ops that require them
- 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.mdcan 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
/compressat session end; run/preserveafter significant learnings - Keep active project list in
LifeOs/CLAUDE.mdcurrent - 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.