Edit diagrams locally

koboyo open opens a diagram in the Koboyo editor in your browser, served from your own machine. You can move boxes, restyle them, add notes and sketch around the diagram, and your changes are saved to files next to the code. It is free and needs no account.

Open a diagram#

koboyo open docs/checkout.kbd

The editor opens on a private 127.0.0.1 address that only your machine can reach. As you edit:

• the board is saved to docs/checkout.kby, the same file format koboyo.com uses for Open and Save to file;
• docs/checkout.svg is redrawn on every save, hand edits included, so the picture in your README always shows the latest version.

Press ⌘S (Ctrl+S on Windows and Linux) to save at any time; the editor also saves as you go. Stop it with Ctrl-C in the terminal.

Open a folder to get a list of every diagram in it:

koboyo open docs

You can also open a board directly: koboyo open docs/checkout.kby.

Start a blank board#

Run koboyo open with no path. If the current folder has diagrams, you get the list. If it has none, Koboyo creates diagram.kby there and opens it, so you can start drawing straight away.

To name the new board yourself, open a .kby that doesn't exist yet:

koboyo open sketch.kby

A .kbd file is diagram code, so Koboyo won't create an empty one. Write the code first, or ask your agent to, then open it.

When the code changes#

If docs/checkout.kbd changes while the editor is open, because you or your agent rewrote it, the drawing follows. If you have already moved or restyled things by hand, the editor asks whether to keep your edits or use the new code.

If the code has an error, the board keeps its last good drawing and the editor shows the error until the code is fixed.

Work with your agent#

An agent can hand you a diagram and wait for it to come back:

koboyo open docs/checkout.kbd --wait --agent-name "Claude Code" --json

The editor shows a Send back to Claude Code button in its top bar. Type a short note if you like ("the cache sits in front of Postgres") and press it, or press ⌘↵. The command then ends and prints what changed:

{
  "ok": true,
  "command": "open",
  "status": "sent",
  "file": "/work/docs/checkout.kbd",
  "board": "/work/docs/checkout.kby",
  "svg": "/work/docs/checkout.svg",
  "png": "/tmp/koboyo-x1y2z3/checkout.png",
  "changed": true,
  "codeInSync": false,
  "changes": {
    "added": ["Cache"],
    "removed": [],
    "renamed": [{ "from": "DB", "to": "Postgres" }],
    "edges": { "added": ["API -> Cache"], "removed": [] }
  },
  "comments": {
    "open": [
      {
        "id": "3f2a9c1e-5b7d-4e8f-9a0b-1c2d3e4f5a6b",
        "on": "Worker",
        "shapeId": "k2f9",
        "at": null,
        "by": "You",
        "text": "Split this into two queues",
        "replies": []
      }
    ],
    "resolved": 0
  },
  "note": "the cache sits in front of Postgres"
}

• status is sent, closed (you closed the tab), timeout or cancelled (Ctrl-C, exit code 130). A reload does not count as closing.
• codeInSync is false when the drawing has hand edits that the code file does not describe. The agent can update the code from changes.
• png is a picture of the board, for an agent that can look at images.
• comments lists the comments you left that are not resolved yet (see below).

--timeout sets how long to wait (30m by default, 0 for no limit). Without --json, the result is JSON when the output goes to another program and a short summary when it goes to your terminal.

If your agent uses the local MCP server, it does the same with the open_editor and wait_for_edits tools, and reads a board without waiting with read_drawing.

Leave comments for your agent#

To ask for a change instead of making it yourself, pin a comment on the drawing: right-click a box and choose Add comment, or pick the comment tool and click where it belongs. Write what you want ("make this Postgres") and press Enter.

Your comments go to the agent when you press Send back, listed by the box they are on. The agent can reply under a comment and mark it resolved when it is done, and you see that in the editor as it happens. Reply to keep the conversation going, or reopen a comment that needs more work.

Comments are saved in a file next to the board, docs/checkout.comments.json, so they are kept when you close the editor. The file is removed when the last comment is. Comments are never part of the board itself: they are not in the picture, in exports or in a board saved to Koboyo.

An agent without MCP reads and answers them with koboyo comments:

koboyo comments docs/checkout.kbd
koboyo comments docs/checkout.kbd --thread 3f2a9c1e --reply "Split it in two" --resolve

Options#

The link works once. After that, the page keeps a cookie for the session, so reloading works but the link cannot be reused by anything else on your machine.

Save to Koboyo#

Everything above stays on your machine. To share a diagram as a board on koboyo.com, with a link and live embeds, save it to your Koboyo account. This is part of Koboyo Pro.

Sign in once. Your browser opens to koboyo.com to approve it:

koboyo login

On a machine without a browser, such as a server you reach over SSH, koboyo login prints a short code instead. Open koboyo.com/device on your laptop or phone, enter the code, and approve. The terminal finishes on its own. Run koboyo login --device to sign in this way anywhere.

Then save from the editor with Save to cloud, or from the terminal:

koboyo save docs/checkout.kbd

Both print the board's link. Saving the same file again updates the same board, so links and embeds you have shared keep working. If someone changed the board on koboyo.com since your last save, nothing is overwritten: pass --replace to overwrite it or --new to save a new board. koboyo whoami shows which account you are signed in to, and koboyo logout signs you out.

Without Pro, saving tells you how to start a free trial at koboyo.com/start; nothing else changes.