4 Sep 2026 · Gander

Watch the file, not the PR

gander watch plan.md publishes a https://gander.md/s/… URL and updates it on every save. That is hosted watch. It is for a reviewer who is not on your machine.

gander plan.md --watch is local preview. It has no URL you can send. It cannot take comments. Mixing the two is the usual footgun. I have seen people run the local flag, stare at a nice live reload on their laptop, and wonder why their teammate cannot open "the link." There is no link. Different command. Different job.

This post is about that distinction, and about why watching the file beats inventing a PR just so someone can read a draft.

What hosted watch is for

Use hosted watch when the file is still moving and someone else has to read it. The agent is mid-rewrite. You want eyes now. The reviewer has a browser, not your IDE.

gander watch plan.md

Every save updates the hosted page. Comments sit on the rendered markdown like Docs. Comments that start with @agent come back into the session that owns the file. Local file stays the source of truth. The hosted page is a live view plus threads, not a second copy.

Directory watch is the same loop for a folder of agent output. New markdown under the path gets its own link. The local files stay truth either way. If your agent dumps a stack of specs into ./plans, watching the directory means you are not manually sharing each file as it appears.

Use a pull request when the file is worth committing. Gander's job ends at that handoff. Before git, not instead of git.

I keep telling people the boring version of this: hosted watch is scaffolding for a moving draft. Scaffolding is useful. Scaffolding comes down. The PR is for the still file. Watch is for the moving one. Confusing those timelines is how you get both a noisy PR history and a review surface that fights the agent.

The footgun, in detail

Local --watch is genuinely useful. You are alone with a buffer. You want the rendered page to reload when you save. No share. No comments. No account. Fine.

The confusion starts when someone says "just watch it" without saying which watch. In our CLI, gander watch plan.md is an alias for hosted share --watch. The local path is gander plan.md --watch (or the older mental model of a render flag). If you teach a teammate the wrong one, they will think Gander is "a markdown previewer" and miss the product.

I keep a dumb mnemonic: if someone else needs the URL, say the word "watch" as a verb with a file. gander watch plan.md. If it is only your eyeballs on your laptop, the flag lives next to the file path. Local. No send.

When you mean review, you also mean comments. Local preview cannot take them. Hosted watch can. If your loop needs @agent, you are already in hosted land.

The footgun is social as much as technical. Someone demos "live markdown" on their laptop, feels the product, then shares the wrong instructions in Slack. The teammate runs local --watch, sees a preview, and reports that Gander "does not do comments." They are right about the command they ran. They are wrong about the product. Naming the hosted command out loud saves that whole loop.

What people try instead of watching the file

Early PR. Commit the plan so someone can use GitHub review. Familiar UI. Wrong timeline while the agent is still rewriting. Diffs fight the live file. You invent PR noise for a document that was never ready for history. Hand off to a PR when the file is still. Do not use the PR as a pre-git messaging bus.

Slack paste. Fast. Frozen. The review surface is no longer the file. Your teammate argues about a blob while disk moves.

Gist. Public snapshot. Fine for "here is what it looked like at noon." Not a live local watch. Not threads that reach @agent. You republish, or you do not, and either way you are managing copies.

Notion or wiki paste. Team home for finished docs. Wrong moment for a still-moving plan. Second copy. Agent does not own it. Drift is not a bug in the paste. It is the paste.

Screenshare. High bandwidth for two minutes. No durable anchors. Nothing for the agent to pick up later.

Each substitute is good at something else. None of them keep one truth on disk while a teammate reviews a live view of the file that is still changing.

I get why people hear "live link" and file us under share tools. A pretty render of a still-moving plan is useful. It is not the product by itself.

The product is the loop: live hosted watch, Docs-style inline threads, and a path for the agent to act. Miss one and you are back to sharing. Preview alone re-enters the old category. Watch is the first piece. It is not the whole thing.

That is why the command matters in prose. gander watch plan.md is the boring line that makes the loop real for a reviewer who is not in your session. Local --watch is a different boring line for a different afternoon.

If all you wanted was a prettier render, local preview would be enough. The moment you need a second human, and a thread, and a way for @agent to reach the session that owns disk, you need hosted watch. Calling both "watch" without the hosted or local qualifier is how demos sell the wrong afternoon.

A small scene

Your agent writes plan.md for twenty minutes. You run hosted watch. You drop the link in Slack with one sentence: "still moving, comment on the link, @agent if you want a change." Your lead opens it on a phone. They leave a human thread about naming. They leave an @agent on the migration order. You keep coding. The agent rewrites the order. Their phone tab updates. Nobody opened a PR. Nobody pasted the plan into Notion "so we have a copy." Nobody asked them to clone.

Later the file settles. You stop the watch in your head, commit, open the PR for the review job git is good at. Handoff. The watch was for the moving file. The PR is for the still one.

I have also seen the bad version of that scene. Same agent, same plan, local --watch because someone remembered the flag and not the verb. Lead asks for the link. There is none. Author panics into an early PR. Comments land on a SHA. Agent rewrites disk. Review becomes archaeology before lunch.

When watch should stop

Hosted watch is not forever. When the file settles and earns a place in history, you hand off. Stop treating the live link as the long-term home. Open the PR for merge-shaped review. The watch was scaffolding for a moving draft. Scaffolding comes down.

Teams get into trouble when they keep watching a file that should have been committed last week, or when they open a PR for a file that will rewrite three more times today. Both mistakes are timeline mistakes. Watch answers "still changing, need eyes." PR answers "ready for history." Pick the tool that matches the moment.

If you are unsure, ask a blunt question: would I be embarrassed if this exact text showed up in git log tomorrow? If yes, keep watching. If no, commit and move the review conversation to the place git is good at.

That question is kinder than "is this done?" Done is a feeling. Embarrassed-in-git-log is a useful filter. It keeps you from minting history as a comment transport, and from clinging to a live link after the file has earned a home.

File, not PR

Watch the file while it is cheap to change. Review on the live link. Let @agent reach the session that owns disk. Then git.

If you catch yourself opening a PR because you needed a comment UI, pause. Ask whether the file has earned history yet. If not, you needed hosted watch, not a fake merge request. Hosted gander watch plan.md for someone else. Local --watch for yourself. Keep them straight, and the rest of the loop gets easier to explain.