Claude Code x Obsidian Integration Guide: Vault Structure, Permissions, Templates, and Link Audits

Obsidian gets more valuable as your Vault grows, but that growth also creates maintenance work. Daily notes pile up, project notes drift out of date, code snippets lose context, and content ideas stop linking to the articles or products they should support. Claude Code can help, because an Obsidian Vault is mostly a folder of Markdown files.

The useful pattern is not “let the AI reorganize everything.” The useful pattern is a bounded workflow: give Claude Code a clear Vault structure, keep permissions narrow, use reusable note templates, and run a small audit before trusting the result. In beginner terms, the Vault is the folder that stores your notes, and the Claude Code harness is the working frame that tells the agent where it may read, where it may write, and what checks it must run.

This guide covers four practical use cases: daily logs, project handoff notes, reusable code snippets, and content operations. It also calls out each major pitfall, because the main risk is not bad prose. The main risk is silent damage to links, metadata, private notes, or published material.

The Integration Model

Obsidian’s official help explains that internal links can use Wikilinks like [[Note name]] or Markdown links. Daily notes are a core plugin for date-based logs. Templates can insert values such as {{date}}, and Properties are stored as YAML at the top of a note. See the official pages for internal links, Daily notes, Templates, Properties, and Web Clipper templates.

On the Claude Code side, use settings and permissions as the safety boundary. CLAUDE.md teaches the agent your Vault conventions. .claude/settings.json tells it which folders are safe, which edits require confirmation, and which files are off limits.

flowchart LR
  A["Inbox"] --> B["Claude Code review"]
  B --> C["Daily logs"]
  B --> D["Projects"]
  B --> E["Content ops"]
  C --> F["Obsidian links"]
  D --> F
  E --> F
  F --> G["Link audit"]

Claude Code is not the system of record. Markdown in Obsidian is the system of record. Claude Code is the assistant that sorts, drafts, summarizes, checks links, and reports what changed.

Use a Small Vault Structure

Start with a structure that maps to real work. Too many folders create another classification problem.

mkdir -p inbox daily projects content-ops snippets templates scripts archive private

Folder	Purpose	Safe Claude Code work
inbox/	Raw captures and Web Clipper notes	Create and triage
daily/	Daily logs and working memory	Create, append, summarize yesterday
projects/	Project handoff and active decisions	Update handoff notes
content-ops/	Article ideas, CTA checks, publishing notes	Organize drafts and links
snippets/	Commands and code examples	Add context and tags
templates/	Obsidian note templates	Read freely, edit only after approval
archive/	Completed or frozen notes	No edits
private/	personal, legal, financial, or secret notes	No reads

This structure supports concrete use cases. Daily logs carry unfinished work from yesterday. Project handoff notes explain the current state when you switch machines or hand work to another person. Snippet notes preserve the exact command, dependency version, and failure mode. Content operations notes connect article drafts to official links, internal links, /products/, and /training/.

Add CLAUDE.md at the Vault Root

Put this file at the root of the Vault. It should be operational, not inspirational.

# Obsidian Vault Rules

## Purpose
- This vault stores daily logs, project handoffs, code snippets, and content operations notes.
- Keep notes useful in Obsidian without requiring Claude Code to read private files.

## Directory policy
- `daily/`: create or update daily notes in `YYYY-MM-DD.md`.
- `projects/`: maintain one handoff note per active project.
- `content-ops/`: maintain article plans, CTA checks, and publishing notes.
- `snippets/`: store runnable commands and code examples with context.
- `templates/`: read freely, but ask before editing.
- `archive/` and `private/`: do not edit. Do not summarize private files.

## Note rules
- Use Wikilinks like `[[Project name]]` for internal links.
- Use YAML properties at the top of notes.
- Keep one paragraph under five lines.
- Add a `source:` property when a note comes from a URL.
- Add `status: draft`, `status: active`, or `status: done`.

## Safety rules
- Never rename existing notes without asking first.
- Never rewrite `.obsidian/` settings.
- Before bulk edits, list the target files and wait for approval.
- After changes, run `node scripts/audit-wikilinks.cjs .`.

The common pitfall is writing “organize my Vault” and expecting stable behavior. Claude Code will infer folder names, headings, and tags. Those guesses may be fluent but still harmful to search, Graph view, and handoff notes.

Configure Narrow Permissions

