herdr-blueprint

Why

Coding agents explain their work in long chat messages. To see what is being built, you read a wall of text. To change one part, you first describe where it is.

Blueprint fixes both ends.

• See it at a glance. The agent draws what it is building, its flow and its branches, next to the chat, and keeps the drawing current as it works.
• Ask where you look. Point at a box and write "add rate limiting here". The agent gets that part, the code behind it, and your note.

What it is

Blueprint is a herdr plugin. Put it next to your coding agent and it shows one thing: the latest doc or diagram the agent sent, drawn in your terminal with colors that match your theme.

• One screen. Each send replaces what is shown. Nothing piles up.
• Point and ask. Press e, pick a box, a branch or a block, and say what should change: the agent next to Blueprint gets the part, its place in the source and your note.
• Work orders on code. When the agent ties boxes to its code, your note becomes a change to that code: made, tested, and drawn again.
• Kept current. With the skill, the agent redraws the code it is building after each unit of work, while Blueprint is open, and the header says when the code behind a drawing changed since it was drawn.
• Draw on request. Mermaid is drawn with termaid when the sender adds --draw; otherwise it stays as clean text. The agent (or r) redraws what is on screen.
• Knows its neighbor. Opened next to an agent, it asks the agent to draw what it is doing (once it is free). Press a to ask again, or o to open a doc from the agent's folder.
• Themes. Press t to pick a theme. Only your theme is saved.
• Runs everywhere. macOS, Linux and Windows. No browser, no images.

Next to your agent

Opened next to an agent, Blueprint shows who is there and asks the agent to draw what it is doing, even while it works (agents queue what arrives); one waiting for your answer is asked after. Press a to ask again, or o to open a doc from its folder.

Install

You need uv and herdr 0.9.3 or newer.

herdr plugin install chappse6/herdr-blueprint
herdr plugin action invoke seeun.blueprint.open

Installing the plugin also gives Claude Code and Codex the Blueprint skill and the short herdr-blueprint command (see Send things from an agent); start a new agent session to pick the skill up.

It opens to the right of the focused pane and takes the focus. If Blueprint is already open in the workspace, it is focused instead of opening a second one. Bind it to a key in ~/.config/herdr/config.toml:

[[keys.command]]
key = "prefix+alt+b"
type = "plugin_action"
command = "seeun.blueprint.open"
description = "open Blueprint"

Keys

Point and ask

Press e and the first part of what Blueprint shows is selected: a box or a branch (a labelled arrow, or an arm of a choice) in a flowchart or state diagram, a participant or message in a sequence diagram, a heading, paragraph, list or table in a document. A diagram drawn inside a document is pointed at box by box too: j and k walk the document and step into it, h j k l move between its boxes, and going past its top or bottom leaves it. Click a part to select it. Moving follows the screen: h and l reach what is on the same rows, j and k what is in the same columns (else the next row), and an arrow leads to what it joins. Press Enter, say what should change, and press Enter again: the agent next to Blueprint gets the part, where it is in the source and your note. Esc steps back. Once it is sent, a banner under the header says so and stays until the agent's new version arrives, and the part stays marked in the drawing. While you type a note, whatever the agent sends waits until you close it, and a note you keep moves to the next version of the same diagram.

When the agent draws the code it is building, it ties each box to that code with a comment Blueprint doesn't draw:

flowchart TD
  T[POST /token] --> V{PKCE valid}
  V -->|no| E[400 invalid_grant]
  V -->|yes| I[Issue tokens]
  %% Blueprint: the code each box stands for (not drawn)
  %% code: V src/auth/pkce.ts:10

Point at such a box (or one of its branches), write "return 401 when the code expired", and the request is a work order: the agent changes the code at src/auth/pkce.ts:10, runs the tests, and redraws the design. To read that code yourself, press c: it opens in your editor at that line.

