Quick start
Three steps, about a minute. No binary to download, no daemon to run.
-
Install the Chrome extension
Add HAVI from the Chrome Web Store — search "HAVI" or use the Add to Chrome button. Sign in with a magic link; the free tier needs no card.
-
Connect your agent
Wire HAVI into Claude Code or Codex — see Connect your agent for the exact commands. Claude Code installs the plugin and authenticates in the browser; Codex uses a one-time setup code.
-
Capture context
Open your app, press
⌘⇧S, and annotate. The screenshot, selector, URL, viewport, and console errors are captured in one annotation.
Connect your agent
HAVI works with any MCP-compatible agent. Pick your tool below — the commands are the same ones the guided setup runs.
/plugin marketplace add
handgemacht-ai/handgemacht-marketplace
/plugin install havi@handgemacht
/mcp
claude mcp add
--transport http
havi https://havi.handgemacht.ai/api/mcp
/mcp
codex plugin marketplace add
handgemacht-ai/handgemacht-marketplace
codex plugin add havi@handgemacht
codex havi-setup
https://havi.handgemacht.ai/api/mcp
HV-XXXX
How HAVI works
HAVI is fully hosted. Connecting your agent wires the hosted MCP server at /api/mcp into your AI coding tool. Claude Code installs the HAVI plugin and authenticates in the browser via OAuth; Codex exchanges a one-time setup code for a bearer token.
After that, every annotation you capture is pulled into your session over MCP when you triage. No copy-paste, no tab-switching.
Slash commands
Once your agent is connected, HAVI adds four slash commands you run from the / menu. Each is a prompt the server hands your agent to run with the HAVI MCP tools.
Reviews the open annotations for your current git worktree and proposes a fix for each, citing the file and line. It scopes to your own worktree so parallel sessions stay isolated, pulls in each screenshot, and stops before resolving so you confirm the plan first. Arguments: worktree or branch to scope explicitly, with worktree taking precedence; omit both and your agent detects your git context.
Summarizes every open annotation across the whole workspace, grouped by domain and by severity, into a prioritized list of what to fix first. Read-only — it fixes and resolves nothing. Arguments: none.
Fixes one annotation and marks it resolved: your agent recalls what it was about, makes the fix in your code, records the current commit, and writes the resolution back. Arguments: id (required), the annotation to resolve; note (optional), a short note used verbatim when you supply one.
Wires your project context — project, branch, commit, worktree, and dev-server port — into the page so every capture carries it. Your agent detects your framework (Next.js, Vite, or Phoenix) and writes the setup. Arguments: framework (optional), one of nextjs, vite, or phoenix; omit it and your agent detects it from your config files.
What HAVI captures
Every annotation carries the full context, generated automatically the moment you capture.
An image of the full page or your selected region.
The exact element you clicked or highlighted, as a stable selector.
The full URL at the moment of capture, including query and hash.
Width × height and DPR, so the agent knows the breakpoint.
JS errors logged to the browser console at capture time.
XHR / fetch failures with status codes and URLs.
Supported AI coding tools
HAVI works with any MCP-compatible agent. Currently tested and supported:
Data & privacy
All annotations are stored EU-hosted by Handgemacht AI FlexCo in Graz, Austria, and follow the W3C Web Annotation standard.
Your data is yours. Export or delete everything at any time from your account settings, or query it through the API. No lock-in by design. See our Privacy Policy for full details.
API reference
Every annotation is reachable over a hosted REST API and the MCP endpoint. The full, always-current contract is the generated OpenAPI spec.
GET /api/open_api OpenAPI spec/api/annotations
Create an annotation. Send multipart/form-data: a JSON part carrying the W3C annotation envelope plus a PNG screenshot part. HAVI stamps creator attribution and persists the full envelope.
/api/mcp
JSON-RPC MCP endpoint. Your agent calls this to list, read, and resolve annotations. The workspace id is a required tool argument.
Every request needs Authorization: Bearer <token> and an explicit workspace id (x-havi-workspace-id) — there is no silent personal-workspace fallback. Read endpoints return the JSON:API envelope described by the OpenAPI spec above.
Troubleshooting
Common issues and how to clear them.
Extension not detected. Reload the page after installing, and make sure you are signed in — the badge on the HAVI connect page turns green once the extension is live.
Agent can't see your annotations. Re-run the connect step for your tool and confirm the MCP server shows as connected. In Claude Code, run /mcp and check that havi is authenticated.
Setup code expired. Codex setup codes are valid for 10 minutes. Grab a fresh one from the connect page and re-run codex havi-setup.
Capture shortcut does nothing. Another extension may own ⌘⇧S. Open the HAVI side panel and trigger the capture from there instead.