The itch
By November 2025 I was running coding agents against my own notes as much as against code. My working knowledge — research, project docs, decisions — lives in an Obsidian vault, and I wanted the agent to treat it as a first-class read/write surface: search it, pull a note, append a section, fix some frontmatter, all inside a session.
The Local REST API plugin already exposed the vault over HTTP, so the raw capability was there. But it's built for a human's convenience, not an agent's. Responses vary in shape, there's no structured search, and "edit the Results section of this note" turns into fetch-the-whole-file, mangle-a-string, write-it-back. An agent driving that by hand is slow and gets it wrong. I wanted the vault to feel like a set of typed operations, not a webpage to scrape.
What I built
A CLI that does one thing: give an agent surgical, structured access to a vault. Installed as the obsidian command, every subcommand returns JSON and nothing else, so there's nothing to parse loosely.
- Search
- Hybrid: fast Omnisearch plugin path, REST API fallback when it's not there.
- Surgical edits
- PATCH targeted by heading or line number — append, prepend, replace, or delete a section, without touching the rest of the file.
- Frontmatter
- Get / set / merge / delete YAML fields;
titleand timestamps kept current automatically. - Big content
--from-fileand--stdin, because shell argument limits are the real ceiling on agent-authored text.- Shape
- JSON on every command. Standalone binary, cross-compiled with Bun, no runtime deps.
The design bet was that agents want narrow, composable operations they can chain — the Unix posture, aimed at a model instead of a person. The clearest expression of that is the edit path:
What happened to it
I built it in an afternoon and expected to touch it occasionally. Instead it became the single most-run tool I've made. Nearly every coding session I open uses it at least once — to search a note, drop a finding, update some metadata. The vault it feeds is now past a thousand notes and well over a hundred megabytes, most of it written through this CLI rather than by hand.
- Nov 15, 2025First commit: REST + Omnisearch, file/stdin input, auto timestamps.
- Dec 17, 2025v0.2.0. Also shipped Excalidraw diagram generation with auto-layout — a DSL that compiled to Excalidraw scenes.
- Jan 24, 2026Added knowledge-management commands: inbox, move, stale, stats.
- Jul 2026Still the tool every session reaches for. The diagram feature has sat unused for months.
I'll be honest about the one part that didn't work. The Excalidraw generation was a real feature — a small DSL that laid out and compiled to Excalidraw diagrams — and it was a good experiment. I almost never use it. The demand I imagined ("the agent will draw diagrams into my notes") wasn't a demand I actually had, and no amount of it being built well changed that.
The lesson I keep relearning: the tool I was least precious about outlived the ones I designed carefully, because it did one boring thing an agent needed every single day. Usefulness isn't in the ambition of the feature — it's in how often the plain one runs.