grove

Comments

Comments are how you direct agents in Grove. You leave a comment on a line of the diff; the agent reads it, replies, and resolves it. It's the load-bearing protocol of the product — the diff view, walkthroughs, and the agent loop are all built on top of it.

Why a protocol, not a chat

Chat is a bad surface for code review: it's linear, it isn't anchored to files, and it conflates "let's talk about design" with "fix line 42." Grove's comments are:

  • Anchored — pinned to content, not line numbers, so they survive rewrites.
  • Threaded — each comment carries its replies, from you and from agents.
  • Durable — one local store per vault, shared across all workspaces. Every surface (the diff overlay, the Comments panel, workspace badges, agent tool calls) is a view onto the same store.

Leaving a comment

Select a line range in any file with changes and add a comment right there in the editor — this works in code and in rendered Markdown notes alike, so you can review an agent's design doc the same way you review its diff. The Comments panel (Cmd+J) shows every thread — pending and resolved — and clicking one jumps to its anchored line. Comment bodies render Markdown, so code snippets and links read properly in both directions.

Comments are never rewritten after the fact: replies append, and resolving marks state without touching history. You can unresolve or delete a thread too.

How comments survive edits

Each comment is pinned two ways: a fingerprint of the surrounding lines, and the code structure around it (the enclosing class or function). When the file changes, Grove relocates the comment:

  • fresh — exactly where you left it.
  • moved — relocated automatically after an edit.
  • stale — the content drifted too far; shown at the nearest line, flagged not deleted.
  • orphaned — the enclosing function or class is gone entirely.

What agents see

Grove's embedded MCP server exposes the comment store to agents as tools:

  • comments_list_pending — unresolved comments for the workspace. The agent's inbox.
  • comments_list_all — full history, including resolved.
  • comments_create — agents can leave comments too; Grove computes the anchor.
  • comments_reply — append to a thread.
  • comments_resolve — mark done, with an optional note.

This is a pull model. Each workspace's instructions tell the agent to check its pending comments as it works — there's no daemon poking the agent awake. When you write a comment, the UI updates immediately; the agent discovers it on its next turn. Nothing is lost if the agent isn't running — the comment just waits in the pending list.

There's deliberately no "acknowledge" state: pending simply means unresolved. An agent replies, resolves, or leaves it open.

Walkthroughs

A walkthrough is an ordered, multi-step explanation pinned across files — each step is a normal comment, so per-step reply and resolve work unchanged. Agents author them to tell a story across files instead of dropping isolated comments. See Walkthroughs.

Limits

  • One agent conversation per workspace drives the comment loop — no multi-agent concurrency on a single workspace's comments.
  • Comment bodies can't be edited after posting (reply or resolve instead).