Noureddine RAMDI / Drawbridge: Bridging UI annotations and AI coding assistants with a universal task protocol

Created Sat, 23 May 2026 20:41:14 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
1019 Words
github-stars javascript chrome-extension ai-coding ui-annotation developer-experience automation

breschio/drawbridge

Drawbridge tackles a common frustration for web developers: turning visual UI feedback directly into actionable prompts for AI coding assistants. Instead of toggling between browser inspection, comment tools, and AI chat interfaces, Drawbridge creates a continuous feedback loop between the running app and multiple AI agents. It does this by capturing UI annotations as structured files that AI tools can consume.

How drawbridge connects UI annotations to AI coding workflows

At its core, Drawbridge is a Chrome extension that lets developers annotate live web pages with Figma-style comments and freeform rectangles. These annotations are not just visual; the extension captures rich context including DOM selectors, bounding boxes, element metadata, and screenshots. This data is then serialized into a local directory named .moat/ inside the project root.

This .moat/ directory holds structured markdown and JSON files representing tasks generated from the annotations. These tasks are augmented with workflow definitions tailored for multiple AI coding assistants like Claude Code, Cursor, Codex, and Windsurf. This multi-agent compatibility is a rare feature — most annotation or AI tools target a single platform or API.

Drawbridge’s architecture is essentially a file-based bridge between visual UI feedback and AI coding workflows. By writing out task files locally, it sidesteps the need for complex API integrations or proprietary cloud services. The .moat/ folder acts as a universal task queue that any compatible AI tool can read and process.

The extension also handles practical web environment challenges: it prevents injecting duplicate drawer UI components on page reloads, recovers gracefully from extension reloads, and automatically updates .gitignore to exclude generated workflow files.

What sets drawbridge apart: structured multi-agent task protocol and resilient extension design

The standout technical feature is the creation of a structured task protocol based on local files. Instead of relying on ephemeral chat prompts or cloud APIs, Drawbridge produces a persistent task queue in the .moat/ directory. This design has several benefits:

  • Multi-agent support: Workflows are defined for Claude Code, Cursor, Codex, and Windsurf, allowing developers flexibility in choosing their AI assistant.

  • Structured data: Tasks include selectors, bounding boxes, element context, and screenshots serialized as JSON and markdown, providing rich, machine-readable context beyond plain text.

  • Offline resilience: Because tasks exist as local files, annotation work can continue without constant network connectivity.

  • Extensibility and transparency: Developers can inspect and modify the task files directly, making the workflow auditable and customizable.

The extension’s code quality reflects careful attention to real-world usage. It handles reload recovery so annotations aren’t lost if the browser or extension restarts. Duplicate UI injection is prevented to avoid clutter when reloading pages. The automatic .gitignore updates reduce developer friction by keeping generated workflow files out of version control.

The tradeoff is that this approach requires developers to adopt the .moat/ directory within their project and to use one of the supported AI tools that can read these task files. It’s not a zero-configuration, plug-and-play cloud service. However, this tradeoff buys flexibility and control, especially for developers who prefer local-first workflows and multi-agent AI tooling.

Setup and getting started with drawbridge

Drawbridge’s installation and usage are well documented and straightforward. Here’s the exact setup process from the README:

## Setup

### 1. Install The Extension

1. Clone or download this repo.
2. Open Chrome and go to `chrome://extensions`.
3. Turn on Developer mode.
4. Click Load unpacked.
5. Select this folder: `drawbridge/chrome-extension/`.
6. Pin Drawbridge from Chrome's Extensions menu.

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

### 2. Connect Your Project

1. Open the app or page you want to annotate.
2. Click the Drawbridge toolbar icon.
3. Click Connect Project in the drawer.
4. Select the local project root for that app.
5. Approve Chrome's file access prompt.

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

### 3. Process The Queue

After adding annotations, open your project in Cursor, Claude Code, Codex, or Windsurf and run `/bridge` or `bridge`.

The workflow is simple: install the extension, connect it to your local project, annotate UI elements in the browser, then have your AI assistant process the generated tasks.

verdict: who drawbridge is for and its practical limits

Drawbridge is clearly aimed at front-end developers and AI-assisted coders who want a tighter feedback loop between UI design and code generation. Its local file-based approach fits well with devs who prefer transparent, extensible workflows and who use one of the supported AI coding assistants.

It’s less suited for teams looking for SaaS-style annotation management or those who want a fully hosted, zero-setup AI integration. The reliance on Chrome and manual extension installation also limits cross-browser usage.

That said, Drawbridge solves a real pain point: bridging visual UI feedback directly into structured AI tasks that multiple agents can consume. The codebase’s attention to robustness (reload recovery, duplicate injection prevention) and multi-agent support are strong signs of practical maturity.

If you often find yourself switching between browser inspection, design feedback, and AI coding chats, Drawbridge offers a tangible way to streamline that cycle with a clear, file-based protocol. It’s worth exploring if your workflow involves AI-assisted UI development and you want more control over the annotation-to-code pipeline.

→ GitHub Repo: breschio/drawbridge ⭐ 930 · JavaScript