Obsidian and Claude Agent: a safe write-back workflow

A durable Obsidian and Claude Agent workflow needs a verifiable data path: archive the source, read only the relevant files, retain citations, write to a draft area, and review every change before it reaches permanent notes. You can build the first version with Markdown files and a CLAUDE.md; MCP and community plugins are optional extensions.

Why Obsidian works well in a Claude Agent workflow

An Obsidian vault is a directory on your file system, and most of its content is stored as regular Markdown. A file-capable agent such as Claude Code can search those files by path, follow links, and read selected notes. Other clients can reach the same material through an MCP server or an Obsidian community plugin.

That gives the workflow three useful properties:

1. The material stays portable. Markdown files can live in Git, a backup drive, or another editor. They do not depend on one AI plugin.
2. Operational rules can live beside the notes. Directory boundaries, naming conventions, citation formats, and write permissions can all go into CLAUDE.md and be reused on every task.
3. Changes are reviewable. You can inspect the lines an agent added or removed through a file diff or Git history.

Public examples already show two broad patterns. Some users open the vault directly in Claude Code and use journals, project material, and writing notes as context. Others expose search, backlinks, tags, and controlled write tools through an Obsidian plugin or MCP server. The community project WeSight goes further by keeping topic selection, content production, formatting, and review inside one local repository. These are community implementations with different security boundaries, not product guarantees from Obsidian or Anthropic.

Three ways to connect Obsidian to Claude

Option 1: let Claude Code read the vault directly

This is the simplest starting point.

Open the vault as the working directory, or mount only the note folders required for the task. Claude Code can search Markdown, follow WikiLinks, create drafts, and organize files much as it would inside a code repository.

The setup is small, the behavior is easy to observe, and file changes are straightforward to review. The trade-off is that the agent sees a file system. It does not automatically understand every semantic rule introduced by an Obsidian plugin, and a large vault should not be loaded into context all at once.

Direct access is useful for:

• turning a set of source notes into a research brief;
• extracting tasks and decisions from meeting notes;
• suggesting tags, summaries, and links for older notes;
• generating a weekly report, tutorial, or FAQ from project material; and
• detecting broken links, duplicate titles, or inconsistent frontmatter.

The screenshot below shows a common setup: Claude Code creates or reads vault instructions on the left, while Obsidian renders the resulting CLAUDE.md on the right. The location is useful as a reference, but the rules still need to match your own folders and permissions.

Option 2: expose dedicated vault tools through MCP

Add an MCP server when you need structured operations such as searching notes, reading backlinks, updating frontmatter, or moving notes.

The open-source LWaetzig/obsidian-mcp project treats a vault as a Markdown directory, so Obsidian does not need to remain open. Once configured, MCP clients such as Claude Code, Claude Desktop, Cursor, or VS Code can call dedicated tools. Another implementation, StevenStavrakis/obsidian-mcp, explicitly warns that the server has read and write access to the selected vault. Back up the vault and expose only the intended directory.

MCP becomes useful when:

• multiple agent clients need the same note collection;
• search, create, move, and tag updates should be fixed tool calls;
• you need clearer parameters and return values than generic file operations; or
• the vault is part of a longer automation pipeline.

MCP does not validate source quality, preserve citations, or define permissions on its own. It is the connection layer. You still decide which write tools an agent can call and which directories it may modify.

Option 3: use a reviewable agent plugin inside Obsidian

A community plugin can keep chat, context selection, and change review inside the Obsidian interface.

For example, Companion for Claude provides vault context, an agent mode, per-hunk diff review, and an optional local MCP bridge. Its public documentation says that read operations are available by default, while create and edit operations require confirmation. The local bridge binds to 127.0.0.1, uses a bearer token, and supports a custom Base URL.

This is an independent community plugin. It is not an Anthropic or Obsidian product. Before installing any plugin, check its maintenance status, requested permissions, data destinations, and fit with your team's security requirements.

Use this table to choose a route:

A 10-minute Obsidian and Claude Code setup

The following walkthrough uses Windows. It does not install MCP or depend on an Obsidian community plugin. Its purpose is to validate the workflow with the smallest possible surface area.

Prerequisites

Prepare the following:

• Obsidian Desktop and a test vault;
• a working Claude Code installation;
• one Markdown source with no sensitive information; and
• a vault backup, or a separate test copy.

