8000 GitHub - asbaker/obeya: obeya: the big room for you and your agent. One live canvas for diagrams, boards and prototypes, all on your machine. · GitHub
[go: up one dir, main page]

Skip to content
asbakerPublic

About

obeya: the big room for you and your agent. One live canvas for diagrams, boards and prototypes, all on your machine.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

obeya

Draw with your AI agent. It sees what you circle.

license: MIT node: ≥ 22.20 telemetry: none dependencies: 0

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.

Three sign-in screens the agent mocked up, and a banner: your agent is waiting for you, which sign-in should we build? Done The person circles screen B, magic link, and adds a pink note: B, plus a Google button The agent marks B as chosen, fades A and C, adds Continue with Google to B and replies: building B
1 · It asks on the page 2 · You circle one and press Done 3 · It builds what you chose

Install

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 obeya

The 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

Your first drawing

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.

Update or remove

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.

How it works

You, the canvas (Excalidraw in a browser tab), the obeya server (saves .excalidraw files) and your agent (the obeya CLI), all on your machine, 127.0.0.1 only

  1. 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.
  2. React on the canvas. Circle, drag, cross out, add sticky notes. No need to put it into words.
  3. 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.

Example use cases

Each example was drawn by an agent through obeya (Claude Code with Claude Opus 5.5). Results depend on your agent.

A team board: To do, Doing, Review and Done columns of sticky notes, coloured by kind
Kanban board
Drag a card: your agent sees it move
A story map with release lines
Story map
Release lines your agent can watch
A roadmap with a today line
Roadmap
Lanes and a today line
A data model
Data model
Tables and how they relate
Three phone screens built from wireframe components, linked into a clickable prototype
Clickable prototype
Click through it in Present mode
Four slides: a title, bullets, a diagram and a chart
Slides
Exported as one offline HTML file
A refactor plan: three big files on the left, split into folders of smaller files on the right, with a note
Refactor plan
Before and after, before any code moves
Mermaid text beside the flowchart it became, drawn as editable shapes
Mermaid diagrams
Editable shapes; change the text and run it again to redraw
A checkout architecture drawn with AWS service icons: CloudFront, API Gateway, Lambda, DynamoDB, EventBridge, SQS and SES
Architecture
Real service icons from public libraries

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.

What you get

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.

The CLI

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 --skill prints the guide for the installed version (a short core; obeya --skill <topic> for one topic, obeya --skill all for 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 --help lists the rest.

Privacy and security

  • 🔒 Listens on 127.0.0.1 only.
  • 🛡️ Other websites open in your browser can't reach it (it checks Host, Origin and Sec-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.

FAQ

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.

Development

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                   # both

Without 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).

License

MIT. See LICENSE. Not affiliated with Excalidraw.

About

obeya: the big room for you and your agent. One live canvas for diagrams, boards and prototypes, all on your machine.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0