# Why FolderMD

A reader, not a transcript.

Claude, Codex, Cursor — they all want to write you long-form things. Plans, reviews, design memos, refactors that span twelve files. Most of it ends up in a terminal scroll-back you'll never read again. FolderMD is a small Mac app that gives those documents a real home — a place to actually read them, edit them, and write new ones yourself.

## Install the CLI. Your agents do the rest.

FolderMD ships with a `foldermd` command-line helper. Click Install CLI helper in the menu bar once, and the routing rules go into every agent you use — Claude Code, Codex, Cursor, Aider, Windsurf. From then on, when an agent has something long to write, it goes through FolderMD. No system prompts to maintain, no folder paths to remember.

Project documents land in a `.foldermd/` folder at the repo root — gitignore-able, shareable, or committable. Anything not tied to a project goes to the global inbox at `~/Library/Application Support/foldermd/inbox/`. Then it's just typography: ⌘S to save a doc out, ⌘W to dismiss, click in the sidebar to revisit yesterday's reading.

## Designed for long-form, not for chat.

Most agent UIs are chat windows. Chat is wrong for a 2,000-word architecture proposal. You can't skim it, can't bookmark a section, can't return to it on Tuesday morning with fresh coffee. A document wants a reader, not a transcript.

So FolderMD reads like a book, not like Slack. IBM Plex Serif for body, JetBrains Mono for code, optical-size hyphenation, generous measure. Light and dark, depending on your system. Mermaid diagrams render on demand. Syntax-highlighting that picks two colours and stops there — comments dim, strings italic, the rest left to the typography.

## Made for agents who already write.

You don't need to rewire your toolchain. The CLI helper installs FolderMD's routing rules into the places your agents already read from — `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.aider.conf.yml`, `copilot-instructions.md`. Any agent that can write a file already knows how to write a FolderMD-shaped one.

Documents can carry optional YAML frontmatter — `title:` and `agent:` — but plain markdown is enough. Files are yours; `.foldermd/` and the inbox are just folders on disk. Delete them, archive them, version-control them, walk away. There is no service, no account, no telemetry.

The full agent integration guide: https://foldermd.com/agent-integration

## Not a documentation generator.

Tools like Docuwriter and Project Guide analyse your codebase and write the documentation for you — they process an entire repository and emit derived prose. FolderMD does no analysis and no generation. Your agent already writes plenty of prose every time you ask it for a plan, a review, or a refactor; FolderMD just gives that prose a place to land. The "AI" is the one you already use, not a new one bolted on.

And it isn't an enterprise document platform. There's no SDK to install, no authentication to maintain, no cloud bucket, no team chrome. The "platform" is a folder on your Mac. The "integration" is one config file in your project. Everything else is markdown on disk and a watcher that quietly notices new files.

## A reader. A writer. A quiet place.

FolderMD started as a calmer way to deal with what your agents write — but it works just as well on its own. Open any `.md` file, edit it inline, save with ⌘S. Drag a folder of notes onto the icon and use it as a reading room. Start a new document from scratch. Everything is plain markdown on disk — the same files your editor opens, the same files Git tracks.

What it's not trying to be: an "AI app." There's no chat panel, no inline assistant, no model picker, no telemetry, no account. The agents you already pay for write to a folder; FolderMD gives those documents a real home and, when you want, a real keyboard to edit them with. macOS-only at v1, signed and notarised, delivered as a 3 MB `.dmg`.

Pay it forward with good will and happy vibes.

Download: https://downloads.foldermd.com/FolderMD-0.1.9.dmg

macOS 13 or later · Apple silicon and Intel · 3 MB