Anriss

Click elements on your running web app, leave a comment, and let your AI coding agent fix it. A tiny self-hosted feedback loop for UI work — no React, no browser extension, no SaaS.

Anriss — from German anreißen: marking out a workpiece before machining. And Riss is the plan itself (Grundriss, Aufriss). Mark it. Plan it. Fix it.

you (browser)                 anriss                  your AI agent
──────────────                ─────────────                 ─────────────
click elements   ──POST──▶    Rust + SQLite    ◀──MCP──     Claude Code /
+ one comment                 W3C annotations               Codex / opencode
                                                            fixes code,
                                                            marks resolved

• One script tag to integrate — works with any frontend (plain HTML, Stimulus/Turbo, Vue, React, server-rendered, anything)
• Multi-select: click several elements, leave one comment for all of them
• Agent-native: built-in MCP endpoint; any MCP-capable coding agent can list open annotations and resolve them
• Standards-based: annotations are stored as W3C Web Annotation Data Model JSON (CSS selector + XPath + HTML snippet per target)
• Self-contained: single Rust binary with the widget embedded; SQLite file as the only state

⚠️ Development tool. CORS is wide open by design and there is no authentication. Run it on localhost or inside your dev network only.

Quick start

It's a single process — just run the binary:

cargo install --path .        # once; installs `anriss` into ~/.cargo/bin
anriss                  # serves on :4855, SQLite in ./data/annotations.db

Or straight from the checkout:

cargo run --release

Open http://localhost:4855/ — the built-in demo page runs the widget, so you can try the whole loop before touching your own app.

Building from a fresh clone only needs Rust; the widget bundle (dist/anriss.js) is committed. Rebuild it after widget changes with npm install && npm run build.

A Dockerfile is included if you prefer a container: docker build -t anriss . && docker run -p 4855:4855 -v "$PWD/data:/data" anriss

Add the widget to your app (dev only!)

<script src="http://localhost:4855/anriss.js" defer></script>

Gate it however your stack gates dev-only markup, e.g. Symfony/Twig:

{% if app.debug %}<script src="http://localhost:4855/anriss.js" defer></script>{% endif %}

Annotate

1. Click the Annotate pill (bottom-left) or press Alt+Shift+A
2. Click one or more elements — click again to deselect
3. Press Enter or click Comment, write what should change, save

Connect your agent (MCP)

Claude Code — .mcp.json in your project:

{
  "mcpServers": {
    "annotations": { "type": "http", "url": "http://localhost:4855/mcp" }
  }
}

Codex — ~/.codex/config.toml:

[mcp_servers.annotations]
url = "http://localhost:4855/mcp"

opencode — opencode.json:

{
  "mcp": {
    "annotations": { "type": "remote", "url": "http://localhost:4855/mcp" }
  }
}

Hand it to your agent — on demand

The loop is pull-based, not a blocking gate: annotate as much as you like, then whenever you're ready say

"Work through the open UI annotations."

The agent calls list_open_annotations, locates each element via the stored selectors and HTML snippets, fixes the code, and calls resolve_annotation. Resolutions show up live in the widget. Keep annotating and re-run the same prompt any time — each call re-polls, so nothing is lost and nothing blocks your agent while you work. (A handy Claude Code slash command: put that one line in .claude/commands/anriss.md.)

Lifecycle & live updates

open  ──agent resolves (MCP/REST)──▶  done  ──you tick ✓ in the widget──▶  archived

• The widget polls the server every 3 s (paused while the tab is hidden), so agent resolutions appear live in the pill's list panel — resolution note included — without a reload. A red dot on the pill means the server is unreachable.
• Resolve never deletes. Archiving is deliberately human-only (no MCP tool for it): you review the fix, then tick it away.
• The panel's Copy JSON button copies all open annotations — the manual fallback when you want to paste them into any agent directly.

REST API

Method	Path	Description
GET	/anriss.js	The drop-in widget
POST	/api/annotations	Create an annotation (the widget calls this)
GET	/api/annotations?status=open|done	List annotations
POST	/api/annotations/{id}/resolve	Mark resolved: {"resolution": "..."}
GET	/healthz	Health check

Annotations are W3C Web Annotations with ext:* extension fields for status/resolution. Comments may reference their targets as [#n] — n is the 1-based index into the annotation's target[] array (the widget's numbered chips/badges use the same numbering). Each target carries a CssSelector, an XPathSelector and a truncated HTML snippet, so agents (and future UI pins) can re-anchor even after the DOM changed.

Configuration

Env var	Default
ANRISS_PORT	4855	HTTP port
ANRISS_DB	./data/annotations.db	SQLite path

Widget: <script ... data-hotkey="ctrl+shift+e"> overrides the hotkey.

Development

npm run build   # compile Tailwind subset + inline into dist/anriss.js
cargo test      # server tests
cargo clippy

End-to-end tests are Cucumber features driven by Playwright (plain ESM steps — no compile step). They exercise the real widget through the pages the binary serves. process-compose boots the server, waits for /healthz, runs the features, and exits with their result:

cargo build --release
cd e2e && npm install && npx playwright install chromium && cd ..
process-compose --tui=false up        # server + Cucumber, one command

Or run the features against an already-running server: cd e2e && npm test. The same process-compose up is what CI runs.

Queries are compile-time checked (sqlx). After changing SQL or migrations: DATABASE_URL=sqlite://.sqlx-dev.db cargo sqlx migrate run && cargo sqlx prepare (the .sqlx/ offline cache is committed, so plain cargo build needs no DB).

dist/anriss.js is committed so the crate builds without Node. The widget UI lives in a Shadow DOM and its Tailwind classes are compiled with important — host-page styles can't break it, and it can't leak out.

Marketing page

docs/index.html is both the landing page and the local demo/test bed:

• Served by the binary at / (embedded at compile time) — there the widget is live and annotations work end to end.
• Publishable via GitHub Pages: repo Settings → Pages → Build and deployment → Source "Deploy from a branch" → branch main, folder /docs. On Pages the widget script simply 404s (no server) — the page itself works.

License

MIT