deck

<p align="center">
  <a href="https://deck.kadal.cc">
    <img src=".github/assets/hero.jpg" alt="Kadal Deck: a slide in the browser, and the audience page on a phone with reactions, pace and a raise-hand button" width="100%">
  </a>
</p>

<h1 align="center">Kadal Deck</h1>

<p align="center">
  <strong>Slides in MDX. A live room for your audience. One command to publish.</strong><br>
  Write the talk in the editor you already use, present it in a browser, and let the room follow,<br>
  react, ask and vote from their phones — nothing for them to install.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@kadal/deck"><img alt="npm version" src="https://img.shields.io/npm/v/@kadal/deck?color=0e7490&label=%40kadal%2Fdeck"></a>
  <a href="https://www.npmjs.com/package/@kadal/deck"><img alt="npm downloads a month" src="https://img.shields.io/npm/dm/@kadal/deck?color=0e7490"></a>
  <a href="https://github.com/kadalcc/deck/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/kadalcc/deck/ci.yml?branch=main&label=CI"></a>
  <a href="https://github.com/kadalcc/deck/releases"><img alt="Latest release" src="https://img.shields.io/github/v/release/kadalcc/deck?sort=semver&color=0e7490"></a>
  <a href="LICENSING.md"><img alt="Licence: AGPL-3.0-or-later" src="https://img.shields.io/badge/licence-AGPL--3.0--or--later-0e7490"></a>
  <a href="https://www.npmjs.com/package/@kadal/deck"><img alt="Node version" src="https://img.shields.io/node/v/@kadal/deck?color=0e7490"></a>
  <br>
  <a href="https://deck.kadal.cc"><img alt="deck.kadal.cc status" src="https://img.shields.io/website?url=https%3A%2F%2Fdeck.kadal.cc%2Fapi%2Fhealth&label=deck.kadal.cc&up_message=online&down_message=down"></a>
  <a href="https://decks.kadal.cc/@pmithunish/tour/"><img alt="Live demo" src="https://img.shields.io/badge/live%20demo-the%20tour-5eead4"></a>
  <a href="https://deck.kadal.cc/docs/"><img alt="Docs" src="https://img.shields.io/badge/docs-deck.kadal.cc-7dd3fc"></a>
  <a href="https://github.com/sponsors/pmithunish"><img alt="Sponsor Kadal Deck" src="https://img.shields.io/badge/sponsor-%E2%99%A5-db61a2?logo=githubsponsors&logoColor=white"></a>
</p>

<p align="center">
  <a href="https://deck.kadal.cc/docs/getting-started/">Get started</a> ·
  <a href="https://deck.kadal.cc/docs/">Docs</a> ·
  <a href="https://decks.kadal.cc/@pmithunish/tour/">Live demo</a> ·
  <a href="https://deck.kadal.cc/showcase/">Showcase</a> ·
  <a href="https://deck.kadal.cc/changelog/">Changelog</a> ·
  <a href="https://deck.kadal.cc/sponsor/">Sponsor</a>
</p>

---

## Why Kadal Deck

- **You write; it presents.** A talk is one `deck.mdx` file: Markdown, plus components when you
  need them. It lives in git, diffs cleanly and reloads as you type.
- **The room is part of the deck.** Your audience scans a QR code and follows along on their
  phones: reactions, questions with upvotes, polls, word clouds, timed quizzes, a pace dial and a
  raised hand, all built in. No add-on, no second app.
- **Any framework on a slide.** React and web components out of the box; Vue, Svelte, Solid,
  Preact, Qwik, Angular, Fresh, Rust/WebAssembly and Python as islands, each loaded only when its
  slide appears.
- **Familiar keys.** Slides split at `---` and `----` the way reveal.js and Slidev do, the
  presenter view opens on `S`, and the keyboard is vim-first.
- **Yours to run.** A built deck is a static site that works offline. Export it to PDF, PNG or
  PPTX, host it anywhere, or publish it with a live room in one command.

## Quick start

You need **Node 20.19+** and npm, pnpm, Yarn or Bun.

```sh
npm create @kadal/deck@latest my-talk
cd my-talk && npm install
npm run dev                  # edit deck.mdx; the slide you're on updates in place
```

```mdx
---
title: Hello, room
---

# Hello, room

---

## Clicks, one point at a time

<Clicks>

- Slides split at `---`, vertical ones at `----`
- Code steps line by line, and notes follow your clicks

</Clicks>

---

<Poll id="lunch" question="Lunch?" options={["Dosa", "Biryani", "Both"]} />
```

When it's ready:

```sh
npx kadal-deck build         # dist/ for any static host (everything but the live room)
npx kadal-deck export        # PDF in export/; add --png --pptx for those too
npx kadal-deck publish       # deck.kadal.cc/@you/my-talk/ with a live room (free plan)
```

## See it

<table>
<tr>
<th width="70%">The presenter view</th>
<th width="30%">The audience, on a phone</th>
</tr>
<tr>
<td valign="top"><img src=".github/assets/presenter.jpg" alt="Presenter view: the current slide, the next slide, notes with click markers, a timer and tools for drawing, pointer, spotlight, blackout, share window, camera and recording" width="100%"></td>
<td valign="top"><img src=".github/assets/phone.jpg" alt="The audience page: the presenter's slide, reactions, and buttons for pace and raising a hand" width="100%"></td>
</tr>
<tr>
<td valign="top">Current and next slide, notes that follow your clicks, a timer with pacing, drawing, laser, spotlight, blackout, a frameless share window for calls, and the room panel.</td>
<td valign="top">The slide in step with you (or roam ahead and catch up), reactions, questions, polls, quizzes, pace and a raised hand.</td>
</tr>
</table>

