MarsDawn

Chip Huyen's read-only/write-action split, and why it matters before you approve anything

Chip Huyen's January 2025 essay “Agents” starts from the textbook definition and works up to something more specific: an agent's actions split into ones that only look at the world and ones that change it. That split is a good way to decide, in the five minutes you have, which lines in a plan deserve a closer look before you say yes.

What the piece argues

Huyen opens plainly:

“An agent is anything that can perceive its environment and act upon that environment.”

From there she builds out what an agent needs: an environment to act in, and a set of tools — its “tool inventory” — that determines what it's able to do. She names a distinction between actions that only let an agent perceive its environment (“read-only actions”) and actions that let it act upon that environment (“write actions”). She's also direct about the risk that comes with the second kind: “Write actions enable a system to do more”, but “the prospect of giving AI the ability to automatically alter our lives is frightening” — as she puts it, “you shouldn’t allow an unreliable AI to initiate bank transfers.” She's also candid about the part of an agent that's hardest to get right:

“If you’ve ever been in any planning meeting, you know that planning is hard.”

Huyen doesn't mention MarsDawn anywhere in this essay, and doesn't recommend any Markdown tool. /reviewing-agent-plans/ already quotes three of her lines from this same essay: the cost of skipping oversight before a plan runs, the agent that thinks it's finished when it isn't, and, inside step 3 of its checklist, her line that a system facing a risky operation “can ask for explicit human approval before executing”. This note doesn't repeat those quotes; if you haven't read that page, it's linked below.

Our reading, not Huyen's

Huyen's read-only/write-action split isn't written as review advice — it's a way of classifying what a tool does. But it's a plain, general-purpose test for spotting the kind of risky-operation line that step 3 of that checklist already asks you to slow down for: reading a file, running a search, listing a directory are read-only, and a read-only step going wrong costs you a re-run; deleting data, force-pushing, merging a branch, sending an email, charging a card are write actions, and — as she says — a write step going wrong is the frightening kind, and by the time you're reading the agent's report, it may already have happened. Her point that planning is hard even for people in a room together is a useful check on expecting more precision from a plan than the format can bear: a plan reading confidently isn't the same as a plan being right.

Where MarsDawn helps, and where it doesn't

MarsDawn can't tell a read-only step from a write step in a plan — that's a judgment call the text doesn't label, and nothing in the app reads for meaning. It has no AI model inside: it won't flag the risky line for you, run the planning-hardness check, or grade the plan. What it does is keep the file legible while you make that call yourself: the Outline tab (View ▸ Show Sidebar, ⌃⌘S) lets you scan a plan's shape before reading it line by line, the source and the rendered page sit side by side (⌘2) so a diagram of the steps doesn't stay stuck as raw Mermaid text, and Edit ▸ Copy Reference (⌥⌘C) turns your place in the file into plan.md:10, ready to paste as feedback the moment you spot a write action in the wrong order.

Try it

MarsDawn is on the Mac App Store. The free marsdawn command-line tool works today:

brew install redtear1115/tap/marsdawn

It exports Markdown to PDF without the app.

Command Line · Know before you buy: What MarsDawn doesn't do

Next

Sources