# Drawbridge: browser annotations that turn into AI coding tasks

> Drawbridge is a Chrome extension for pointing at a running web app, leaving Figma-style notes, and writing the result into the project as markdown and JSON that an AI coding tool can pick up. It closes the gap between what a designer sees on screen and what an agent can read, but the file layout it writes into your repository and its custom licence both need a look before you adopt it.

**breschio/drawbridge** — Design editor for Claude Code and Cursor. "Figma Comments" for the browser, are sent directly to Claude Code and Cursor as prompts.

- Repository: https://github.com/breschio/drawbridge
- Stars: 971 · Forks: 81
- Language: JavaScript
- License: NOASSERTION
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/breschio-drawbridge

## The gap between a screenshot and an actionable task

The problem Drawbridge addresses shows up whenever a person looks at a running web application and an agent works on the code behind it. The human sees a broken layout, an overlapping panel, a missing state. The agent sees a text description, if the human bothers to write one. The gap between those two views is where most of the effort goes.

Drawbridge is a Chrome extension that lets you click on your running app, leave Figma-style comments, capture screenshots, and turn those notes into local task files that AI coding tools can act on. The README frames it as visual annotations for AI coding assistants, built for browser-to-code feedback loops with Cursor, Claude Code, Codex and Windsurf.

The important word in that description is local. The tasks are not pushed to a server. Drawbridge creates and maintains files in the project you connect it to, and the AI tool reads them from disk like any other file in the repository. That keeps the feedback loop inside tools that already exist, and it means the mechanism works with whichever agent you happen to be running, as long as that agent can be told to read a markdown file and follow a workflow document.

The repository reflects a project still being shaped. Alongside the extension itself, the top level holds a PRD for native screenshot capture, an IDEAS.md, a JOBS-TO-BE-DONE.md, a STYLEGUIDE.md, a V2_CHANGELOG.md, a CHANGELOG.md, a demo folder with its own static site, and a run-demo.sh script. The package name is moat and the version there is 2.0.0, while the published release tags stop at v1.0.6, which is a sign of internal churn behind a public version number.

## Two annotation tools and the context captured with every note

There are two ways to point at a problem, and the split is a sensible one.

The comment tool is for elements that exist in the DOM. You press C, or pick Tools then Comment, click an element, and leave a note. The rectangle tool is for everything else, the spacing and layout problems that belong to an area rather than to a node. You press R, or use Tools then Rectangle, drag over the region, and leave a note. Press Esc to leave either mode. The README is explicit that freeform rectangles exist for visual bugs that are not tied to a single DOM node, which is precisely the class of problem a DOM-targeted tool would miss.

With each note, the extension captures selector data, element context, bounding boxes and screenshots. That combination is what makes the notes usable by an agent. A selector and a bounding box let a tool locate the same thing in the code, the element context gives the surrounding markup, and the screenshot shows what the person actually saw rather than what they described. The rectangle notes get the same treatment, so a purely visual problem still arrives with a picture attached.

Tasks then appear in the drawer and sync to the connected project. The drawer is also the control surface for the whole extension. It can dock to the bottom, left or right of the viewport, and when collapsed on the side it becomes a slim rail carrying the project button, the tools button and colour-coded counts for to do, doing and done. The chevron points in the direction the drawer will open, which is a small touch, but it is the kind of detail that tells you the interface was actually used.

## Loading an unpacked extension and connecting it to a project

Installation is the developer path rather than a store listing. You clone or download the repository, open chrome://extensions, turn on Developer mode, click Load unpacked, and select the drawbridge/chrome-extension/ folder, then pin Drawbridge from Chrome's Extensions menu. For local file:// pages, the extension details page has an Allow access to file URLs option that has to be enabled.

That last point is the one that trips people up. Without file URL access, the extension cannot read a page served from disk, and annotating a local build of a static site simply does not work.

Connecting a project takes a few clicks in the drawer. Open the page you want to annotate, click the toolbar icon, click Connect Project in the drawer, select the local project root for that app, and approve Chrome's file access prompt. Selecting the project root is a meaningful choice rather than a formality, because that directory is where the generated files land and where the agent will look for them.