**[Open the tour →](https://decks.kadal.cc/@pmithunish/tour/)**: the engine's own feature deck, nine chapters
showing every layout, component, background, transition and view, with every framework island
running on one slide. Press `?` for the keys. Its source is [`examples/showcase`](examples/showcase),
and `node tools/showcase-check.mjs` drives every slide and view of it in a headless browser.

## Features

<table>
<tr>
<td valign="top" width="50%">

**Authoring**

- MDX with clicks (`<Click>`, `<Clicks>`, `at="+2"`), layouts and named slots
- Code that steps line by line, Shiki highlighting, magic move
- KaTeX maths and Mermaid diagrams
- Excalidraw sketches drawn in code, with guided steps
- Glossary term cards: the compiler links the first mention of each term
- 14 layouts, 30+ backgrounds (aurora, starfield, a wire globe…), transitions,
  auto-animate and motion

</td>
<td valign="top" width="50%">

**Presenting**

- Presenter view with notes, timer, next slide and tools
- A frameless share window for video calls; a projector mode that ignores stray input
- Overview, search, jump to slide, zoom, drawing, laser, spotlight, blackout
- Vim keys and Vimium-style `f` hints for everything clickable
- The same slide at any window size: authored at 1920 × 1080 and scaled, never reflowed

</td>
</tr>
<tr>
<td valign="top">

**The live room**

- The audience follows on their phones, or roams and catches up with one button
- Reactions, questions with upvotes, polls, ratings, word clouds, timed quizzes and a leaderboard
- Pace feedback and raised hands in the presenter's room panel
- Your drawings, confetti and shared term cards on every screen

</td>
<td valign="top">

**Shipping it**

- `kadal-deck build`: a static site for any host, working offline
- `kadal-deck export`: PDF, PNG and PPTX (one image per slide, notes attached)
- `kadal-deck publish`: hosted with a live room, analytics, passcodes and share links
- Publishes from CI with an API token; only changed files are uploaded

</td>
</tr>
</table>

## Use with AI agents

Kadal Deck is built to be written by an agent as well as a person: a skill that teaches the
format and the workflow, an MCP server that can edit slides precisely and **look at them**, and a
CLI whose every command answers in JSON.

**Claude Code plugin** (the skill and the MCP server together):

```text
/plugin marketplace add kadalcc/deck
/plugin install kadal-deck@kadal-deck
```

(On Claude Code 2.1.275 or later, `/plugin install kadal-deck --marketplace kadalcc/deck` does both.)

**The skill alone, for any agent** ([Agent Skills](https://agentskills.io) format, in
[`skills/kadal-deck`](skills/kadal-deck)): `npx skills add kadalcc/deck`

**The MCP server alone** — `kadal-deck mcp` speaks the Model Context Protocol on stdio. It works
on the deck in the folder it starts in (or `--dir <path>`; every tool also takes a `dir` inside
it). Tools never read or write outside that folder unless the server is started with
`--allow-outside`.

```sh
claude mcp add kadal-deck -- npx -y @kadal/deck mcp          # Claude Code
```

```jsonc
// Claude Desktop (claude_desktop_config.json) and Cursor (.cursor/mcp.json)
{ "mcpServers": { "kadal-deck": { "command": "npx", "args": ["-y", "@kadal/deck", "mcp", "--dir", "/path/to/my-talk"] } } }

// VS Code (.vscode/mcp.json)
{ "servers": { "kadal-deck": { "type": "stdio", "command": "npx", "args": ["-y", "@kadal/deck", "mcp"] } } }
```

| tools | |
| --- | --- |
| `deck_reference`, `deck_frontmatter_schema` | every component, layout, background and option, from the engine's own catalog |
| `deck_create`, `deck_outline`, `deck_read_slide`, `deck_check` | scaffold, read the deck as structure, lint it |
| `slide_add`, `slide_update`, `slide_remove`, `slide_move`, `deck_update_frontmatter`, `notes_set` | edits that change only that slide's lines, linted on the spot |
| `slide_render`, `deck_preview` | PNG pictures of slides from a dev server kept running between calls, and a live URL for you |
| `deck_build`, `deck_export`, `deck_publish` | a static site, PDF/PNG/PPTX, and a published deck (with your saved `kadal-deck login`) |

It also serves the catalog, the reference and the guides as resources, and two prompts:
`draft_deck` (outline → finished deck) and `review_deck`. Rendering and export need Playwright
in the deck: `npm i -D playwright && npx playwright install chromium`.

**The CLI, for scripts and agents**: `kadal-deck check` (lint, exit 1 on errors),
`kadal-deck screenshot` (PNGs), `kadal-deck info [topic]` (the reference), `kadal-deck new <dir>`
(no questions asked); `--json` on every command prints one JSON object on stdout. Exit codes:
0 ok · 1 failed · 2 usage · 3 not