gtapps/obsidian-setup

Obsidian Setup

Sets up the Hermit Cortex in the current project. Safe to re-run — see --force scope below.

Pass --reconfigure-manifest to re-run only the artifact path discovery wizard (updates cortex-manifest.json and rebuilds Connections.md).

Step 1 — Check prerequisites

1. Read .claude-code-hermit/config.json to confirm the hermit is hatched.
2. If .claude-code-hermit/ does not exist, stop: "Run /claude-code-hermit:hatch first."
3. Check whether an obsidian/ directory already exists by using Glob("obsidian/*.md") — if it returns results, the Cortex is already set up.
   • If it exists and neither --force nor --reconfigure-manifest was passed: list existing pages and ask: "Obsidian Cortex already set up. Use --force to overwrite static pages, or --reconfigure-manifest to update artifact paths."
   • If --force was passed: proceed (static pages will be replaced).
   • If --reconfigure-manifest was passed: skip to Step 4 directly.

--force scope:

| Component | Default | --force | | ------------------------------------------------------ | ------------------ | ---------------------------------------- | | Static pages (Brain, Cortex, Evolution, System Health) | Skip if exists | Overwrite | | cortex-manifest.json | Skip if exists | Skip (operator-managed, never overwrite) | | Connections.md / Cortex Portal.md | Always regenerated | Always regenerated |

Step 2 — Set path mode

Set HERMIT_PATH = .claude-code-hermit.

Step 3 — Copy templates

For each template in ${CLAUDE_PLUGIN_ROOT}/state-templates/obsidian/:

• Replace {{GENERATED_AT}} with current ISO timestamp
• Write to obsidian/<template-name-without-.template> in the project root
• Skip files that already exist (unless --force)

Templates to copy:

• Brain.md.template → obsidian/Brain.md
• Cortex.md.template → obsidian/Cortex.md
• Evolution.md.template → obsidian/Evolution.md
• System Health.md.template → obsidian/System Health.md
• Connections.md.template → obsidian/Connections.md (header only — body generated in step 5)
• Cortex Portal.md.template → obsidian/Cortex Portal.md (header only — body generated in step 5)

Step 4 — Generate cortex-manifest.json

If .claude-code-hermit/cortex-manifest.json does not exist (first run):

1. Scan the project root for candidate artifact paths using these heuristics:

   • Directories containing 2+ .md files (exclude .git, node_modules, .claude-code-hermit, .claude, obsidian, .vscode, .github)
   • Root-level .md files with existing YAML frontmatter (stronger signal than bare .md)
   • Root-level .md files matching date-like patterns (e.g. *-2026-*.md, *-YYYY-*.md)
   • Always include .claude-code-hermit/compiled as a default path — this is where durable domain outputs live and should always be indexed.

2. If candidates found, present them to the operator:

   questions: [
     {
       header: "Artifacts",
       question: "These directories and files look like hermit-produced content. Files in these paths will appear in Connections.md and the Obsidian graph:\n{candidate_list}\nConfirm, edit, or skip.",
       options: [
         { label: "Confirm as-is", description: "Use all listed paths" },
         { label: "Skip", description: "Empty artifact_paths — add later via --reconfigure-manifest" }
       ]
     }
   ]
   

   • If "Confirm as-is": use all candidates
   • If free text typed via Other: parse as the operator's edited list
   • If "Skip": write empty artifact_paths: []

3. Let the operator confirm, add, remove, or skip entirely.

4. Write .claude-code-hermit/cortex-manifest.json with confirmed paths. If operator skips: write with an empty artifact_paths array.

If .claude-code-hermit/cortex-manifest.json already exists and --reconfigure-manifest was passed:

1. Read the current file and show the operator the existing artifact_paths as the starting point.
2. Re-run the scan for any new candidate paths not already in the manifest.
3. Present existing + new candidates:

   questions: [
     {
       header: "Artifacts",
       question: "Current paths: {existing}\nNew candidates found: {new_candidates}\nConfirm, edit, or reset.",
       options: [
         { label: "Confirm all", description: "Keep existing paths and add new candidates" },
         { label: "Keep current", description: "Ignore new candidates, keep only existing" },
         { label: "Reset", description: "Clear all artifact paths and start fresh" }
       ]
     }
   ]
   

4. Write the updated manifest. Then skip to Step 5 (generate dynamic pages) and stop after — skip steps 6–7.

If file already exists and --reconfigure-manifest was NOT passed: skip this step.

Step 5 — Generate dynamic pages

Run:

node ${CLAUDE_PLUGIN_ROOT}/scripts/build-cortex.js .claude-code-hermit obsidian .

This generates obsidian/Connections.md from current session, proposal, and artifact data. obsidian/Cortex Portal.md is a static Dataview template copied from the plugin — it does not need generation and should not be overwritten by this script.

Step 5b — Create Latest Review placeholder

If obsidian/Latest Review.md does not exist, write a placeholder:

# Latest Review

> No weekly review has run yet. Run `/claude-code-hermit:weekly-review` manually, or enable the `weekly-review` routine in config.json.

This file is overwritten by scripts/weekly-review.js on first run — the placeholder simply prevents dangling wikilinks in Cortex.md and Cortex Portal.md.

Step 6 — Add cortex-refresh routine

Read .claude-code-hermit/config.json. Check if a routine with id: "cortex-refresh" already exists.

• If not: append to the routines array:

  {
    "id": "cortex-refresh",
    "schedule": "30 23 * * *",
    "skill": "claude-code-hermit:cortex-refresh",
    "enabled": true
  }
  

• If it exists: skip (no duplicate).

Write the updated config.json back atomically (write to state/.config.json.tmp, rename to config.json).

Step 7 — Print first-run instructions

Hermit Cortex created in obsidian/

  Operator view into your hermit's current state and evolution.

  First look:
  1. Open your repo root as an Obsidian vault (if not already)
  2. Install the FolderBridge community plugin — required for Dataview to read .claude-code-hermit/
     https://github.com/tescolopio/Obsidian_FolderBridge
  3. Open obsidian/Brain.md — live session, fragile zones, what needs attention
  4. Open obsidian/Cortex.md — uncertainty, stability, regressions, operator dependence
  5. Open obsidian/Cortex Portal.md → right-click tab → Open local graph
     Session and proposal nodes radiate from the cortex pages at center.

  Pages:
    Brain.md            — live session, fragile zones, what needs attention
    Cortex.md           — uncertainty, stability, regressions, operator dependence
    Evolution.md        — first vs latest, cost trends, autonomy trajectory
    System Health.md    — agent state, alerts, incomplete sessions
    Connections.md      — relationship map: sessions ↔ proposals ↔ artifacts
    Cortex Portal.md    — graph center: links everything

  Artifact tracking:
    Files declared in cortex-manifest.json appear in Connections.md.
    Add title + created frontmatter to connect them to the graph.
    Update paths anytime: /claude-code-hermit:obsidian-setup --reconfigure-manifest

  Connections refresh nightly at 23:30.

  To enrich existing content with frontmatter and tags:
    /claude-code-hermit:cortex-sync

Note: At session 1, Brain.md shows your live session and empty Dataview tables. By session 10, Cortex.md starts showing fragile zones. By session 20, Evolution.md tells a real story. The cortex gets more useful the longer your hermit runs.