The extension then creates and maintains files in the project so the AI tool can read the work queue. Nothing is uploaded and no service is involved, which is the property that makes the tool usable on internal code that cannot leave the machine.

For development, the repository exposes a small npm script set:

```bash
npm ci
npm test -- chrome-extension/background.test.js --runInBand
npm run build
```

The test run uses jest, and the build writes a packaged extension to dist/drawbridge-v<version>.zip. The package.json also defines npm run watch, which runs moat-watcher.js, and npm run demo, which serves the demo folder with python3 -m http.server 8080 so you can exercise the extension against a static page without a real application.

## The .moat directory and the workflow files written into your repository

Drawbridge writes a specific set of files into the connected project, and knowing them matters because your repository will contain them afterwards.

The queue itself lives in .moat. The file moat-tasks.md is the human-readable task list, moat-tasks-detail.json is the structured task data meant for machine processing, and a screenshots directory holds the captured images with their annotations. The status of a task moves through to do, doing and done, which is recorded in those files.

The agent-facing instructions sit in .moat as well, in a file called drawbridge-workflow.md. That file is what makes the loop work with agents that need to be told what to do: the extension supplies the workflow rules, and the tool then reads the task list and works through it.

The per-tool command files are the third piece:

```text
.claude/commands/bridge.md
.windsurf/workflows/bridge.md
.codex/prompts/bridge.md
```

One file per agent, each giving that tool its own entry point. The README describes this as deploying the /bridge workflow for Claude Code, Codex and Windsurf, plus Drawbridge workflow rules for AI agents. Drawbridge also updates .gitignore for the generated local workflow folders, so the extension tries to keep the noise out of your commits.

That last detail is the one to check on your own repository. The extension edits a file you also edit, and if your .gitignore is generated, or shared across a monorepo, the behaviour of that update is not described anywhere in the README. The troubleshooting section gives the recovery path when the expected files are missing: reconnect the project from the drawer, and if the AI tool cannot find tasks, confirm the project contains .moat/moat-tasks.md and .moat/moat-tasks-detail.json.

## Step, batch and yolo: three ways to let the agent work the queue

With annotations collected, you open the project in Cursor, Claude Code, Codex or Windsurf and run the bridge command:

```text
/bridge
```

or, where the tool expects a plain word, bridge on its own. The README lists three supported modes:

```text
step bridge
batch bridge
yolo bridge
```

Step mode processes one task at a time with approval, which is the sensible default when the agent is about to edit code that a human will review. Batch mode groups related tasks and processes them together, which suits a set of notes that describe one visual problem across several elements. Yolo mode processes all pending tasks autonomously, with no approval step.

The naming is informal and the distinction that matters is the approval gate. On a repository you care about, step mode is the setting to keep. Yolo mode exists for the case where the queue is a list of trivial, self-evident fixes, and the README does not describe any sandboxing, branch protection or diff review that would make the autonomous mode safe on real work. The tasks themselves come from annotations, which are visual notes that may be ambiguous, and an agent interpreting a note about a cramped header can produce a change nobody wants.

The screenshots travel with the tasks, which helps, since the agent can see the same picture the reviewer saw. It does not remove the risk, because a picture shows the symptom and not the intent.

## Reloading the extension without stacking drawers

Chrome extensions have to be reloaded whenever the code changes, and the usual result is a broken page or a duplicate drawer. Drawbridge handles this deliberately. The toolbar icon can inject missing scripts into existing tabs and toggles the existing drawer instead of stacking duplicates, and the troubleshooting notes repeat the instruction: if the icon does nothing after reloading the extension, click it once on the page again.

This is the kind of detail that only exists because someone hit the problem. The same list of recovery steps covers the other common failures: a stale drawer is fixed by closing and reopening it with the toolbar icon, and missing project files are fixed by reconnecting the project from the drawer.

