remarq

Google Docs comments are where feedback goes to die. We built the antidote.

Remarq is a lightweight document annotation tool for the agent era. Drop a single <script> tag into any HTML page — reviewers highlight text and leave threaded comments (no accounts needed). Then your AI agent polls the API, revises the document, and resolves comments automatically.

The feedback loop isn't just faster. It's closed.

The Problem

You know the drill. Someone leaves a comment on your Google Doc: "this is confusing." Great. Now you get to:

1. Read all 47 comments
2. Interpret what each reviewer actually meant
3. Manually edit the document
4. Click "Resolve" on each one
5. Miss three of them
6. Get a passive-aggressive follow-up email

For a 50-page doc, that's hours of your life you'll never get back. And if you're copy-pasting feedback into ChatGPT? You're living in the stone age.

Google Docs is a word processor cosplaying as a collaboration tool. It was built in 2006. We can do better.

The Solution

Reviewer highlights text → leaves comment → agent reads API → agent revises → agent resolves → done.

That's Remarq. Human judgment in, machine execution out. The feedback cycle is closed.

Works for solo creators pair-writing with their AI — you annotate, your agent revises — or teams with multiple reviewers feeding back into one agent loop. Same tool, same API, just different numbers of humans.

Quick Start

1. Start the backend

git clone https://github.com/cass-clearly/remarq.git
cd remarq
echo "POSTGRES_PASSWORD=remarq" > .env
docker compose -f docker-compose.remarq.yml up --build

Backend runs on port 3333. Visit http://localhost:3333 for the demo.

2. Add to any HTML page

<script
  src="http://localhost:3333/feedback-layer.js"
  data-api-url="http://localhost:3333"
  data-content-selector="article"
></script>

One script tag. That's the whole integration. Works on any HTML page — your blog, your docs, your marketing site, your contracts. Not trapped in a proprietary editor.

3. Let your agent close the loop

# Get open feedback
curl "http://localhost:3333/comments?status=open&document=DOC_ID"

# Your agent gets structured annotations with exact text anchors,
# threaded replies, and author context. It knows exactly what to fix.

This is the superpower. Every other annotation tool treats comments as a human-to-human channel. Remarq treats them as an API for your agent to consume.

Why Remarq

Configuration

Configure via data- attributes on the script tag:

Production

Docker Compose (recommended)

Create a .env file next to docker-compose.remarq.yml (docker compose reads it automatically):

POSTGRES_PASSWORD=your-secure-password-here

docker compose -f docker-compose.remarq.yml up --build -d

Direct (bring your own Postgres)

npx @csalvato/remarq-server

Or:

npm install --prefix server
DATABASE_URL=postgres://user:pass@localhost:5432/remarq node server/index.js

OpenAPI Spec

The server exposes a machine-readable OpenAPI 3.0 spec at:

GET /openapi.json

Use it with any OpenAPI tooling — Swagger UI, Redoc, Insomnia, Postman, code generators, or your own AI agent:

curl http://localhost:3333/openapi.json

The spec includes x-cli vendor extensions that drive the CLI — every endpoint appears as a CLI command automatically. New server endpoints added to the spec appear in the CLI with zero CLI code changes.

API Reference

Stripe-inspired resource pattern. All responses include an object field. Full documentation with request/response schemas, error codes, and curl examples: docs/api.md

Documents

Comments

Webhooks

Events: comment.created, comment.resolved, comment.deleted. Payloads are signed with HMAC-SHA256 using the webhook's secret.

Status is a thread-level concept — only root comments have status ("open" or "closed"). Replies always have status: null. The ?status= filter matches root comments and includes all their replies. Query params can be combined (e.g. ?document=<id>&status=open&expand=document).

POST /comments body

{
  "uri": "https://example.com/doc.html",
  "quote": "selected text",
  "prefix": "text before",
  "suffix": "text after",
  "body": "This needs work",
  "author": "Alice",
  "parent": null,
  "color": "red"
}

For replies, set parent to the parent comment's ID. Replies don't need quote/prefix/suffix.

Highlight Colors

Comments support customizable highlight colors. Set color on POST /comments or update it later with PATCH /comments/:id. Colors are validated on both the client and server.

Preset names

You can also pass any 6-digit hex code directly (e.g. "#ff6b6b"). The database enforces a CHECK constraint — values must be a preset name, a valid #rrggbb hex code, or null.

Usage from agents

Agents writing comments via the API can use colors to visually categorize feedback — for example, red for errors, blue for suggestions, green for approvals.

# Create a comment with a preset color
curl -X POST http://localhost:3333/comments \
  -H "Content-Type: application/json" \
  -d '{"uri":"https://example.com/doc.html","quote":"important text","body":"Needs revision","author":"agent","color":"red"}'

# Create a comment with a hex color
curl -X POST http://localhost:3333/comments \
  -H "Content-Type: application/json" \
  -d '{"uri":"https://example.com/doc.html","quote":"looks good","body":"Approved","author":"agent","color":"#51cf66"}'

# Update color on an existing comment
curl -X PATCH http://localhost:3333/comments/cmt_abc123 \
  -H "Content-Type: application/json" \
  -d '{"color":"blue"}'

# Clear color (revert to default)
curl -X PATCH http://localhost:3333/comments/cmt_abc123 \
  -H "Content-Type: application/json" \
  -d '{"color":null}'

If omitted, color defaults to null (the client uses yellow as the default highlight).

Client-side default color

Set a default highlight color for all new comments on a page using the data-default-color attribute on the script tag:

<script
  src="http://localhost:3333/feedback-layer.js"
  data-api-url="http://localhost:3333"
  data-content-selector="article"
  data-default-color="blue"
></script>

Accepts any preset name or hex code. Users can still override the color per-comment using the color picker in the sidebar.

Features

• No accounts — reviewers just type their name
• Text anchoring — annotations are anchored to specific text passages using TextQuoteSelectors (via Apache Annotator), so highlights survive minor edits
• Threaded replies — discuss any annotation
• Resolve/unresolve — mark feedback as addressed
• Keyboard shortcuts — full keyboard navigation for the sidebar
• One script tag — drop-in integration for any HTML page
• Agent-ready API — structured feedback your AI can consume and act on

Documentation

• Best Practices Guide — Deployment configurations, content selector strategies, agent integration patterns, multi-reviewer workflows, and document lifecycle management.

Keyboard Shortcuts

The following keyboard shortcuts are available (they are disabled when focus is in an input field, textarea, or contenteditable element):

Press the ⌨ button in the sidebar header to see shortcuts at any time.

The Bottom Line

Your team's feedback shouldn't rot in a Google Docs sidebar. Build the agent loop. Close the feedback cycle. Ship faster.

git clone https://github.com/cass-clearly/remarq.git
cd remarq
echo "POSTGRES_PASSWORD=remarq" > .env
docker compose -f docker-compose.remarq.yml up --build

Star the repo if you're tired of manually resolving comments.

License

Remarq is dual-licensed:

• Open Source — AGPL-3.0. Free for individuals, self-hosters, and open source use. If you modify Remarq and make it available over a network, you must release your source code.
• Commercial — A separate commercial license is available for organizations that need to keep their code proprietary. See COMMERCIAL.md for details.

Built by cass-clearly