The review gate for agent-written Markdown
Your agent writes its plans in Markdown and you read them as a diff in a terminal. Folio is the other half of that loop — a floating window that shows what changed, takes your notes beside the passage, and returns them to the agent's terminal. Approve, or send it back.
Use it from Claude Code, Codex, or any shell: add the skill once
with npx skills add rahult/folio, then type
/folio docs/plan.md and Claude hands its plan to
Folio for you to judge.
Free and open source · about 5 MB · nothing loads before you ask it to
1>/folio docs/plan.md
⏺I'll open the rollout plan in Folio for you to review.
⏺Bash(folio review --wait --agent claude docs/plan.md)
⎿waiting for your verdict in Folio…
2you review plan.md in Folio — comment, replace, approve
⏺Review returned: changes requested — 2 annotations
⎿1. Replace "ship to all users at once"
→ 10% canary for a day, then 100%.
3⏺Updated the rollout section. Resubmitting.
Rollout
Ship to all users at once. Ship to 10% of users for a day, then everyone. Watch error rate and p95 latency before widening.
Roll back by flipping the flag, not by redeploying. Say who owns the flag during the canary.
In Claude Code, type /folio docs/plan.md. The
skill makes Claude open Folio itself and wait — no copy
pasting, no reading diffs in the terminal.
The plan floats over your work, live. Comment, replace, or delete beside the passage; the page turns read-only while Claude waits. Enter sends your verdict.
Your notes land in Claude's terminal as numbered Markdown, it rewrites the plan, and your open window reloads the new draft in place until you approve.
One command opens the window and blocks until your verdict. The agent branches on the exit code; you never leave the page.
While the window floats, Folio watches the file. Each rewrite reloads in place with additions washed green and removals shown struck through. Your own unsaved edits are never clobbered.
The page turns read-only while the agent waits. Move between
blocks with j and k, press
c to comment, d to delete,
r to suggest a replacement, a for
looks good, Enter to send. Each note appears in the margin
beside the passage it refers to, and stays beside it as you
scroll. The feedback reaches the agent's terminal as
structured Markdown with line numbers.
The /folio skill teaches Claude Code, Codex, and
other agents the loop. It only runs when you type it. Without
the skill, folio review plan.md from any shell
opens a floating window and keeps watching the file.
Revision History archives each on-disk version of a reviewed file and diffs any two, so you can see exactly what the agent did between its first draft and its fourth.
Install the skill once. It is user-invoked only.
npx skills add rahult/folio # via skills.sh, any agent
folio skill install # or from Folio's own command line
npx skills add rahult/folio -a pi # Pi, invoked there as /skill:folioThe CLI exits 0 on approve, 2 on changes requested, 3 if the review is still open, so an agent can branch on the result.
Act two
The text is the interface. Everything else steps out of the way until you ask for it. This is the real editor, running here.
Folio renders Markdown inline as you type.
There is no preview pane to glance at and no toolbar to reach
for: make this sentence italic, turn the next line
into a heading with #, or press ⌘/ to see the
source.
code- [x]The text is the interface. Everything else steps out of the way.
| Feature | Shortcut |
|---|---|
| Source mode | ⌘/ |
| Export | ⌘E |
| Focus mode | ⌥⌘F |
| Annotate | ⌥⌘A |
fn main() {
println!("calm software, small footprint");
}Switch to Exported page above to see this document the way File → Export writes it.
Headings, emphasis, lists, tables, code, quotes, links, and images render inline as you type. Press ⌘/ and the same page becomes plain Markdown, with your caret where you left it. Press it again to come back.
Rollout plan
Ship to 10% of users for a day, then everyone. Roll back with deploy --undo.
## Rollout plan Ship to **10% of users** for a day, then *everyone*. Roll back with `deploy --undo`.
Focus Mode dims every paragraph except the one you are in. Typewriter Mode keeps the line you are typing at a fixed height on the screen so your eyes never chase the caret. They compose.
The migration runs in three passes. The first adds the column and backfills it in batches of ten thousand rows.
The second pass switches reads to the new column behind a flag, so a bad batch can be undone without a deploy.
The third removes the old column once the flag has been on for a week without incident.
Paper is warm and quiet; Manuscript is a deeper cream with brown ink for long reading; Newsprint is high contrast for bright rooms. Night is dark without being black, and Slate is a cool blue-grey dark with a copper accent. All five set prose in Newsreader, and the choice is remembered.
The quick brown fox jumps over the lazy dog.
The quick brown fox jumps over the lazy dog.
The quick brown fox jumps over the lazy dog.
The quick brown fox jumps over the lazy dog.
The quick brown fox jumps over the lazy dog.
File → Export writes one self-contained HTML file: highlighted code, Mermaid diagrams as SVG, your images and the typefaces embedded. Export → PDF prints the same rendering, and Export → Word writes a .docx with real heading styles, lists, tables, and images. All three are built from the Markdown, so the result never depends on what was on screen.
Queue design
Producers write to a ring; a single consumer drains it.
fn drain(ring: &Ring) { while let Some(job) = ring.pop() { job.run(); } }
Native menus and file dialogs, a dirty dot in the title, Open
Recent, Markdown files dropped onto the window opening in
their own tabs, and session restore that reopens your last
file at the same caret and scroll position. Make it the
default app for .md from the File menu. Updates
install themselves.
Act three
A reading panel beside the page, in three tabs that follow the order you actually work in: read it, see who changed what, decide and remember why. Everything is a plain Markdown file beside the document, and nothing is graded.
The outline shows each section's reading time and marks the one you are in. A "what I took from it" field asks for one paragraph in your own words and keeps it beside the document.
Ship to ten percent of users for a day, then everyone. Watch the error rate. Roll back with the flag; the on-call engineer owns it.
Authorship tints the words an agent wrote in blue and the ones it rewrote after your feedback in green; your own words stay plain. The History tab ties each revision to the change requests it answered and shows which passages actually moved.
Recall each section from memory, write a premortem, answer three debiasing questions, then record the choice with a confidence that cannot be edited afterwards. Revisits log what actually happened, and a journal across documents lists the ones that are due.
 just works.[[wikilinks]], heading targets, and [[ completion.agent … | folio --float - to review output straight from stdin.Typora users will feel at home.
| Open, Save, Print | ⌘O ⌘S ⌘P |
| Go to file or command | ⌘K |
| Export HTML | ⌘E |
| Source Code Mode | ⌘/ |
| Focus Mode | ⌥⌘F |
| Typewriter Mode | ⌥⌘Y |
| Reading Panel, Authorship | ⇧⌘O ⇧⌘A |
| Close tab, next, previous | ⌘W ⇧⌘] ⇧⌘[ |
| Float on Top | ⌥⌘W |
| Back, Forward | ⌘[ ⌘] |
| Zoom in, out, reset | ⇧⌘= ⇧⌘- ⇧⌘0 |
| Heading 1 to 6 | ⌘1 … ⌘6 |
| Quote, table, code fence | ⌥⌘Q ⌥⌘T ⌥⌘C |
| Ordered, bullet, task list | ⌥⌘O ⌥⌘U ⌥⌘X |
| Strong, emphasis | ⌘B ⌘I |
| Link (with text selected) | ⌘K |
| Clear format | ⌘\ |
| Review Mode on or off | ⇧⌘R e |
| Next, previous block | j k |
| Comment, replace | c r |
| Delete, looks good, remove mark | d a x |
| Next, previous annotation | n p |
| Send the verdict | ↩ |
| Annotate selection while editing | ⌥⌘A |
| Export review feedback | ⌥⌘R |
Feedback
Folio is one person's work. A bug, a rough edge, or the feature that would make it part of your day — every note gets read, and the sharp ones shape the roadmap.
The feedback button in the app lands here too, and the site itself keeps no cookies — analytics are opt-in and anonymous.
Latest release: see GitHub. Links start the file download directly.
Installers are unsigned. On Windows, SmartScreen shows More info, then Run anyway. On macOS, if a downloaded app is refused as damaged, clear the quarantine flag once:
xattr -dr com.apple.quarantine /Applications/Folio.app