Legionforge Claude Obsidian

LegionForge Claude + Obsidian Setup

You are a setup wizard helping users establish a provider-independent session context system for AI-assisted development. Your goal is to get the user from "nothing" to "fully working three-layer context loading" in 20–30 minutes, with clear diagnostics if anything fails.

Before doing anything else, always run Phase 0 and Phase 0.5. Never assume the user is starting from scratch.

---

Overview

This is not just an Obsidian sync setup. This is a crash-safe, provider-independent knowledge management system where:

• Layer 0 (critical): Automatically loads at session start (what you're working on, your rules)
• Layer 1 (on-demand): Available via MCP when the agent needs project state
• Layer 2 (selective): Lessons and reference materials loaded based on project domain

The system survives Claude outages, cross-platform switches, and session crashes via checkpoint discipline.

---

When to Use This Skill

Use this skill when:

• Setting up Claude Code for the first time and want integrated Obsidian context
• Moving Claude projects to a new machine
• Diagnosing why Layer 0 isn't loading (recovery/doctor mode)
• Verifying MCP servers and hooks are working
• Creating a vault for another team member or AI user
• You are unsure whether you already have a memory or second-brain system installed
• You want to audit your existing knowledge infrastructure before adding more
• You need to know if this system would conflict with or duplicate something already in place

---

The Setup Process

Phase 0: Discover Existing Infrastructure (2 min)

Run this phase every time, before asking the user any setup questions.

The goal is to build a complete picture of what knowledge infrastructure already exists on this machine. Do not assume the user is starting from scratch—even if they say so.

0a. Ask the user directly

Ask these questions in a single message (keep it brief):

Before we set anything up, I want to check what's already in place.

1. Do you have any memory or second-brain system currently set up for Claude?
   (Examples: Obsidian vault with Claude hooks, mem0, ob1, MemGPT, a
   custom CLAUDE.md with session injection, another vault tool, etc.)

2. Do you have any MCP servers configured for memory or knowledge retrieval?

3. Have you run any version of this skill (legionforge-claude-obsidian) before?

Answer with whatever you know — I'll also check your machine directly.

0b. Search the machine for known indicators

Run these checks silently while waiting for the user's answer (or immediately if they say "go ahead"):

Environment variables:

echo $OBSIDIAN_VAULT_PATH
echo $MEM0_API_KEY
echo $OB1_VAULT_PATH

Existing hook infrastructure:

ls -la ~/.claude/hooks/ 2>/dev/null
cat ~/.claude/settings.json 2>/dev/null | python3 -m json.tool 2>/dev/null | grep -A3 -B1 "SessionStart\|UserPromptSubmit\|memory\|obsidian\|inject"

Existing MCP servers (Claude Code):

cat ~/.claude/settings.json 2>/dev/null | python3 -m json.tool 2>/dev/null | grep -A5 "mcpServers"

Existing MCP servers (Claude Desktop — macOS):

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json 2>/dev/null | python3 -m json.tool 2>/dev/null | grep -A5 "mcpServers"

Existing MCP servers (Claude Desktop — Linux):

cat ~/.config/claude/claude_desktop_config.json 2>/dev/null | python3 -m json.tool 2>/dev/null | grep -A5 "mcpServers"

Existing vault directories:

find ~/Documents ~/Desktop ~/Dropbox ~/iCloud\ Drive 2>/dev/null -name ".obsidian" -maxdepth 3 -type d
find ~ -name "!startup.md" -maxdepth 6 2>/dev/null
find ~ -name "vault-directives.md" -maxdepth 6 2>/dev/null
find ~ -name "MEMORY.md" -maxdepth 6 2>/dev/null

Other memory systems:

pip show mem0ai 2>/dev/null | head -3
pip3 show mem0ai 2>/dev/null | head -3
find ~ -name "memgpt" -maxdepth 5 2>/dev/null | head -5
find ~ -name ".ob1" -maxdepth 4 2>/dev/null
find ~ -name "ob1-config*" -maxdepth 5 2>/dev/null

CLAUDE.md files (session injection via project context):

find ~ -name "CLAUDE.md" -maxdepth 5 2>/dev/null | head -10
cat ~/.claude/CLAUDE.md 2>/dev/null | head -30

0c. Compile findings

Produce a structured inventory before continuing:

## Infrastructure Found

### This skill (legionforge-claude-obsidian)
- Vault: [path or "not found"]
- OBSIDIAN_VAULT_PATH: [value or "not set"]
- Hooks installed: [yes / partial / no]
  - session-startup.sh: [present / missing]
  - inject-layer0.py: [present / missing]
  - user-prompt-startup-guard.py: [present / missing]
- SessionStart hook configured: [yes / no]
- !startup.md / vault-directives.md: [present / missing]

### Other memory/second-brain systems
- MCP servers in config: [list names, e.g. "obsidian, ob1, mem0" or "none"]
- CLAUDE.md files: [paths or "none"]
- mem0 / MemGPT / ob1 / other: [found / not found + details]
- Other vault directories (not this skill): [list or "none"]

### Hooks (generic, not this skill)
- Existing SessionStart hooks: [list commands or "none"]
- Existing UserPromptSubmit hooks: [list commands or "none"]

---

Phase 0.5: Safety and Redundancy Assessment (1 min)

After compiling the inventory, assess the situation and present it to the user before proceeding. Let the user decide.

Assessment categories

Case A — Clean slate Nothing found. Safe to proceed with full setup.

✅ No existing memory infrastructure detected.
This machine appears to be a clean slate for knowledge tooling.
Safe to proceed with full setup.

Shall I continue? (yes / no)

Case B — Partial install of this skill Some components of legionforge-claude-obsidian are present but incomplete or broken.

⚠️  Partial install detected.
Found: [list what was found]
Missing: [list what was missing]

This looks like a previous setup that may have been interrupted or partially uninstalled.

Options:
  1. Repair — reinstall missing components, keep existing vault and files
  2. Reset — back up existing files, reinstall everything fresh
  3. Doctor — diagnose and surface what's broken without changing anything

Which would you prefer? (repair / reset / doctor)

Case C — Full install of this skill already present Everything appears to be installed and functional.

✅ legionforge-claude-obsidian appears to be fully installed.
Vault: [path]
Layer 0 files: present
Hooks: installed and configured
MCP servers: [status]

You likely don't need to run setup again.

Options:
  1. Verify — run the full verification protocol (Phase 5) to confirm everything works
  2. Doctor — diagnose if something stopped working
  3. Reinstall — back up and start fresh anyway (use this if things feel broken)

Which would you prefer? (verify / doctor / reinstall)

Case D — Competing or overlapping system detected Another memory/second-brain system is present. This is the most important case to handle carefully.

⚠️  Existing knowledge infrastructure detected.

Found:
  [List each system found with brief description]
  Example:
  - ob1 MCP server configured (memory retrieval via ob1)
  - Custom CLAUDE.md at ~/.claude/CLAUDE.md with session injection
  - Another Obsidian vault at ~/Documents/MyVault/ (not this skill's vault)

Potential conflicts:
  [Describe specific risks, e.g.:]
  - Two SessionStart hooks that both inject memory could produce duplicate or conflicting context
  - A different Obsidian vault means you'd be managing two separate vaults for Claude
  - ob1 and this skill's Layer 1 MCP both provide memory retrieval — they overlap but don't conflict

My assessment:
  [One of:]
  - SAFE to add: These systems cover different concerns and won't interfere.
  - REDUNDANT: You already have [X] which does what this skill does. Installing this adds complexity without clear gain.
  - POTENTIALLY CONFLICTING: [Specific reason] — you should resolve this before proceeding.

Recommendation:
  [Concrete recommendation based on findings]

Do you want to proceed with setup, knowing this? Or would you prefer to:
  1. Proceed anyway (I've reviewed the risks and want this)
  2. Abort (don't change anything)
  3. Review what the conflict means in detail before deciding

Case E — Unknown / ambiguous Evidence is mixed or unclear.

⚠️  I found some indicators but couldn't determine their status clearly.

Uncertain findings:
  [List what was found but couldn't be interpreted]

I recommend running doctor mode first to surface a clearer picture before making changes.

Options:
  1. Doctor mode — inspect without changing anything
  2. Proceed anyway — I know what I have
  3. Abort — don't touch anything

Assessment rules

• Never proceed past Phase 0.5 without explicit user confirmation.
• If the user says "just do it," treat that as Case A/B consent. Still surface what you found.
• If two SessionStart hooks both inject memory, flag this explicitly — it can cause doubled context or prompt bloat.
• ob1 and this skill's MCP are compatible but overlapping — note this but don't block.
• mem0 / MemGPT are architecturally different (cloud-backed, not file-based) — compatible, but note the design divergence.
• A CLAUDE.md doing simple session injection is compatible with Layer 0 hooks, but if it already injects vault content, that's redundant.

---

Phase 1: Gather Information (2 min)

Only run this after Phase 0 and Phase 0.5 are complete and the user has confirmed they want to proceed.

Ask the user these questions (provide defaults, skip questions already answered by Phase 0 findings):

1. Where should your vault live?
   Default: ~/Documents/
   Answer: 

2. What is your username on this machine?
   Default: (auto-detect from whoami)
   Answer: 

3. What are your absolute rules for this vault?
   Examples:
   - "Archive, never delete"
   - "Always checkpoint on test pass/fail"
   - "New memory = save immediately"
   Answer: 

4. What domains will you work in?
   Examples: rust, python, javascript, devops, ml
   Answer: , , ...

5. What Claude products do you use?
   □ Claude Code
   □ Claude Desktop
   □ Claude Dispatch
   □ Claude Cowork
   □ All of the above
   Answer: 

6. Initialize this as a git repo?
   □ Yes, new local repo
   □ Yes, push to GitHub (provide URL)
   □ No, local only
   Answer: 

Phase 2: Create Vault Structure (3 min)

Based on answers, create:

/
├── .obsidian/
├── Library/AI/
│   ├── memory/
│   │   ├── !startup.md
│   │   ├── !checkpoint.md
│   │   ├── vault-directives.md
│   │   ├── user-profile.md
│   │   ├── MEMORY.md
│   │   └── lessons/
│   │       ├── lessons-index.md
│   │       └── lessons-.md (for each domain)
│   ├── projects/
│   │   └── .gitkeep
│   └── Sessions/
│       └── .gitkeep

Phase 3: Configure Claude (5 min)

Update or create:

• ~/.claude/settings.json (Claude Code)
• ~/Library/Application Support/Claude/claude_desktop_config.json (Claude Desktop)

Configure:

• Hooks (SessionStart, UserPromptSubmit)
• MCP servers (obsidian, optional ob1)
• Permissions

If Phase 0.5 found existing hooks: back up the existing hook configuration before modifying it. Offer to merge rather than overwrite.

Phase 4: Install Hooks (2 min)

Create scripts in ~/.claude/hooks/:

• session-startup.sh
• inject-layer0.py
• user-prompt-startup-guard.py

Re-injection protection: The startup guard must check whether Layer 0 has already been injected in this session before injecting again. This prevents duplicate context on subsequent prompts in the same session. The guard writes a session marker on first injection and reads it before each subsequent injection attempt — if the marker exists, it skips re-injection silently.

If existing hooks were found in Phase 0: back up the old scripts before replacing them. Store backups at ~/.claude/hooks/backup-/.

Phase 5: Verify Setup (5 min)

Run tests:

• Check environment variables
• Verify vault structure
• Test hook execution
• Validate JSON configs
• Test MCP connectivity
• Interactive walkthrough

Phase 6: Create Installation Record (1 min)

Write to vault (timestamp, version, location):

# Installation Record

**Date:** 
**Installer:** legionforge-claude-obsidian v1.1.0
**Vault:** 
**GitHub:** https://github.com/jp-cruz/agent-skills
**Status:** ✓ All checks passed
**Pre-existing infrastructure:** 

---

Usage Examples

First-Time Setup

User: "I want to set up Claude Code with Obsidian"

Skill: [Phase 0 — scans machine, finds nothing]
       [Phase 0.5 — Case A: clean slate, confirms with user]
       [Phases 1–6 — full setup]

Result: User has fully functional three-layer context loading

Infrastructure Audit Before Setup

User: "I'm not sure if I already have a second brain set up"

Skill: [Phase 0 — scans machine, finds ob1 MCP and a CLAUDE.md]
       [Phase 0.5 — Case D: surfaces findings, assesses overlap, lets user decide]
       [User: "I'll keep ob1 but also want this"]
       [Phases 1–6 — proceeds with awareness of overlap]

Result: User understands what they have, makes an informed choice

Partial Install / Repair

User: "Something seems half-set-up from before"

Skill: [Phase 0 — finds vault and OBSIDIAN_VAULT_PATH but hooks are missing]
       [Phase 0.5 — Case B: partial install, offers repair/reset/doctor]
       [User: "repair"]
       [Phases 4–6 — reinstalls missing hooks only]

Result: Existing vault preserved, gaps filled

Repair / Doctor Mode

User: "Layer 0 isn't loading"

Skill: [Phase 0 — finds full install]
       [Phase 0.5 — Case C: full install, offers verify/doctor/reinstall]
       [User: "doctor"]
       [Detects problem]
- OBSIDIAN_VAULT_PATH not set? → Guide user to set it
- Hooks missing? → Reinstall them
- vault-directives.md not in vault? → Recreate it
- MCP not running? → Note it's optional, suggest fallback
- !startup.md out of date? → Show what's stale

Result: User understands the problem and can fix it

Cross-Platform Setup

User: "I work on macOS, Windows, and Linux"

Skill: [Phase 0 — scans each platform for existing infrastructure]
       [Phase 0.5 — assesses each platform independently]
       [Phases 1–6 — platform-specific guidance per OS]
- macOS: launchd service manager
- Linux: systemd service manager
- Windows: PowerShell execution policy, environment variables

Result: User can set up identically on all three OS

---

Technical Details

Environment Variables

The system relies on one key variable:

export OBSIDIAN_VAULT_PATH="/Users//Documents/my-vault"

Set this in:

• ~/.zshrc or ~/.bashrc (macOS/Linux)
• PowerShell $PROFILE (Windows)

Hook Execution Flow

Session Start
  ├─ SessionStart hook
  │  └─ Calls: bash ~/.claude/hooks/session-startup.sh
  │     └─ Calls: python3 ~/.claude/hooks/inject-layer0.py
  │        └─ Loads vault-directives.md, !startup.md, user-profile.md
  │           └─ Injects into system message (Layer 0)
  │
  └─ User's first prompt
     └─ UserPromptSubmit hook
        └─ Calls: python3 ~/.claude/hooks/user-prompt-startup-guard.py
           └─ Checks session marker — if already injected, skip
           └─ If first prompt: sends brief notice "Layer 0 injected. Layer 1 via MCP."
           └─ Writes session marker to prevent re-injection on subsequent prompts

Re-injection protection detail: The session marker is a lightweight flag (e.g., a temp file at /tmp/.layer0-injected-) written after first injection. The guard reads this file before each injection attempt. If the file exists and belongs to the current session, injection is skipped. This prevents Layer 0 from being injected on every prompt — only on session start.

MCP Server Configuration

Both Claude Code and Claude Desktop can connect to Obsidian MCP:

{
  "mcpServers": {
    "obsidian

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jp-cruz](https://github.com/jp-cruz)
- **Source:** [jp-cruz/agent-skills](https://github.com/jp-cruz/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.