Content
<p align="center"><img src="docs/logo.svg" width="88" alt="Anriss logo"></p>
<p align="center">
<a href="https://github.com/anriss-dev/anriss/actions/workflows/ci.yml"><img src="https://github.com/anriss-dev/anriss/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
</p>
# 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](https://modelcontextprotocol.io) endpoint;
any MCP-capable coding agent can list open annotations and resolve them
- **Standards-based**: annotations are stored as
[W3C Web Annotation Data Model](https://www.w3.org/TR/annotation-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:
```bash
cargo install --path . # once; installs `anriss` into ~/.cargo/bin
anriss # serves on :4855, SQLite in ./data/annotations.db
```
Or straight from the checkout:
```bash
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!)
```html
<script src="http://localhost:4855/anriss.js" defer></script>
```
Gate it however your stack gates dev-only markup, e.g. Symfony/Twig:
```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:
```json
{
"mcpServers": {
"annotations": { "type": "http", "url": "http://localhost:4855/mcp" }
}
}
```
**Codex** — `~/.codex/config.toml`:
```toml
[mcp_servers.annotations]
url = "http://localhost:4855/mcp"
```
**opencode** — `opencode.json`:
```json
{
"mcp": {
"annotations": { "type": "remote", "url": "http://localhost:4855/mcp" }
}
}
```
Then just ask: *"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`.
## 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
```bash
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](https://f1bonacc1.github.io/process-compose/) boots
the server, waits for `/healthz`, runs the features, and exits with their
result:
```bash
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