Do not start with the vault you use every day. Create a vault named Obsidian-Agent-Demo and add three to five public documents.

Step 1: start Claude Code inside the vault

Open PowerShell and enter the vault directory:

Set-Location -LiteralPath "D:\Notes\Obsidian-Agent-Demo"
claude

Keep the quotation marks and use -LiteralPath if the path contains spaces or non-ASCII characters. Start with a read-only test:

List the Markdown files and first-level directories in the current directory.
Do not create, edit, move, or delete any file.

The result should contain only a file listing. No write operation should occur.

Step 2: create the minimum folder structure

You can create the folders manually or ask Claude Code to do it. For the first run, creating them manually makes every path easy to verify:

$folders = @(
  "00_Inbox",
  "10_Sources\Web",
  "10_Sources\Meetings",
  "20_Notes\_drafts",
  "20_Notes\Concepts",
  "30_Projects\_drafts",
  "90_Archive"
)

foreach ($folder in $folders) {
  New-Item -ItemType Directory -Force -Path $folder | Out-Null
}

Place the test article in 10_Sources/Web/. Use a descriptive topic in the filename instead of the random string left by a browser download.

Step 3: add CLAUDE.md

Save the rules template later in this guide as CLAUDE.md in the vault root. Restart Claude Code and ask:

Restate the read scope, write scope, and actions that require human approval in this vault.
Do not perform any file operation.

A correct response should identify the read-only source directory, the writable draft directories, and the approval requirement for delete and move operations. If any boundary is missing, verify that CLAUDE.md is in the current working directory and that the folder names match the rules.

Step 4: complete one controlled write

Ask the agent to read one source and create a note only in the draft area. Then run:

Get-ChildItem -LiteralPath ".\20_Notes\_drafts" -Filter "*.md"

Check the last-modified timestamps of the source files:

Get-ChildItem -LiteralPath ".\10_Sources" -Recurse -File |
  Select-Object FullName, LastWriteTime

Those timestamps should not change. You now have a minimal closed loop: the agent can read source material, write to an approved draft directory, and leave the original material untouched.

Add an Obsidian MCP server when file access is not enough

Add an MCP server when plain file access cannot cover backlinks, tag queries, or multi-client access. The commands below use the npx execution pattern from the open-source obsidian-mcp project. Back up the vault first:

claude mcp add obsidian -- npx -y obsidian-mcp "D:\Notes\Obsidian-Agent-Demo"
claude mcp list

Package names, arguments, and Node.js requirements vary across MCP implementations. Check the current README of the repository you choose before copying any command. Once connected, test a read operation first:

Use the obsidian tool to find notes with "Agent" in the title.
Return only the matching titles and file paths. Do not write any file.

After that test passes, create one empty note in _drafts. Do not enable delete, bulk move, or whole-vault rewrite permissions during the first connection.

Four MCP settings to verify before regular use

For a shared team vault, give the agent a synchronized working copy. Merge reviewed drafts into the primary vault through a pull request, file review, or manual move. This avoids concurrent edits to the same file by both people and agents.

Separate source material from agent drafts

This directory template is intentionally small:

MyVault/
├─ 00_Inbox/                 # Temporary captures waiting for triage
├─ 10_Sources/               # Original sources; read-only for the agent
│  ├─ Web/
│  ├─ Reports/
│  └─ Meetings/
├─ 20_Notes/                 # Reviewed, durable knowledge
│  ├─ Concepts/
│  ├─ Cases/
│  └─ _drafts/               # Agent drafts; the only writable subfolder
├─ 30_Projects/              # Project notes and deliverables
├─ 90_Archive/               # Archived material
├─ Templates/
└─ CLAUDE.md

Two boundaries do most of the work:

• 10_Sources contains original material and remains read-only to the agent.
• New material starts in 20_Notes/_drafts and moves to a permanent directory only after review.

You do not need to rebuild an existing PARA, Zettelkasten, or project system. Mark the existing source, draft, and permanent-note areas instead.

Add minimum metadata to source notes

When you save a web page, newsletter, or article as Markdown, retain at least these fields:

---
title: "Article title"
source_url: "https://example.com/article"
author: "Author or organization"
published_at: "2026-08-20"
retrieved_at: "2026-08-22"
source_type: "web"
status: "source"
---

