Claude Code and Obsidian: one vault for you and your agent

Why Claude Code and Obsidian fit together

An Obsidian vault is an ordinary folder of text files, with no database in between. That’s why an agent can work in it just like you do.

Claude Code is an AI agent that runs in the terminal, in your editor, or in the desktop app, and works in the folder where you start it. It reads files, creates new ones, changes existing ones, and runs commands. Start it in your vault, and your whole second brain is in front of it: It summarizes meeting notes, adds missing links, sorts a collection of sources, or turns your outline into a first draft that lands as a new note in the right folder.

This isn’t limited to Claude Code. Codex, Cursor, Gemini CLI, and other agents with file access work the same way. A chat in the browser, on the other hand, doesn’t see your vault unless you copy files into it.

Set up Claude Code in your vault

Use your vault as the working directory

Claude Code works in the folder where you start it. If your vault is in iCloud Drive, it looks like this in the terminal, for example:

cd ~/Library/Mobile\ Documents/iCloud~md~obsidian/Documents/Vault
claude

Decide deliberately how much the agent should see. For a first try, a subfolder is enough, such as the folder for one project. Back up your vault before you allow larger changes: Claude Code can roll back its own file edits, but not changes made through terminal commands. Git in your vault or Time Machine closes that gap.

Give access to tasks in a linked folder

If you bring TandemLoop’s data folder into your vault with a symbolic link, its real location is outside the working directory, and Claude Code asks for permission every time it writes. So give it access to the folder as well: at startup with --add-dir, in a running session with /add-dir, or permanently under additionalDirectories in the settings:

claude --add-dir "<TandemLoop folder>"

How to create the link and why it only works on a Mac is explained in the guide Connect your second brain and your to-do list.

CLAUDE.md: the rules for your vault

At the start of every session, Claude Code reads the CLAUDE.md file in the working directory and in the folders above it. It holds what the agent needs to know about your vault and what it may do. Run /init to create a first draft, then refine it. Anthropic recommends keeping the file short, ideally under 200 lines, and writing down only what the agent can’t figure out on its own.

# Vault

Obsidian vault with notes in Markdown. Links as wikilinks [[Note]].

## Folders
- Notes/: my notes, change only when asked
- Online Course/: material and results for the course
- TandemLoop/: data folder of my to-do app (link)

## Rules
- Never delete or rename a note without asking.
- Save results as a new note in the matching folder.
- Don't restructure the properties at the top of a file.

## Tasks
For tasks, read TandemLoop/AGENTS.md first and follow its rules.

Other agents usually read AGENTS.md instead of CLAUDE.md. Claude Code reads an AGENTS.md on its own as long as it doesn’t find a CLAUDE.md. If you want to use both, include one file in the other with @AGENTS.md. How such manuals for agents are structured is covered in the guide Agentic engineering.

Obsidian tasks: checkboxes and the Tasks plugin

Obsidian handles tasks as checkboxes. A line like - [ ] Write script for lesson 2 is an open task; with [x], it’s done. For an Obsidian to-do list inside a single note, that’s enough.

The Tasks community plugin turns this into task management across your whole vault. You write due date, priority, and recurrence as symbols in the line, such as 📅 2026-10-23 for the due date. When you complete a task, the plugin adds the date; for recurring tasks, it creates the next line. Queries in a code block collect tasks from all your notes:

```tasks
not done
due next week
```

The strength of this approach: Tasks live where they come up, right in project notes and meeting minutes. For many people who keep their second brain in Obsidian, that’s enough.

Where the Tasks plugin reaches its limits

• Reminders: The Tasks plugin itself doesn’t notify you. Notifications come from another plugin such as Reminder, and its documentation says that system notifications aren’t possible on iPhone and Android.
• Capturing on the go: Since iOS 26, Obsidian offers Quick Capture from the Lock Screen, Control Center, and widgets. What you capture this way lands as text in a note. You add date, project, and who is responsible later by hand.
• Assignment: A line has no field for who is responsible. You can agree on a tag like #agent with your agent, but there’s no status for “for review” and no place for its result or your questions to each other.
• Your notes, not the agent’s: To check off or add to a task, the agent has to change the line in your note. The more notes contain tasks, the more files it touches to do that.

Obsidian tasks with Claude Code: assign them to your agent

The alternative to a line is a task of its own with a status, a due date, and an assignee. It comes with a description of the goal and acceptance criteria, and a log where your agent records what it did.

When you work with an agent, this has concrete advantages:

• The agent changes a task without touching your notes.
• Responsibility and status are clear: You assign the task to your agent, and when it’s finished, the task comes back to you as “For Review.”
• Results and questions stay on the task instead of in a chat history that’s gone tomorrow.

Nobody wants to maintain this structure by hand. It takes a manual for the agent and an app that turns the files into lists, views, and reminders.

Where TandemLoop helps: capture, views, reminders

TandemLoop is a to-do app for Mac, iPad, and iPhone that works exactly this way. Its data folder, local or in iCloud Drive, can be a subfolder of your vault or show up there through a link. Your agent then works across the whole vault, notes and tasks included.

• Capture: Quick Entry, the Share menu, Control Center, Shortcuts, and Siri create a real task, for your agent right away if you like.
• Views: List, Table, Board, Agenda, Calendar, Multi-View, and Dashboard, with filters, for example by assignee or due date.
• Reminders: Due dates with times, notifications with “Complete,” “Later,” and “Tomorrow,” and widgets on the Home Screen and Lock Screen.
• Agent: The data folder contains AGENTS.md, the manual for your agent. The agent has access to everything in the data folder: it creates tasks, projects, areas, and views, changes and moves them, and works on the tasks assigned to it. With proposals turned on, it only adds new items to the Inbox directly and files everything else as a proposal.
• Handback: When it’s finished or needs something from you, it hands the task back. The task shows up under Back from Agent, on iPhone in the From Agent tab.

Everything about dividing work with your agent, from proposals to handbacks, is on the page To-do app for working with AI agents. The full feature set without an agent is in the to-do app overview.

Example workflow: Inbox → agent → result

A workflow from the “Online Course” project: The outline is a note in Obsidian, and the agent is supposed to draft the script for lesson 2.

1. Capture. On your way to work, you type “Write script for lesson 2” into Quick Entry and assign the task to your agent with the delegation Draft. It lands in the Inbox.
2. Instruction. On your Mac, you start Claude Code in your vault and type: “Work through your tasks in TandemLoop.” It reads the manual, finds the task, and also your course outline.
3. Result on the task. It saves the script as a note in the Online Course folder and writes in the task’s log what it did, with a link to the note.
4. Back from Agent. Because the delegation was Draft, it doesn’t complete the task itself but hands it back for review. You read the script in Obsidian and choose Accept in TandemLoop, or Request Changes with a comment.
5. What only you can do. If it needs a confirmed account on the course platform for the upload, it puts “Confirm access to the course platform” in your Inbox instead of mentioning it in a long reply.

If the agent runs in a loop on your Mac, for example with TandemLoop’s worker skill and /loop 10m /tandem-worker in Claude Code, it works through tasks like these even while you’re away. Only one agent should write at a time.

Which approach suits you

You can mix both: Checklists for small things stay in your notes, and everything your agent works on gets a task of its own. If you organize your tasks with Getting Things Done, the guide to the GTD method shows which steps your agent can take on.