bluedoc

An agent skill for engineering docs, plans, code reviews, UI designs, slide decks, website reviews, app icons and app store listings. The agent writes one JSON file, plus small HTML fragments for screens and SVG layers for icons; a local server renders it as a page. You tick checklists, pick options, comment on any element and approve or send back; your answers and change requests go to the agent, and each revision can be compared with the last. Works with Claude Code, Codex, pi, omp, Copilot CLI and Antigravity CLI.

bluedoc 1.0 is tested on macOS; Linux and Windows are untested. Issues and feedback are welcome on GitHub.

Doc types

Type	What it's for	Page
docs	Architecture pages, walkthroughs, runbooks, setup guides, change proposals	docs
plan	A plan you approve or send back before the agent writes code	plan
review	Review findings pinned to their lines from git, one decision per finding	review
design	UI screens on a board and app icons	design
website	A site's pages, live from its dev server: comment on sections, pick versions in place, each comment names the source to edit	website
presentation	Slide decks with speaker notes, played in Present	presentation
storelisting	An app's Google Play and App Store listing: screenshots per device, store text per locale, store checks, fastlane export	storelisting
other	Status pages, incident reports, inventories, meeting notes, comparisons	other

What you get

• A home page. http://127.0.0.1:8740/ lists every doc the server knows. It opens on a pixel-art banner of a bay with a ringed planet, a night version for the dark theme and a day version for the light one, with the title and search field over it. Under the search field, chips filter by doc type and status, with a count on each; a sidebar lists projects with their folder trees. Each doc is a card whose hero shows its type's own element (a review's +/− lines, a plan's step timeline, a doc's drawing), in a grid (2–6 columns), a list or a board.
• Blueprint canvas. Open a system to see its parts; each level plays its own animated flow (request, event, data). Nests 3 levels deep. Edges are routed at right angles around the nodes, with labels that don't overlap.
• Checklists as task trackers. Each item is a two-line row (the action, then why it matters) that opens to show details, commands, checks, tables or a sub-checklist. Ticks persist on the local server; Copy progress exports Markdown for a PR or issue. A finished step or check can carry its evidence: the test it ran and its output, a screenshot, a link to a log or review. Adding evidence after approval keeps the plan approved. Evidence is pinned to the commit it checked: once the code it covers changes, the page marks it stale and doesn't count it as done until the agent re-runs it.
• Decisions. When the agent needs you to choose, it asks in a decision list, apart from the work checklists: each item shows its options as pills with the agent's recommendation starred, and a chip under the title counts the questions still open. Pick one, or press Accept recommended to take every starred option at once. Change a pick after approving and the plan says so until you send it.
• Need more details. Every decision item has a Need more details toggle after its pills. It leaves the pick alone, turns the item's dot amber and asks what is missing; the agent answers in the next revision with a fuller description and options. A plan, design, presentation or website can't be approved while an item asks for more details. Turning the toggle off withdraws a sent request.
• Comments and Revisions tabs. The right panel of every doc has two tabs. Comments lists your notes as Pending (saved), Open (sent) or Resolved, with a General comment field for the whole doc. Revisions switches to any earlier revision or compares two: new, changed and removed parts are marked in place with a word-level diff, next to the author's note on what changed.
• Comments on anything. A tray of keys at the bottom (View, Point, Select, Draw) pins a comment on an element, a selected passage or a drawn mark. Request changes sends the pending comments to the agent as edits to make; Send answers sends your picks, ticks and item comments.
• The agent resolves what it addressed. Each comment in a reply carries an id. The agent lists the ids it addressed in the new revision (build.py patch … --resolves <id>); on load, those comments move to Resolved with "Resolved by the agent in rev X".
• Plans you approve on the page. The goal, the proposed design on a canvas, before/after panes, mockups, a numbered timeline of steps, the files each step touches, open questions, risks and checks. Approve plan or Request changes; the agent waits for approval before it writes code.
• Code review. A diff block shows a change with each finding as a comment on its lines and its options on the card. The doc stores only the git range (gitdiff.py writes it); the server expands it from git on each render, falling back to gh pr diff. GitHub review threads come in through ghthreads.py.
• Designs on a board. Screens for a watch, phone, tablet, desktop window or browser, side by side on a pan-and-zoom board, at sketch, wireframe or hi-fi fidelity. Comment on a button, draw a box to ask for a new screen, compare a screen with an earlier revision, then Approve design.
• Design navigation and editing. A tappable element names the screen it opens. The board draws each link as a connector routed around the screens, and Present follows the taps. Drag a link's end to another screen, draw a new link, move screens or press Tidy up: each edit is a draft that goes to the agent with Request changes, as a build.py patch command that writes it into the doc.
• Edit text and delete elements on the board. In Edit (E) on a design, presentation or website, double-click a screen's text to change it in place, or select an element and press Delete. Each change is a plain-text draft the agent applies, with a patch command for screen files and the source file for a live page. ⌘Z and ⇧⌘Z (Ctrl+Z, Ctrl+Y) undo and redo every draft, moves and Tidy up included, from one history per doc that survives a reload. A deck's Export to… can include the unapplied edits.
• App icons. --icons adds an icon artboard of SVG layers. The board shows the iOS light, dark and tinted icons, Android's masks and themed icon, the store icons and four home screens. Export writes every PNG with Contents.json and the adaptive-icon XML.
• Presentations. build.py new presentation scaffolds a deck of 16:9 slides with speaker notes. Present plays them full-window: ← → to step, N for notes, Esc to leave. Then Approve presentation or Request changes.
• Websites. build.py new website --url http://localhost:4321/ puts a site's pages on a board, live from its dev server through a local proxy, hot reload included. Switch every page between desktop, tablet and mobile widths, pick between versions of a section in place, and point at anything: each comment carries its section's source file and the width you saw it at. Then Approve website.
• Store listings. build.py new storelisting lays out an app's Google Play and App Store pages: every device's screenshot set at its store size and maximum, the icon and feature graphic, the store text with live counters, each locale with its machine-translated strings badged until accepted. Screenshots come from HTML mock-ups, from capture.py on simulators, emulators or headless Chrome, or from PNGs you drop; the build checks every store rule. Edit any store text or caption in place and Save it as a draft the agent writes in, pick caption styles, the font and colors, compare A/B treatments and custom pages, then Approve listing and export the fastlane ZIP.
• HeroUI and Tailwind ship with the skill. A screen uses the plain kit, HorizonUI, HeroUI with Tailwind, Tailwind alone or your project's own CSS, all offline.
• Your input stays on your machine. Ticks, picks, comments and replies live in ~/.bluedoc/state.db, a SQLite file the server owns, never in the repo. Only a browser that opened a link from serve.py open or serve.py unlock can save. Design screens run sandboxed, with no network; a website's live pages load only from its dev server on this machine.
• JSON only. serve.py renders each doc from its JSON on every request; agents never write the page HTML. build.py -o writes a standalone HTML file when you need to send one.
• Readable pages. Light and dark theme, adjustable text width, clean print, keyboard and screen-reader outline. The build flags filler, vague words, long sentences and checklist items that don't start with a verb.

