Skip to content

About

Margin: review Markdown files in Tern and leave CriticMarkup comments, block by block. Built for reviewing plans with coding agents.

Topics

Resources

Stars

4 stars

Watchers

0 watching

Forks

Latest commit

 

History

7 Commits

Folders and files

Repository files navigation

Margin, a plugin for Tern: review Markdown with your agents, one block at a time. Signed Nicholas DiMoro.

Margin

Test

Margin is a Markdown review tool for Tern. Open a Markdown file and Margin renders it block by block. Comment on any paragraph, list item, heading, table or code block, and the comment is saved in the file as CriticMarkup ({>>comment<<}). Git, editors and agents can all read it, and nothing else in the file changes.

Margin was built for reviewing plans and drafts with coding agents. An agent runs margin open plan.md, you review in Tern, and the agent gets your comments back when you press D.

A Markdown file in Margin: rendered headings, a list and a table, two comments shown under their blocks, the table selected, and a comment being written at the bottom

The review screen is a Tern Surface Protocol program: it runs in a pane like any command, and Tern draws it natively. No plugin code runs in the window, so any Tern client attached to the session should be able to show it.

Tested with Tern 0.6.1. MIT licensed.

Install

Margin needs Node 22 or later on the machine that holds your files.

npm install -g github:Noctivoro/tern-margin

That puts the margin command on your PATH. Optionally, add the palette command Review this Markdown file (it starts a review beside the focused Markdown file block):

tern plugin install github.com/Noctivoro/tern-margin

Review a file

margin review notes.md
Key Action
k or ↓ / j or ↑, click Next block / previous block, or select by clicking
g / G First or last block
c, enter, double-click Comment on the selected block
tab / shift+tab Next or previous comment
e, double-click a comment Edit the selected comment
x Delete the selected comment (y confirms)
D Done: close and report that you finished
q Close without finishing
t Open the file as text in a Tern file block
r Reload from disk
? Show more keys

In the comment box, enter saves, shift+enter adds a line and esc cancels. With Tern's native composer editing on (Settings › Terminal), the comment box behaves like any text field: selection, ⌘⌫, ⌘Z. Without it, ⌃U, ⌃K and ⌃W delete to line start, to line end and a word back, and ⌘Z undoes.

On macOS, holding a letter key shows the accent menu instead of repeating, so holding k or j moves only once. To make held keys repeat in Tern (as most terminals do), turn off press-and-hold for Tern only, then quit and reopen Tern:

defaults write so.stencil.tern ApplePressAndHoldEnabled -bool false

defaults delete so.stencil.tern ApplePressAndHoldEnabled undoes it.

For agents and scripts

margin open docs/plan.md --json    # review in a new pane beside this one; waits for the result
margin doctor docs/page.md --json  # exit 1 when CriticMarkup remains

margin open splits the current pane, runs margin review in the new pane, and waits for it to exit. It prints:

{ "status": "done", "path": "…/plan.md", "comments": 3, "comments_before": 0,
  "changed": true, "pre_review_path": "…", "diff_path": "…" }
status Exit Meaning
done 0 The reviewer pressed D
abandoned 3 The reviewer pressed q
closed 3 The pane closed without the reviewer finishing

A script can also run margin review directly. It exits 0 on D, 3 on q (or Ctrl+C), 4 if Tern discards its screen, and 5 outside Tern. margin doctor counts CriticMarkup outside fenced code and inline code; use it as a gate before publishing a reviewed file.

Other Tern clients

margin open and margin review run on the machine that holds the file, in an ordinary pane. Tern's session daemon starts them, so the review doesn't depend on which window has focus or on any plugin being installed in it. By Tern's design, every client attached to that session draws the same pane, so Tern's announced iOS app and web client should show the review too. Neither is publicly available yet, so Margin is tested on the macOS desktop app only. Install Margin on the machine where your files live.

How comments are stored

Block Where the comment goes
Paragraph, list item, heading, quote Appended to the line the block's text ends on: …text.{>>comment<<}
Table, code block, HTML, front matter A new paragraph after the block: {>>comment<<}

Margin edits only the comment's own characters. Adding and then deleting a comment restores the file exactly; the tests check this against every block of every fixture, including CRLF files and emoji. One exception: a comment after a table or code block that runs straight into the next line gets a blank line after it, and if the file changes on disk or you reopen the review before you delete that comment, the blank line stays. Comments inside fenced code and inline code spans are text, not comments. A {>> with no <<} before the next blank line is plain text.

The file is written in place, so symlinks and file modes survive. Before every write Margin re-reads the file. If something else changed it, Margin reloads the file and keeps your unsaved comment in the box. While a review is open, Margin also checks the file for changes once a second.

Limits

  • Margin creates comments only. It shows highlights ({==…==}) unwrapped, and shows insertions, deletions and substitutions as raw text.
  • Comments attach to whole blocks, not word ranges.
  • Files over 4 MiB are not opened.

Develop

npm install
npm test     # node:test: parser, comment edits, editor, review state machine, CLI helpers

To see the screen while you work, run node bin/margin.mjs review some.md in a Tern pane. To drive it from a script, run a second Tern with its own config and daemon and use tern ctl:

D=/tmp/margin-dev; mkdir -p $D
(cd $D && TERN_CONFIG_DIR=$D TERN_DAEMON_SOCKET=$D/daemon.sock tern --control $D/ctl.sock $D) &
C="tern ctl --control $D/ctl.sock"
$C run "\"node $PWD/bin/margin.mjs review some.md\""
$C plugins expect '"Some heading"'
$C key c; $C type '"a note"'; $C key Enter
$C shot review    # PNG under $D/target/shots/tern/live/
Path What
bin/margin.mjs The margin command: review, open, doctor
review/app.mjs The review screen: state, view, keys, file writes
review/blocks.mjs Markdown to top-level blocks with source line ranges
review/critic.mjs CriticMarkup comment helpers
review/model.mjs Blocks plus comments, and the edits that add, change and remove comments
review/editor.mjs The comment box's text editing
cli/core.mjs margin doctor's CriticMarkup counter
plugin.toml, window.luau The optional palette command

Also by me

Chirp gives Tern a small robot voice that beeps when an agent finishes or needs you. Jev picks the mood, so you can hear how the turn went.


Made by Nicholas DiMoro.

About

Margin: review Markdown files in Tern and leave CriticMarkup comments, block by block. Built for reviewing plans with coding agents.

Topics

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages