Screenshot Annotation & Split-View Markdown Note-Taking for Developers & Technical Writers
Ultra-fast, zero-friction canvas annotations with synchronized sequential numbered badges, rich markdown notes, and 1:1 pixel-perfect composite clipboard export.
Important
Anot8 is an independent, personal open-source project created and maintained by Prashanth Subrahmanyam. It is not an official Google project or product, and is not supported, certified, or endorsed by Google LLC in any capacity. This software is provided strictly on an 'AS IS' BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. Use at your own risk.
- Overview & Vision
- Key Features
- System Architecture
- Comprehensive Keyboard Shortcuts
- Install as an App
- Agent Usage (CLI, MCP, Browser)
- Getting Started & Local Development
- Testing & Quality Assurance
- Production Deployment
- Contributing
- License
Developers, technical writers, support engineers, and product teams constantly capture screenshots to document bugs, write architectural runbooks, and explain UI workflows. Existing tools are either bloated desktop apps, cloud platforms requiring accounts and uploads, or basic screenshot utilities that lack structured note synchronization.
Anot8 is built to solve this with a single high-efficiency web tool:
-
Paste screenshot (
Cmd+V/Ctrl+V). -
Draw vector callouts (Boxes, Circles, Arrows, numbered Pins) that automatically receive sequential
$1..N$ badges. - Write structured markdown notes in the synchronized split-view sidebar.
-
Copy 1:1 pixel-perfect composite image (
Cmd+C/Ctrl+C) or copy structured markdown list (Cmd+Shift+C) directly to your clipboard for instant pasting into GitHub issues, Jira tickets, PR descriptions, or Slack. - 100% Client-Side Privacy: All processing occurs locally in the browser with zero server egress or external dependencies.
- System Clipboard Paste: Global listener captures pasted images (
Cmd+V/Ctrl+V) instantly decoding raw image blobs into natural-resolution bitmaps. - Drag-and-Drop & File Picker: Drop PNG, JPEG, or WebP files anywhere onto the canvas or click to select from your file manager.
- Bounding Boxes: Highlight UI regions with custom stroke widths and adjustable background fill opacity.
- Ellipses / Circles: Circle focal elements with corner or center-anchored geometry.
- Directional Arrows: Point to specific controls with 30° arrowhead wings and tail-anchored numbered badges.
- Numbered Callout Pins: Place compact numbered badge pins directly over UI targets.
- High-Contrast Palette: 5 calibrated color presets (Red, Amber, Green, Cyan, Purple) designed for maximum visibility over light and dark screenshots. Specs can also use any hex color; badge text picks black or white for contrast.
- Spotlight & Redaction: Highlight dims everything outside the selected regions, and Blur bakes an unrecoverable Gaussian blur into the export. Neither takes a number badge.
- Text Labels & Frames (spec only): Free-standing text callouts, plus crop and padding with a background color applied at export.
- Interactive Transform Handles: 8-point bounding box resize handles and drag-to-move capabilities in native image space.
- Every annotation automatically receives a continuous sequential number badge (
$1, 2, 3 \dots N$ ). - Deleting or reordering any annotation instantly renumbers all remaining annotations across both canvas SVG badges and sidebar note cards with zero index gaps.
- Bidirectional Hover & Focus: Hovering or selecting a note card in the sidebar illuminates the corresponding canvas badge and shape with a halo glow effect, and vice-versa.
- Inline Markdown Editor: Write rich markdown notes per badge with live syntax rendering, bold (
Cmd+B), italic (Cmd+I), code blocks, and keyboard shortcuts (Cmd+Enterto commit). - Drag & Reorder: Reorder notes via intuitive controls to dynamically re-index sequential callouts across your entire workflow.
- Offscreen Canvas 2D Rasterizer: Asynchronously composites the original unscaled image bitmap at 100% native resolution with crisp vector overlays, anti-aliased geometry, and drop-shadowed badges.
- Async Clipboard Copy:
Cmd+C/Ctrl+C: Writes composite PNG binary blob directly to system clipboard.Cmd+Shift+C: Copies structured markdown list/table of numbered notes to system clipboard.
- File Downloads: Direct one-click download for high-resolution PNG files and
.mddocumentation files.
- Dark / Light Theme: Semantic styling tokens with automatic system theme detection and local storage persistence.
- Focal-Point Zoom & Pan: Smooth wheel/pinch zoom centered on cursor focal point, spacebar-drag panning, and middle-click pan.
- 50-Step Undo / Redo: Complete immutable state history stack with pointer-up transaction batching.
- Zero Network Egress: Once loaded, operates completely offline with full client-side execution.
- Anot8 spec: A JSON document format (
.anot8.json) that describes the image, frame, and annotations, with percentage coordinates and live anchors such as"@submit.right". - Headless rendering: The same Canvas2D exporter runs in Node via
@napi-rs/canvas, so the CLI and MCP server produce the exact same PNG as the Export button. - MCP Server + Agent Skill: Stdio MCP server (
anot8_schema,anot8_inspect_image,anot8_init_spec,anot8_validate,anot8_apply_ops,anot8_render,anot8_markdown,anot8_share_url, plus resources and prompts) paired withskills/anot8/SKILL.mdfor closed-loop visual self-check. - Local only: A CLI, a stdio MCP server, an agent skill, and a
window.anot8browser bridge. Nothing is hosted. See Agent Usage. - Round trip with people: Save the current canvas as a spec, share a
#spec=<base64url>link, or drop/paste a spec onto the app to load it.
Anot8 is structured around a 5-Layer Hybrid Architecture that cleanly separates interactive viewport rendering from high-resolution export rasterization:
┌─────────────────────────────────────────────────────────────────────────────┐
│ Anot8 Application │
├─────────────────────────────────────────────────────────────────────────────┤
│ Layer 1: Interactive Viewport Layer │
│ ┌───────────────────────────────┐ ┌───────────────────────────────────┐ │
│ │ Base Image Canvas / Layer │ │ Interactive SVG Overlay │ │
│ │ - Native Aspect Ratio │ │ - Vector Shapes & Halos │ │
│ │ - CSS Hardware Zoom / Pan │ │ - 1..N Numbered Visual Badges │ │
│ │ - Viewport Coordinate Space │ │ - 8-Point Transform Handles │ │
│ └───────────────────────────────┘ └───────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────────┤
│ Layer 2: State & Invariant Management Engine │
│ ┌───────────────────────────────┐ ┌───────────────────────────────────┐ │
│ │ Coordinate Transformer │ │ App Reducer & History │ │
│ │ - Screen <-> Image Math │ │ - 1..N Re-indexing Invariant │ │
│ │ - Natural Dimension Bounds │ │ - 50-Level Undo/Redo Stack │ │
│ └───────────────────────────────┘ └───────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────────┤
│ Layer 3: Synchronized Split-View Notes Engine │
│ ┌───────────────────────────────┐ ┌───────────────────────────────────┐ │
│ │ Notes Sidebar Panel │ │ Inline Markdown Editor │ │
│ │ - Ordered Annotation Cards │ │ - Syntax Highlighting │ │
│ │ - Bidirectional Hover Sync │ │ - Live Markdown Preview │ │
│ └───────────────────────────────┘ └───────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────────┤
│ Layer 4: 1:1 Native Resolution Export Engine │
│ ┌───────────────────────────────┐ ┌───────────────────────────────────┐ │
│ │ Offscreen Canvas 2D Engine │ │ Async Clipboard & Exporters │ │
│ │ - Unscaled Native Bitmaps │ │ - image/png Binary Blobs │ │
│ │ - Crisp Vector Rasterizer │ │ - text/plain Markdown Lists │ │
│ └───────────────────────────────┘ └───────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────────────────┤
│ Layer 5: Modern UI & Theming System │
│ ┌───────────────────────────────┐ ┌───────────────────────────────────┐ │
│ │ Dark / Light Theme Provider │ │ Keyboard Shortcuts Modal │ │
│ │ - Tailwind Semantic Tokens │ │ - Interactive Help Cheat-Sheet│ │
│ └───────────────────────────────┘ └───────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
The reducer, geometry math, markdown serializer, and Canvas2D exporter form a portable core with no React or DOM dependencies (enforced by ESLint). The exporter takes an injectable RenderBackend: the browser one in the app, @napi-rs/canvas in Node. On top of that core:
| Module | Role |
|---|---|
src/spec/ |
Zod schema for the Anot8 spec, compileSpec (percentages and anchors → annotations), toSpec, and edit applyOps |
src/core/node/ |
Node render backend (@napi-rs/canvas), SSRF/bounds guards, buildStarterSpec, and renderSpec (PNG + markdown + bounds) |
cli/ |
The anot8 CLI and the stdio MCP server (8 tools, 3 resources, 2 prompts), bundled by tsup to dist-cli/ |
src/bridge/ |
window.anot8 session, #spec= links, and spec drop/paste in the app |
skills/ |
Cross-harness agent skills (npx skills layout); .claude/skills/ and .agents/skills/ symlink here |
| Category | Action | Mac Shortcut | Windows / Linux Shortcut | Description |
|---|---|---|---|---|
| Tools | Select & Transform | V | V | Select, move, and resize annotations on canvas |
| Tools | Bounding Box | B or R | B or R | Draw rectangular bounding box with stroke & fill |
| Tools | Ellipse / Circle | C or O | C or O | Draw circular or oval vector annotation |
| Tools | Directional Arrow | A | A | Draw vector pointer arrow with 30° wings |
| Tools | Numbered Callout Pin | P | P | Place auto-incrementing sequential pinpoint badge |
| Tools | Pan Tool | H | H | Activate viewport hand/pan tool |
| Tools | Quick Pan | Space + Drag | Space + Drag | Hold spacebar and drag anywhere to pan |
| Canvas | Zoom In | + | + | Enlarge canvas view centered on viewport |
| Canvas | Zoom Out | - | - | Reduce canvas view scale |
| Canvas | Focal Zoom | Scroll / Pinch | Scroll / Pinch | Smooth zoom centered at cursor position |
| Canvas | Fit to Screen | 0 | 0 | Fit screenshot to viewport with comfortable padding |
| Canvas | Actual Size (100%) | 1 | 1 | Reset zoom to native 1:1 unscaled pixel resolution |
| Canvas | Middle Click Pan | Middle Click + Drag | Middle Click + Drag | Drag viewport using middle mouse button |
| History | Undo | ⌘ + Z | Ctrl + Z | Revert last annotation stroke or transformation |
| History | Redo | ⌘ + ⇧ + Z | Ctrl + Y / Ctrl + ⇧ + Z | Replay previously undone action |
| History | Delete Selected | ⌫ / Delete | Backspace / Delete | Delete selected annotation and re-index badges (1..N) |
| History | Deselect / Cancel | Esc | Esc | Clear active selection or cancel drawing |
| Sidebar | Bold Note | ⌘ + B | Ctrl + B | Format selected note text with bold (**text**) |
| Sidebar | Italic Note | ⌘ + I | Ctrl + I | Format selected note text with italics (*text*) |
| Sidebar | Indent / Outdent | Tab / ⇧+Tab | Tab / ⇧+Tab | Insert or remove 2-space indentation |
| Sidebar | Commit Note | ⌘ + ↵ | Ctrl + ↵ | Save and blur markdown note editor |
| Sidebar | Reorder Notes | ⌥ + ↑/↓ | Alt + ↑/↓ | Move cards up/down to re-index all badges 1..N |
| Export | Copy Composite Image | ⌘ + C | Ctrl + C | Render 1:1 pixel-perfect PNG and copy to clipboard |
| Export | Copy Markdown Notes | ⌘ + ⇧ + C | Ctrl + ⇧ + C | Serialize numbered notes list as markdown to clipboard |
| Export | Paste Screenshot | ⌘ + V | Ctrl + V | Ingest screenshot directly from clipboard |
| General | Shortcuts Cheat-Sheet | ? | ? | Open interactive keyboard shortcuts modal |
| General | Close Modal | Esc | Esc | Dismiss any open modal dialog or overlay |
Anot8 is a Progressive Web App. Installing it gives it its own window, a taskbar/Dock icon, and offline launch. Everything still runs locally in your browser engine.
| Platform | How to install |
|---|---|
| Chrome / Edge (Windows, macOS, Linux) | Click the install icon at the right of the address bar, or open the browser menu and choose Install Anot8. Then pin it to the taskbar or keep it in the Dock. |
| Safari (macOS Sonoma or later) | File → Add to Dock. |
| Safari (iOS / iPadOS) | Share → Add to Home Screen. |
When a new version is deployed, the app shows an Update available toast. The update only applies when you click Reload, so in-progress annotations are never discarded by surprise.
App icons are generated from public/logo.svg and scripts/logo-maskable.svg with npm run generate-pwa-assets.
AI agents and scripts can use Anot8 as a parametric editor. They describe annotations as a JSON spec, render it headlessly, inspect the returned preview and pixel bounding boxes, and adjust with edit ops. Everything runs locally: a CLI and stdio MCP server published to npm as @ksprashu/anot8, an agent skill in skills/anot8/SKILL.md, and a window.anot8 bridge in the app.
No clone needed. Install the skill into whichever agents you use (Claude Code, Gemini CLI, Codex, Cursor, Copilot, and others):
npx skills add ksprashu/anot8 # pick agents interactively; add -g for all projectsThen ask your agent to annotate or redact a screenshot. The skill runs the engine with npx -y @ksprashu/anot8 (Node.js 20+), so there is nothing else to install. For tools that return the rendered PNG straight into the agent's context, also register the MCP server:
claude mcp add -s user anot8 -- npx -y @ksprashu/anot8 mcp # Claude Code
gemini mcp add -s user anot8 npx -y @ksprashu/anot8 mcp # Gemini CLI
codex mcp add anot8 -- npx -y @ksprashu/anot8 mcp # Codex CLIAny other MCP client: { "mcpServers": { "anot8": { "command": "npx", "args": ["-y", "@ksprashu/anot8", "mcp"] } } }.
To move between agent and browser, anot8 share spec.json prints a link that opens the spec in the web app, and dropping a .anot8.json file onto the app loads it.
{
"version": 1,
"image": { "source": "shot.png" },
"annotations": [
{ "id": "submit", "type": "box", "x": "30%", "y": 326, "width": 148, "height": 52, "color": "#22C55E", "note": "Primary action" },
{ "type": "text", "at": { "anchor": "@submit.right", "dx": 24 }, "text": "Make this full width" },
{ "type": "blur", "x": 550, "y": 392, "width": 190, "height": 32 }
]
}npm install -g @ksprashu/anot8 # or prefix each command with npx -y
anot8 inspect shot.png
anot8 init shot.png -o shot.anot8.json
anot8 render shot.anot8.json -o out.png --md notes.md --format report
anot8 markdown shot.anot8.json --format checklist -o tasks.md
anot8 apply shot.anot8.json --ops '[{"op":"update","id":"submit","set":{"x":300}}]' --in-place
anot8 share shot.anot8.json| MCP Capability | Name | Description |
|---|---|---|
| Tool | anot8_schema |
Usage guide plus JSON Schemas for DocumentSpec (v1) and SpecOp[] |
| Tool | anot8_inspect_image |
Returns natural { width, height } of an image path, URL, or data URL |
| Tool | anot8_init_spec |
Creates a validated starter .anot8.json spec with image dimensions populated |
| Tool | anot8_validate |
Validates a spec and returns path-addressed issues or compiled annotation bounds |
| Tool | anot8_apply_ops |
Applies add, update, delete, reorder, clear, setFrame while keeping @id anchors live |
| Tool | anot8_render |
Renders composite PNG + Markdown and returns a visual preview image + pixel bounds |
| Tool | anot8_markdown |
Serializes numbered notes into list, table, checklist, or report Markdown |
| Tool | anot8_share_url |
Encodes a spec into a #spec=<base64url> link for opening in the browser editor |
| Resource | anot8://guide, anot8://schema/spec, anot8://schema/ops |
Guide and JSON Schemas exposed as MCP resources |
| Prompt | annotate-screenshot, redact-screenshot |
Guided prompts for closed-loop visual callouts and privacy redaction |
See docs/agent-usage.md and sk 8BD0 ills/anot8/SKILL.md for the full spec reference (anchors, percentages, hex colors, text labels, crop and padding), edit ops, MCP server, and browser bridge.
- Node.js:
v20or higher - npm:
v9.0.0or higher
-
Clone the repository:
git clone https://github.com/ksprashu/anot8.git cd anot8 -
Install dependencies:
npm install
-
Start local development server:
npm run dev
Open
http://localhost:5173to explore Anot8 with instant Vite Hot Module Replacement. -
Production build:
npm run build
Compiles TypeScript and bundles production assets into
dist/. -
Preview production build locally:
npm run preview
Anot8 has an automated test matrix covering unit math, React components, integration pipelines, 4-tier opaque-box E2E scenarios, and headless agent surfaces. Vitest runs two projects: dom (jsdom, everything under tests/ except tests/node/) and node (golden image renders, CLI, and MCP server over stdio).
# Run the complete test suite (84 files, 1502 tests)
npm test
# Run only the headless spec, CLI, and MCP tests
npx vitest run --project node
# Regenerate golden images after an intentional rendering change
UPDATE_GOLDEN=1 npx vitest run --project node
# Run the master E2E feature suite
npm run test:e2e
# Run tests in interactive watch mode
npm run test:watch
# Run tests with code coverage analysis
npm run test:coverage
# Run TypeScript strict type verification
npm run typecheck
# Run ESLint validation
npm run lint
# Build the CLI and MCP server into dist-cli/
npm run build:cliAnot8 is a fully static, client-side app: once loaded, all image processing, annotation, and export runs in the browser with no backend.
It is deployed to GitHub Pages by .github/workflows/deploy-pages.yml on every push to main. The workflow typechecks, builds, runs the test suite, and publishes dist/. The site is served at the custom domain configured in the repository's Pages settings.
To preview a production build locally:
npm run build
npm run previewContributions, bug reports, and suggestions are welcome! Please review our Contributing Guide for details on development standards, testing requirements, and pull request workflows.
Please note that this is a personal open-source project maintained on a best-effort basis without official support or SLA guarantees.
Anot8 is open-source software licensed under the Apache License, Version 2.0.
Copyright 2026 Prashanth Subrahmanyam
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.