回 kai
A UI annotation tool for developers and AI coding agents.
What is kai?
Click any element on a web page, describe what should change, and export structured feedback as Markdown. kai runs entirely client-side as a single Web Component inside a small Chrome extension, with zero dependencies.
The name 回 (kai) is Japanese for "turn," as in a turn in a cycle. Annotate what needs to change, hand it to your coding agent, and move on to the next iteration.
Features
- Zero dependencies, one self-contained script
- Works on any website via a Chrome extension: one click in the toolbar, no host permissions
- Closed Shadow DOM — fully isolated from host page styles
- Smart element selection with hover highlight, breadcrumb paths, and computed styles (px→rem)
- CSS variable autocomplete — type
-- to browse the page's custom properties
- Measurement mode (Alt): crosshair with dimensions, text metrics, box model (padding, margin, flex/grid gaps), selection rectangle
- Drag to adjust (P M G F L B): drag padding, margin, gap, font size, line height or border radius live on the page; the change lands in the element's annotation
- Interaction mode (I): interact with the page without leaving the annotator
- Shortcut reference (?): see shortcuts for every mode in one panel
- Copy any element's selector with the cursor action bubble
- Markers with automatic clustering for dense annotations
- Session persistence via localStorage — survives reloads
- Export as Markdown (optimized for AI agents)
- Keyboard-first — every interaction reachable without a mouse
Get started
Chrome extension
kai isn't on the Chrome Web Store. Install it locally as an unpacked extension:
- Download
kai-extension.zip from the latest release and unzip it
- Open
chrome://extensions and turn on Developer mode (top right)
- Click Load unpacked and select the unzipped folder
- Pin kai from the puzzle-piece menu so the icon stays in your toolbar
To update, replace the folder's contents with the new release (for example unzip -o kai-extension.zip -d path/to/your/kai-folder) and click the reload icon on kai's card in chrome://extensions. Unzipping by double-click creates a new folder instead, so Chrome would keep loading the old one.
kai can't run on Chrome's own pages (chrome://…) or the Chrome Web Store; clicking the icon there shows a ! badge. For local file:// pages, turn on Allow access to file URLs in kai's details.
From source
bun install
bun run build # writes the unpacked extension to dist/extension/
Then load dist/extension/ as above.
Checks
bun run check # typecheck, build, unit tests, browser checks (what CI runs)
The browser checks drive the built extension bundle with
agent-browser 0.38.1 and its Chrome
(npm i -g [email protected] && agent-browser install), covering keyboard and click
isolation plus hostile pages: strict CSP, Trusted Types and pages that remove kai.
bun run record saves a video of a sample flow to .check-artifacts/recordings/;
bun run record --extension does the same with the unpacked extension loaded in Chrome.
Amp orbs and coding agents
.agents/setup installs development dependencies from bun.lock and makes sure agent-browser
has its Chrome. No secrets, backing services, or resume hook are required. Agent guidance lives
in AGENTS.md (Claude Code reads it through CLAUDE.md), with project skills in
.claude/skills/: verify-kai and release.
How it works
- Activate — click the kai icon in the toolbar (click again to turn it off)
- Select — hover over elements to see selector paths, computed styles, and dimensions
- Annotate — click an element, describe what should change, save
- Repeat — annotate as many elements as needed
- Export — copy as Markdown and paste into your AI coding agent
Measurement mode
Hold Alt to enter measurement mode. A crosshair follows your cursor showing element dimensions. Hold Shift additionally to see text metrics. Hold Ctrl as well to see the box model: padding in the accent color, margin and flex/grid gaps hatched, with values in px and rem. It shows while Ctrl is held. Shift and the box model combine. ↑ / ↓ move whatever you're measuring to the parent or child, and the selection carries across annotating, measuring and the box model as long as you keep the mouse still. The first mouse move after switching goes back to the innermost element. Click and drag to measure arbitrary distances.
Drag to adjust
Hover an element and press a property key: P padding, M margin, G gap
(of the element or its nearest flex/grid container), F font size, L line height,
B border radius. Then press, drag and release anywhere on the page. The side or corner
nearest the pointer changes; hold Alt for it and its opposite side (or both corners on that
side) and Shift for all of them. The page updates live on its identical
siblings too (the items of a list, the cards of a grid), and the HUD shows the new value and the change.
Release adds the change to the element's annotation; a sibling group shares one change, so dragging any
card moves them all. The annotation's popover lists its changes under your note, one per line, each with a
remove button on hover, and the Markdown export adds them as a Changes list.
Esc cancels. Deleting the annotation, or one of its changes, puts the page back.
While a property is armed, ← / → nudge the side under the pointer by one step
and save it right away, and Backspace resets the property on the element and its identical siblings
(an annotation left with neither a note nor changes goes). If the page has
its own scale (Tailwind-style utility classes, or :root variables like --space-4), T
snaps drags and nudges to it and the change names the class: padding-right 24px → 32px pr-8.
Snapping stays on until you press T again.
Every change can be undone with ⌘+Z (Ctrl+Z elsewhere) and
redone with ⇧+⌘+Z: drags, nudges, resets, notes, deletes and
clear all. The HUD says what it undid. In a text field, the shortcut undoes typing as usual.
Interaction mode
While kai is in annotation mode, page clicks and keyboard input are blocked. Press I to
switch to interaction mode: links, inputs, popovers, and dialogs work normally, with no modifier
held. Press I again to annotate what appeared. In a text field, use the
pointer button beside kai instead; typing I or ? does not switch modes or open help.
Press ? (or choose Keyboard shortcuts in settings) for shortcuts in every mode. Escape closes the
shortcut panel. In interaction mode, other shortcuts—including Escape—belong to the page.
The HUD fades out when hovered and never intercepts pointer events, so elements beneath it
remain selectable. Interaction and selector-pick buttons sit together beside the FAB; their
pointer-hand and selector icons use Hugeicons Stroke Rounded, embedded as local SVGs with no runtime dependency.
Selecting a covered parent
When a child fills its parent (a link wrapping a card, a span filling a button), press ↑ while hovering to move the highlight to the parent and ↓ to go back down.
Copy a selector
Click the cursor bubble next to the FAB, then click any element. Its selector lands on the clipboard and the bubble shows a check.
Keyboard shortcuts
Every action has a keyboard path. Annotation shortcuts apply in annotation/inspection/selector
mode with no text field focused; the FAB button tooltips show them too. I and ? also work in
interaction mode outside text fields.
| Shortcut | Context | Action |
|---|
| Ctrl+Shift+A | Any tab | Toggle kai on / off (extension shortcut, change it at chrome://extensions/shortcuts) |
| Esc | Annotation mode | Close help / panel / settings → cancel a drag or disarm → cancel pick mode → deactivate, whichever applies first |
| Esc | Interaction mode | Dismiss the page's topmost overlay |
| S | Active | Toggle copy-selector pick mode |
| C | Active, has annotations | Copy all annotations as Markdown |
| ⌘+Z / ⇧+⌘+Z (Mac), Ctrl+Z / Ctrl+Shift+Z / Ctrl+Y | Annotation mode, outside text fields | Undo / redo the last edit or annotation (drags, nudges, resets, notes, deletes, clear all) |
| P / M / G / F / L / B | Annotation mode, element hovered | Arm padding / margin / gap / font size / line height / border radius; the same key or Esc disarms |
| Drag | Property armed | Adjust the nearest side or corner; release adds it to the annotation |
| Alt / Shift (hold) | Dragging | That side and its opposite / all sides, corners or gaps |
| T | Property armed, page has a scale | Snap to the project's utility classes or scale variables (stays on) |
| ← / → | Property armed | Nudge the side under the pointer one step, saved right away |
| ⌫ / Del | Property armed | Reset the property on the element |
| ⌫ / Del | Active, has annotations, nothing armed | Clear all: first press arms, second press within 3 s confirms |
| , | Active | Toggle settings |
| I | Active, outside text fields | Toggle interaction / annotation mode (also a button beside kai) |
| ? | Active, outside text fields | Toggle shortcut reference for all modes |
| Alt (hold) | Active | Measurement mode |
| Alt+Shift (hold) | Active | Measurement mode with text metrics |
| Alt+Ctrl (hold) | Active |
FAQ
What inspired kai?
agentation.dev — a great annotation tool for AI agents with MCP integration and bidirectional agent communication. But it requires npm install into your project and leans React-first. I wanted something that works on any site. Just a toolbar button you click and use anywhere.
Can I adapt this?
Yes, it's MIT licensed. Fork away.
Bug or feedback?
Open an issue or email hi [at] dominikhofer [dot] me.
Changelog
Changelog
License
MIT