Built examples to open in a browser: acme-orders.html (architecture and runbook), acme-review-findings.html (review findings for two PRs), acme-saved-carts-plan.html (a plan to approve), acme-status.html (a weekly status page) and acme-site.html (a website board; its live page needs the server). Download the file, then open it; GitHub shows HTML as source. Their JSON sources sit in skills/bluedoc/examples/, with the design board (acme-fit-design.bluedoc.json), the deck (acme-fit-deck.bluedoc.json) and the store listing (acme-fit-listing.bluedoc.json). serve.py open <json> opens any of them.

Install

Pick your agent. Each one installs the same skill from this repository.

Claude Code

claude plugin marketplace add andreiverdes/bluedoc
claude plugin install bluedoc@bluedoc

Inside a session the same commands are /plugin marketplace add andreiverdes/bluedoc and /plugin install bluedoc@bluedoc. Start a new session to load the skill.

Plan mode. With the plugin installed, every plan Claude finishes in plan mode opens as a bluedoc plan page in your browser. Claude waits for your answer on the page, revises the doc on Request changes and leaves plan mode once you Approve plan. If the plan names a *.bluedoc.json Claude already wrote, that doc opens; otherwise the plan is imported into ~/.bluedoc/plans/<project>/. The gate stays out of the way in CI, over SSH without a display and in bypassPermissions mode, and BLUEDOC_PLAN_GATE=0 turns it off; in those cases, and on any error, Claude Code shows its own plan dialog. Plannotator installed too means two reviews open for one plan. The other agents below share this gate, each through its own hook.

