Claude Code + Obsidian without the flat log

Why one big results file stops working

The old setup was a good idea that outgrew one file.

When I set up Claude Code, its config had one rule: after every code change, write the steps, what changed, the benefit and the reason into RESULTS.md. For the first few days this was great. I could open one file and see everything the agent had done, and why.

Then the file kept growing. One week in, it was 407 lines: eleven entries for eight real fixes - and four of those entries were about the same fix:

• ## F1 — Server-render all commercial content · Status: partial
• ## F1 (revised) — Server-render the REAL product UI · Status: done, one regression flagged
• ## F1 (final) — All category cards in the DOM · Status: done, one gap flagged
• ## F1 (complete) — Unlimited durations linked, 100% plan coverage · Status: done

To find out what actually shipped, you read all four and trust the last one. The file was great at answering "what happened" - and useless at answering the only question that matters on Monday morning: "where are we now?"

The agent was not doing anything wrong. I told it to add to one file, so it added. A file you can only add to can only grow.

And once the file got long, a quieter problem appeared: re-reading all of it before every change got expensive, so the agent stopped doing it - and new entries sometimes contradicted old ones.

A log that is too long to read back is a log that slowly stops being true.

Expand image

One note per fix: the template that works

The fix was a template, not a tool.

Everything below is one short paragraph in the project's CLAUDE.md. It tells the agent to keep two kinds of notes:

• Goals/{Goal Name}.md — one "big picture" note per goal: what we are building, the rules, a status table, results so far, open questions.
• {Goal Name}/{Item}.md — one small note per fix or decision.

Each small note has the same four parts:

1. Changed - which files.
2. What changed - two to four plain sentences.
3. Benefit - what this makes possible, in plain words.
4. Verified - the commands that were run and what they showed.

Expand image

Verified is the part that keeps the notes honest. It makes the agent write down what it actually ran, not what it planned to run. In one of my notes it added this on its own: "the local backend returns price: 1 for every plan, so price values can only be verified on preview - structure only, locally." Before Obsidian, a detail like that lived in a chat window and was gone by Thursday.

One more rule: notes are for decisions too, not only code. One of my notes records a decision that produced no code change at all - that around 20,000 generated pages stay open to search engines. Months from now, "why we chose this" will matter more than "which files changed", and only a note can tell you that.

Every note ends with links - back to the goal note, and to the previous and next fix. That one line turns a folder of files into a map you can follow.

Connect Claude Code to Obsidian in five minutes

Install one plugin, copy one key, run one command.

MCP - if the word is new to you - is simply the standard way tools like Obsidian connect to Claude Code. You set the connection up once, and every project can use it.

1. In Obsidian, open Community plugins and install Local REST API with MCP by Adam Coddington. MCP support landed in v5.0.0 on 24 July 2026; I am running 5.0.2 against Obsidian 1.12.7.
   • Local REST API with MCP: https://github.com/coddingtonbear/obsidian-local-rest-api
   • MCP: https://modelcontextprotocol.io
2. Open Settings → Local REST API and copy the API key.
3. Register the server with Claude Code:

claude mcp add --transport http obsidian https://127.0.0.1:27124/mcp/ \ --header "Authorization: Bearer YOUR_API_KEY" \ --scope user

Then check it worked: claude mcp list shows the server with a health status, and typing /mcp inside a session lists its tools. You should see 16 of them, with names like vault_read, vault_write, vault_patch and search_query.

Expand image

One thing usually eats most of the five minutes: the certificate. Port 27124 uses HTTPS with a self-signed certificate, and strict clients reject it without any error message:

curl https://127.0.0.1:27124/ # returns nothing - certificate rejected curl -k https://127.0.0.1:27124/ # {"status":"OK","service":"Obsidian Local REST API", ...}

Two easy fixes: trust the certificate (the plugin serves it at https://127.0.0.1:27124/obsidian-local-rest-api.crt), or turn on the plain HTTP server in the plugin settings and use http://127.0.0.1:27123/mcp/ instead.

And one tip before you debug anything: the server runs inside Obsidian itself. If Obsidian is closed, the connection is gone.

Set it up once, use it in every project

You set this up once. Every project after that gets it for free.

Claude Code can remember a connection at three levels, and the level decides how far it travels:

• local (the default) - this project only; saved in ~/.claude.json.
• project - this project only, shared with your team through Git; saved in .mcp.json inside the repository.
• user - all your projects; saved in ~/.claude.json.

--scope user is the right choice here for two simple reasons. The vault belongs to you, not to the project. And the API key is a password - using the project level would save that password into the repository for everyone to see.

{ "mcpServers": { "obsidian": { "type": "http", "url": "https://127.0.0.1:27124/mcp/", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } }

That block is written once into ~/.claude.json and is loaded by every project on the machine. The only real per-project work is one paragraph in that project's CLAUDE.md: where to write notes and the template from section 2. Add a repo: line to each goal note (mine says repo: roamify-web) and one vault can hold several projects without mixing them up.

One small detail worth knowing: if the same server is defined at two levels, local beats project, which beats user - and only the winning definition is used.

What you get

The same eight fixes now live in nine small notes - together less than half the size of the old file, and far easier to read.

The biggest change is simple: updates now replace old text instead of piling on top of it. The F1 fix is one note marked done; the three outdated versions do not exist anymore, because the agent edits the note instead of adding below it.

And there is finally a Monday-morning page. The goal note shows the whole project on one screen: a status line per fix, the results so far, and the open questions. The old log could never give you that - its top was always three weeks old.

Expand image

In plain terms, here is what you get:

• You always know the current state - one note per fix, kept up to date.
• You can find things - every note has a name and a link, so nobody scrolls.
• You can trust it - every note says what was actually run and checked.
• You do the setup once - it works in every project after that.

Four small things to know before you start:

• Without the template paragraph in CLAUDE.md, the agent invents a new note shape every session - the template is the whole trick.
• Ask the agent to use vault_patch for updates; vault_write replaces a note completely. Keeping the vault in Git is a cheap safety net.
• Spot-check the Verified lines now and then - a model can write "build passes" without running the build.
• Obsidian's graph view is a nice picture, not a tool; the links inside the notes are where the value is.

None of this is really about Obsidian - any tool with linked notes would work. The change that mattered is smaller than a tool: I stopped asking the agent to log, and started asking it to file.