Skip to content

v1.0 · Agent skill · Local · MIT

Point, pick, approve.
Your agent does the rest.

bluedoc turns plans, code reviews, architecture docs, UI designs, slide decks and store listings into interactive pages. Comment on any element, pick an option, approve. Your agent reads the answers and gets on with it.

InstallView on GitHub
claude plugin marketplace add andreiverdes/bluedoc
claude plugin install bluedoc@bluedoc
Notes and requirements ↓

Why a page

A chat asks you to reply in prose.

Agents answer in walls of text and wait for a reply in prose. A bluedoc page asks you the questions and keeps your answers.

  • 8Doc typesDocs, plans, reviews, designs, decks, sites, store listings and more.
  • 6Agent pluginsClaude Code, Codex, pi, omp, Copilot CLI, Antigravity CLI. Any other through the skills CLI.
  • 1JSON file per docThe server renders the page from it; no HTML to keep in sync.
  • 0AccountsIt runs on 127.0.0.1, MIT, with no hosted service.

With bluedoc

Point, pick, approve, and your agent reads every answer.

See how it works

One home for every doc

Every doc your agent writes, in one place.

The local server lists each doc with its type, status and revision. Filter by type or status, browse projects in the sidebar, and open a doc to read, comment and decide.

The bluedoc home page in dark mode: the pixel-art banner behind the title and search field, filter chips by type and status, the sidebar of projects and the doc cards.

How it works

One loop, from draft to approved.

The agent writes, you answer on the page, the agent revises. Each round is a revision you can compare with the last.

  1. saved-carts.bluedoc.json
    {  "title": "Acme Shop: saved carts",  "meta": { "type": "plan", "rev": "1" },  "sections": [{    "title": "Open questions",    "blocks": [{      "type": "checklist", "id": "decisions",      "items": [{        "id": "retention", "recommend": "d180",        "text": "How long does a saved cart stay?",        "choices": [          { "id": "d90", "label": "90 days",            "md": "Half the storage." },          { "id": "d180", "label": "180 days",            "md": "Most reorders fit." },          { "id": "forever", "label": "Until deleted",            "md": "No sweeper." }
    01 / 05

    Agent writes

    One JSON file

    One JSON file. The local server renders it as a page; no HTML to keep in sync.

  2. 02 / 05

    You mark up

    Pins · passages · drawings

    Pin a comment on any element, a selected passage or a box you draw.

  3. 03 / 05

    You decide

    Option rows · ★ recommended

    Pick an option per question. The agent’s recommendation is starred.

  4. 04 / 05

    Agent revises

    Revisions · word by word

    It edits one part at a time and marks the comments it resolved.

  5. 05 / 05

    You approve

    Approved · rev 1

    Approve the current revision; the agent waits for it before it writes code.

Doc types

Eight kinds of page, one way to answer them.

Each type has its own layout and its own decisions. Comments, revisions and approval work the same on all of them.

01 / 08

Docs

Architecture pages, walkthroughs, runbooks, setup guides and change proposals.

  • A zoomable blueprint canvas, nested up to 3 levels
  • Animated flows: a request, an event, a data path
  • Checklists whose ticks the local server keeps
Open the Docs page
The Acme orders doc: the order path canvas zoomed into the orders-api system, playing step 3 of a flow.

Features

Built for answering, not just reading.

Six things every doc type does, from the first comment to the approval.

See every feature

  • Comments that become conversations

    Point at an element, select a passage or draw a box. Each note, item and general comment is a thread the agent replies in.

  • Options as rows, recommendation starred

    Each option explains itself in a line. Pick one, or several where a question allows, or Accept recommended to take every starred option.

  • Revisions you can compare

    Every build is a revision. Compare any two: new, changed and removed parts are marked in place, word by word.

  • Approve, and the agent proceeds

    Plans, designs, decks and store listings wait for approval on the current revision. Request changes sends them back.

  • Your input stays on your machine

    Ticks, picks and comments live in a local SQLite file the server owns, never in the repo. Screens run sandboxed, with no network.

  • Works with your agent, plan mode too

    Claude Code, Codex, Copilot CLI, Antigravity CLI, pi and omp install it as a plugin, with /bluedoc-* commands. In plan mode, the plan opens as a page and waits for your approval.

JSON in, page out

The agent writes JSON. You get a page.

Agents never write page HTML. The server renders each doc from its JSON on every request, so an edit and a reload is the whole build.

saved-carts.bluedoc.json
{  "title": "Acme Shop: saved carts",  "meta": { "type": "plan", "rev": "1" },  "sections": [{    "title": "Open questions",    "blocks": [{      "type": "checklist", "id": "decisions",      "items": [{        "id": "retention", "recommend": "d180",        "text": "How long does a saved cart stay?",        "choices": [          { "id": "d90", "label": "90 days",            "md": "Half the storage." },          { "id": "d180", "label": "180 days",            "md": "Most reorders fit." },          { "id": "forever", "label": "Until deleted",            "md": "No sweeper." }        ]      }]    }]  }]}
Rendered by the local server
The rendered Acme saved carts plan: the retention question with its options 90 days, 180 days (starred) and Until deleted.

Install

Pick your agent.

Each one installs the same skill from the GitHub 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.

Needs
  • Python 3.9 or later on PATH
  • git, for code reviews
  • gh, only to import GitHub review threads

FAQ

Questions, answered.

01Is it free?

Yes. bluedoc is open source under the MIT licence. There is no account, no subscription and no hosted service.

02Which agents does it work with?

Claude Code, Codex, Copilot CLI, Antigravity CLI, pi and omp install it as a plugin, with a plan-mode gate and /bluedoc-* commands. Any other agent that reads skills can get it with the skills CLI (npx skills add andreiverdes/bluedoc) or a copy of the skill folder.

03Where does my data live?

On your machine. Ticks, picks, comments and replies live in ~/.bluedoc/state.db, a SQLite file the local server owns, never in the repo. Only a browser that opened a link from the server can save.

04Does it need an internet connection?

No. The server runs on 127.0.0.1 and serves its fonts, styles and UI kits itself. Design screens run sandboxed with no network. Only importing GitHub review threads, or diffing a PR whose repo isn’t checked out, calls gh.

05Can I export a doc?

Yes. Add -o name.html to the build command for a standalone HTML file you can send to someone. Decks also export as PDF, and store listings as a fastlane ZIP, a plain-folders ZIP, a PDF or HTML.

06What licence is it under?

bluedoc’s own code is MIT. The vendored HorizonUI build is Apache-2.0, and the fonts it ships are SIL OFL 1.1. The repository’s README lists every third-party licence.

Approved · rev 1

Answer your agent
on a page.

Install the skill, ask your agent for a plan, and answer it on a page.

Star on GitHubInstall