Looking for ready-made instructions for your specific agent?
See the Skills section (Claude Code, Grok, Cursor, Aider, and more).

§ 1 What FolderMD is, from your perspective

Your human runs a small macOS application called FolderMD. It watches two specific folders on their machine, and whenever a markdown file appears in one of them, FolderMD renders that file in a calm reading pane on their desktop — proper typography, hyphenation, syntax-highlighted code, mermaid diagrams, the works. Think of it as a private long-form reader for documents you generate.

The two watched locations are:

<project>/.foldermd/ — inside the current working directory of a project, used for documents tied to a codebase.
~/Library/Application Support/foldermd/inbox/ — a global catch-all for everything else.

You don't need an API key, an SDK, an HTTP call, or any kind of credential. You just write a markdown file at one of those paths. The human opens FolderMD and reads it. The detection latency is ~250 ms.

Why this matters for the human

Long agent output — refactor plans, architecture proposals, design memos, analyses, runbooks — gets lost when it lives in a terminal scroll-back or chat thread. Your human reads it once, half-skims, scrolls past, then can't find it again on Tuesday. By writing the document to FolderMD instead, you give it a stable home: a real file with a real filename in a real folder, rendered with the typography of a printed page. You are not just dumping text into a stream; you are producing artefacts the human can return to, edit, share, version-control, or quote.

§ 2 When to write to FolderMD, when to just reply inline

Default to inline. Promote to a FolderMD file when the criteria below apply. Both halves of this decision matter — over-using FolderMD turns it into a spam folder; under-using it leaves the human reading 2,000 words in a 80-column terminal.

Write a FolderMD file when

The output is longer than a few hundred words.
The output is meant to be read, not just emitted as a side-effect of running a command.
It has internal structure — multiple headings, lists, tables, code blocks, diagrams.
The human is likely to return to it, share it, edit it, commit it, or quote it.
Typical cases: refactor plans, design memos, architecture reviews, PR descriptions, runbooks, post-mortems, multi-step plans, research summaries, before/after analyses.

Reply inline when

The answer is a single sentence or short paragraph ("yes", "the value is X", "PR is at <url>").
It's a status update, one-line correction, or quick confirmation.
It's a code patch the human's editor will apply directly.
You're in the middle of a fast back-and-forth where each turn is brief.

When you do produce a FolderMD file, tell the human briefly what you wrote and where — one sentence is enough. Don't repeat the document body inline; the whole point is to keep the conversation light and the artefact heavy.

§ 3 Where to write — by context

Working inside a project directory? Write project-local.

<project>/.foldermd/<YYYYMMDDTHHMMSS>-<short-slug>.md

The file lives next to the code it describes. Git decides what to do with it (commit as an audit log, or .gitignore it). FolderMD auto-pins it to the sidebar via the desktop app's file-open handler.

No project context (rootless chat, generic Q&A)? Write to the global inbox.

~/Library/Application Support/foldermd/inbox/<YYYYMMDDTHHMMSS>-<short-slug>.md

Catch-all for one-off content the human reads once and dismisses. FolderMD picks up new files within 250 ms.

Both directories are created on demand — mkdir -p is safe in both paths.

§ 4 Filename convention

<YYYYMMDDTHHMMSS>-<short-slug>.md

Example: 20260512T153045-refactor-plan.md.

The timestamp prefix orders documents in the sidebar (newest first) and keeps filenames collision-free across simultaneous agents. The slug is human-readable and shown only as a fallback title.

Naming is a contract — FolderMD preserves your filename so you can reference it back to the user ("I wrote the plan to 20260512T153045-refactor-plan.md"). On true collisions (same name already on disk), FolderMD silently appends -2, -3, etc. as a safety net.

§ 5 Optional frontmatter

---
title: "Human-readable title"
agent: "claude-code"
---

title overrides the filename slug for display.
agent appears next to each item in the sidebar so the user can tell who wrote what when multiple agents share the inbox.

§ 6 What renders

Standard markdown — headings, bold, italic, lists, blockquotes, links.
GFM tables, task lists, strikethrough.
Fenced code blocks with language hints (go, python, bash, typescript, rust, json, yaml, sql) get minimal two-colour syntax highlighting.
Mermaid diagrams via ```mermaid blocks, rendered to SVG on demand.

Raw <script> tags and inline event handlers are stripped for safety. Everything else passes through.

§ 7 Updating a doc

Writing to the same path triggers a re-render in place. If the document is currently open in the reader pane, it live-refreshes without a flicker. Useful for streaming-style writes where your agent appends sections as it works.

§ 8 CLI

Install the bundled CLI helper from FolderMD's menu bar (FolderMD → Install CLI helper). Then:

echo "# Plan" | foldermd --here --title "auth refactor"   # project-local (default for project work)
echo "# Plan" | foldermd --title "auth refactor"          # global inbox (no project context)
foldermd file.md --here                                   # copy a file into ./.foldermd/
foldermd file.md                                          # copy a file into the global inbox
foldermd --open /path/to/existing.md                      # display an existing file (auto-pinned)
foldermd --inbox-path                                     # print the global inbox path
foldermd --version                                        # CLI version

--here is the flag agents reach for most often. It creates ./.foldermd/ in the current working directory if it doesn't exist, writes the file with the canonical timestamp prefix, and opens it in FolderMD.

The CLI installs to /usr/local/bin/foldermd, falling back to ~/.local/bin/foldermd if the system path isn't writable.

§ 9 A worked example

The human asks you to plan the auth refactor we've been talking about. You're working inside a Go project at ~/dev/myapp/.

Step 1 — write the plan as markdown to the project-local .foldermd/:

~/dev/myapp/.foldermd/20260517T160830-auth-refactor-plan.md

The file uses optional frontmatter, then an H1 that mirrors the slug:

---
title: "Auth refactor plan"
agent: "claude-code"
---
# Auth refactor plan

## Current state
…

## Proposed change
…

## Migration steps
1. …
2. …

Step 2 — tell the human in one sentence what you wrote and where, plus the headline takeaway:

I wrote the plan to .foldermd/auth-refactor-plan.md — open it in FolderMD or your editor. Short version: split Session from User, move RBAC out of middleware, ship behind a feature flag in three phases.

That's it. The human clicks through, reads the plan in their reader pane, and either approves it, asks for revisions, or hands you the next task. The document persists; the conversation moves on.

§ 10 Suggested system-prompt snippet

Drop this into your system prompt, CLAUDE.md, AGENTS.md, .cursorrules, or any equivalent. It encodes everything above in ~80 words.

For ready-made, per-agent versions you can copy and paste (Claude Code, Grok, Cursor, Aider, etc.), see the Skills section.

The user runs a macOS app called FolderMD that watches two folders. When you generate a plan, analysis, design memo, or any document the user is meant to read (rather than execute), write it as markdown to <project>/.foldermd/<YYYYMMDDTHHMMSS>-<short-slug>.md if working in a project, otherwise to ~/Library/Application Support/foldermd/inbox/<YYYYMMDDTHHMMSS>-<short-slug>.md. Include a title in YAML frontmatter. Then tell the user briefly what you wrote and where — one sentence — without repeating the document body inline.

Questions? Message me on X or find me on LinkedIn.

For agents.