drawui
README.md
# drawui
Draw a UI on a canvas, and your coding agent builds it in your project.
drawui is a local canvas (Excalidraw) with an MCP server. You sketch screens freeform: rectangles are containers, text inside a shape is its label, and text starting with `//` is a note to the agent. The agent reads the drawing, writes the frontend with the component library you chose, and draws its changes back onto the canvas, so the drawing and the code stay in step.
It works with any MCP client that speaks streamable HTTP, such as Claude Code and Switchback.
## Run it
You need [Bun](https://bun.sh) 1.4 or later.
```sh
bunx drawui ~/code/my-app
```
That opens the canvas at `http://localhost:4747` for `~/code/my-app`. Leave the path off to use the current directory, or point it at an empty folder to start from a blank canvas. Then connect your agent:
```sh
claude mcp add --transport http drawui http://localhost:4747/mcp
```
Or copy [`.mcp.json`](.mcp.json) into your project's root so everyone working in it gets the server. Change the port there if you start drawui with `--port`.
### The agent skill
drawui ships an [agent skill](plugin/skills/drawui/SKILL.md) that teaches an agent the working loop: check the connection, ask before the first build, build, draw back, and wait for the next edit. In Claude Code, install it as a plugin, which also connects the MCP server:
```sh
claude plugin marketplace add Harville-Labs/drawui
claude plugin install drawui@drawui
```
For other agents that read Agent Skills, copy `plugin/skills/drawui` into their skills folder, such as `~/.claude/skills` or your project's `.agents/skills`.
Pick a component library in the top bar. Sivir UI, shadcn/ui, and shadcn-svelte are suggested; for any other library, give its name and a link to its docs, and the agent reads them before building. If you like, set the URL of your dev server too, so the preview sits beside the drawing. Drag the divider to resize it, expand it to fill the window, or collapse it to the right; switch it between phone, tablet, and full width to check each size. Then ask the agent to "build what I drew in drawui", or use the `build` prompt.
The [user guide](docs/guide.md) covers setup, drawing conventions, and working with the agent in more detail.
Before its first build of a drawing, the agent asks the few questions the drawing leaves open, such as where data comes from, what a button does, or what the empty and error states look like.
## How to draw
| You draw | The agent reads |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| A rectangle, ellipse, or frame around other shapes | A container. Nesting is layout; rows and columns are inferred. |
| A frame | A screen, named by the frame's name. **New screen** in the top bar makes one sized for a device |
| Frames named `Login (mobile)` and `Login (desktop)` | One screen at two sizes; the agent builds it responsive. Without a suffix, the frame's width decides |
| Text inside a shape | That component's visible text, used verbatim |
| Text starting with `//` | A note to the agent about the element just beside it, or else the container it sits in |
| An arrow from a note to an element | A note about that element |
| An arrow between elements | Navigation or data flow; its label says which |
| Fill, stroke, and text colors | Colors to keep, mapped to the library's closest theme color |
| Dashed strokes | Deliberate hints |
| Freehand lines | A rough sketch; the agent looks at an image of it |
Select text and use **Mark as note** to turn it into a note without typing `//`. Select part of the drawing to ask the agent to build only that part.
Things the agent draws are tagged as its own, and elements it implemented link to their source file. When it can't build something or had to guess, it leaves a note with an arrow pointing at the element.
## What's saved
Everything stays on your machine. The server listens only on `127.0.0.1` and answers only requests addressed to localhost.
- `drawui.excalidraw`: the drawing, in the project directory. Open it in Excalidraw too.
- `drawui.json`: the chosen `library`, the `docs` link for a library drawui doesn't suggest, and the `preview` URL.
Commit both if you want the drawing to live with the code.
## MCP tools
`get_project`, `set_project`, `get_canvas`, `get_selection`, `get_canvas_image`, `get_image`, `wait_for_change`, `draw`, `update`, `delete`, and `annotate`. See [docs/mcp.md](docs/mcp.md).
## Develop
```sh
bun run check # lint, typecheck, tests, build, file length; what CI runs
bun run dev # build the canvas and start the server on the current directory
bun start ~/code/my-app # start the server from source on a project
bun run package # build the npm package in dist/drawui
```
To release, bump `version` in `apps/server/package.json`, merge it, and publish a GitHub release tagged with that version, like `v0.2.0`. The [release workflow](.github/workflows/release.yml) checks the build and publishes `dist/drawui` to npm; a prerelease goes to the `next` tag. `bun run package` builds the same package locally.
See [AGENTS.md](AGENTS.md) for the layout and the rules changes must follow.
## License
[Apache 2.0](LICENSE).
This server cannot be deployed
Maintenance
ActivityNo data
ResponsivenessOutdated data