published_at records when the original material appeared. retrieved_at records when you captured it. Keeping both helps the agent reason about time-sensitive material.

Preserve headings and original links in the body. Screenshots can remain as attachments, but important claims should also exist as searchable text. Record page numbers for PDF sources. If text came from OCR, mark it as OCR output so a recognition error does not silently become a source claim.

Write CLAUDE.md rules for an Obsidian vault

Save the following template as CLAUDE.md in the vault root, then replace the directory names where necessary:

# Vault operating rules

## Read scope
- You may read: 10_Sources, 20_Notes, and 30_Projects.
- Search titles and summaries first, then read only the most relevant files.
- Do not load the entire vault at once.

## Write scope
- You may create or edit files only in 20_Notes/_drafts and 30_Projects/_drafts.
- Do not edit, move, or delete files in 10_Sources.
- Do not bulk-rename permanent notes.

## Citation requirements
- Retain source_url for every external factual claim.
- Include the source note path when citing local material.
- Cite page numbers for PDFs; retain the title and URL for web sources.
- If a claim has no supporting source, mark it as "Needs verification." Do not present it as fact.

## Output format
- Every new note must include title, summary, sources, status, and updated.
- Set status to draft by default.
- End with: Verified facts, Items to verify, and Suggested related notes.

## Execution rules
- Provide a change summary before editing an existing note.
- Wait for human approval before overwrite, move, or delete operations.
- Process only the scope named in the current task.

These instructions do not replace operating-system permissions. If the agent can write to the entire drive, a prompt can only reduce the chance of a mistake. For team material or an important vault, use file permissions, a container, an isolated copy, or version control to limit the blast radius.

Generate the first traceable research note

Choose one source already stored in 10_Sources/Web/, then send the following task:

Read 10_Sources/Web/obsidian-agent-source.md.

Create a research note in 20_Notes/_drafts/ with these requirements:
1. Explain the source's subject in no more than 120 words.
2. Extract five concrete findings.
3. For each finding, include the original section heading, local source-note path, and source_url.
4. Put claims that cannot be confirmed from the source under "Needs verification."
5. Do not edit the source file or move any existing note.
6. When finished, report only the new file path and citation count.

Review the output against four checks:

1. Open two citations at random and verify that the source supports the finding.
2. Check whether an author's opinion was rewritten as an objective fact.
3. Confirm that the new note did not overwrite an existing file.
4. After approval, move the draft into 20_Notes/Cases/ or the relevant project directory.

Add batch processing, backlinks, or automatic tags only after this single-source task passes. A small first test makes failures easier to locate.

Three reusable Obsidian Agent task templates

Turn web sources into research cards

Use this for product research, market research, and editorial source libraries.

Task: Turn today's new files in 10_Sources/Web/ into research cards.

Requirements:
- Create one card per source and save it in 20_Notes/_drafts/.
- Retain the original title, author, publication date, retrieval date, and source_url.
- Keep the summary under 150 words.
- Separate the output into Facts, Author's interpretation, and Actionable information.
- Give each fact its original heading or source location.
- When sources conflict, record both claims instead of merging them.
- Mark unsupported data as "Needs verification."
- Do not edit files in 10_Sources.

At the end, return the generated-file list, total citation count, and items requiring verification.

During review, check whether an author's view became an industry-wide fact and whether a secondary report still identifies its primary source.

Turn meeting notes into decisions and tasks

Use this for weekly meetings, project reviews, and customer calls.

Read 10_Sources/Meetings/2026-08-22-project-weekly.md.

Create a meeting brief in 30_Projects/_drafts/ that contains:
1. Confirmed decisions.
2. Action items, owners, and due dates.
3. Unresolved disagreements.
4. Material that still needs to be collected.
5. The original meeting-note paragraph supporting each item.

If the meeting does not specify an owner or date, write "Not specified." Do not guess.
Do not create calendar events, send messages, or edit a permanent project document.

Meeting notes often tempt a model to fill gaps so that the table looks complete. Explicitly using Not specified prevents the agent from inventing team decisions.

Generate an article outline from existing notes

Use this when an editorial team wants to connect its source library to a writing workflow.

Create an article outline about safely connecting an Obsidian vault to Claude Agent in an organization.