Codex

codex plugin marketplace add andreiverdes/bluedoc
codex plugin add bluedoc@bluedoc

Restart Codex. The skill is listed as bluedoc:bluedoc; mention it with $bluedoc or let Codex pick it from your request.

Plan mode. The plugin's Stop hook opens the plan Codex proposes in Plan mode (/plan) as a bluedoc plan page; Codex waits for your answer on the page, revises the doc on Request changes and, after Approve plan, goes on with your decisions. Codex runs a plugin's hooks only once you trust them: open /hooks and trust the bluedoc Stop hook (again after an update changes it).

The sandbox. In Codex's default workspace-write sandbox, every serve.py wait (it calls the server on 127.0.0.1) and build.py patch (it writes ~/.bluedoc) asks you to approve running outside the sandbox. A plugin can't widen the sandbox, so to skip those prompts add this to ~/.codex/config.toml (Codex sandbox settings):

[sandbox_workspace_write]
writable_roots = ["~/.bluedoc"]
network_access = true

network_access lets sandboxed commands reach any host. To allow only the local server, use a permissions profile instead (beta; it replaces sandbox_mode and [sandbox_workspace_write]):

default_permissions = "bluedoc"

[features]
network_proxy = true

[permissions.bluedoc]
extends = ":workspace"

[permissions.bluedoc.filesystem]
"~/.bluedoc" = "write"

[permissions.bluedoc.network]
enabled = true

[permissions.bluedoc.network.domains]
"127.0.0.1" = "allow"

pi

pi install git:github.com/andreiverdes/bluedoc

Restart pi. Run it as /skill:bluedoc or let pi pick it from your request.

The plan gate: /bluedoc-plan-mode [file.md] turns on plan mode; the agent writes its plan and calls bluedoc_submit_plan, which opens it as a bluedoc page and returns your approval or change request. /bluedoc-<name> commands come from the bundled extension.

omp

omp plugin marketplace add andreiverdes/bluedoc
omp plugin install bluedoc@bluedoc

Added the marketplace before? Run omp plugin marketplace update bluedoc first: omp installs from its cached catalog.

Run /reload-plugins in an open session, or start a new one.

The plan gate: the bundled extension opens omp's plan reviews as bluedoc pages: Approve executes the plan, Request changes refines it; the terminal picker stays live. The /bluedoc-<name> commands come from the extension too.

Copilot CLI

copilot plugin install andreiverdes/bluedoc

Start a new session. Plan mode: when Copilot calls exit_plan_mode, its plan.md opens as a bluedoc plan page; Copilot waits for your answer there and leaves plan mode after Approve plan. If the gate takes longer than its 120 s timeout, Copilot shows its own plan prompt.

Antigravity CLI

git clone https://github.com/andreiverdes/bluedoc.git
agy plugin install bluedoc/antigravity

Restart agy. antigravity/ is the Antigravity plugin: its manifest, its hooks and the skill (a link to skills/bluedoc, copied on install). Plan mode (agy --mode plan or /plan): when the agent writes its implementation plan for your review, the plan opens as a bluedoc plan page instead; the agent waits for your answer there, revises the doc on Request changes and, after Approve plan, writes the plan again and implements it with your decisions. agy asks you before each serve.py wait and build.py patch the gate runs.

Any other agent

With the skills CLI:

npx skills add andreiverdes/bluedoc

Or copy the skill folder by hand. Codex, pi and omp read ~/.agents/skills; Claude Code reads ~/.claude/skills.

git clone https://github.com/andreiverdes/bluedoc.git
ln -s "$PWD/bluedoc/skills/bluedoc" ~/.agents/skills/bluedoc

