breschio/drawbridge: Browser Annotations to AI Code Prompts

Developers iterating on frontend code face a persistent friction: the gap between seeing a visual bug in the browser and communicating that observation to an AI coding assistant. Screenshots pasted into chat windows lose selector context. Descriptions of layout issues rely on imprecise language. The loop of observe → describe → prompt → verify consumes cycles that compound across every UI adjustment.

breschio/drawbridge addresses this directly. It is a Chrome extension that lets you click on running applications, leave Figma-style comments, capture screenshots with full DOM context, and convert those annotations into local task files that Claude Code, Cursor, Codex, and Windsurf can read and act upon. With 956 GitHub stars and active development through June 2026, it represents a focused attempt to tighten the browser-to-code feedback loop for AI-assisted development.

What is breschio/drawbridge?

breschio/drawbridge is an open-source Chrome extension maintained by breschio, distributed under a custom license that permits free use, copying, and modification for lawful purposes while restricting redistribution, sublicensing, and commercial service offerings without separate commercial licensing. The project is built primarily in JavaScript^{↗ Bright Coding Blog} and has accumulated 80 forks, suggesting modest but engaged community interest.

The tool occupies a specific niche: visual annotation infrastructure for AI coding workflows. Rather than competing with design tools like Figma or prototyping platforms, Drawbridge operates at the intersection of browser inspection and AI prompt engineering. It treats UI observations as structured data—selector paths, bounding boxes, screenshots, and human notes—that can be consumed programmatically by coding agents.

This matters because AI coding assistants are increasingly operating in agentic modes, where they read files, execute commands, and iterate autonomously. For these systems to fix visual bugs effectively, they need more than vague descriptions. They need precise, reproducible context. Drawbridge generates that context at the point of observation—the browser viewport—and formats it for machine consumption.

The project's recency (last commit June 2026) and its explicit support for multiple AI tools—Cursor, Claude Code, Codex, and Windsurf—indicate it is designed for the current generation of AI-assisted development rather than legacy tooling.

Key Features

Element-Aware Annotation: Drawbridge captures selector data, element context, and bounding boxes with each comment. When you click a UI element to leave a note, the extension records what you clicked, not just where you clicked.

Freeform Rectangle Drawing: For layout, spacing, and visual bugs that span multiple elements or lack a single DOM anchor, Drawbridge supports rectangle annotations decoupled from specific nodes. Press R or select Tools → Rectangle, drag over an area, and attach a note.

Screenshot Capture: Each annotation includes a screenshot, stored in .moat/screenshots/ within the connected project. This creates visual audit trails that complement textual task descriptions.

Structured Task Output: Annotations sync to two file formats: .moat/moat-tasks.md for human readability and .moat/moat-tasks-detail.json for AI processing. This dual-format approach serves both manual review and automated consumption.

Status Tracking: Tasks move through to do, doing, and done states, visible in the drawer and reflected in generated files. The collapsed drawer shows color-coded counts for each status.

AI Tool Integration: Drawbridge deploys workflow files for supported tools—.claude/commands/bridge.md, .windsurf/workflows/bridge.md, and .codex/prompts/bridge.md—plus a general .moat/drawbridge-workflow.md for agent instructions. Running /bridge or bridge in the AI tool triggers task processing.

Resilient Injection: After extension reloads, the toolbar icon can inject missing scripts into existing tabs and toggles the existing drawer rather than creating duplicates. This addresses a common pain point in extension development where state becomes inconsistent across browser sessions.

Flexible Docking: The drawer docks to bottom, left, or right viewport edges and collapses to a slim rail showing project button, tools button, and status counts.

Use Cases

Frontend Bug Triage: A developer notices misaligned padding in a staging environment. Instead of switching to Slack or a ticket system, they press C, click the offending element, note "reduce gap to 8px per design system," and continue. The annotation includes the exact selector and screenshot. Later, running /bridge in Claude Code surfaces the task with full context.

Design QA Passes: Before deployment, a team member systematically reviews UI against mockups. Rectangle annotations mark areas where implementation diverges from design intent—without requiring DOM precision. The batch is processed via batch bridge mode for grouped fixes.

Autonomous Agent Workflows: For teams using yolo bridge mode, Drawbridge enables fully autonomous iteration. Annotations accumulate during human review; the AI agent processes all pending tasks without per-step approval. This suits mature codebases where the cost of human intervention exceeds the risk of autonomous changes.

Cross-Tool Portability: Teams evaluating or switching between AI assistants benefit from Drawbridge's multi-tool support. The same annotation set feeds Claude Code, Cursor, Codex, or Windsurf without reformatting or duplicate entry.

Local File Development: With file:// URL support enabled, Drawbridge annotates static HTML files and local development servers equally, supporting early-stage prototyping before deployment infrastructure exists.

Installation & Setup

Install the Extension

# Clone or download the repository
git clone https://github.com/breschio/drawbridge.git