To change the text yourself, press e again while pointing. Your editor ($BLUEPRINT_EDITOR, $VISUAL, $EDITOR, else nvim, vim, vi or nano, and Notepad last on Windows) opens on that line, in a pane below Blueprint inside herdr, and every save redraws the drawing above. Save and quit (:wq) and the change goes to the agent: a diff for a file, the new version for something the agent sent. Quit without saving (:q!) and nothing happens. Blueprint never writes the file itself: the agent applies the change, and you roll it back the way you roll back any agent change. Set BLUEPRINT_EDITOR when your $EDITOR is set up for something else, such as an editor that starts in insert mode.

With no agent there but a shell, Blueprint offers to start one. A note that could not be sent is kept for that part; an edit, for that document. Point again (or press e twice) to pick it up, or save an edit empty to throw it away.

Send things from an agent

herdr-blueprint show docs/design.md               # a file
printf 'graph LR\n  A --> B\n' | herdr-blueprint send --draw --title "Flow"
herdr-blueprint refresh --draw                    # redraw what is shown
herdr-blueprint status                            # open or closed

--draw makes Blueprint draw Mermaid. Without it, diagrams show as text, which is faster. Each send or refresh carries its own flag.

herdr-blueprint is on your PATH once the skill is installed (see below; it goes in ~/.local/bin). Without it, run the command through the plugin folder:

root=$(herdr plugin list --plugin seeun.blueprint --json | uv run --no-project --quiet python -c 'import json, sys; p = json.load(sys.stdin)["result"]["plugins"]; print(p[0]["plugin_root"] if p else "")')
uv run --project "$root" --no-sync python -m herdr_blueprint send --draw --title "Flow" < flow.mmd

The skill teaches Claude Code and Codex to use Blueprint on their own: draw what they are building, keep it current, and act on what you point at or edit. Installing or updating the plugin copies it into ~/.claude/skills and ~/.agents/skills and puts the short herdr-blueprint command in ~/.local/bin, never over files that aren't its own. A plugin used from a local folder (herdr plugin link) isn't built, so add the skill there with:

herdr plugin action invoke seeun.blueprint.install-skill

Start a new agent session to pick it up. Removing the plugin leaves the skill behind: undo with herdr-blueprint uninstall-skill first.

Token use

Blueprint itself uses no tokens; the agent does when it writes what Blueprint shows. The skill asks the agent to redraw its design after each unit of work (a feature piece, a fix, a change to the flow), but only while Blueprint is open: it first runs status, a short command, and draws nothing when Blueprint is closed. Agents load a skill when its description matches what they are doing; if yours doesn't redraw, press a.

Rough figures, not measurements (they vary with the model, the language and the size of the diagram):

Each redraw is also one more step for the agent, which reads its conversation again; prompt caching makes that cheap, but it counts toward usage limits. To use fewer tokens, close Blueprint while you don't look at it, or tell the agent to redraw only when you press a.

FAQ

Why not just ask the agent for Mermaid? You can, and Blueprint draws it. What it adds: the drawing stays current (redrawn after each piece of work, flagged when the code behind it changed), you point at a part instead of describing it, boxes tied to code turn your note into a change to that code, and it all runs locally in your terminal, as open source.

Does it cost tokens? Blueprint doesn't; the agent does when it draws. See Token use.

Themes

Rosé Pine (default), Blueprint, Catppuccin Mocha, Tokyo Night, Nord, Gruvbox and Dracula. Your choice is saved.

Development

uv sync
uv run pytest
uv run herdr-blueprint            # run outside herdr
herdr plugin link "$PWD"          # use this folder as the plugin

README images come from scripts/screenshots.py (themes) and scripts/demo (herdr with an agent).

Credits

Blueprint stands on these MIT-licensed projects:

• termaid by Fabio Souto: Mermaid in the terminal
• Textual and Rich by Will McGugan and Textualize
• watchfiles by Samuel Colvin
• platformdirs

License

MIT