Requirements

• Python 3.9 or later on PATH (the build and diff scripts use the standard library only).
• git, for code reviews.
• gh, signed in, only for importing GitHub review threads or diffing a PR whose repo isn't checked out.

Use

Ask in plain words. The skill triggers on requests for HTML docs, architecture pages, walkthroughs, runbooks, status pages, plans, browsable reviews, UI mockups, slide decks, website reviews, app icons and store listings.

• "Write a bluedoc of how a request flows through this service."
• "Make a runbook for setting up the local stack, as a bluedoc with checklists."
• "Review PR 412 and give me a bluedoc where each finding sits on its code."
• "Put the open review threads on PR 412 in a bluedoc so I can decide what to do with each."
• "Plan saved carts as a bluedoc and wait for my approval."
• "Mock up the sign-in screen for the phone and the web as a bluedoc design."
• "Make a five-slide launch review deck as a bluedoc presentation."
• "Open our marketing site as a bluedoc website so I can comment on it."
• "Design the app icon for iOS and Android in the bluedoc design."
• "Make the App Store and Google Play listing for our app as a bluedoc, in English and Spanish."

The agent scaffolds docs/<topic>/<name>.bluedoc.json from the type's skeleton (the only file it edits, plus any images the doc shows and a design's screen files; the revision history <name>.bluedoc.history.json and a review's diff cache <name>.diffcache.json sit next to it), fills it in, validates it and opens it on the local server:

python3 <skill>/scripts/build.py new plan docs/plans/saved-carts.bluedoc.json --title "Saved carts"   # skeleton with <<…>> to fill
python3 <skill>/scripts/build.py docs/plans/saved-carts.bluedoc.json        # validate, record the revision
python3 <skill>/scripts/serve.py open docs/plans/saved-carts.bluedoc.json   # start the server, print the URL (with a key good for an hour)

When you send comments back, the agent revises one object at a time, and the revision bumps itself:

python3 <skill>/scripts/build.py patch docs/plans/saved-carts.bluedoc.json item:decisions/retention \
  --set recommend=d90 --change "Retention: recommend 90 days, as asked."

Every doc the server knows is listed at http://127.0.0.1:8740/. When another program already holds port 8740, the server takes the next free port up to 8759, and the links serve.py open prints carry it; set BLUEDOC_PORT to pin a port of your own. Edit the JSON and reload; there is no build output to keep in sync. For a file you can send to someone, add -o <name>.html to the build command.

Per doc, the agent reads about 1.5k tokens of instructions (SKILL.md) plus one type guide (types/<type>.md), and greps the schema only for the fields it needs.

<skill> is the installed skill folder, for example ~/.agents/skills/bluedoc.

Slash commands

Every bluedoc feature is also a command. The prompt commands start an agent turn with the skill; the action commands run a script and show its output.

Command	What it does
/bluedoc-plan <what>	writes a plan doc, opens it and waits for your approval or changes
/bluedoc-review [PR, branch or paths]	reviews code (default: uncommitted changes) as a review doc
/bluedoc-docs <what>	documents a system, flow or runbook
/bluedoc-design <screens>	designs UI screens on a board
/bluedoc-deck <topic>	makes a slide deck
/bluedoc-website <URL>	opens a website from its dev server for review
/bluedoc-icons <app>	designs an app icon
/bluedoc-listing <app>	lays out the Google Play and App Store listing
/bluedoc-status <project>	writes a status page
/bluedoc-last [notes]	turns the agent's previous reply into a docs page
/bluedoc-open <doc>	opens a doc in the browser
/bluedoc-home	opens the home page in your default browser, with a link that lets that browser save
/bluedoc-replies [doc]	prints the newest reply to the doc, or to any doc
/bluedoc-export <doc> [format]	writes the doc's file next to it: a deck (html, pdf), a listing (zip, folders, pdf, html) or a page (html)

Agent	How you run them
Claude Code	/bluedoc:bluedoc-plan …; Claude Code prefixes plugin commands with the plugin name
omp, pi	/bluedoc-plan …, from the bundled extension
Copilot CLI	/bluedoc-plan …; an action asks the agent to run its script
Antigravity CLI	/bluedoc-plan …; each command is a skill, and an action asks the agent to run its script
Codex	no commands; ask for $bluedoc <request>, e.g. $bluedoc plan saved carts

