Fast ways to get through a pile of agent-written Markdown

Your agent finished a long run. Now there are fourteen new Markdown files in the folder: a plan, two handoffs, a notes file, a to-do list, and a few drafts you don't remember asking for. Some matter today. Most can wait. The hard part is telling which is which without reading all of them top to bottom.

This page gives you a fast routine for that pile. First you triage in a terminal with a few short commands, so you know where the work is before you open anything. Then you read the files that matter in a Markdown reader set up for many files at once: tabs, a kept place in each one, quick edits on the formatted page, and saves that touch only what you changed.

The first half needs no special software. A Mac or Linux terminal is enough.

Step one: triage in the terminal

Triage means sorting the pile before you read it. Three questions cover most of it: what changed last, which files mention the thing you care about, and how much is still open in each file.

The examples use a folder called agent-notes/ and files named plan.md and notes.md. Swap in your own names.

See the newest files first

ls -t agent-notes/

ls -t sorts by the time each file was last modified, most recent first. The files at the top changed most recently, so they are a good place to start. If two files share a time, they sort by name.

Find the files that mention a word

grep -l deploy agent-notes/*.md

grep -l prints only the names of files that contain the word. You get a short list of file names instead of every matching line. Add -i to ignore case, so "Deploy" and "deploy" both count:

grep -l -i deploy agent-notes/*.md

For the search word, try a feature name, or a word like "blocked" or "question".

Count open to-do boxes

A Markdown to-do box is written - [ ] when open and - [x] when ticked. To count the open ones in a file:

grep -c '\[ \]' agent-notes/plan.md

grep -c prints a count of matching lines, not the lines themselves. A plan with 2 open boxes is nearly done. A plan with 30 is where your afternoon is going. The post on Markdown task lists has more on writing and tracking these boxes.

Read the handoff file first

Before you open the plan or the notes, find the handoff. A good agent handoff file says what the agent finished, what it left open and where it stopped. Five minutes on the handoff can save you an hour of reading files that no longer matter.

If your agents don't write handoffs yet, or they scatter them across folders, the guide to organizing agent-written docs with folders, front matter and handoffs sets that up.

A triage routine you can repeat

1. List the folder newest first with ls -t.
2. Open the handoff file and read it start to finish.
3. Use grep -l to find the files that mention your topic.
4. Run grep -c on each plan or to-do file to see how much is open.
5. Write down the three to five files you'll actually read. Leave the rest.

Triage should end with a short reading list.

Step two: what a good Markdown reader should do with a pile of files

Once you know which files to read, the tool you read them in decides how fast the rest goes. A plain text editor shows raw syntax. A one-file previewer makes you open and close files over and over. Neither fits a stack of agent output.

Open many files at once

You've just made a reading list in the terminal. You shouldn't have to retype it in a file dialog. A good reader should accept several files from a terminal command in one go, open each one as a tab, and hand your terminal straight back so you can keep working. It should also take a batch of files dragged onto the app, and an Open dialog that lets you pick several files at once.

Sashmark is being built for this; the roadmap shows where it stands.

One tab per file, no duplicates

When you're moving between six files, duplicate tabs cause real mistakes. You edit one copy, then read the other and wonder where your change went. Each file should get exactly one tab. Opening a file that's already open should just switch to its tab.

Keep your place in every tab

You read half the plan, jump to the notes to check a detail, then come back. You should land where you left off, not at the top. Each tab should remember how far you scrolled. This matters even more when the agent is still writing; the guide on keeping your place while your agent rewrites the file covers that case.

Move between tabs from the keyboard

With a pile of files, the mouse slows you down. You should be able to go to the next or previous tab from the keyboard, close the one you're done with, and reopen the last tab you closed when you change your mind. It also helps if the reader remembers your open tabs and brings them back the next time it starts, so a half-finished review survives a restart.

A command palette

A command palette is a list of actions you open from the keyboard, filter by typing, pick with the arrow keys and run with Enter. For a pile of files, the useful actions are plain ones: open a file, close a tab, next and previous tab, show the file in its folder, and copy its full path so you can paste it into a terminal or a prompt.

A good reader should put those everyday actions one short search away. Sashmark is planned to have a command palette like this; check the roadmap for its current state.

Tick boxes and fix lines on the formatted page

Most of what you do to agent files is small. Tick a finished box. Fix a wrong date. Change one word in a step. Switching to raw Markdown for each of these breaks your reading flow.

A good reader should let you click into the formatted page and type. A click on a to-do box should tick or untick it. Tables should let you click a cell and edit it. In a list, Tab and Shift+Tab should move an item in or out a level.

Save only what you changed, and only when you say so

The agent or a script will read the file again after you, so two rules apply:

1. Saving is your call. Nothing should be written to disk until you save. No surprise writes in the background.
2. A save touches only your lines. If you ticked one box, the file on disk should differ by that one character. Every other line, including its line ending, should stay byte for byte as it was.

Not every editor keeps to the second rule, and when one doesn't, the agent's next diff fills with changes you never made. The post on why editors reformat Markdown on save explains how that happens, and what a byte-for-byte round-trip save is explains the fix.

Two more checks help. Before writing, the reader should confirm the file on disk is still the version your edits started from, so you don't overwrite something the agent saved a moment ago. And if some block can't be written back exactly, that block should become read-only while the rest of the file stays editable.

A good reader should let you tick a box, save, and leave every other byte alone. That is a core part of what Sashmark is being built to do; the roadmap shows how far along it is.

A short checklist for the next pile

• I listed the folder newest first before opening anything.
• I read the handoff file first.
• I used grep -l to find the files that mention my topic.
• I counted open boxes with grep -c to see where the work is.
• I wrote a reading list of three to five files and left the rest.
• My edits changed only the lines I meant to change.

Where Sashmark fits

Sashmark is a Markdown reader and editor for people whose AI agents write Markdown, being built for Mac, Windows and Linux. It is in development and has not been released, and the app itself has no AI features. It is planned to cover the second half of this page: opening many files at once from the terminal or by dragging them onto the app, one tab per file with your place kept in each, a command palette, edits on the formatted page, and saves that change only the lines you edited. When Sashmark is released, installers will come only from the Sashmark website. See the planned features, the help pages and the roadmap for where each part stands.

Sashmark is in development. See what it is at sashmark.com.