Feature request: react-grab-style highlight + annotate on markdown, exportable as a changelist for coding agents

[JohnnyBonk]

TLDR

Inspired by react-grab: highlight any markdown passage in Marky and get a small action menu (annotate / cut / reword / note). Those actions accumulate into a timestamped list on the document. Export the whole list back to your coding agent as a structured changelist.

Workflow

Coding agents constantly produce markdown for humans to review — READMEs, specs, plans, architecture notes. Today, reading in Marky is passive: I read, I mentally flag what needs changing, then I translate those notes back to the agent as prose. Context evaporates between reading and reporting.

What I'd love — colour-first, lists are just named colours:

1. Pre-set an active highlight colour (say yellow). Highlight any passage the normal way and it uses that colour.
2. On highlight, a small menu offers: add an annotation, mark it cut / flag / note, or leave the highlight bare.
3. Swap the active colour at any time (keyboard shortcut / palette / menu). Highlights from that point land in the new colour, then switch back whenever — no ceremony.
4. Each colour is implicitly a list. Optionally name a colour ("grammar issues", "no citation", "cut candidates") and that becomes its list title. Until named, it's just "yellow" or "pink".
5. Every action carries a timestamp and the surrounding section heading (## / ###) automatically.
6. At the end, copy to clipboard at three granularities: a single item, one whole list (i.e. one colour), or all lists. Output is a structured changelist ready to paste to Claude Code / Cursor / Aider.

Example flow: default colour is yellow, I highlight a bunch of things as "grammar issues" and annotate as I go. Mid-read I spot an uncited claim, switch to pink, highlight it as "no citation", then switch back to yellow for the next passage. At the end I copy the pink list by itself for the citation-chasing round, then the yellow list for the prose round.

Example export (all lists)

Source: /abs/path/to/README.md
Exported: 2025-03-12 11:07

## List: grammar issues (yellow)

### Section: "Installation"
> Run `npm install` and then configure your environment.
Action: annotate — awkward sentence, split into two.
Timestamp: 2025-03-12 10:43

### Section: "Usage"
> Import the client and call .run()
Action: annotate — missing article before "client".
Timestamp: 2025-03-12 10:45

## List: no citation (pink)

### Section: "Performance benchmarks"
> The library is 3x faster than alternatives.
Action: flag — needs a benchmark link.
Timestamp: 2025-03-12 10:44

Or copy just one list (pink), or just one item — same structure, narrower scope. Paste straight to the agent, it applies the edits.

Why react-grab is the inspiration

react-grab's win is that its output is formatted for a coding agent, not a human reader. File path first-class, location automatic, one action captures everything the agent needs. The same principle carries to markdown: file path, section heading, passage text, action, timestamp. The specific keystrokes or menu chrome matter less than the principle — output should be immediately pasteable to an agent.

Nice-to-haves

• Three copy granularities: single item, one list (one colour), all lists
• Keyboard shortcut to cycle the active colour without leaving the document
• Export formats: plain, markdown-blockquote, JSON
• Per-file persistence for in-progress reviews
• Optional custom pipe command, e.g. --pipe "claude --append-prompt '{changelist}'"

Secondary ask: folder disambiguation in the sidebar

Opening Marky on a directory with markdown from several projects shows leaf names (plans, drafts, notes) with no project context. Would love parent repo in parens:

plans (coax-climate)
drafts (coax-climate)
plans (bookie)

Detection: walk up until you hit .git, use that folder's name.

Why it matters

The read-review-feedback loop with coding agents is now a core workflow, and no tool treats it as first-class. Marky is already the best place I read agent output. This bridge would make it the home for the whole cycle.

Happy to spec further or test a prototype.

[GRVYDEV]

This is a great suggestion! If you could spec out the highlighting implementation a bit more that would be super helpful to me. I think I understand what you're asking for but would like some more detail. Im happy to implement the folder disambiguation though

[JohnnyBonk]

Appreciate it! Thanks for picking up the folder disambiguation. Spec for the highlighting below — I'm leaning on three UX references: Apple Books (selection popover + notes sidebar), PDF Gear / Preview (multi-colour highlighting with margin notes), and react-grab (agent-ready output format). Each covers part of what I want; Marky would be the first tool I've seen that puts them together.

1. Selection → action popover

User selects any text in the rendered markdown view. A small floating popover appears anchored to the selection (Apple Books style), containing:

• Colour swatches (e.g. 5 presets — yellow, pink, blue, green, purple; user-configurable palette if you want). Each swatch represents an existing list.
• New list button — creates a new list on the fly (see below), applies its colour, and assigns the highlight to it.
• Existing list picker — small dropdown or menu showing all named lists in the current doc, so you can drop a highlight into a named list without going to the swatch row.
• Annotate button — applies the currently active colour / list and opens an inline note field below the highlight for a per-item note.
• Copy for agent button — single-item agent-ready export straight to clipboard (the react-grab-parity shortcut).

Click a swatch once → highlight applied in that list's colour, popover dismisses.
Click Annotate → highlight + per-item note input.
Click New list → list-creation mini-form (see §4).
Click outside → dismiss without action.

2. Active colour

• There's a persistent "active colour" for the session, shown as a single swatch in the top toolbar.
• Click the toolbar swatch to change it (or key shortcut, e.g. 1–5 for preset slots).
• When the user has a keyboard highlight shortcut bound (e.g. ⌘H), it applies the active colour without opening the popover — lets fast readers skim-highlight quickly.

3. Annotations

• Inline text field that appears below the highlight on "Annotate".
• Single field, commits on Enter / blur, cancels on Esc.
• After save, a small margin marker next to the highlight indicates a note exists (Apple Books / PDF Gear convention). Hover or click to expand.
• Annotations are optional per highlight — a bare highlight is fine.

4. Lists (the review-organising primitive)

A list has:

• Name (e.g. "unclear citations").
• Colour (the visual marker — one list → one colour, swappable).
• Description / rules (freeform text — e.g. "these citations have the following issues: missing page numbers, stale URLs, uncited claims that need a source"). This is the big unlock: the description captures the general criteria that apply to every item in the list, so per-item notes are only needed when one specific item has nuance beyond the list description. An item with no personal note just inherits the list description when exported.
• A list of items (highlights).

Creating a list

Two ways:

1. From the selection popover → New list → inline mini-form: Name (required), Description (optional, multi-line), Colour (swatch picker). Save → the currently selected passage becomes the first item.
2. From the sidebar → + New list button at the top.

Editing a list

• Name: inline-editable in the sidebar header.
• Description: expandable text area under the header.
• Colour: click the swatch to change; all items in the list update visually in the document.

Review sidebar

• Togglable sidebar showing all lists for the current document, collapsible per list.
• Each list header: colour swatch, name (inline-editable), item count, "Copy list" button, expand/collapse chevron.
• Under the header: the list's description (inline-editable multi-line).
• Under the description: item rows — truncated passage, per-item note (if any), section heading, timestamp.
• Click an item → jump to that highlight in the document and centre it.
• Drag items between lists → reassigns list + colour.
• Per-item and per-list action menus: copy, move-to-list, archive, delete permanently.
• Multi-select lists via cmd/shift-click on list headers → "Copy selection" bundles the selected lists. No prominent "Copy all" — users can select all if they really want to, but the default UX should favour focused scopes.

This is the "lists are named colours with a description" model.

5. Export / copy granularities

Three scopes, same output shape — listed roughly in the order of how often they should be used:

• Single item (right-click item in sidebar, or Copy-for-agent in the popover on the highlight itself): one block. Tightest context, best agent precision.
• Single list (button on list header): all items in that list, grouped under the list header + description. This should be the default granularity for most review sessions.
• Multi-select lists (cmd/shift-click list headers in the sidebar → "Copy selection"): user picks exactly which lists to bundle together. Worth explicitly calling out: copying many lists at once is usually a bad idea — large contexts degrade agent accuracy, and it's better to run multiple focused paste-and-apply rounds than one mega-paste. A plain "Copy all" button is therefore not prominent — it's accessible via selecting all lists, but the UX should nudge users toward smaller scopes.

Default output format (plain text on clipboard):

Source: /abs/path/to/README.md

## List: unclear citations (pink)
Description: These citations have the following issues — missing page numbers, stale URLs, or claims that should cite a primary source instead of a news article. Please either fix each one or flag it as genuinely uncitable.

> The library is 3x faster than alternatives.
Section: Performance benchmarks
Timestamp: 2026-04-20T10:44:27Z

> Studies show developers prefer minimal APIs.
Section: Philosophy
Timestamp: 2026-04-20T10:46:11Z
Note: this one specifically needs a primary source, not a blog post.

## List: grammar issues (yellow)
Description: Awkward phrasing, missing articles, or sentences that run long. Fix in place.

> Run `npm install` and then configure your environment.
Section: Installation
Timestamp: 2026-04-20T10:43:12Z

> Import the client and call .run()
Section: Usage
Timestamp: 2026-04-20T10:45:03Z
Note: missing article before "client".

Shape:

• Absolute source path up top so the agent can locate the file.
• One ## List: header per list, with a Description: line if the list has one.
• Under each list, items as blockquoted passages with section + timestamp always, and an optional Note: line only when the item has a per-item annotation.
• Items without a note inherit the list description as their context, so the agent has everything it needs without repetition.

Nice-to-haves on export (all optional):

• Format toggle in settings: plain (above), markdown-blockquote, JSON.
• Optional --pipe "command {changelist}" — pipe clipboard contents through a user command for direct agent integration.

6. Versioning & archive

Lists and items should be editable, and past versions recoverable. Simple model:

• Edit history per list and per item. Every edit to a list (name, description, colour) or an item (passage binding, per-item note) is recorded with timestamp and the prior value. The sidebar has a small "History" expander on any list or item showing the last N versions; click a past version to preview, and a "Restore" action to roll back.
• Archive by default, hard-delete when you want it gone. The primary delete button on any list or item archives — moves it out of the default sidebar but keeps it recoverable via a "Show archived" toggle, one-click restore. Next to it, a separate Delete permanently button wipes the object and its history completely. Archive is the safety-net default; hard-delete is available when the user genuinely wants to flush something.
• No cross-document undo stack required. Edit history scoped to the document is enough; Marky doesn't need to behave like a full CRDT or multi-user editor.

The simplest implementation is an append-only event log inside the sidecar file — each edit / delete / restore is a stamped entry, current state is derived. But a straight history: [...] array per object is fine too and probably easier to render.

7. Persistence

My instinct: sidecar JSON next to the markdown file. For README.md, store at .marky/README.md.json in the same directory (keeps the tree clean, easy to gitignore). Alternative is a global app-scoped store keyed by absolute path + content hash. I'd defer to whatever fits the rest of Marky's architecture — this is a decision for you.

Shape (sketch):

{
  "source": "/abs/path/to/README.md",
  "lists": [
    {
      "id": "l_01",
      "name": "unclear citations",
      "description": "These citations have the following issues — missing page numbers, stale URLs, or claims that should cite a primary source.",
      "colour": "pink",
      "createdAt": "2026-04-20T10:40:00Z",
      "updatedAt": "2026-04-20T10:52:00Z",
      "archived": false,
      "history": [
        {
          "at": "2026-04-20T10:40:00Z",
          "op": "create",
          "values": { "name": "citations", "description": "", "colour": "pink" }
        },
        {
          "at": "2026-04-20T10:52:00Z",
          "op": "edit",
          "changed": ["name", "description"],
          "prev": { "name": "citations", "description": "" }
        }
      ]
    }
  ],
  "highlights": [
    {
      "id": "h_01",
      "listId": "l_01",
      "passage": "Studies show developers prefer minimal APIs.",
      "section": "Philosophy",
      "note": "this one specifically needs a primary source, not a blog post.",
      "range": { "startOffset": 1234, "endOffset": 1289 },
      "createdAt": "2026-04-20T10:46:11Z",
      "updatedAt": "2026-04-20T10:46:11Z",
      "archived": false,
      "history": []
    }
  ]
}

Range offsets resilient to rerender would be ideal; if the markdown changes upstream, fall back to fuzzy passage match before showing the highlight as orphaned.

8. Open decisions (your call)

• Palette: fixed 5 colours, or user-configurable?
• Persistence: sidecar files vs global app store?
• Keyboard shortcuts: what's idiomatic in Marky today? Happy to match existing conventions rather than invent new ones.
• Scope of v1: would you rather land highlight + sidebar + copy first, and defer annotations/lists/naming to v2? I'd honestly take a v1 that's just "highlight + colour + copy one or copy all" and iterate from there.

Happy to answer anything, iterate on the spec, or test builds. Cheers for taking this on.