Draw with your AI agent. It sees what you circle.
Your agent draws instead of describing. No more ASCII diagrams in your terminal. Your agent sketches its thinking on a real Excalidraw canvas in your browser: flows, architectures, roadmaps, wireframes, slides.
You answer by drawing. Circle the part that's wrong, drag a card, stick a note on it, the way you would at a whiteboard. Press Done, and your agent sees exactly what you did and what you pointed at, and draws its next move.
Local only. Pages are .excalidraw files, in whatever folder you keep them.
Obeya (大部屋, "big room") is the lean practice of a room whose walls hold the team's plans, charts and artifacts. This is that room, with an agent in it.
| 1 · It asks on the page | 2 · You circle one and press Done | 3 · It builds what you chose |
What you need: Node 22.20 or later, and a browser. Chrome or Chromium is optional: with it, your agent can take screenshots and export files while no canvas tab is open.
npm i -g obeya # the CLI and the canvas server
npx skills add asbaker/obeya -g # the skill: teaches your agent when and how to use obeyaThe skill works with Claude Code, Codex, Cursor, OpenCode and more. Or paste this to your agent, and it installs both, asking first:
Set up obeya: https://github.com/asbaker/obeya/blob/main/INSTALL.md
In any project, try:
Use obeya to draw how this project fits together. Put the page in docs/obeya.
Your agent starts obeya in the background and opens the canvas in your browser. Keep that tab open: it's where you both draw. Pages are saved as you go.
npm update -g obeya and npx skills update obeya keep both current; CHANGELOG.md says what's new. Removing obeya leaves your pages where they are; see INSTALL.md.
- Ask for a picture. "Map out how a request flows through this app." Your agent draws it in your open tab, live, and points your view at it.
- React on the canvas. Circle, drag, cross out, add sticky notes. No need to put it into words.
- Press Done, or say "take a look". Your agent reads what you changed and what each mark points at, then answers on the page: it moves cards, adds options, redraws.
Every change goes through the live editor, so your open tab stays in step. Pages are plain .excalidraw files: commit them, or keep them out of git.
Each example was drawn by an agent through obeya (Claude Code with Claude Opus 5.5). Results depend on your agent.
The prototype uses components from ecommerce mobile ui by Webkul Software (MIT), and the architecture uses AWS Serverless Icons v2 by slobodan, both from the public Excalidraw libraries catalogue.
| It draws instead of describing Diagrams, flows, wireframes and slides on a real canvas, not ASCII in a terminal. |
You answer by drawing Circle, arrow, sticky note, drag. It reads what you did and what each mark points at. |
It checks its own work It checks the page for overlaps, clipped text and hard-to-read colours, fixes them, and takes one screenshot of what it built. |
| It shows you where to look It moves your view to the right frame while you talk. |
Real components Wireframe kits, cloud icons, C4 and more, from about 230 public libraries. |
Share the result Present frame by frame with a laser pointer, or export PNG, SVG, PDF or a one-file slideshow. |
Your agent drives obeya through a CLI that prints JSON. When it asks which sign-in to build and you circle one, add a note and press Done, this is what it gets back:
$ obeya wait signup-flow --frame f-signup --ask "Which sign-in should we build? Circle one, add a note, then press Done."
{"result":{"done":"button","rev":366,"changes":[{"op":"added","id":"e1","type":"ellipse","frame":"f-signup","pointsAt":[{"id":"sb-h","type":"text","text":"Sign in with email"},{"id":"sb-sub","type":"text","text":"We'll email you a link. No password."},{"id":"sb-cta","type":"rectangle","text":"Email me a link"}]},{"op":"added","id":"n1","type":"stickynote","text":"B, plus a Google button","frame":"f-signup","pointsAt":[{"id":"sb-shell","type":"rectangle"},{"id":"e1","type":"ellipse"}]}]}}| Command | What it does |
|---|---|
obeya patch <page> |
Add, change or delete elements through the live editor |
obeya changes <page> |
What the person changed since the agent last looked, and what each annotation points at |
obeya wait <page> --ask "…" |
Ask you for something on the page; returns your changes when you press Done |
obeya describe <page> |
A plain-text outline of the page |
obeya lint <page> |
Overlaps, clipped text, stray elements, low contrast: checks instead of a screenshot |
obeya shot <page> |
A PNG of a page, a frame or a few elements, so the agent can look |
obeya export <page> |
PNG, SVG, PDF or an HTML slideshow |
obeya mermaid <page> |
Draw a Mermaid diagram as editable elements; run it again to update it |
obeya library |
Search, view and insert components from public libraries |
obeya --skillprints the guide for the installed version (a short core;obeya --skill <topic>for one topic,obeya --skill allfor everything); the installed skill points at it.- Every command prints one compact JSON line,
{result}or{error: {code, message, hint}}, holding only what an agent acts on; a success with nothing to report prints nothing. obeya --helplists the rest.
- 🔒 Listens on
127.0.0.1only. - 🛡️ Other websites open in your browser can't reach it (it checks
Host,OriginandSec-Fetch-Site). ⚠️ No login or token: other programs and users on the same machine can reach it, as with most local dev servers.- 🚫 No telemetry. Pages, screenshots and exports never leave your machine.
- ⬇️ Downloads only: the pinned Excalidraw editor, its Mermaid converter and fonts (from
esm.sh), and component libraries you ask for. Your Mermaid text is converted in your browser.
What does it change about working with an agent?
obeya was planned and designed in obeya. What changed:
- Decisions come faster. The agent lays out the options side by side, as mockups or numbered questions. You circle one, dot-vote, or write "yes" next to it, with no long back-and-forth in chat.
- You see it before it's built. The page picker, the export dialog and folders were mocked up and clicked through in Present mode before any code changed.
- Feedback lands where it belongs. A sticky note on the draft ("skip the gif, 3 stills is fine") says exactly what you mean and where.
- Big plans become readable. A refactor became before/after diagrams and state machines, not a wall of text in the terminal.
- The page is the record. Decisions, the roadmap and a done log stay on the canvas, so the next session, or the next agent, picks up where you left off.
What does it cost my agent?
Little. Learning obeya costs an agent about 3k tokens, every command prints one compact line with only what the agent acts on, and it checks its work as text before taking a screenshot.
Is this an official Excalidraw project?
No. It uses the open-source Excalidraw editor (MIT) at a pinned version.
Where do my pages go?
Wherever you say: any folder, in or out of a project (--dir, or OBEYA_DIR; ./obeya if you don't say). obeya adds only a hidden .obeya/ inside it (change logs, logs, screenshots), which git ignores.
Which agents work?
Any agent that can run shell commands, such as Claude Code, Codex, Cursor or OpenCode. The skill installs into most of them.
With mise (pins Node; mise tasks lists the rest):
mise install && mise run setup # Node, then playwright-core (used only by the smoke test)
mise run test # unit and integration tests (node --test)
mise run smoke # browser smoke test: needs Chrome or Chromium (CHROME_PATH=…)
mise run check # bothWithout mise, on Node 22.20 or later: npm install, npm test, npm run test:smoke. From a checkout, run node bin/obeya.mjs … or npm link.
Made with obeya itself: the logo (mise run brand opens docs/brand/logo.excalidraw, mise run logo exports it) and every image here (mise run stills redraws the pages in docs/readme/ and exports them; node docs/readme/stills.mjs kanban redraws one).
MIT. See LICENSE. Not affiliated with Excalidraw.