Using Obsidian as a developer: one vault, three readers, and the one it cannot reach

Obsidian is a good tool for developers. Notes are plain markdown files in a folder you choose, code blocks get syntax highlighting, and since February 2026 there is an official command line, so a script or a coding agent can search and read the vault without screen-scraping an editor.

What changed is who reads the notes. A developer's vault used to have one reader. Now it has three: you in Obsidian, the coding agent working next to you, and the team that needs the decision you wrote down last week. Obsidian serves the first reader better than anything else. This guide sets the vault up for all three, and is plain about where Obsidian stops, which is the third reader. That gap is the one Baalda, the app this site is for, was built to close, and the post shows how it does that against the same folder of files.

Is Obsidian good for developers?

Yes, for most of the reasons developers already like plain text. A vault is a folder on disk, every note is a .md file, and Obsidian's settings sit in a hidden .obsidian folder inside it. You can grep it, diff it, back it up with the tools you already use, and open it in your editor when Obsidian is closed.

Code is a first-class citizen. Fence a block with three backticks and a language name and Obsidian highlights it. Its help page says "Obsidian uses Prism for syntax highlighting", with the caveat that Source mode and Live Preview "do not support PrismJS, and may render syntax highlighting differently", so the reading view is where highlighting looks right.

It is also free for work. Obsidian's licence page, last updated 20 February 2025, says the app is "free for all purposes, including personal, commercial, and non-profit use". The paid parts are Sync and Publish, and you do not need either to start.

How should a developer set up an Obsidian vault?

Keep it small and keep the answers in the files. How to build a second brain in Obsidian covers the general method. For a developer, the version that holds up is:

1. One vault, outside your repos. Notes that cross projects (why you picked a queue, how the staging database gets reset) do not belong to any one repository. Documentation that has to change in the same pull request as the code still goes in the repo's docs/ folder.
2. Folders by kind of note, not by technology. decisions/, runbooks/, debugging/, projects/ and an inbox/. A folder per language or framework turns into a filing problem by the third month.
3. One template per kind. A decision note gets the same headings every time, so a reader (or an agent) knows where the rejected option is.
4. Daily notes for the working log. What you tried, what failed, the command that finally worked. It is the note you will search most.
5. A `README.md` at the vault root. Two paragraphs saying what each folder holds. An agent reads this first, and so does a colleague.

A decision note made from that template looks like this:

---
type: decision
status: accepted
repo: billing-api
date: 2026-10-20
---

# Retry failed webhooks from a queue, not in the request

Context: the payment provider times out after 10 seconds.
Decision: write the event to the queue and acknowledge at once.
Rejected: inline retries, because they hold the connection open.
Runbook: [[Replaying dead-lettered webhooks]]

Every line of it is readable by anything that can open a text file, which is the property the rest of this guide depends on.

Which Obsidian plugins do developers actually use?

Fewer than the plugin lists suggest. The test worth applying to each one is where its output lives, because that decides whether the agent and the team can read it.

Obsidian Git deserves a note of its own because it is the default developer answer to sync. Its README describes "automatic commit-and-sync (commit, pull, and push) on a schedule", which is a fine history for one person on one desktop. It also says, about phones, "Mobile users: The plugin is highly unstable", and that its author "would not recommend using this plugin on mobile". Git also syncs files, not keystrokes: two people who edit the same note between pulls get a merge conflict in prose. Obsidian sync conflicts explains why that happens.

If you meant Obsidian for developers in the other sense, building plugins and themes, Obsidian's developer documentation is the place, and the CLI below adds commands for it.

How does a coding agent read an Obsidian vault?

There are three routes, and which one you use depends on where the agent runs.

The filesystem. An agent on the same machine can read the folder directly. Claude Code, for example, can add the vault as an extra working directory, and Claude Code as a second brain has the exact flags. No plugin, no server. The limit is the boundary: the agent can read everything under that path.