Create .claude/settings.json in the Vault. This example allows routine note work, asks before template edits or network access, and blocks private or fragile areas.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Read(./CLAUDE.md)",
      "Read(./daily/**)",
      "Read(./projects/**)",
      "Read(./content-ops/**)",
      "Read(./snippets/**)",
      "Read(./templates/**)",
      "Read(./scripts/**)",
      "Edit(./daily/**)",
      "Edit(./projects/**)",
      "Edit(./content-ops/**)",
      "Edit(./snippets/**)",
      "Write(./inbox/**)",
      "Write(./daily/**)",
      "Write(./projects/**)",
      "Write(./content-ops/**)",
      "Write(./snippets/**)",
      "Bash(node scripts/audit-wikilinks.cjs .)"
    ],
    "ask": [
      "Edit(./templates/**)",
      "Bash(git *)",
      "WebFetch"
    ],
    "deny": [
      "Read(./private/**)",
      "Read(./**/.env)",
      "Read(./**/.env.*)",
      "Edit(./.obsidian/**)",
      "Edit(./archive/**)",
      "Write(./archive/**)",
      "Bash(rm *)",
      "Bash(del *)"
    ]
  }
}

This is intentionally conservative. If your use case requires Web Clipper cleanup or source verification, approve WebFetch when needed instead of making it automatic. Avoid broad bypass modes for a real personal Vault unless the Vault is disposable or isolated.

Create Three Obsidian Templates

The daily template should stay thin. A heavy daily note becomes a guilt machine instead of a log.

---
date: "{{date:YYYY-MM-DD}}"
status: active
tags:
  - daily
---

# {{date:YYYY-MM-DD}}

## Today
- [ ]

## Learned
-

## Questions
-

## Links
- [[Weekly review]]

The project handoff template should make the next action obvious. Claude Code can summarize, but humans need the status and risk first.

---
status: active
owner: Masa
tags:
  - project
  - handoff
updated: "{{date:YYYY-MM-DD}}"
---

# Project handoff: {{title}}

## Goal

## Current state

## Next action
- [ ]

## Decisions
-

## Risks and pitfall
-

## Links
- [[Daily note]]
- [[Related snippet]]

For content operations, include the monetization path before drafting. That keeps CTAs relevant instead of bolted on later.

---
status: draft
channel: blog
source:
target_cta:
  - /products/
  - /training/
tags:
  - content-ops
---

# Content ops note: {{title}}

## Search intent

## Reader problem

## Outline

## Internal links
- [[Claude Code approval sandbox guide]]
- [[Claude Code documentation generation]]

## Monetization CTA
- Product CTA:
- Training CTA:

## Publish checklist
- [ ] Official links checked
- [ ] Code examples tested
- [ ] Broken internal links audited

Related site workflows: approval and sandboxing, documentation generation, and content funnel audits. For reusable prompts and setup material, route readers to products. For team rollout, permission design, and repository-specific training, use training.

Audit Broken Internal Links with Node

Save this as scripts/audit-wikilinks.cjs and run it after Claude Code edits the Vault. It checks Wikilinks and non-external Markdown links against files in the Vault.

#!/usr/bin/env node
const fs = require("node:fs");
const path = require("node:path");

const vaultRoot = path.resolve(process.argv[2] || ".");
const ignoredDirs = new Set([".git", ".obsidian", ".trash", "node_modules"]);
const allFiles = [];
const markdownFiles = [];

function walk(dir) {
  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    if (ignoredDirs.has(entry.name)) continue;
    const full = path.join(dir, entry.name);
    if (entry.isDirectory()) {
      walk(full);
    } else if (entry.isFile()) {
      allFiles.push(full);
      if (entry.name.toLowerCase().endsWith(".md")) markdownFiles.push(full);
    }
  }
}

function toPosix(filePath) {
  return filePath.split(path.sep).join("/");
}

function withoutMd(value) {
  return value.replace(/\.md$/i, "");
}

function stripTarget(raw) {
  return raw.split("|")[0].split("#")[0].split("^")[0].trim();
}

function safeDecode(value) {
  try {
    return decodeURIComponent(value);
  } catch {
    return value;
  }
}

