Comments

Comments let you annotate work in three places: a block in an artifact's body, the artifact as a whole, or a specific line of code in a file or diff. The primary use case is guiding an agent's next pass — write specific feedback, the agent reads it via MCP tools and iterates.

Comments are stored locally on your machine. They live in a SQLite database in your Spruce project's comments/ folder, but the database isn't committed and doesn't sync through the project's git remote. They're meant for the in-flight loop with an agent (and your own thinking-out-loud), not cross-team review.

Where you can leave a comment

Three surfaces, one comment system:

• On a block in an artifact body: paragraph, list item, heading, code block. Hover the block, click the comment icon in the gutter.
• Top-level on the artifact: for notes that aren't tied to a specific block. Use the Comment button in the artifact editor header, or open the Comments tab in the tool panel.
• On a line of code: inside a file or diff in the Code page or the artifact's Git tab. Hover the line; click the comment icon in the gutter.

Artifact editor with a comment thread anchored to a paragraph and a code-line comment in the diff view

Inline vs. in the panel

Comments live in two display states depending on whether the Comments tab is open:

• Comments tab closed: open threads render inline, anchored to the block in the editor, or in the gutter next to the line in the diff/file viewer. They're the visible reminder that the artifact has open feedback.
• Comments tab open: the inline gutter markers go away. Open threads collect in the Comments tool panel as a list, ordered by anchor. Use the panel for triaging a long thread or scanning everything an agent has posted in one place.

Resolved comments are never shown inline; they only appear in the panel, and only when you toggle resolved-comment visibility (Show Resolved Comments in the breadcrumb-bar (...) menu, ⌘⇧/).

So the workflow is: keep the panel closed while you're writing or reviewing in context, and open it when you want to triage or sweep.

Anchoring

Comments remember what they were attached to so they can re-locate themselves when content changes.

Block-level (artifact comments)

Block-anchored comments capture:

• The block type (paragraph, heading, list-item, code-block, etc.)
• A snapshot of the block's text
• The nearest preceding heading

If the artifact body changes, Spruce re-anchors to the moved-or-edited block. If the original block is gone, the thread becomes "orphaned" and surfaces with a warning so you can re-locate it manually.

Line-level (code comments)

Line-anchored comments capture:

• File path (relative to the linked code repo)
• Line number
• Side: left or right for diff-view comments (old or new content)
• Commit hash: the revision the comment was made against

Same fallback: re-anchor when possible, mark "orphaned" if the line is gone.

Authorship

Every comment renders with the name of whoever created it. When an agent posts a comment via MCP tools, it shows up under whatever name the agent runs as, typically claude or codex. There's no special "Agent" badge; the author name is the indicator.

Routing comments to agents

A comment is most useful when it actually reaches a running agent. Spruce auto-routes when it can and surfaces a menu when it can't, so every open comment has an obvious path forward.

Forwarding to a session that's already listening

An action subscribes to comment events by declaring forward: [comment-added] in its frontmatter. The base-bundle Respond action does this out of the box; add it to any agent action that uses an interactive REPL-style command (e.g. claude "prompt"). One-shot commands (claude --print, codex exec) exit before any forward could be delivered.

When you reply to a comment on an artifact while a forwarding-enabled session is running, Spruce auto-routes the reply to that session — no menu, no extra click. The session reads the new comment on its next prompt.

See Actions → Anatomy of an action for the forward: field.

The route menu — when there's no obvious target

When a comment is open with no listening session (either you posted it before launching an action, or you cancelled the previous routing — see Nevermind below), Spruce shows a small Choose how to handle this comment menu under the reply box:

• Send to <session> — for each currently-running session on the artifact. One click posts the comment as a PTY nudge to that session and the activity badge appears.
• Start new <action> — for each forwarding-capable action defined in the project. One click spins up a fresh session with the comment baked into its initial prompt (via the {{initial_comment_nudge}} template variable), so the agent reads it the moment it boots.

The menu lists every existing-session option and every available action option in one row — so re-routing after a Nevermind is one click, not a re-type.

Comment route menu showing Send to <session> and Start new <action> options

Activity badges

While an agent is handling a comment, the reply input is replaced by a status badge:

• Waiting for agent… (gray) — the nudge has been delivered but the agent hasn't claimed the comment yet. Either the session is busy with prior work, or the agent doesn't claim aggressively.
• Being addressed… (blue) — the agent has called artifact_comment_claim with a one-line note describing what it's doing. The note is shown in the badge (e.g. "Rewriting the migration to drop-before-create") so you don't have to follow the session to see the work in flight.

Click either badge to jump straight to the running session.

Nevermind — cancelling an in-flight comment

Both badge states show a Nevermind button. Click it to:

1. Post a short cancellation status line into the thread, so the audit trail shows the comment was withdrawn rather than resolved.
2. Signal the running session to stop working on the comment via a [reply-cancelled] PTY tag — the agent's system instructions tell it to wind down work on that thread.
3. Clear the badge immediately.

After cancel, the comment is back to unrouted; the route menu re-appears so you can resolve the thread or re-route to a different session or action.

Comment thread showing the Being addressed… badge with the agent's note and the Nevermind cancel button

Threaded replies

Click an existing comment marker to open the thread and reply. Replies stack inline; threads stay collapsed in the gutter until expanded so they don't clutter the body or the diff view.

Resolving

When a thread is addressed, click Resolve. Resolved comments are hidden by default but toggleable from the artifact header (or, on code, from the diff view's settings). Resolution is under your control; agents can't re-open a resolved thread.

The agent review loop

Comments are the primary channel for reviewing and guiding an agent. The cycle:

1. Comment is routed. You reply (auto-forwarded into a listening session) or click an option in the route menu. The badge enters the Waiting for agent… state.
2. Agent claims. The agent calls the artifact_comment_claim MCP tool with a one-line note, and the badge flips to Being addressed… with the note inline.
3. Agent works, then replies to the comment with its response. The claim auto-releases on reply and the badge clears.
4. You review the reply and either resolve the thread, reply with further direction, or click Nevermind to cancel any in-flight work.
5. If you reply, the agent re-claims on its next pass and the cycle continues.

For the agent-side mechanics and the practical guidance on writing comments that agents can act on, see Commenting Back on Agent Work.

Browsing comments project-wide

For a project-wide view of every thread, open the global Comments page from the Tools section of the sidebar (⌘⌥M on macOS, Ctrl+Alt+M elsewhere). It lists every comment in the project (artifact and code) filterable by artifact, status, and origin. Useful for triaging open threads or catching up after a sync.

The same content is also available scoped to one artifact in the Comments tab of the tool panel. See Embedded vs. global for the broader page-vs-embedded model.

Storage

Comments live in a SQLite database in your Spruce project's comments/ folder. The database is local to your machine; it isn't committed and doesn't sync through the project's git remote. Both artifact comments and code comments share the same backend; both are local-only.

If you switch machines, those comments don't follow.

Related

• Commenting Back on Agent Work — agent-side mechanics and practical review-comment patterns.
• MCP Tools — how agent comments are written.
• The Artifact Editor — where artifact comments are rendered.
• Diffs and Commits — where most code comments happen.
• Hand Work to an Agent — kicking off the loop.