The Obsidian CLI. Obsidian shipped a command line interface in the 1.12 desktop release on 27 February 2026. You turn it on under Settings → General → Command line interface, and it registers an obsidian command:

obsidian search query="webhook retries"
obsidian read file="Replaying dead-lettered webhooks"
obsidian create name="Queue sizing" content="Draft"
obsidian daily:append content="- [ ] Check DLQ alert threshold"

There is also search:context, which returns grep-style path:line: text output that an agent can parse. The help page has a developer section with commands such as plugin:reload and dev:screenshot, and says "These commands allow agentic coding tools to automatically test and debug." That sentence is about agents testing plugins, but the everyday commands above are what an agent would shell out to for notes.

The constraint is stated plainly in the same docs: "Obsidian CLI requires the Obsidian app to be running. If Obsidian is not running, the first command you run launches Obsidian." It controls the desktop app on your machine, so an agent in a container, in CI or on a colleague's laptop cannot use it against your vault.

Obsidian Headless. For machines without the app, Obsidian points to Obsidian Headless, an open beta that its help page calls "a standalone client that runs independently, no desktop app required". It syncs a vault through Obsidian Sync, and one of the uses it lists is to "Give agentic tools access to a vault without access to your full computer." What the agent gets is a synced copy of the vault's files. Who can see which note is not part of it. MCP servers for Obsidian covers the community plugins that add an MCP server, most of which also need Obsidian open on that machine.

What happens when the team needs the same notes?

This is the third reader, and none of the routes above is built for it. A decision note is only useful if the person who joins next quarter can find it, and if the agent working in their session reads the same version you do.

Obsidian's way to share a vault is Sync, which shares the whole vault, needs every collaborator to hold their own subscription, and gives everyone in it the same access. Obsidian for teams has the costs. Git shares the folder too, and brings the merge conflicts with it. Neither gives an agent anything narrower than "all of it".

Baalda takes the same folder and adds the parts a team needs, without changing the files:

• The vault stays plain markdown on disk. An Obsidian vault moves across as a copy, wikilinks and frontmatter included. Baalda watches the folder, so an edit an agent makes with its own file tools syncs to the team like anyone else's.
• Live editing over a CRDT. Two developers, or a developer and an agent, can type in the same runbook at once and the changes merge as they type, not file by file at the next pull.
• Permissions per folder and per note. Each person gets Can edit, Can view or No access on the vault, a folder or a single note. The hiring notes and the runbooks can sit in one vault with different readers.
• An MCP endpoint that does not need an app open. The vault is served at the server URL plus /api/mcp, and each person mints their own token under Vault settings → MCP. The agent then has tools such as search_notes, read_note and edit_note, limited to exactly what that person can see.

The write path is what makes it safe to let an agent maintain the decisions folder. read_note returns the note's revision, and passing it back as expectedRevision makes a write refuse if somebody changed the note in between. edit_note takes anchored edits, and an anchor that matches nothing, or matches twice, refuses the whole call. A teammate with the note open watches the agent's change arrive rather than finding a second copy tomorrow. Setup for Claude Code, Cursor and the other clients is in the MCP setup guide.

Where is Obsidian the better choice?

If the vault is yours alone, stay in Obsidian. The CLI and the filesystem route cover a coding agent on your own machine, Obsidian Git or Sync covers your devices, and nothing here needs a server.

Baalda also gives some things up. It has no plugin system, so Dataview queries, Templater scripts and Bases views do not run in it. It is a desktop app for macOS, Windows and Linux with no mobile app yet. It is open source under Apache-2.0 and free to run locally, but the shared, always-on version needs a process somewhere, either the managed Team plan or a server you host. And it is not a code host: it does not index your repositories or replace the docs that belong next to the code.

The setup in this guide works either way. Keep the answers in the files, write the decision down when you make it, and the folder is ready for whichever readers it ends up with.