function isExternal(target) {
  return /^(https?:|mailto:|obsidian:|#|\/)/i.test(target);
}

function candidateKeys(target, fromFile) {
  const clean = safeDecode(stripTarget(target));
  if (!clean) return [];
  const keys = new Set();
  const normalized = toPosix(path.normalize(clean));
  keys.add(normalized);
  keys.add(withoutMd(normalized));

  if (clean.includes("/") || clean.includes("\\")) {
    const fromDir = path.dirname(toPosix(path.relative(vaultRoot, fromFile)));
    const relative = toPosix(path.normalize(path.join(fromDir, clean)));
    keys.add(relative);
    keys.add(withoutMd(relative));
  } else {
    keys.add(withoutMd(path.posix.basename(normalized)));
    keys.add(path.posix.basename(normalized));
  }

  return [...keys].filter(Boolean);
}

walk(vaultRoot);

const byPath = new Map();
const byBase = new Map();

for (const file of allFiles) {
  const rel = toPosix(path.relative(vaultRoot, file));
  const lowerRel = rel.toLowerCase();
  byPath.set(lowerRel, file);
  if (rel.toLowerCase().endsWith(".md")) byPath.set(withoutMd(lowerRel), file);

  const base = rel.toLowerCase().endsWith(".md")
    ? withoutMd(path.posix.basename(rel)).toLowerCase()
    : path.posix.basename(rel).toLowerCase();
  const list = byBase.get(base) || [];
  list.push(file);
  byBase.set(base, list);
}

const problems = [];
const wikilink = /!?\[\[([^\]]+)\]\]/g;
const markdownLink = /!?\[[^\]]*\]\(([^)]+)\)/g;

for (const file of markdownFiles) {
  const text = fs.readFileSync(file, "utf8");
  const rel = toPosix(path.relative(vaultRoot, file));
  const targets = [];
  let match;

  while ((match = wikilink.exec(text))) targets.push(match[1]);
  while ((match = markdownLink.exec(text))) {
    const target = match[1].replace(/^<|>$/g, "").trim();
    if (!isExternal(target)) targets.push(target);
  }

  for (const target of targets) {
    const clean = stripTarget(target);
    if (!clean || isExternal(clean)) continue;
    const keys = candidateKeys(clean, file);
    const pathHit = keys.some((key) => byPath.has(key.toLowerCase()));
    const baseHits = keys.flatMap((key) => byBase.get(path.posix.basename(key).toLowerCase()) || []);

    if (!pathHit && baseHits.length === 0) {
      problems.push(`${rel} -> missing [[${clean}]]`);
    } else if (!pathHit && baseHits.length > 1) {
      problems.push(`${rel} -> ambiguous [[${clean}]] (${baseHits.length} matches)`);
    }
  }
}

if (problems.length) {
  console.error("Broken or ambiguous internal links:");
  for (const problem of problems) console.error(`- ${problem}`);
  process.exit(1);
}

console.log(`OK: checked ${markdownFiles.length} Markdown files in ${vaultRoot}`);

Run it from the Vault root:

node scripts/audit-wikilinks.cjs .

Then give Claude Code a bounded prompt:

Read `daily/2026-06-02.md` and `projects/site-refresh.md`.
Create `daily/2026-06-03.md` from `templates/daily.md`.
Carry over unfinished tasks only when they still have an owner.
Do not edit `.obsidian/`, `archive/`, or `private/`.
After editing, run `node scripts/audit-wikilinks.cjs .` and report the result.

Pitfalls to Avoid

The first pitfall is letting Claude Code edit .obsidian/. Plugin settings, themes, workspaces, and hotkeys are user experience state, not ordinary notes.

The second pitfall is renaming notes outside Obsidian. Obsidian can help update links when you rename files in the app, but external bulk renames can still break links. Ask before renames.

The third pitfall is malformed YAML Properties. If a property contains an internal link, quote it, for example related: "[[Project name]]".

The fourth pitfall is overbuilt daily notes. Keep the template small and ask Claude Code to summarize only the parts you will actually read.

The fifth pitfall is treating content operations as pure writing. A public article also needs official links, internal links, CTA checks, and a final verification record.

What Masa Tested

In Masa’s test Vault, the best return came from two workflows: carrying unfinished daily work into the next note, and auditing links before publishing content notes. The weakest experiment was asking Claude Code to “clean up the whole Vault.” It invented too many tags and headings. A narrow permission set, thin templates, and the Node link audit produced a more reliable Obsidian workflow without making the Vault feel machine-owned.