The guide.

§ 1 Installing FolderMD

1. Download FolderMD.dmg from foldermd.com.
2. Open the DMG and drag FolderMD into your Applications folder.
3. Launch FolderMD from Applications, Spotlight, or the Dock.
4. The first time, macOS may warn that the app is from an unidentified developer. Right-click the icon and choose Open — one time only.

No account to make, nothing to configure, no permissions to grant.

§ 2 What you see on first launch

FolderMD opens to a quiet empty state with three buttons:

• Copy path — copies the inbox folder location to the clipboard.
• Install CLI helper — installs the foldermd command-line tool (see § 4).
• Drop a test document — drops a sample file into the inbox so you can see the rendering immediately.

The inbox folder lives at:

~/Library/Application Support/foldermd/inbox/

Anything written there shows up in FolderMD's sidebar within a second.

§ 3 Three ways to display a file

Project-local .foldermd/ — default for agent-written project docs

When an AI agent is working inside one of your projects, it writes plans, refactor notes, and design memos to:

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

then runs foldermd --open <abs-path>. The file appears in FolderMD's sidebar under Pinned and live-refreshes as the agent iterates. Because the file lives in the project, git diff shows it, git log tracks it, and you can grep the repo to find what the agent wrote about something you're now stuck on. Git decides what to do with the folder — commit it as an audit trail, or .gitignore it. Your call per project.

The global inbox — for content with no project context

Generic Q&A, research notes, "scratch a quick idea." Files land in:

~/Library/Application Support/foldermd/inbox/

Sidebar groups them by Today, Yesterday, Older. Press ⌘W to dismiss — the doc moves to Trash and auto-clears after seven days.

Open from Finder

Right-click any .md or .markdown file in Finder, choose Open With → FolderMD. The file appears in the reader pane AND auto-pins to the sidebar. Click Unpin if you don't want it sticking around (the file on disk is never touched).

Open from the command line

After installing the CLI:

foldermd --open ./notes.md

Auto-pins and live-refreshes as the file changes on disk. The killer flow for AI-assisted writing — you watch the doc evolve as the agent iterates.

§ 4 Installing the command-line tool

The CLI is bundled inside the FolderMD app. Two ways to install it.

From the app menu (easiest)

1. Open FolderMD.
2. Click FolderMD → Install CLI helper.
3. A dialog confirms the install path — /usr/local/bin/foldermd if writable, else ~/.local/bin/foldermd.

Test it from a new terminal window:

foldermd --inbox-path

If the command isn't found, the install location isn't on your PATH. Add it:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

CLI flags

foldermd                                       # open the FolderMD app
echo "# project plan" | foldermd --here        # write to ./.foldermd/, opens here
echo "# quick note" | foldermd                 # write to the global inbox
foldermd file.md --here                        # copy a file into ./.foldermd/
foldermd file.md                               # copy a file into the global inbox
foldermd --title "My plan" file.md             # custom sidebar title (works with or without --here)
foldermd --open file.md                        # open an existing file (no copy, live-render, auto-pinned)
foldermd --inbox-path                          # print the global inbox path
foldermd --set-threshold 2000                  # set agent long-output threshold (default: 1500)
foldermd --version                             # CLI version
foldermd --help                                # show all flags

--here is the flag agents reach for most often when working in a project. It creates ./.foldermd/ if it doesn't exist and opens the new file in FolderMD. Without --here, content goes to the global inbox.

§ 5 Working with AI agents

The most valuable thing you can do after installing FolderMD is tell your AI coding agents that it exists. Once they know, they route long markdown output into FolderMD instead of dumping it into chat.

Most of this is done for you

When you click Install CLI helper, FolderMD also:

1. Copies a folder of agent templates to ~/Library/Application Support/foldermd/agent-templates/. One template per supported agent: CLAUDE.md, AGENTS.md, .cursorrules, copilot-instructions.md, .windsurfrules, CONVENTIONS.md.
2. Configures supported agents globally by appending a FolderMD section to each agent's global rules file:

   Agent	File
   Claude Code	~/.claude/CLAUDE.md
   Codex CLI	~/.codex/AGENTS.md

   Each section is bracketed by <!-- FolderMD:begin --> / <!-- FolderMD:end --> markers so re-installing replaces rather than duplicates. If an agent's directory doesn't exist (you don't have it installed), that step is silently skipped.

After Install CLI helper finishes, Claude Code and Codex CLI are configured globally. For any other agent, copy the matching template into your project.

For other agents: project-local install

Each agent reads its rules file from a specific path inside your project. Copy the right template:

You can also drop a project-local AGENTS.md or CLAUDE.md in any project to override the global config for that project.

Example — set up Cursor for a project at ~/code/myproject:

cp ~/Library/Application\ Support/foldermd/agent-templates/.cursorrules ~/code/myproject/.cursorrules

Then start a fresh agent session in that project and the rules take effect.

Browse the templates inside FolderMD

Click Help → AI agent instructions in the menu bar. FolderMD opens an overview document showing every template with its target location and full content. Easier than digging through the filesystem.

Shortest-possible system prompt

If you'd rather skip the templates entirely and add one line yourself, this is the minimum:

If you want to show me a markdown file, run foldermd --open <path> after writing it.

The full reference for agent authors lives at foldermd.com/agent-integration.

§ 6 Making FolderMD your default

Once FolderMD is your default markdown app, double-clicking any .md file in Finder opens it in the reading pane.

To set it:

• From the app — click FolderMD → Set as default markdown viewer.
• From Finder — right-click any .md file → Get Info → expand "Open with:" → choose FolderMD → click Change All...

FolderMD will also offer once you've opened 20 markdown files from Finder, again at 50, and one final time at 150. Decline as many times as you like — after the third decline, it stops asking.

§ 7 Live preview while your agent writes

This is the workflow that surprises people the most. An example session:

1. You ask your agent: "Write me a README for this project."
2. The agent writes ./README.md in your project directory.
3. The agent runs foldermd --open ./README.md.
4. FolderMD opens the README in the "Now reading" pane.
5. The agent reads its own draft, revises it a few times.
6. FolderMD refreshes the rendered version automatically as the file changes on disk.
7. You watch the document evolve in real time — typeset, syntax-highlighted, ready to read.

When you're done, click Close; the watcher stops. If you Pin the file instead, it stays in the sidebar and continues to live-render whenever you select it.

§ 8 Tips & FAQ

Where is the inbox?
~/Library/Application Support/foldermd/inbox/. Click Copy path in the empty state, or run foldermd --inbox-path.

How do I delete a document?
Press ⌘W or click Dismiss. The doc moves to Trash (bottom of the sidebar). Auto-emptied after seven days; click an item before then and choose Restore to recover it.

Can I edit documents in FolderMD?
No. FolderMD is read-only by design — a viewer, not an editor. Click 📂 Reveal in Finder to jump to a file in your editor.

Light vs dark mode?
FolderMD follows your macOS system appearance setting.

Column width?
Click the ⟷ button in the toolbar to toggle between a centred narrow column (best for prose) and full-width (best for tables and wide code). The setting is remembered.

iCloud Drive / external drives?
Both "open from Finder" and foldermd --open work fine with files on any mounted volume. Pinned files on unmounted drives are silently dropped from the sidebar; re-pin after mounting.

What about huge markdown files?
Files over 10 MB are rejected with a friendly error. (10 MB is well past the size of any reasonable human-written document.)

Uninstalling.
Drag FolderMD.app to the Trash. Optional cleanup: rm -rf ~/Library/Application\ Support/foldermd removes your inbox and preferences. rm /usr/local/bin/foldermd (or ~/.local/bin/foldermd) removes the CLI.

Is FolderMD open source?
No — FolderMD is a closed-source commercial application. Your files, on the other hand, are always plain markdown on disk and entirely yours.

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