The commands are generated from commands/commands.json by tools/gen_commands.py; edit the spec and run it, never the generated files.

Design mockups

A design doc is a brief and one board of screens. Each screen is an HTML fragment in <name>.design/<artboard id>.html beside the JSON; the server wraps it in the chosen kit (plain, HorizonUI, HeroUI with Tailwind, Tailwind or your own CSS) and runs it sandboxed. Screens link to each other with data-nav, and --icons adds an app-icon sheet with PNG export. A presentation is the same page with a board of slides only; a website, with a board of web pages, live from the dev server or mocked up as screens.

Frameworks, navigation, board editing, app icons and the sandbox are covered in docs/types/design.md; decks in docs/types/presentation.md; live sites in docs/types/website.md; store listings in docs/types/storelisting.md.

Update and remove

Agent	Update	Remove
Claude Code	claude plugin marketplace update bluedoc then claude plugin update bluedoc@bluedoc	claude plugin uninstall bluedoc@bluedoc
Codex	codex plugin marketplace upgrade bluedoc	codex plugin remove bluedoc@bluedoc
pi	pi update --extension git:github.com/andreiverdes/bluedoc (plain pi update updates pi itself, not its packages)	pi remove git:github.com/andreiverdes/bluedoc
omp	omp plugin marketplace update bluedoc && omp plugin upgrade bluedoc@bluedoc (omp upgrades from its cached catalog, so refresh it first)	omp plugin uninstall bluedoc@bluedoc
Copilot CLI	copilot plugin update bluedoc	copilot plugin uninstall bluedoc
Antigravity CLI	git -C bluedoc pull && agy plugin install bluedoc/antigravity	agy plugin uninstall bluedoc
skills CLI	npx skills update	npx skills remove bluedoc

What's in the repo