Source scope:
- 10_Sources/Web/Obsidian/
- 20_Notes/Cases/Obsidian/

Write to: 30_Projects/_drafts/obsidian-agent-outline.md

Requirements:
- List the source files actually used.
- Attach at least one source to each H2.
- Distinguish vendor documentation, open-source project documentation, and individual user experience.
- Do not use performance claims that the sources do not substantiate.
- List sections that still lack evidence at the end of the outline.
- Do not draft the full article yet.

A source-linked outline exposes evidence gaps before the draft grows around unsupported claims.

Use consistent frontmatter for agent drafts

Give agent-generated notes one shared schema so you can filter and review them later:

---
title: "Safe write-back for an Obsidian Agent workflow"
summary: "How to combine read-only sources, draft-only writes, and human review"
type: "research-note"
status: "draft"
created_by: "claude-agent"
created_at: "2026-08-22"
reviewed_by: ""
reviewed_at: ""
sources:
  - "[[10_Sources/Web/obsidian-agent-source]]"
tags:
  - obsidian
  - agent-workflow
---

After approval, set status to reviewed, add the reviewer and date, and move the note into a permanent directory. Obsidian Search, Dataview, or Bases can then list every pending draft without requiring a manual folder-by-folder review.

Standardize the citation block

Each durable claim should point back to a source. A compact format is enough:

## Finding

An Obsidian Agent workflow should keep original sources separate from generated drafts.

**Evidence**
- Source note: [[10_Sources/Web/obsidian-agent-source]]
- Location: Section 3, "Write-back safety"
- External URL: https://example.com/article
- Verification status: Verified

For a larger research collection, you can also store exact excerpts, page numbers, retrieval times, and content fingerprints. The open-source codex-obsidian-workflow project uses page- or block-level provenance, line-number and hash binding, and conflict rollback. A personal vault may not need every mechanism, but every durable finding should still lead back to the relevant source passage.

Safe write-back: propose, review, then merge

A controlled write flow has four steps:

1. Generate a draft. New content goes only into _drafts.
2. Show the diff. Before editing an existing note, display added, deleted, and replaced passages.
3. Require human review. Accept useful changes and reject incorrect or excessive rewrites.
4. Keep a history. Use Git, the Obsidian Git plugin, or regular snapshots.

Enable per-hunk diff review when a plugin supports it. With direct Claude Code access, ask for a change plan before editing and inspect the resulting file diff. Keep human approval for delete, move, bulk rename, and frontmatter overwrite operations.

Start with these capabilities disabled:

• file deletion;
• changes to 10_Sources;
• bulk move or rename operations;
• automatic publishing to a website or newsletter; and
• access to folders containing passwords, original contracts, or customer data.

Retrieval strategy for a large Obsidian vault

Once a vault contains hundreds or thousands of notes, sending the whole repository as context increases latency, irrelevant context, and token usage. Use this retrieval order instead:

1. Filter by filename, tags, frontmatter, and keywords.
2. Read summaries and headings from the candidate notes.
3. Expand only the passages directly related to the task.
4. Add a local index or semantic-search MCP tool only when cross-vault keyword search is insufficient.

Summaries are navigation aids, not substitutes for source text. Return to the relevant passage before writing a finding.

A four-pass reading strategy that reduces token use

For a vault with 3,000 notes, split a research task into four passes:

1. Retrieval pass: return file paths, titles, tags, and one-sentence summaries.
2. Selection pass: choose 10 to 20 candidates and read their headings.
3. Evidence pass: open only the passages that can support the planned findings.
4. Drafting pass: send the reviewed evidence packet to the model.

Persist the output of each pass so a failed request does not restart the entire vault search. Reusable project context, editorial rules, and templates can use prompt caching or local summaries. Time-sensitive web facts should still be rechecked at the beginning of the task.

Handling sensitive material in an Obsidian vault

Start by assigning a risk level to vault content:

Before installing a third-party plugin, establish whether content leaves the machine, which model service receives it, how long logs persist, and whether the plugin can read the entire vault. If the answers are unclear, use a test vault with public material.

Where Code0 fits in the architecture

Obsidian provides local knowledge storage and the editing interface. Claude Agent interprets tasks, calls tools, and generates output. MCP or a plugin provides the connection. Code0 sits at the model-access layer, where one key can access 300+ models while centralizing request endpoints, model switching, call records, and cost management.

