§ 1 Where to paste
Claude Code reads CLAUDE.md at session start. Two scopes:
- Project-level (recommended) —
<your-project>/CLAUDE.md. Applies only when you runclaudein that directory. Commit it; your teammates get the same behaviour. - Global —
~/.claude/CLAUDE.md. Applies to every session, regardless of where you launch from.
If a CLAUDE.md already exists, just append the snippet below. Claude Code is happy with multiple instruction sections in one file.
§ 2 The snippet
Open the file in your editor, paste this, save.
## FolderMD — long-form markdown belongs in a folder, not the terminal
When you produce long-form markdown — roughly 1500+ characters, or anything
with multiple headings, tables, or sections that the user will want to
*read* rather than skim past — route it through FolderMD instead of
emitting inline. The user works in a calm reading pane on their Mac, not
the chat window.
The CLI helper is at `~/.local/bin/foldermd` (already on PATH after
installation). Pipe markdown into it with a short slug title:
```bash
cat <<'EOF' | foldermd --here --title "auth-refactor-plan"
# Auth refactor plan
...
EOF
```
The `--here` flag writes to `<project>/.foldermd/<timestamp>-<slug>.md`
when you're inside a project. Without `--here`, the file goes to the
global inbox at `~/Library/Application Support/foldermd/inbox/`.
After routing, send a brief confirmation in chat — one or two sentences,
no more. Example:
"Dropped <title> into FolderMD — appears in your sidebar within a
second. Short version: <one-line takeaway>."
Do NOT repeat the document body inline. The whole point is to keep the
conversation light and the artefact heavy.
### When TO route
- Long explanations / strategy docs / how-tos (deploys, refactors, runbooks)
- Analysis reports / audit summaries
- Anything with more than two headings or a table
- Documents the user might want to keep, edit, share, or commit
### When NOT to route
- Short answers / single-paragraph replies
- Direct factual answers ("yes", "the value is X", "PR is at <url>")
- Tool output you're just relaying
- Status updates mid-task ("done, moving on")
§ 3 Confirm it took
Start a new claude session in the directory where you added the file. Ask for something deliberately long-form:
Write me a complete deployment plan for migrating our Node 18 service to Node 20, including risk analysis and a rollback strategy.
You should see Claude reply with one or two sentences — no wall of markdown — and a confirmation like "Dropped node-20-migration-plan into FolderMD — it'll appear in your sidebar within a second." Switch to FolderMD; the document is there, rendered properly, ready to read.
If Claude still dumps the plan inline, double-check that CLAUDE.md is in the project root (not a subdirectory), and that the snippet was appended below any existing instructions rather than orphaned at the bottom of a code block.
§ 4 Tuning
The default trigger is roughly 1500 characters. To make Claude more or less eager to route, add a single line after the snippet:
The threshold for routing to FolderMD is <N> characters of markdown — be
<more eager / more conservative> than the default.Drop the angle-bracketed bits to the values you want. Claude reads it literally — there's no need to tell it about a tuning system; the natural-language directive is enough.
§ 5 Companion tools
If you also write rules for Cursor, Codex, Aider, Windsurf, or GitHub Copilot in the same projects, each of those is one click away — same snippet, different config file. See the skills index.
Found a tweak that works better for Claude Code? Message me on X or LinkedIn.