Agents

Bogen has no model of its own. Your coding agent does the agent work, with the account and plan you already have. There are two ways in:

• Your agent connects to Bogen. You work in Claude Code, Codex or another MCP client, and it draws through Bogen's MCP tools. It can work with no editor open.
• Bogen starts your agent. From the canvas, Ctrl+K or a comment that mentions @claude or @codex runs your own claude or codex CLI with only Bogen's tools.

Connect a client

bogen install claude-code

bogen install --all sets up every client it finds on this machine and skips the rest. Edits keep the comments and formatting of your config files, and a file that cannot be read as JSON is left alone. Running it again is safe.

Claude Code and Codex have been set up for real this way. For the other clients the entries follow their documented config formats, but have not been tried with the apps themselves.

To take Bogen out again:

bogen uninstall claude-code

The client starts bogen mcp, which talks to the local server and starts it when it is not running. If bogen is not on your PATH, the entry names Node and the exact script instead.

Other clients

Any MCP client can connect in one of two ways:

• stdio: the command bogen mcp.
• Streamable HTTP: http://127.0.0.1:29990/mcp.

A server started with --token needs Authorization: Bearer <token> on HTTP, or BOGEN_TOKEN in the environment of bogen mcp. BOGEN_URL points bogen mcp at a server elsewhere.

An agent shows up in Bogen under the name of its MCP client. A client can set its own with the X-Bogen-Agent header.

The skill

For Claude Code and Codex, bogen install also writes a small skill, skills/bogen/SKILL.md, in ~/.claude or $CODEX_HOME. It is made from the same text as the server's own guides, so the two agree. It tells the agent when to reach for Bogen and how to work well in it. bogen uninstall removes it, and a file of that name that Bogen did not write is left alone. No model run has been seen loading the skill yet.

What your agent can do

Everything a person can do in a file, through 129 tools. In short:

• Look: what you have open and selected (context_get), the layer tree, any layer's values, computed styles, and screenshots of a layer or page.
• Draw: artboards, real HTML written one section at a time (html_write), styles, text, attributes, images, icons, shaders, animations, and layers repeated from data.
• Organise: groups, flex wrappers, alignment, components with props, variants and slots, shared libraries, tokens, theme modes and text styles.
• Check: contrast, tokens, the 4px grid, overflow, alt text, small text and small targets (design_lint); widths (responsive_check); pixel differences (visual_diff); the brand (brand_check).
• Hand off: code as HTML, React or React with Tailwind, tokens as CSS or a Tailwind theme, and exports to files.
• Work next to you: read and answer comments, wait for what you do, select layers or bring them into your view, and make proposals for you to accept.

Every tool and its arguments are in the MCP tool reference. When it connects, your agent also gets short instructions, and guide_get has longer guides on design, layout, tokens, components, shaders, code handoff, live work, checks and brands.

Clients that offer MCP prompts as commands get four: review this design, design with this brand, implement the selection in my repo, and build from my repo's tokens. They are listed and rendered correctly, but have not been run as slash commands in a real client yet.

Agents leave locked layers alone. Unlocking needs a tool call the instructions tell them to make only when you ask.

Ask from the canvas: Ctrl+K

Press Ctrl+K, type what you want and press Enter. Bogen runs your own claude or codex CLI on your plan, with no API key. The run sees your file, page and selection.

• Pick the runner, the model and the effort in the bar. The model list comes from the CLI itself (claude --help, codex debug models). Your choice is remembered.
• Pick where the work lands: Change it works on the layers, Propose works on a copy for you to accept, 3 directions makes three copies side by side.
• The CLI gets the Bogen tools and nothing else: no shell, no file access, none of your own MCP servers. With Codex, your user config and rules are left out too.
• One run per file at a time, and at most four at once.

Runs of both CLIs have been made for real through the same route the bar uses. The bar itself has been tested against stand-in CLIs.

Ask in a comment: @claude and @codex

Press C, click a layer, and write a comment that mentions @claude or @codex. The CLI starts with the thread and the layer as context, answers in the thread, and resolves it when the work is done. If it needs something from you, it asks in the thread and leaves it open.

• One run per file at a time; up to five more mentions wait in line. A file can start at most 20 runs from comments in ten minutes.
• Comment runs start on the cheapest model each CLI offers, at low effort (for Claude, haiku). Change that in the Agents tab, or under the comment.
• Only you, on this device, start runs. A comment that arrives from a paired device, that an agent writes, or that comes with an imported file never starts anything.

Proposals: review before it counts

When your agent changes something you care about, it can work in a proposal: a marked copy next to the original, with Accept and Discard on the canvas. Accepting puts the copy's content into the original as one undo step, and the original keeps its id and its place. With three directions, accepting one discards the others. The agent hears your decision through wait_for_event.

Two limits: a comment pinned to a layer inside the original loses its pin when you accept, and page exports and thumbnails include open proposals.

Undo what an agent did

• Agents tab: each agent working in the file has an undo button for its last edit. Its own steps only: what you and other agents did stays.
• Activity: in the Agents tab, every step an agent took is a row. A row jumps to its layers, shows them before and after as pictures and values, and undoes that one step, also out of order. This lasts while the file stays loaded on the server.
• Your agent itself can call agent_undo, with redo.
• Any change, any time: History can revert a single change or a whole run, also after a restart.

Ctrl+Z in the editor undoes your own edits, not an agent's.

Let agents show you things

An agent can select layers in your editor or bring them into view, to point at what it means. It waits while you drag or type. Turn Let agents show me things off in the Agents tab to stop it.

Run settings and run history

The Agents tab keeps:

• Run settings: model and effort per runner, for the prompt and for comments. They are saved in run-settings.json in the data folder.
• Run history: per file, every run with its prompt, runner, model, effort, tools, duration, result, layers touched and status, with Stop and Run this again. It survives a restart.
• Run reports: when the file has a brand, a run ends with its brand score and what is still open. See Brands.

Waiting for you: events

Most clients only act when they call a tool. wait_for_event lets an agent wait until you comment, select something, change page, edit a layer, or a run ends, and then act. The log of events is kept in memory per file; after a server restart the agent is told to catch up.

Clients that show MCP resource updates can subscribe to a file's selection, tokens, layer tree and comments instead. These work in tests with the MCP SDK; no client that shows them to its model has been tried yet.

Live site mode

Live site mode edits the source of your own web project instead of the canvas:

bogen live http://localhost:5173 --dir ~/Work/my-site

It opens your dev server in Bogen through a proxy on its own local port, with hot reload. Point at an element and click it, then ask claude or codex for a change. The CLI gets the element's selector, HTML, computed styles and, where React, Vue, Svelte or a data attribute exposes it, its source location. Its only tools are six file tools that stay inside the project folder: no shell and none of its built-in tools. It starts in an empty folder, so hooks in the project's settings do not run.

The dev server must be plain http on localhost or 127.0.0.1. You can also open live site mode in the editor at #/live.

This has run with a Vite project and a real claude run. Codex was only tried with a stand-in, and the source locations for React, Vue and Svelte follow their documentation without a run against those frameworks.