Obsidian and Claude Code – working on the same files

Markdown is plain text in which a handful of characters do the formatting: a hash at the start of a line turns it into a heading, two asterisks on each side make a word bold, and vertical bars line up into a table. Obsidian, a free note-taking app, reads those characters as formatting and shows you the finished page instead.

You won’t be using Obsidian here to read and correct every file Claude Code leaves behind. It earns its place with the files the two of you work on together and keep coming back to – a draft partnership agreement, say, with the parties’ details still to be filled in. Claude Code suggests clauses and edits, and you add what only you know. You see every change from Claude Code in Obsidian as soon as it’s made, so not every fix has to go through Claude Code: sometimes it’s quicker to change one word in a sentence directly in the file than to ask Claude Code to do it, and simply let Claude Code know afterwards. You put Obsidian next to the terminal, and the two of you take turns writing in the files.

What Obsidian is, and what this lesson leaves out

Obsidian is an app for writing and organising notes that are stored as ordinary files on your computer. It was built for personal knowledge bases: one note points to the next, a bit like a private Wikipedia. Usually someone spends years building a collection of notes in Obsidian and only then lets AI into it. For you it works the other way round: Claude Code creates the files, and you read them in Obsidian and edit them together with Claude Code.

Obsidian has enough features for a course of its own. Working together doesn’t need any connection between the two programs, because both simply work on the same files in the same folder.

Obsidian is free for any use, business use included. The commercial licence is optional and lets the people who use the app fund it themselves. You don’t need an account to use it, and according to Obsidian’s privacy policy your data is stored locally, on your computer, and doesn’t go to the company’s servers.

Installing Obsidian

Download Obsidian from the official page, obsidian.md/download. You’ll find versions for Windows, macOS and Linux there, plus phone apps you won’t need for this lesson. Download the version for your system, run the installer and finish with the default settings.

This lesson uses the English names of Obsidian’s buttons. If the app starts in another language for you, switch it under Settings → General → Language. The windows change a little from version to version, so what you see may not match the description exactly – go by the button names.

Open your folder as a vault

A vault, in Obsidian, is the folder whose files the app shows you. The first time you start Obsidian, it opens a window asking you to choose a vault. Claude Code’s files are already in your working folder, so that folder becomes the vault – not a new, empty one:

1. Next to Open folder as vault, click Open.
2. Pick the folder where you run Claude Code – the one with the CLAUDE.md file in it.
3. Confirm your choice in the folder picker.

If CLAUDE.md is in your working folder but you can’t see it on the left side of the window, Obsidian has opened a different folder. Click the vault icon in the bottom-left corner, choose Manage vaults… and open the right folder again.

In the folder you opened, Obsidian creates a hidden .obsidian folder with its settings. Leave it alone. Claude Code will learn about it from the note in CLAUDE.md you add at the end of this lesson.

Open CLAUDE.md and read it in Obsidian

Obsidian shows the tree of folders and files from your working folder on the left side of the window. Click CLAUDE.md there. It’s the same file that, in a plain text editor such as Notepad, is full of hashes and asterisks. Here the headings are bigger, bold text is bold, and the table that was a tangle of bars in the editor has rows and columns.

When you click a file, Obsidian opens it in editing mode by default. The file already looks formatted there, because most of the Markdown characters stay out of sight, and you can correct the text right away. When you only want to read, the shortcut Ctrl+E (Cmd+E on macOS) switches the file to Reading view, which shows nothing but the formatted content. The same shortcut takes you back to editing.

The large text above the content isn’t a heading – it’s the file’s name. Obsidian lets you change it right there, and every edit to that text renames the file on your disk. Treat that text as read-only.

Word and Excel files don’t appear in the tree on the left by default. Obsidian lists the formats it can open: Markdown, images, PDFs, recordings and its own canvases. Your quotes and price lists stay on the disk where they were, and you open them as you always have. A PDF, on the other hand – a supplier’s price list, for instance – you can read in the same window as your notes. More features come from Community plugins, which you switch on in Obsidian’s settings; this lesson doesn’t need any.

Leave file and folder names to Claude Code

The file tree in Obsidian makes it tempting to tidy the folder your own way: drag a file into another folder, fix a name. Leave moving and renaming files to Claude Code – and not only in Obsidian, but in File Explorer on Windows or Finder on macOS too. CLAUDE.md and the notes Claude Code writes tell it where everything is – “the quote templates are in the quotes folder”, for example.

Claude Code works here like an assistant who knows that the contract with the wholesaler is in the next room, on the third shelf from the top. Move it to another room yourself, and tomorrow the assistant walks to the third shelf and comes back empty-handed. Ask the assistant to move it and write down where it is now, and tomorrow it goes straight to the new place.

Renaming a folder works the same way, except it affects every file inside at once. So ask for the move or the rename in the conversation:

Move the file meeting-notes.md into the meetings folder, and if that folder doesn't exist, create it. Then go through CLAUDE.md and the other files where you keep track of where things are, and fix every place that still has the old path.