1. Open Chrome and navigate to chrome://extensions
2. Enable Developer mode
3. Click Load unpacked
4. Select the folder: drawbridge/chrome-extension/
5. Pin Drawbridge from Chrome's Extensions menu

For local file:// pages, open Drawbridge's extension details in Chrome and enable Allow access to file URLs.

Connect Your Project

1. Open the target application or page in Chrome
2. Click the Drawbridge toolbar icon
3. Click Connect Project in the drawer
4. Select the local project root directory
5. Approve Chrome's file access prompt

Drawbridge creates and maintains files in your project so your AI tool can read the work queue.

Process the Queue

After adding annotations, open your project in Cursor, Claude Code, Codex, or Windsurf and run:

/bridge

or:

bridge

Real Code Examples

The README provides direct examples of annotation commands and workflow invocation. These are reproduced exactly as documented.

Annotation Shortcuts

# Press C, or use Tools -> Comment, then click an element and leave a note
C

# Press R, or use Tools -> Rectangle, then drag over an area and leave a note
R

# Press Esc to exit annotation mode
Esc

These keyboard-driven interactions minimize context switching. The developer never leaves the browser viewport to document observations.

Workflow Commands

# Process one task at a time with approval
step bridge

# Group related tasks and process together
batch bridge

# Process all pending tasks autonomously
yolo bridge

The three modes reflect different risk tolerances and review requirements. step bridge suits sensitive changes requiring human verification. yolo bridge maximizes throughput for trusted, low-risk modifications.

Generated File Structure

Drawbridge writes these files into the connected project:

.moat/moat-tasks.md              # human-readable task list
.moat/moat-tasks-detail.json     # structured task data for AI processing
.moat/screenshots/               # screenshots captured with annotations
.moat/drawbridge-workflow.md     # agent workflow instructions
.claude/commands/bridge.md       # Claude Code slash command
.windsurf/workflows/bridge.md    # Windsurf workflow
.codex/prompts/bridge.md         # Codex prompt

The README notes that Drawbridge also updates .gitignore for generated local workflow folders, preventing accidental commits of tool-specific configuration.

Advanced Usage & Best Practices

Drawer Management: The chevron button collapses or expands the drawer. When collapsed on left or right edges, it becomes a slim rail with status counts. This minimal chrome preserves screen real estate during focused work.

Script Recovery: If the toolbar icon becomes unresponsive after extension reload, a single click re-injects necessary scripts into existing tabs. This is documented behavior, not a bug—expect to use it during active development of the extension itself or after browser updates.

Stale State Handling: Close and reopen the drawer with the toolbar icon if content appears outdated. This forces re-synchronization with the project's task files.

Project Reconnection: If .moat/ files disappear or become corrupted, reconnect the project from the drawer rather than manually recreating files.

AI Tool Verification: When an AI tool cannot locate tasks, confirm the presence of .moat/moat-tasks.md and .moat/moat-tasks-detail.json in the project root. These files are the single source of truth for task state.

License Awareness: The custom license permits personal and internal use but restricts commercial redistribution. Organizations considering Drawbridge as part of client-facing services should contact breschicreative@gmail.com for commercial licensing.

Comparison with Alternatives

Drawbridge's distinct advantage is context preservation at the point of observation. Where alternatives require developers to translate visual observations into textual descriptions, Drawbridge captures the observation itself—selector, bounds, screenshot—and formats it for AI consumption. The trade-off is Chrome-only support and the need to install an unpacked extension during development.

FAQ

Is breschio/drawbridge free to use? Yes, for lawful personal and internal purposes under its custom license. Commercial redistribution requires separate licensing.

Which AI coding tools are supported? Claude Code, Cursor, Codex, and Windsurf, with workflow files generated for each.

Does it work with local HTML files? Yes, enable "Allow access to file URLs" in the extension's Chrome details page.

What happens if the extension reloads? Click the toolbar icon once to re-inject scripts into existing tabs; the drawer toggles rather than duplicating.

Where are tasks stored? In .moat/moat-tasks.md and .moat/moat-tasks-detail.json within your connected project directory.

Can I use this in production environments? The extension operates on whatever pages you browse; task files are local. Evaluate security implications of file system access for your environment.

How do I check if annotations synced correctly? Verify .moat/ directory contents exist and the AI tool can access the project root.

Conclusion

breschio/drawbridge solves a specific, well-defined problem: the friction between observing visual issues in a browser and supplying AI coding assistants with actionable, contextual tasks. It does not attempt to replace design tools, project management systems, or IDE functionality. Instead, it bridges—appropriately—the gap between visual inspection and code generation.

The tool suits developers and teams already using Claude Code, Cursor, Codex, or Windsurf who want tighter feedback loops without context-switching overhead. Its 956 stars and active maintenance suggest viability, though the custom license requires attention for commercial use cases.

If your workflow involves frequent UI iteration with AI assistance, [INTERNAL_LINK: ai-coding-tools-comparison] breschio/drawbridge merits evaluation. Install from the repository, annotate your next review session, and run /bridge to measure the time saved against your current process.

Get started: https://github.com/breschio/drawbridge