Folio

I keep my notes in Obsidian, and my coding agent reads and writes the same vault. That setup already works well. Folio started as a question about whether it could work better.

The question comes from Thariq Shihipar's piece, "The Unreasonable Effectiveness of HTML." His point is that once a note has real structure, a table, a diagram, a dashboard, some comparison data, HTML carries more than Markdown does, and an agent can reason over that structure instead of reading it as flattened text. So the hypothesis behind Folio is simple: notes written as HTML might give an AI agent better working context than the same notes in Markdown. Folio is how I'm testing it.

The shape is familiar if you've used Obsidian. Your notes are plain files in one folder, no account and no database. The difference is that a note doesn't have to be just text. Notes are Markdown by default, but the moment one needs a real table, a diagram, or a live chart, it can become HTML without you choosing a format. The folio-notes.com page is itself one of these notes.

Because it's just files, your agent works the same folder you do. Point a coding agent like Claude Code at it and it reads and writes the exact notes you do, with no API key, no plugin, and no MCP server. Your edits show up live in the app, and the app shows you what the agent changed with per-note history and one-click revert.

It does the notebook basics too: relative links, backlinks, a graph, and full-text search, all built from your files with nothing to maintain. There's also an Agent panel that surfaces the files shaping your agent's behavior, like CLAUDE.md and AGENTS.md, so you can see and edit them in one place.

It's free and local-first, so your files never leave your disk, with a model closer to Obsidian than to a typical open-source project. It's macOS only right now, with Windows and Linux coming. It's early, currently v0.1.5.