Minerva: Human-agent Collaborative Slides

Slides live as a portable JSON file (deck.json) inside a Minerva project. Humans drag, type, and style in a WYSIWYG canvas. Claude Code, running in the same folder, edits the same file.

💥 News

• [2026-05-19] Initial release of Minerva! Try it out and let us know any issues or feature requests. Open issues and we will fix them asap.

Setup

Clone the repo, then pick whichever flow fits how you work. The first run installs dependencies and builds (~30s); after that, ./minerva is instant.

git clone https://github.com/arijitray1993/minerva.git my-slides
cd my-slides

A. Paste into Claude Code (recommended)

claude

> Run `./minerva` in the background, then read MINERVA.md and follow it.

Claude starts the server, opens the editor in your browser.

B. Run it yourself, then open Claude

./minerva
# in another terminal:
claude

Either way, the cloned dir now contains your deck alongside the editor source:

deck.json       slide content (live-reloaded on edit)
assets/         images (drop files here or paste/upload in the UI)
comments.json   feedback you leave for Claude from the editor
MINERVA.md      the rules Claude follows when editing this deck
.minerva/       per-slide PNG previews + the server's port breadcrumb
packages/       editor source — off-limits to Claude

The editor URL prints to the terminal — by default http://localhost:5174, but Minerva auto-walks forward (5175, 5176, …) if that port is taken, so you can run multiple decks side-by-side without conflict.

Multiple decks

Each deck is its own cloned folder. Clone again into a different directory:

git clone https://github.com/arijitray1993/minerva.git deck-research
git clone https://github.com/arijitray1993/minerva.git deck-talk
cd deck-research && ./minerva &     # picks 5174
cd ../deck-talk    && ./minerva &   # picks 5175 (5174 is busy)

Both servers know their own port via .minerva/server.json, so Claude's ./minerva render slide-1 always talks to the right one. No --port juggling.

What this gives you

• A real WYSIWYG editor. 30 shapes, rich text (font, size, color, bold/italic/underline/strike, super/sub, highlight, alignment), tables, images via drag-drop / paste / upload, drop shadows, corner radius, opacity, layer ordering, group/ungroup, zoom + pan, undo/redo, format painter.
• Claude as a competent collaborator. Right-click any element → "Leave Claude comment…" to scope a request. Claude reads comments.json on session start, edits deck.json, renders the slide to PNG, looks at the PNG, and iterates against the actual rendered output — not a hallucinated HTML preview.
• One file is the whole deck. deck.json is portable. Diff it, commit it, copy it between machines. No database, no SaaS account, no lock-in.
• PDF export that looks like the canvas. Playwright drives the same /print route to produce a faithful, slide-only PDF.

Quick How-To's

Right click to leave a comment for claude

Simply select elements and right click to leave a comment for claude to work on.

Use template skills

• CVPR 2026 Poster skill: Simply ask Claude to look at templates/CVPR26_POSTER_SKILL.md.

More coming soon...

Quick shortcuts

• Select multiple items: Cmd/Ctrl + click and drag a marquee, or Shift + click to add/remove from the current selection.
• Move canvas: Hold Space, then click-and-drag anywhere.
• Zoom in/out: Cmd/Ctrl + scroll wheel zooms toward the cursor. Cmd/Ctrl + = / - zoom from the center, Cmd/Ctrl + 0 resets to fit.
• Move elements: Drag with the mouse, or select and use arrow keys (1 px; Shift + arrow = 10 px).
• Crop images: Double-click an image to enter crop mode; drag the handles, Esc (or click outside) to exit.
• Edit text inline: Double-click a text element to type/format directly on the canvas.
• Copy / paste: Cmd/Ctrl + C, Cmd/Ctrl + V — duplicates with a small offset. Works across element types.
• Delete: Select + Delete/Backspace.
• Undo / redo: Cmd/Ctrl + Z, Cmd/Ctrl + Shift + Z.

Requirements

• Node 18 or newer.

• A Chromium build, used by PDF export and PNG rendering. Minerva looks for one in this order:

  1. $MINERVA_CHROMIUM env var
  2. Playwright's cache (~/.cache/ms-playwright/chromium-*)
  3. System Chrome / Chromium (/Applications/Google Chrome.app, /usr/bin/google-chrome, etc.)

  If none of these resolve, install one with:

  npx playwright install chromium

./minerva — what it does

./minerva                          # start the editor with the deck at the repo root
./minerva start [dir]              # explicit deck dir
./minerva render <slide-id|all>    # render via the running server (auto-detects port)
./minerva init [dir]               # just scaffold deck.json, MINERVA.md, etc.
./minerva --port 5180              # pin to a specific port (fails if busy)
./minerva --no-open                # don't open a browser tab

First invocation runs npm install + npm run build:workspaces. After a git pull that touched packages/, re-run npm run build:workspaces to pick up renderer changes.

Source layout

• packages/schema — Zod schema + types for deck.json and comments.json. The source of truth for the deck format.
• packages/server — Express + chokidar + ws + Playwright. Watches the deck, serves the UI, exports PDF, renders PNG previews.
• packages/web — Vite + React + Konva. The WYSIWYG editor.
• minerva — the shell entrypoint described above.
• scripts/build-publish.mjs — kept for a future npm publish; not used in the github-install flow.

Citation

If you use Minerva in academic work, please cite it. GitHub renders the machine-readable CITATION.cff at the repo root as a "Cite this repository" button at the top-right of the project page. For BibTeX:

@software{ray2026minerva,
  author  = {Ray, Arijit},
  title   = {Minerva: a JSON-backed slide editor for human + Claude collaboration},
  year    = {2026},
  url     = {https://github.com/arijitray1993/minerva},
  license = {MIT}
}

License

Minerva is released under the MIT License — free to use, modify, and redistribute, including in commercial projects. Just keep the copyright notice in copies and substantial derivatives.