The file and folder names in this prompt are only an example – use your own. You ask for a new file name the same way. And if a file has already been moved by hand, tell Claude Code where it was and where it went, then paste the second sentence of the prompt, the one about fixing the paths.

One name never changes: CLAUDE.md, in capitals, with .md at the end. That’s the name Claude Code looks for at the start of a conversation to find its instructions, and a file called anything else, instructions.md for example, is just another note to it.

Watch a change arrive live, then edit the file yourself

Put the Obsidian window next to the terminal window so you can see both at once. Obsidian refreshes the vault whenever another program changes a file, so you don’t have to close or reopen anything. Try it on a file Claude Code creates while you watch:

Create a file called todays-plan.md with my plan for today: call the wholesaler back about the price list, send a quote to a new client, go through the contract template. Write it as a checklist.

When todays-plan.md appears in the tree on the left, click it in Obsidian. Then ask Claude Code to add something:

Add to todays-plan.md: 3 pm call with the supplier.

The new item shows up in Obsidian as soon as Claude Code finishes saving the file. If nothing changes in Obsidian, ask Claude Code for the full path of the file it changed and check whether that file is in the folder you opened as a vault. If it’s somewhere else, Claude Code is working in a different folder from the one Obsidian shows – close Claude Code and start it again in the folder you opened as a vault.

Now it’s your turn. In todays-plan.md in Obsidian, change one word – “call the wholesaler back” to “ring the wholesaler back”, say – by clicking into the text and editing it as you would in any editor. If the file is in Reading view, switch it first with Ctrl+E (Cmd+E on macOS). Then let Claude Code know:

I changed one word in todays-plan.md by hand. Read the file again before you change anything in it.

Only one of you writes in a file at a time. On our courses we see what happens when you and Claude Code write in the same file at the same time: a sentence Claude Code added a moment earlier gets deleted in Obsidian, and at the next change Claude Code looks for it and can’t work out where it went. So make your edits once Claude Code has finished, and tell it about each change you make before you ask for the next one. Ticking off an item on a list in Obsidian is a change to the file too.

Graph view and canvas

Graph view draws every Markdown file as a dot and every link between files as a line. You open it with the Open graph view button in the sidebar on the left of the window. In a folder where the files don’t point to each other, the graph is nothing but loose dots. Lines appear as your notes start linking to other files – for instance when you ask Claude Code to link each note to the files it’s based on.

A Canvas in Obsidian is an endless surface where you lay out cards with notes. Obsidian saves it as a file ending in .canvas, in an open format, so Claude Code can create one just like any other file:

Turn todays-plan.md into an Obsidian canvas in a file called todays-plan.canvas: each task on its own card, laid out from morning to afternoon.

Click todays-plan.canvas in the tree on the left. You can drag the cards around, and when you select a card, buttons appear next to it, one of them for changing its colour. Moving a card is a change to the file as well, so here too only one of you writes at a time: arrange the cards while Claude Code isn’t doing anything, then tell it the canvas now has your layout.

Tell Claude Code you use Obsidian

Claude Code doesn’t know you read and edit its files in Obsidian until you tell it. One note in CLAUDE.md is enough, because Claude Code reads that file at the start of every conversation:

Note in CLAUDE.md that I read and edit the files in this folder in Obsidian. Add three rules: before you change a file, you read it again, because it may contain my edits; you don't change the .obsidian folder, because it holds Obsidian's settings; you only rename or move files when I ask, and you fix the paths in your own files straight away.

You check whether the note works in a new conversation: type /exit to close Claude Code, start it again with the claude command in the same folder, and ask what it knows about the .obsidian folder. If the answer says nothing about Obsidian’s settings, ask Claude Code to show you the note in CLAUDE.md, and read it in Obsidian.

What to take away from this lesson

• You and Claude Code take turns writing. Claude Code suggests and adds, and you read and fix the small things directly in the file, because changing one word yourself is quicker than asking Claude Code to do it.
• Your working folder becomes the vault, not a new, empty folder – only then does Obsidian show the files Claude Code works on.
• The text above a file’s content is its name, and every edit to it renames the file on your disk.
• Claude Code changes file names and locations, when you ask, and fixes the saved paths straight away. CLAUDE.md stays CLAUDE.md, in capitals.
• Only one of you writes in a file at a time, and when you fix something by hand, you tell Claude Code before the next change.

Tasks

Tick them off as you go. Your progress is saved in the browser, so you can come back to this list tomorrow.

• Obsidian downloaded from obsidian.md and installed
• Working folder opened as a vault, CLAUDE.md visible in the tree on the left
• CLAUDE.md read in Reading view
• A file moved or renamed by Claude Code, paths in CLAUDE.md fixed
• The addition to todays-plan.md visible in Obsidian without reopening the file
• One word in todays-plan.md changed by hand in Obsidian, and Claude Code told about it
• The todays-plan.canvas canvas opened in Obsidian
• The Obsidian note in CLAUDE.md checked in a new conversation