Agent Comments

Google Docs-style comments and suggested edits for Obsidian Markdown, designed for local command-line agents.

Agent Comments adds a review layer to Markdown notes: anchored comments, threaded replies, and CriticMarkup suggestions that can be accepted, rejected, or edited. Review state is written directly into the note, so it stays readable in Obsidian, git, mobile sync, and any terminal agent that can inspect the file.

The plugin can run a configured command-line agent for a single thread, or open an embedded terminal for broader work. It includes presets for Codex, Claude, and OpenCode, and can run custom local commands.

Status

Agent Comments is a personal, experimental project, shared as-is under the MIT license. Fork it, remix it, and build on it freely. I do not currently have the time to actively maintain it, so issues and pull requests may go unanswered.

Screenshots

Installation

Agent Comments is not in the Obsidian community store yet. Install it manually or with BRAT.

Manual

1. Download main.js, manifest.json, and styles.css from the latest release, or build them locally with npm install && npm run build.
2. Create <your-vault>/.obsidian/plugins/agent-comments/.
3. Put the three files in that folder.
4. In Obsidian, open Settings -> Community plugins, reload plugins, and enable Agent Comments.

BRAT

1. Install the BRAT plugin.
2. In BRAT, choose Add beta plugin and enter andrewroxby/agent-comments.
3. Enable Agent Comments under Community plugins.

Privacy & Security

Agent Comments has no cloud backend and no sidecar review database. Comments and suggestions are stored in your Markdown files as CriticMarkup.

Configured agent commands may still send prompts, note contents, or document context to their own providers. Background agents and terminal agents run from the vault root, so use commands you trust and understand their credentials, permissions, and provider policies.

Quick Start

1. In Agent Comments settings, choose an agent preset or configure a custom command. Run the reply and terminal health checks. See Setup for examples.
2. Open a Markdown note, select a passage, and choose Add comment.
3. Use Send to Agent for a scoped thread reply, or open Terminal for broader work against the note.

Features

Comments and suggestions

• Anchor a comment to selected text.
• Reply in document-backed threads with the user and local agents.
• Propose edits as CriticMarkup additions, deletions, and substitutions.
• Accept, reject, or edit proposed changes inline.
• Start a discussion from a standalone suggestion.
• Resolve settled threads, or finalize a note by accepting/rejecting remaining CriticMarkup.

Agent workflows

• Send the full note, target thread, and review index to a background reply command.
• Use the embedded terminal to send the current note, selected review items, all open items, or only the filepath.
• Switch between configured agents from the sidebar.
• Configure separate reply and terminal commands per agent.
• Run built-in health checks for both command paths.
• Show run status and optional completion notifications.

Obsidian behavior

• Review cards in an Open | Terminal sidebar.
• Author colors for user and agent replies.
• Click comments or highlighted passages to reveal them in the note.
• Wikilink completion in comment boxes with [[.
• Enter to send; Shift+Enter for a newline.
• Cmd/Ctrl + scroll over the sidebar to resize comment text.
• Rendering in both Live Preview and reading mode.

Documentation

• Setup
• Workflow
• Architecture
• Agent protocol
• Append to AGENTS.md or CLAUDE.md
• Engineering notes
• Roadmap
• Notices

Mobile Behavior

Mobile and iPad can view and edit the Markdown/CriticMarkup review state. Local agent execution and the embedded terminal are desktop-only.

Platform Note

The review UI is ordinary Obsidian plugin UI. The embedded terminal, local background-agent runner, and desktop notifications are currently macOS-first. They use local command-line agents, a Unix PTY bridge, and macOS notification tools.

Agent Protocol

Agents should use CriticMarkup in the Markdown file rather than hidden sidecar state.

{>>Codex: This claim needs a source.<<}
{++Add this sentence.++}
{--Remove this sentence.--}
{~~old phrasing~>new phrasing~~}
{==highlight this passage==}

Adjacent comment blocks form one thread:

{>>Codex: This needs a citation.<<}{>>user reply with clarification<<}{>>Claude: Found the likely source.<<}

Agent comments should be prefixed with the agent display name. User replies are unprefixed.

Do not nest CriticMarkup forms. For edits to already-commented text, keep markup flat by replacing the text anchor with the suggestion and placing the thread immediately after it:

{==X==}{>>Agent: initial concern<<}{>>user reply<<}

becomes:

{~~X~>Y~~}{>>Agent: initial concern<<}{>>user reply<<}{>>Agent: rationale for Y<<}

Attribution

The CriticMarkup parser, source-edit operations, editor decorations, reading-mode rendering, author coloring, and finalize flow draw substantially from the MIT-licensed Track Changes plugin by philphilphil. Its license is included in TRACK_CHANGES_LICENSE; additional notices are in NOTICE.md.