devnotation
v1.2.0
Published
The visual feedback tool for AI coding agents (Claude Code, Cursor, Codex, Grok, Windsurf). Pointing beats describing.
Maintainers
Readme
Devnotation
💡 Why Devnotation?
Communicating UI bugs and design tweaks to an AI coding agent in chat is tedious and error-prone:
"In the sidebar under Bookings, the third action button is misaligned, change its padding to 12px, font to semi-bold, and make the icon 16px."
This approach wastes tokens, creates ambiguity, and forces the model to guess which file, line, and component hierarchy to touch.
Devnotation eliminates the friction:
- Click or drag on any element in your running
localhostapplication. - Devnotation extracts the underlying React Fiber source file and line number, semantic DOM selectors, sibling context, route metadata, and computed design tokens.
- Devnotation bundles your notes into machine-readable punchlists or feeds them directly into your agent via the Two-Way Model Context Protocol (MCP) server on
localhost:4747.
📸 Visual Showcase (Snaps in Action)
1. In-Page Element Inspection & React Fiber Source (_debugSource)
Point to any UI element to lock its exact CSS selector, React component name, and source file:line location without opening browser DevTools.
2. Snapshot Studio Suite (21 Vector & Privacy Annotation Tools)
Capture your screen with GPU acceleration (zero layout distortion) or paste with Ctrl+V. Mark up UI with dimension rulers (176px), privacy blur masks, auto-incrementing badges, and red vector pointers.
3. Feedback Punchlist Drawer & Token Optimization
Review open visual issues in a slide-out drawer, choose from 4 output schemas, and copy structured prompt payloads for Claude Code, Cursor, or Windsurf.
⚡ Flagship Features
1. 🎯 React Fiber _debugSource Code Inspection
Devnotation queries internal React Fiber nodes (fiber._debugSource and fiber._debugOwner) to pinpoint the exact component source file, line number, and column:
Source: src/components/reservation/AddReservationModal.tsx:64:18
Component: <AddReservationModal> -> <DialogBody> -> <Button>Your AI coding agent jumps straight to the exact line in your editor with zero searching or file-tree guesswork.
2. 📸 Full-Featured Snapshot Studio (21 Annotation Tools)
Take screenshots of your app or paste images directly from your clipboard (Ctrl+V) into an interactive annotation canvas equipped with 21 precision tools:
| Category | Tools & Capabilities |
| :--- | :--- |
| Selection & Crop | Pointer (Move/Select), Crop (Resize canvas bounds) |
| Pointers & Vectors | Arrow (Single-head vector), 2-Way Arrow (Bi-directional vector), Line (Straight segment) |
| Measurement | Measure (Dimension lines with live pixel distance readout, e.g. 124px) |
| Shapes | Rectangle (Border or filled), Ellipse (Round containers or badges) |
| Freehand & Mark | Pencil (Smooth freehand curve), Highlighter (Semi-transparent overlay) |
| Text & Dialogue | Text (Multi-line typography), Callout (Speech bubble pointer with text) |
| Badging & Sequence | Numbered Badges (Auto-incrementing step indicators: ①, ②, ③...) |
| Privacy & Security | Pixelate Blur (Scramble PII / API keys), Redact Blackout (Solid mask) |
| Inspection & Zoom | Eyedropper (Sample any screen pixel & copy HEX to clipboard), Magnifier (2x loupe zoom circle) |
| Attention & Review | Spotlight (Darken canvas around a highlighted focal area), Emoji Stamp (Reaction icons), Comment Pin (Marker pin with note) |
- Zero Layout Breakage (Native GPU Capture): Captures your screen cleanly using the browser's native
navigator.mediaDevices.getDisplayMediaAPI. Nohtml2canvasiframe mutations, no responsive layout collapse, and no frozen video streams. - Image Adjustments: Fine-tune brightness, contrast, saturation, invert colors, sepia, grayscale, or apply blur.
- Canvas Zoom & Pan: Zoom
- 67% +,Fit to Screen, and1:1 Pixel Match. - Export Anywhere: Download as PNG/JPEG/WEBP, copy to clipboard, or embed into Devnotation Markdown payloads.
3. 📝 Precision Text Mode (T Text)
- Single-Click Extraction: Click any button, heading, or paragraph to immediately capture its raw text string.
- Drag-to-Select: Highlight exact substrings to flag typos, microcopy revisions, or internationalization keys.
- Visual Hover Outline: Amber focus border (
#f59e0b) confirms the targeted text range before you click.
4. 🧊 Live Animation & Transition Freezer
Click the Pause icon on the toolbar to freeze all running CSS keyframe animations, CSS transitions, and HTML5 video loops on that exact frame. Inspect transient hover states, modal entrances, and timing regressions with zero rush.
5. 📐 Area Box Selector
Drag a bounding box over any arbitrary layout area, multi-column grid, or empty space. Perfect for reporting whitespace defects, missing elements, or structural alignment issues.
6. 📑 4 Agent-Optimized Output Formats
Generate the exact level of detail your workflow requires:
- Compact Mode (
~45 tokens/item): Single-line bulleted punchlist for fast minor edits. - Standard Mode (
~120 tokens/item— Recommended): Component hierarchy, source file:line, user directive, and essential computed styles. - Detailed Mode (
~210 tokens/item): Exact bounding box coordinates (x, y, w, h), parent-child paths, and complete stylesheet dumps. - Forensic YAML (
~340 tokens/item): Machine-structured schema with raw HTML snippets, sibling context, and theme tokens for autonomous multi-agent loops.
7. 🔌 Two-Way Model Context Protocol (MCP) Server
Run the local MCP daemon to connect Devnotation directly to Claude Code, Cursor, or Windsurf:
npx -y devnotation-mcpYour agent reads pending visual feedback annotations directly from http://localhost:4747, implements code changes, and marks issues as resolved autonomously.
8. 🛡️ Bulletproof Stacking Context & Max 32-bit Z-Index (2,147,483,647)
Devnotation renders directly into document.body via React Portals, completely escaping host application stacking contexts (transform, filter, isolation: isolate). Using the browser engine's maximum 32-bit signed integer z-index (2147483647), Devnotation is guaranteed to never be covered by host modals, sweetalerts, sticky headers, or toast notifications.
9. ⏱️ Smart Inactivity Auto-Collapse
When not in use, Devnotation automatically collapses after 10 seconds into a sleek, unobtrusive floating micro-pill ([D]), keeping your screen clutter-free during normal development. Hovering or clicking instantly expands the toolbar. Safe-guards prevent auto-collapse while you are actively annotating or inspecting.
10. ⚙️ Interactive Preferences & Settings Suite
Click the ⚙️ Settings icon on the toolbar to open the multi-tab preferences modal:
- 🎨 Theme & Style: Dark, Light, or System mode; 6 custom brand accent colors (Electric Blue, Royal Violet, Emerald, Amber, Rose, Cyan); UI translucency slider.
- ⚙️ General Options: Configurable idle timeout (5s, 10s, 15s, 30s, 60s), audio feedback cues, default severity tag, and output format.
- 🔌 MCP Server Management: Live port configuration (default
4747), connection test ping, 1-click CLI launch command, and Cursor.cursor/mcp.jsonsnippet generator.
11. 🎨 Ultra-Compact Draggable UI
- 34px Sleek Toolbar: Draggable anywhere on the screen with pointer capture, live MCP sync indicator, and collapse toggle.
- 328px Inspector Popover: Compact, floating inspection card that automatically stays within viewport bounds.
- Custom 5px Rounded Scrollbars: Modern, minimalist scrollbars across all modals and code blocks (
border-radius: 9999px). Zero clunky browser defaults.
🔄 Zero-Touch Auto-Update (Evergreen Mode)
Want Devnotation to always run the latest version automatically without typing npm update or asking your AI agent to update it? Choose any of these 3 zero-maintenance methods:
Option 1: Universal Evergreen CDN (100% Zero-Touch — Recommended)
Add this single script tag to your index.html (works with React, Next.js, Django, FastAPI, Flask, Laravel, Rails, or plain HTML):
<!-- Always runs the latest version from CDN on every page refresh -->
<script src="https://cdn.jsdelivr.net/npm/devnotation/dist/devnotation.standalone.js"></script>Whenever a new version is released, your browser immediately runs the latest code upon refresh with zero terminal commands and zero build steps.
Option 2: React Component Evergreen Mode
If installed via npm, simply pass the evergreen flag:
import { Devnotation } from 'devnotation';
export default function App() {
return (
<>
<MainApp />
<Devnotation evergreen />
</>
);
}Devnotation checks the NPM registry on mount and seamlessly hot-upgrades to the latest release in development.
Option 3: Vite Background Auto-Updater Plugin
Automatically keep your local node_modules on the latest release every time you run npm run dev:
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { devnotation } from 'devnotation/vite';
export default defineConfig({
plugins: [
react(),
devnotation({ autoUpdate: true }) // Silently checks NPM & auto-executes npm/pnpm/yarn/bun update
]
});📦 Installation
Install Devnotation as a development dependency:
# npm
npm install -D devnotation
# pnpm
pnpm add -D devnotation
# yarn
yarn add -D devnotation
# bun
bun add -d devnotation🚀 Quick Start
Next.js (App Router)
Create a client-side wrapper or render conditionally inside app/layout.tsx:
// app/layout.tsx
import type { Metadata } from 'next';
import { Devnotation } from 'devnotation';
import 'devnotation/style.css'; // Optional: bundled styles are included automatically
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
{children}
{process.env.NODE_ENV === 'development' && <Devnotation />}
</body>
</html>
);
}Tip for React Server Components: If your root layout is a Server Component, import Devnotation inside a client component with
'use client'or load it vianext/dynamicwith{ ssr: false }.
'use client';
import dynamic from 'next/dynamic';
export const DevTools = dynamic(
() => import('devnotation').then((mod) => mod.Devnotation),
{ ssr: false }
);Vite + React
Drop <Devnotation /> directly into src/App.tsx:
// src/App.tsx
import { Devnotation } from 'devnotation';
export function App() {
return (
<>
<MainApplication />
{import.meta.env.DEV && <Devnotation />}
</>
);
}Remix
Add Devnotation inside app/root.tsx:
// app/root.tsx
import { Devnotation } from 'devnotation';
export default function App() {
return (
<html lang="en">
<head />
<body>
<Outlet />
{process.env.NODE_ENV === 'development' && <Devnotation />}
</body>
</html>
);
}Python Projects (Django, Flask, FastAPI, Streamlit, FastHTML)
Devnotation is 100% compatible with Python web projects! You can load the self-contained standalone script directly into your HTML templates or Python frontend without needing any npm build step or Node.js runtime:
Django Templates (templates/base.html)
{% if debug %}
<!-- Injects Devnotation toolbar & inspector automatically in development -->
<script src="https://cdn.jsdelivr.net/npm/devnotation@latest/dist/devnotation.standalone.js"></script>
{% endif %}Flask Jinja2 (templates/layout.html)
{% if config['DEBUG'] %}
<script src="https://cdn.jsdelivr.net/npm/devnotation@latest/dist/devnotation.standalone.js"></script>
{% endif %}FastAPI (HTMLResponse / Jinja2Templates)
<script src="https://cdn.jsdelivr.net/npm/devnotation@latest/dist/devnotation.standalone.js"></script>Streamlit Apps (app.py)
import streamlit as st
import streamlit.components.v1 as components
# Embed Devnotation floating toolbar in development mode
components.html(
'<script src="https://cdn.jsdelivr.net/npm/devnotation@latest/dist/devnotation.standalone.js"></script>',
height=0,
width=0,
)FastHTML
from fasthtml.common import *
app, rt = fast_app(
hdrs=[Script(src="https://cdn.jsdelivr.net/npm/devnotation@latest/dist/devnotation.standalone.js")]
)Full-Stack Python (FastAPI / Django + React / Vite / Next.js)
If your Python backend serves a React/Next.js frontend, install the npm package in your frontend folder:
npm install -D devnotationand import <Devnotation /> in your root component.
⌨️ Keyboard Shortcuts
| Shortcut | Action |
| :--- | :--- |
| A / Ctrl+Shift+A | Toggle Annotate Click Mode |
| Ctrl+Enter / Cmd+Enter | Save Active Annotation Note |
| Escape | Dismiss Popover / Cancel Current Selection / Close Modals |
| Ctrl+V | Paste Clipboard Image into Snapshot Studio |
| Delete / Backspace | Delete Selected Canvas Annotation Shape |
| Space + Drag | Pan Snapshot Studio Canvas |
| Ctrl+Z / Ctrl+Shift+Z | Undo / Redo Canvas Annotation Edits |
🤖 MCP (Model Context Protocol) Integration
Devnotation includes first-class support for the Model Context Protocol, enabling zero-copy agent workflows.
1. Start the MCP Server
npx -y devnotation-mcpThis spins up a local server listening on http://localhost:4747.
2. Configure Your AI Coding Agent
Claude Code CLI
Run your task directly:
claude "Read all open visual annotations from the local Devnotation MCP server at localhost:4747. Inspect each component path and CSS selector, implement the design changes in the codebase, and verify the resulting layout."Cursor (.cursor/mcp.json)
{
"mcpServers": {
"devnotation": {
"command": "npx",
"args": ["-y", "devnotation-mcp"]
}
}
}Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"devnotation": {
"command": "npx",
"args": ["-y", "devnotation-mcp"]
}
}
}📑 Output Formats Showcase
Standard Format (Default)
### 1. [HIGH] `button#btn-checkout.bg-emerald-600`
> **Instruction:** Increase button padding from 8px to 14px and add subtle drop shadow.
- **Source File:** `src/components/cart/CheckoutButton.tsx:42:15`
- **React Component:** `<CartDrawer> -> <CheckoutFooter> -> <CheckoutButton>`
- **Page Route:** `/checkout` (URL: `http://localhost:3000/checkout`)
- **Viewport:** `1440x900` (DPR: 2)
- **Full DOM Path:** `body > div#root > aside.cart-drawer > div.footer > button#btn-checkout`
- **Sibling Context:** [before: "Subtotal: $49.00"] [current: "Complete Order"] [after: "Secure 256-bit SSL"]
- **Computed Styles:** `padding: 8px 16px; font-weight: 600; background-color: rgb(5, 150, 105)`Forensic YAML Format
# Forensic Node [1] -> button#btn-checkout.bg-emerald-600
index: 1
id: "ann_1793132002789"
severity: "high"
type: "element"
selector: "button#btn-checkout.bg-emerald-600"
sourceLocation: "src/components/cart/CheckoutButton.tsx:42:15"
componentTree: "<CartDrawer> -> <CheckoutFooter> -> <CheckoutButton>"
fullDomPath: "body > div#root > aside.cart-drawer > div.footer > button#btn-checkout"
environment:
routeUrl: "/checkout"
fullUrl: "http://localhost:3000/checkout"
viewport: "1440x900"
devicePixelRatio: 2
siblingContext:
before: "Subtotal: $49.00"
current: "Complete Order"
after: "Secure 256-bit SSL"
directive: "Increase button padding from 8px to 14px and add subtle drop shadow."
boundingBox:
x: 1040
y: 680
width: 320
height: 48
rawHtmlSnippet: |
<button id="btn-checkout" class="bg-emerald-600 px-4 py-2 font-semibold text-white rounded-lg">Complete Order</button>
computedStyleTokens:
padding: "8px 16px"
font-weight: "600"
background-color: "rgb(5, 150, 105)"📊 Feature Comparison
| Feature | Devnotation | Agentation | Traditional Screenshot | Browser DevTools |
| :--- | :---: | :---: | :---: | :---: |
| React Fiber _debugSource (File:Line:Col) | ✅ Native | ✅ | ❌ | ❌ |
| Snapshot Studio Suite | ✅ 21 Tools | ❌ (Basic) | ❌ | ❌ |
| Native GPU Screen Capture | ✅ (Zero DOM mutation) | ❌ (html2canvas) | Manual OS | ❌ |
| Instant Clipboard Paste (Ctrl+V) | ✅ | ❌ | ❌ | ❌ |
| Two-Way MCP Server Sync (:4747) | ✅ Native | Partial | ❌ | ❌ |
| Live Animation Freezer | ✅ | ❌ | ❌ | Complex pause |
| Single-Click Text Extraction | ✅ | ❌ | ❌ | Manual copy |
| Area / Multi-Component Box Selection | ✅ | ❌ | ❌ | ❌ |
| 4 Agent Output Formats | ✅ (Compact to YAML) | Standard only | Unstructured | Raw styles |
| Draggable UI & Compact Cards | ✅ (34px Toolbar / 328px Card) | Fixed | N/A | Full pane |
| Bundle Footprint | ~36 kB gzipped | ~80 kB | N/A | Built-in |
🛠 Local Development & Showcase
To run the Devnotation showcase and development playground locally:
git clone https://github.com/cmtimran/Devnotation.git
cd Devnotation
npm install
npm run devTo build both the showcase application and the standalone npm library bundle:
npm run build