kadal-deck

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.

Related MCP server: Presentation Agent MCP

Quick start

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

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

---
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:

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

Open the 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, and node tools/showcase-check.mjs drives every slide and view of it in a headless browser.

Features

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

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

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

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

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):

/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 format, in 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.

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

// 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"] } } }

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 signed in · 4 missing prerequisite.

Building your own tooling? @kadal/deck/catalog is everything a deck can use as data, @kadal/deck/authoring reads, lints and edits a deck as text (no Node APIs), and @kadal/deck/schema/frontmatter.json is the JSON Schema for frontmatter.

Islands, in any framework

Put a component from any of these on a slide. Each runtime is code-split and loads only when its slide appears; examples/showcase runs all eleven on one slide.

Packages

Every package is published from this repository's release workflow through npm trusted publishing, with provenance you can check on each npm page.

The live room: self-hosted or hosted

Everything one machine can do is free and stays free: writing, presenting, the presenter view, export and a static build. The live room needs a server that holds a WebSocket per deck.

• Host it yourself. The room protocol is typed in the engine (@kadal/deck/protocol) and documented endpoint by endpoint, so a room server you write against it can't drift from the client.

• Or use deck.kadal.cc. npx kadal-deck publish gives the deck a live room, analytics, passcodes, version history and teams. There's a free plan, and the paid plans fund the engine, the way Slides.com funds reveal.js.

Documentation

The engine's own reference, with every component and option, is in packages/deck/README.md.

Sponsors

Kadal Deck is made by @pmithunish, an independent developer in Chennai working as Kadal. Sponsorships go straight to the maintainer and pay for time on the open-source engine: issues, docs, new islands and the features you ask for. Become a sponsor →

One-time sponsorships of $10 and $50 are welcome too. Companies can sponsor by invoice.

Contributing

Bug reports with a small deck.mdx that reproduces them are the most useful thing you can send, and pull requests are welcome. CONTRIBUTING.md covers the setup (Bun 1.3+), the tests and the island verifier. Please follow the code of conduct, and report security issues privately as SECURITY.md describes.

Licence

AGPL-3.0-or-later, with a commercial licence for anyone who wants to build a hosted or proprietary product on the engine without publishing their changes. Presenting with it, self-hosting your own decks or embedding a deck in a site you publish triggers nothing. The details are in LICENSING.md.