skills/bluedoc/
  SKILL.md               the workflow card the agent reads first
  types/<type>.md        one guide per doc type: plan, review, docs, design, presentation, website, storelisting, other
  references/schema.md   every JSON field and command, for lookup
  references/kits.md     the plain kit's classes, HorizonUI in a screen, bringing your own framework, the store shot kit
  assets/skeletons/      fill-in skeleton per doc type (build.py new), plus review-area.json (--shape area)
  scripts/build.py       new, validate, lint, patch, from-md (a Markdown plan → a plan doc), build the HTML
  scripts/mdplan.py      the Markdown plan importer behind build.py from-md
  scripts/hook.py        agent hooks: the plan gate for Claude Code, Codex, Copilot CLI and Antigravity CLI, `ext open|wait` for the pi/omp extension, Claude's Bash allowance
  scripts/listing.py     store listings: the rules file, store checks, l10n, sections and variants, the fastlane export plan
  scripts/capture.py     store screenshots from capture recipes: simctl, adb and emulator, headless Chrome
  scripts/fonts.py       the fonts installed on this machine, for a listing's caption font
  scripts/gitdiff.py     git range + findings -> diff block (a git reference)
  scripts/diffref.py     expands diff references from the cache, git or gh
  scripts/migrate.py     one-off: embedded diffs -> references, reports contract gaps; --decks: slide-only designs -> presentations
  scripts/ghthreads.py   GitHub review threads -> findings + diff comments
  scripts/serve.py       local server: renders docs and design screens, proxies a website's dev server, home page, answers and change requests
  scripts/statedb.py     the reader's input and replies in ~/.bluedoc/state.db (SQLite)
  assets/template.html   the page runtime (styling, canvas, checklists, diff browser, design board, annotator)
  assets/board-geo.js    board layout and orthogonal edge routing, shared by design boards and blueprint canvases
  assets/home.html       the home page (HorizonUI)
  assets/store-rules.json  every store set, asset, text limit, variant and locale rule, each with its source and date
  assets/listing.html    a listing's HTML export and its print view (the PDF)
  assets/kits/           what a design screen is wrapped in: shell, plain kit CSS, wireframe CSS, inspector (also injected into live website pages), the store shot kit and its styles
  assets/kits/icon-sheet.*  the app-icon sheet: every iOS and Android tile, drawn from the icon's layers
  assets/vendor/         files the pages load from the local server, never the network:
    horizon-ui/          HorizonUI browser build (Apache-2.0, see its NOTICE)
    heroui/              HeroUI's CSS and Tailwind's browser build, for design screens
    hero/                the home page's pixel-art banners, dark and light
    fonts/               the sketch hand font, Inter (store shot captions) and Lexend's licence (Lexend-OFL.txt), all OFL-1.1
  examples/              Acme examples (JSON, history, diff cache, the review's git bundle)
  examples/*.design/     the design, deck, website and store listing examples' screen files
  examples/*.listing/    the store listing example's captures (capture.py writes them; uploads go here too)
  examples/media/        images the examples show (media blocks)
docs/types/              one page per doc type, for GitHub readers
docs/media/              the screenshots those pages and this README show
docs/examples/           the examples built to HTML, for GitHub readers
commands/commands.json   the slash commands' spec, the one place they're edited
commands/bluedoc-*.md    Claude Code's commands, generated by tools/gen_commands.py
com.github.copilot/commands/  Copilot CLI's commands, generated
antigravity/skills/bluedoc-*/  Antigravity CLI's commands (skills), generated
tools/gen_commands.py    writes every agent's command files from the spec (--check: are they up to date)
tests/                   the test suite (python3 -m unittest discover -s tests)
.claude-plugin/          Claude Code plugin and marketplace (omp reads it too)
hooks/hooks.json         Claude Code hooks: the plan gate (omp doesn't run them)
codex/hooks.json         Codex hooks: the plan gate (Stop), wired from .codex-plugin/plugin.json
.codex-plugin/plugin.json  Codex plugin manifest (skills, hooks)
.plugin/plugin.json      Copilot CLI plugin manifest (skills, com.github.copilot/ commands and hooks)
com.github.copilot/hooks/  Copilot CLI hooks: the plan gate (preToolUse on exit_plan_mode; agentStop after an approval)
antigravity/             Antigravity CLI plugin: manifest, hooks.json (the plan gate), skills/ (the commands and a link to the skill)
extensions/bluedoc.ts   pi and omp extension: the plan gate and /bluedoc-* commands
.agents/plugins/         Codex marketplace
package.json             pi package manifest (skills, extension)
LICENSE                  MIT
TRADEMARK.md             what the bluedoc name and logo may be used for
CONTRIBUTING.md          DCO sign-off, tests, generated commands

The examples describe Acme Corp, a fictional company.

License

bluedoc's core is MIT and stays MIT: every version in this repository, now and later. A separate paid app, bluedoc Desktop, is planned. It will live in its own repository under its own license and doesn't change anything here. The MIT license covers the code, not the bluedoc name, wordmark or logo; see TRADEMARK.md. Contributions come in under MIT with a DCO sign-off; see CONTRIBUTING.md.

bluedoc's own code: MIT (LICENSE). The vendored HorizonUI build under skills/bluedoc/assets/vendor/horizon-ui/ is Apache-2.0 (its LICENSE and NOTICE), and the Inter and JetBrains Mono fonts it ships are OFL-1.1 (its THIRD_PARTY_NOTICES.md). Under skills/bluedoc/assets/vendor/heroui/, Tailwind's browser build (@tailwindcss/browser 4.3.3) is MIT, and HeroUI's CSS (@heroui/styles 3.2.6) declares MIT in its package.json while its LICENSE file is the Apache-2.0 text; both licence files sit in licenses/ there, unchanged. The Architects Daughter hand font and Inter (the store shots' default caption font) under skills/bluedoc/assets/vendor/fonts/ are OFL-1.1 (their licence files sit beside them). The bluedoc wordmark is "bluedoc" set in Lexend Bold and outlined to paths in home.html and template.html; Lexend is OFL-1.1 (vendor/fonts/Lexend-OFL.txt). The manifests declare MIT AND Apache-2.0 AND OFL-1.1, which covers both readings.