Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
37 lines (25 loc) · 1.63 KB

ARCHITECTURE.md

File metadata and controls

37 lines (25 loc) · 1.63 KB
Raw

Agent Comments Architecture

Agent Comments is local-first and file-centered. Markdown is the source of truth.

Core Idea

All review state lives in the Markdown file as CriticMarkup. There are no active sidecar review files.

This lets multiple agents coordinate through the same visible review state:

  • user comments
  • agent replies
  • additions
  • deletions
  • substitutions
  • highlights

Suggestions and discussions remain flat adjacent CriticMarkup in the file. The UI turns that flat markup into linked proposal cards and inline accept/reject/edit controls without creating hidden state.

Main Modules

  • main.ts wires Obsidian, settings, commands, selection popovers, background agent runs, notifications, and editor synchronization.
  • src/panel/view.ts renders the Open | Terminal sidebar and embedded terminal.
  • src/review-model.ts converts parsed CriticMarkup into sidebar review items.
  • src/parser.ts parses CriticMarkup while ignoring code blocks.
  • src/operations.ts produces source edits for accept, reject, reply, resolve, and finalize.
  • src/edit-suggestion-modal.ts edits proposed suggestion text without applying it to prose.
  • src/wikilink-suggest.ts adds Obsidian note completion to comment textareas.
  • src/terminal.ts wraps xterm.js and a small Python PTY bridge.

Agent Paths

Background reply agents are one-shot commands that receive stdin and either edit the Markdown file or print a reply.

Terminal agents are interactive CLI sessions inside the sidebar. They are better suited to broader research, citation work, and multi-step edits.

Both paths are expected to write durable output back into Markdown.