If an Obsidian plugin or agent client supports a custom Anthropic-compatible Base URL, set the request address to https://code0.ai. Use the API key and model ID currently shown in the Code0 console. Existing clients usually need only the request-address update, but field names vary by software version.

Changing the Base URL does not limit which local notes the agent can read, and it does not add write approval. Directory allowlists, read-only source areas, diff review, and versioned backups remain separate controls.

Obsidian Agent deployment checklist

• [ ] Back up the vault or add it to Git.
• [ ] Identify source, draft, and permanent-note areas.
• [ ] Add source_url, author, and dates to source notes.
• [ ] Create CLAUDE.md in the vault root.
• [ ] Enable only read access and draft-directory writes in the first phase.
• [ ] Test citation traceability with one source.
• [ ] Inspect the actual permissions and network exposure of each plugin or MCP server.
• [ ] Keep human approval for move, delete, overwrite, and publish actions.
• [ ] Observe context size and request cost before adding an index.
• [ ] Audit generated notes for unsupported facts and dead links.

Once these ten checks pass, the vault becomes a maintainable knowledge workspace rather than an unrestricted folder that happens to be visible to an agent.

Common Obsidian and Claude Agent errors

Seven acceptance criteria before production use

Move an Obsidian Agent workflow from a test vault into daily work only when all seven conditions pass:

1. The agent can read only authorized directories.
2. Original sources remain unmodified during the test.
3. New material is written only to a draft area.
4. Sampled claims can be traced to a source passage or page.
5. Delete, move, overwrite, and publish actions wait for human approval.
6. An incorrect change can be restored from Git or a backup.
7. Markdown notes remain readable and portable when the model service is disconnected.

A polished summary proves that the model can write. A workflow that cannot control provenance and write scope is still unsuitable for permanent knowledge.

FAQ

Does Obsidian need to stay open?

Not always. Obsidian can remain closed when Claude Code reads the Markdown directory directly. A workflow that depends on an Obsidian plugin or its local bridge usually needs Obsidian to keep running. Whether an MCP server depends on Obsidian varies by implementation.

Do I need MCP to connect Claude Agent to Obsidian?

No. Direct vault access is simpler for reading sources, generating drafts, and organizing Markdown. Add MCP when you need dedicated search, backlink queries, tag management, or access from several clients.

How do I prevent an agent from damaging existing notes?

Make the source directory read-only, allow writes only in _drafts, disable delete and bulk move operations, review diffs before editing permanent notes, and keep Git history or snapshots. Prompt rules should sit alongside file permissions and version control.

Can the workflow read PDFs and images?

It depends on the client or plugin. A client with PDF and vision input can read them directly; other setups need text extraction or OCR first. Retain page numbers, filenames, and OCR status in the research note so the result can be reviewed.

What should I do when a large vault returns poor search results?

Normalize titles, tags, and frontmatter, then make the agent search first, read summaries second, and expand relevant passages last. Add semantic indexing only when keyword search no longer covers the task. Do not send the entire vault to the model.

Can I call Claude through Code0 from Obsidian?

Yes, when the plugin or client supports a custom Anthropic-compatible Base URL. Set the request address to https://code0.ai, and use the API key and model ID currently visible in the Code0 console. Third-party compatibility can change by version, so run a small connection test after configuration.

API endpoint: Primary API with U.S. CN2 GIA acceleration: https://code0.ai

Third-party platform disclaimer: Code0 is an independent third-party multi-model API aggregation service and is not affiliated with Anthropic, OpenAI, Obsidian, or any other platform mentioned here. Models, pricing, quotas, regional availability, and tool compatibility are subject to the Code0 console and the relevant model provider's current rules. Test with limited traffic before production use and comply with applicable service terms, data-security requirements, and content policies.

Sources

• Companion for Claude — Obsidian community plugin
• LWaetzig/obsidian-mcp on GitHub
• StevenStavrakis/obsidian-mcp on GitHub
• codex-obsidian-workflow: a local knowledge workflow with provenance
• WeSight: a public Codex and Obsidian content-workflow case
• Obsidian for Claude Code: how to use your vault as AI memory
• Claude Code from the Sidebar — Obsidian Forum