The cost of this approach is that it is a development-install workflow. There is no Chrome Web Store listing mentioned in the README, and every user of the extension has to clone the repository, enable Developer mode and load the folder unpacked. For a team of one or two people on the same project that is manageable. For a wider rollout across a department, the friction of an unpacked extension and the manual project-root selection in step four of setup becomes the thing you will be asked about.

The screenshots, the drawer and the file layout all point the same way. This is a tool shaped for an individual developer or a tight group working on a web application, not a shared service with an onboarding process.

## A custom licence that contradicts the package metadata

The licence is the part of this repository that deserves the closest reading. The README states that the project uses a custom licence and that the LICENSE file governs. It summarises the terms: free to use, copy and modify for lawful purposes, while redistribution, sublicensing, selling, or offering as a commercial service are not permitted without a commercial licence, with commercial licensing handled by an email address given in the README.

That is a source-available licence with commercial restrictions, not an open source licence, and the metadata reflects the ambiguity. The repository's licence field is recorded as a custom licence that GitHub cannot classify, while the package.json inside the same repository declares the MIT licence. Two files in one project claiming different things is a real problem for anyone running a licence check in CI, and the reason to read LICENSE directly rather than trusting either field.

The maintenance picture is good. The repository is not archived, the last push was on 2026-10-12, and the release tags show regular work: v1.0.4 in November 2025 added task thumbnails with hover review, v1.0.5 in December 2025 added the freeform rectangle drawing tool, and v1.0.6 in June 2026 added the collapsible drawer and editable tasks. The rectangle tool and the collapsible drawer are exactly the two features the README spends the most space describing, so the visible surface and the release history line up.

Because the licence forbids offering the extension as a commercial service and restricts redistribution, the realistic uses are internal: an individual developer, or a team running the extension from a checkout on machines they control. Distributing it to clients, or embedding it in a product, needs the commercial licence that the README points to. The description here covers the published terms rather than legal advice.

## Conclusion

Drawbridge is a good fit for a team that reviews a web app visually and then wants the same feedback delivered to an AI coding agent without retyping it, provided you are willing to load an unpacked extension and let it write into the project root. It is a poor fit for a repository you cannot modify, for a page you do not control, and for any redistribution of the extension itself, because the custom licence forbids that. Before adopting it, read the LICENSE file, since it conflicts with the MIT value recorded in package.json, and check that the .moat directory and the generated workflow files match the conventions of the agent you plan to drive.

## FAQ

### What is Drawbridge and which tools does it feed?

Drawbridge is a Chrome extension for visual annotations of a running web app. It writes the notes into a project as markdown and JSON, and the README says the workflow is built for Cursor, Claude Code, Codex and Windsurf.

### How do I install the Drawbridge extension in Chrome?

Clone or download the repository, open chrome://extensions, turn on Developer mode, click Load unpacked and select the drawbridge/chrome-extension/ folder, then pin it from the Extensions menu. For local file:// pages you also have to enable Allow access to file URLs in the extension details.

### Which files does Drawbridge write into my project?

The queue goes into .moat as moat-tasks.md, moat-tasks-detail.json, a screenshots directory and drawbridge-workflow.md. The per-tool command files are .claude/commands/bridge.md, .windsurf/workflows/bridge.md and .codex/prompts/bridge.md, and the extension also updates .gitignore for the generated folders.

### What is the difference between step bridge, batch bridge and yolo bridge?

Step mode processes one task at a time with approval, batch mode groups related tasks and processes them together, and yolo mode processes all pending tasks autonomously with no approval step.

### Can I redistribute the Drawbridge extension commercially?

Not under the licence published in the repository. The README says the project is free to use, copy and modify for lawful purposes, but redistribution, sublicensing, selling, or offering it as a commercial service require a commercial licence, and the LICENSE file is the one that governs.

## Sources

- [breschio/drawbridge on GitHub](https://github.com/breschio/drawbridge)
- [Issues](https://github.com/breschio/drawbridge/issues)
- [README](https://github.com/breschio/drawbridge/blob/main/README.md)
- [Releases](https://github.com/breschio/drawbridge/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/breschio-drawbridge