files.md: The Anti-Obsidian Note-Taking Tool That Took 5 Years to Build

I found files.md on Hacker News a few days ago. 3,000 GitHub stars, MIT license, built by one person over five years. The GitHub description calls it "a private, quiet space for thinking." Then I read the README and something clicked.

The author, Artem Zakirullin, spent years as an Obsidian power user. He built elaborate template systems, installed dozens of plugins, optimized every workflow. Then he wrote this:

"Eventually, I realized I had created a new problem: deferral. The more my system grew, the more I deferred the work of thought to some future self who would sort, tag, distill, and extract the gold. That self never arrived."

files.md is his answer. It's a thin web interface wrapped around a folder of plain .md files. No plugin marketplace, no template engine, no graph database, no Electron shell. And that's the entire point.

What you actually get

Open app.files.md, grant it access to a local folder, start writing. No installation, no accounts, no build steps. The whole thing is a single-page PWA — the author promises that web/index.html will still work in ten years.

The feature list, in its entirety:

• A CodeMirror-powered Markdown editor with a few essential hotkeys (Cmd+K for file search, [ to insert links, Cmd+N to create a new note)
• Bi-directional linking between notes (type [ to bring up a file search modal)
• A chat-like input flow for quick capture
• Predefined but optional folder structure: brain/ for thinking notes, journal/ for daily entries, Chat.md as an append-only inbox
• Four sync options: local-only, cloud folder (iCloud/Dropbox/Google Drive), self-hosted Go binary, or api.files.md

What makes it interesting

LLM-native from the ground up

The project ships an llms.txt file that describes the entire knowledge base structure. Copy it into CLAUDE.md or AGENTS.md, and your AI agent immediately understands how your notes are organized — where things live, how they connect, how to read and write to the right places.

This is what differentiates files.md from Obsidian: your notes don't just work for you, they work for your AI agents. Claude Code can read your brain dumps, extract themes, summarize threads, and surface connections you missed.

The codebase is small enough that "one person or an LLM can fit the whole project in their head" — that's not marketing, it's a design constraint. The author actively rejects complexity. The contribution guidelines say it plainly: "Ideally, every PR should remove or simplify code, not add it."

Telegram bot for on-the-go capture

@FilesMDBot is deliberately write-only. You send it a message, it appends to Chat.md. You can't browse your notes, can't search, can't read.

The constraint is intentional. If you could browse on your phone, you'd never return to your desk for deep thinking. The bot is a capture valve, not a consumption surface.

Zettelkasten without the ceremony

files.md supports linked notes (one idea per file, connected via standard Markdown links). The author's method is aggressively simple: write one idea per note, link related notes, revisit and think. No categories, no tags, no templates. Just connection.

"To achieve all that, you'll have to use your brain, not advanced templates or AI workflows."

The technical choices that reveal the philosophy

The project maintains an Architecture Decision Record that's worth reading even if you never touch the code:

• Dropped WASM — eliminated an 8MB binary and simplified the JS↔Go bridge
• Abandoned their own Markdown parser — "Markdown isn't that hard to parse, we can do it via good old straightforward code. We have 3x less code now."
• Switched from Wikilinks to standard Markdown links — "our knowledge base must be interoperable"
• Merged Inbox into Chat — "Inbox is too abstract, productivity-related and GTD-ish. I want calmness and simplicity."
• Vendored all dependencies — the repo is self-contained, no external package managers needed

Every decision pushes toward the same conclusion: less code, fewer dependencies, longer shelf life.

Background philosophy

The README contains a surprisingly personal essay about thinking, healing, and the limits of note-taking. The author argues that:

1. Note-taking can masquerade as understanding. "Reading and taking notes can easily fool us into believing that we understand a text. We think we understand, but in reality we just know."
2. System maintenance replaces actual thinking. Templates, plugins, and optimization become a form of procrastination that feels productive.
3. Some things can't be solved through intellectual work. "Harm caused at the emotional level must be healed at the emotional level. Not through intellectual work and taking notes. Healing happens by feeling."
4. Constraints create creativity. When you strip away the tools, you're left with your own mind.

This is the anti-Second Brain. No externalized memory system, no automated workflows, no deferred understanding. Just you, a text file, and the discomfort of actually thinking.

Should you use it?

If you're deep into Obsidian with Dataview queries and Canvas maps and a templating system that took months to build, files.md will feel barren. It's not trying to compete there.

But if you've ever looked at your note-taking system and felt like it was doing the thinking for you — if the tools have become the task — this project is worth trying. Open the browser, write something, link it to something else, sit with it. No configuration required, no lock-in, no barriers to leaving.

files.md on GitHub · app.files.md