Lectern docs

Everything you need to run Lectern, connect models, drive it from other agents and build on its API.

Overview

Lectern turns a prompt, plus spreadsheets, documents and links, into a finished presentation. It has two parts that share one engine:

• server/: a FastAPI service with the agents, the layout engine, the Critic and the exporters. It stores everything in a local SQLite database.
• web/: a Next.js 15 app for the whole flow, from new deck to present mode.

The same engine is also an MCP server, so Claude Code, Codex, Cursor or Antigravity can make decks without the web app.

Quick start

You need Python 3.12+ with uv, and Node 20+ with pnpm.

git clone https://github.com/mrigankad/Lectern.git
cd Lectern

# 1. Backend · http://localhost:8000 (API docs at /docs)
cd server
uv sync
uv run uvicorn lectern.main:app --port 8000

# 2. Web app · http://localhost:3000 (in a second terminal)
cd web
pnpm install
pnpm dev

Open http://localhost:3000 and start a deck. With no keys, every agent uses the built-in offline provider: it writes a sensible deck from the prompt alone, with no network, so you can try the whole flow first.

Connect a model

Open Connections and models in the sidebar, add a key and press Test. Then pick a preset (Best quality, Balanced, Lowest cost) or choose a provider and model for each agent.

Keys are stored in your local database and the API never returns them. A role whose provider has no key falls back to offline.

How a deck is built

1. Brief. POST /api/decks with a prompt and optional audience, goal, length and sources.
2. Interview. The Strategist asks only the questions the brief leaves open. If audience, goal and length are already set, it skips straight to the outline.
3. Outline. You edit and reorder the headlines, then approve. Nothing is built before approval.
4. Build. Slides are built three at a time: Writer, Art Director, Renderer, then Critic. You can pause and resume.
5. Review. A slide with a high or medium finding goes back to the Writer once and is checked again.
6. Edit and export. Ask for changes in chat, edit directly, then export.

Every step is recorded as a run with a one-sentence summary, which feeds the live activity view.

The agents

Your rules ("never use the word synergy", "always show currency in USD") are added to every agent prompt. A rule that bans a word is also enforced by the lint.

Scene graph

A slide is typed JSON: a layout id plus nodes (headline, text, bullets, stat, chart, table, image, quote). The placer turns it into a RenderedSlide on a 1920×1080 canvas. The web canvas, PowerPoint, PDF and PNG are all drawn from that one rendered form, so every format matches. The full schema is in docs/SPEC.md.

The Critic

The Critic runs without a model. Its rules:

• Story: long or topic-only headlines, missing notes, placeholder text left on a slide.
• Design: text overflow, text that is too small, more than five bullets, long bullets, low contrast, the wrong chart for the data.
• Accuracy: a number in the text or notes that differs from the slide's chart or stat value.
• Your rules and brand: banned words, brand colours, fonts and minimum sizes.

Each slide starts at 100 and loses points by severity; the deck score is the mean, with Story, Design and Editability sub-scores. For each finding you can Fix it, or Keep it, which adds a rule so the Critic stops raising it.

Undo

• Slide undo takes back the latest change to a slide, whoever made it, one version at a time.
• Ask undo (under a chat reply) reverts exactly what that request changed. If you edited a field again afterwards, your later edit is kept.

Removed slides are not restored yet.

Data and charts

Attach spreadsheets, CSVs, documents or links as sources. Charts and stats link to sheet ranges. Refresh from sheet re-reads them and also rewrites matching figures in headlines, text and notes; anything it can't trace to a single changed cell is flagged for you.

Brand kits

Upload a .potx or .pptx (and optionally a brand PDF). Lectern reads the colour scheme, fonts, logos and layouts, builds a theme, and suggests rules the Critic checks. A branded deck's PowerPoint export is built on your template's master.

Images and video

Export

• PPTX: native text boxes, tables and charts you can edit in PowerPoint, with speaker notes.
• PDF: vector, 960×540 pt pages, Urbanist embedded, optional notes pages.
• Images: a zip of 1920×1080 PNGs.
• Notes: a Markdown speaker script.

Every export comes with a report that counts editable objects, charts, tables and pictures. Urbanist isn't embedded in PPTX files, so a machine without the font shows a fallback; the PDF always looks right.

MCP server

Lectern runs as an MCP server in two ways, on the same engine and database:

• stdio: uv --directory /path/to/server run lectern-mcp. The agent starts Lectern itself.
• HTTP: http://localhost:8000/mcp, served by the running API. Builds show live in the web app.

Claude Code

claude mcp add lectern -- uv --directory "/path/to/Lectern/server" run lectern-mcp
# or, with the API running
claude mcp add --transport http lectern http://localhost:8000/mcp

Claude desktop, Cursor, Gemini CLI, Antigravity

{
  "mcpServers": {
    "lectern": {
      "command": "uv",
      "args": ["--directory", "/path/to/Lectern/server", "run", "lectern-mcp"]
    }
  }
}

Codex

# ~/.codex/config.toml
[mcp_servers.lectern]
command = "uv"
args = ["--directory", "/path/to/Lectern/server", "run", "lectern-mcp"]

The web app's Claude Code and agents page shows these with your machine's path filled in.

Tools

create_deck, get_interview, answer_interview, skip_interview, get_outline, update_outline, regenerate_outline, approve_outline, get_status, wait_until_ready, get_critic_report, fix_findings, ask, edit_slide, list_decks, export_deck. Resources: lectern://decks/{id} and lectern://decks/{id}/outline.

HTTP API

All routes are under /api and return JSON. Errors are an HTTP status plus { "detail": "..." } in plain language. Interactive docs are at http://localhost:8000/docs.

Events

GET /api/decks/{id}/events streams Server-Sent Events: deck.updated, outline.ready, slide.updated, run.updated (one plain sentence per agent step), message.updated, finding.updated, and a ping every 20 seconds.

Environment

Repository

Run the checks with cd server && uv run pytest (offline) and cd web && pnpm typecheck && pnpm lint.

Status

Lectern is early. Built and tested: the full flow from brief to export, chat edits and undo, the Critic, data sources, brand kits, share links, present mode and the MCP server. Not built yet: invite by email, comments, Google Slides export, restoring removed slides, and accounts. Paid image providers are wired in but need your own keys or credits.