<div align="center">

# AutoDemo

**Demos as code.** Turn any running web app into demo videos, interactive walkthroughs, and marketing captures — in one command. Regenerated by CI, so they can never go stale.

[![CI](https://github.com/praveen-palanisamy/autodemo/actions/workflows/ci.yml/badge.svg)](https://github.com/praveen-palanisamy/autodemo/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/@praveen-palanisamy/autodemo)](https://www.npmjs.com/package/@praveen-palanisamy/autodemo)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-agent--ready-7c5cff)](docs/AGENTS.md)

[Product page](https://praveen-palanisamy.github.io/autodemo/) · [Quick start](#quick-start) · [GitHub Action](docs/GITHUB_ACTION.md) · [For AI agents](docs/AGENTS.md) · [Recipes](docs/RECIPES.md) · [Contributing](CONTRIBUTING.md)

</div>

---

```bash
autodemo demo "Sign up and open the dashboard" --url http://localhost:3000
```

That single command drives a real browser through your real app and produces:

| Artifact | What it's for |
| --- | --- |
| `video.mp4` | launch posts, landing pages, PR descriptions — cursor, click rings, human-paced typing |
| `index.html` | static, embeddable **interactive walkthrough** (step screenshots + notes, keyboard navigable) |
| `assets/*.png` | **named marketing captures** of real UI regions, for homepages and decks |
| `run.json` | reproducible metadata — timings, steps, artifact contract for tooling |

The teaser below was generated by AutoDemo, about its own product page, in CI:

[![AutoDemo teaser](public/demos/site-landing/latest/steps/0001.png)](https://praveen-palanisamy.github.io/autodemo/demos/site-landing/latest/video.mp4)

## Why

Demos and screenshots rot the moment the UI changes. Re-recording them is manual, slow, and always last on the list. Interactive-demo SaaS tools fix freshness with $300–500/month plans, per-seat pricing, and a browser extension that captures snapshots into their cloud.

AutoDemo treats demos like the rest of your software:

- **Versioned** — scenarios are YAML in your repo, reviewed like code
- **Reproducible** — deterministic Playwright steps, or AI steps when you want speed
- **Continuous** — a [5-line GitHub Action](docs/GITHUB_ACTION.md) regenerates everything on merge; a failing demo is a failing user flow
- **Yours** — runs on your machine and your CI; no cloud, no telemetry, MIT licensed

## Quick start

**One-line install** (macOS / Linux / WSL — installs Bun, the CLI, and a browser):

```bash
curl -fsSL https://raw.githubusercontent.com/praveen-palanisamy/autodemo/main/install.sh | bash
```

Or zero-install / per-project:

```bash
bunx @praveen-palanisamy/autodemo --help          # Bun
npm add -D @praveen-palanisamy/autodemo           # or as a dev dependency
bunx playwright install chromium
```

### 1. The magic moment (AI-authored)

With any LLM key in your env (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`, `GROQ_API_KEY` — or a local `OLLAMA_HOST`, auto-detected):

```bash
autodemo demo "Sign up, create a project, open the dashboard" --url http://localhost:3000
```

Watch the browser do it, then open the printed `video.mp4` and walkthrough. Add `--save` to keep the scenario for replay.

### 2. Deterministic demos (no LLM needed)

```bash
autodemo init   # writes a commented .autodemo.yml
```

```yaml
scenarios:
  signup:
    description: "Signup with readable typing and click highlights"
    steps:
      - type: goto
        url: /signup
      - type: fill
        selector: "[data-testid=email]"
        value: "maya@example.com"
        typing: true
      - type: click
        selector: "[data-testid=submit]"
      - type: waitFor
        text: "Dashboard"
      - type: screenshot
        name: dashboard-hero
        selector: "[data-testid=dashboard]"
```

```bash
autodemo run signup --url http://localhost:3000          # one scenario
autodemo run --all --url http://localhost:3000 --headless # all of them (CI)
```

### 3. Keep them fresh forever (CI)

```yaml
- uses: praveen-palanisamy/autodemo@v0
  with:
    url: http://localhost:3000
```

Full inputs and recipes: [docs/GITHUB_ACTION.md](docs/GITHUB_ACTION.md).

## For AI agents

AutoDemo is agent-native: coding agents use it to **show their work** — a demo video on every PR.

```bash
bunx @praveen-palanisamy/autodemo mcp --no-tui    # MCP server over stdio
```

One-line registration for Cursor / Claude Code / Codex, JSON CLI contracts, and a drop-in rules snippet: [docs/AGENTS.md](docs/AGENTS.md).

## Features

- **Any LLM, or none** — OpenAI, Anthropic, Google, Groq, Ollama/local, any OpenAI-compatible endpoint; deterministic scenarios need zero keys
- **Authenticated flows** — reusable browser storage state; login once, demo logged-in forever
- **Marketing-grade output** — dev overlays hidden, loading noise trimmed (`videoStartStep`), named region captures, custom cursor & click highlights
- **Story tools** — on-screen `narrate` beats, per-step notes in walkthroughs
- **Interactive TUI** — wizards for recording and running (`autodemo record --interactive`)
- **CI-grade** — `--json` output, stable exit codes, `trace.zip` on failure, artifacts contract in `run.json`

## How it compares

| | **AutoDemo** | Demo SaaS (Supademo, Arcade, Storylane…) | Screen recorders |
| --- | --- | --- | --- |
| Price | Free, OSS | $300–500/mo for HTML capture, per-seat | $10–30/mo |
| Freshness | Regenerated in CI | Manual re-capture | Manual re-record |
| Output | Video + walkthrough + stills, one run | Usually one format | Video only |
| In git / code review | ✅ | ❌ | ❌ |
| Agent-operable (MCP) | ✅ | ❌ | ❌ |

The SaaS tools are great for no-code editing, analytics, and hosted demo hubs. AutoDemo is for teams who want demos to be **build artifacts**.

## Docs

| | |
| --- | --- |
| [CLI reference](docs/CLI.md) | commands, flags, exit codes |
| [Configuration](docs/CONFIG.md) | `.autodemo.yml`, step types, LLM providers, auth state |
| [GitHub Action](docs/GITHUB_ACTION.md) | demos in CI |
| [AI agents](docs/AGENTS.md) | MCP setup, JSON CLI, rules snippet |
| [Recipes](docs/RECIPES.md) | copy-paste scenarios |
| [Architecture](docs/ARCHITECTURE.md) | engines, runner, artifact pipeline |
| [Testing](docs/TESTING.md) · [Local CI](docs/CI_LOCAL.md) | development workflows |

## Requirements

- [Bun](https://bun.sh) ≥ 1.3 (the installer sets it up)
- Playwright Chromium (one-time `bunx playwright install chromium`)
- `ffmpeg` for MP4 export (optional — everything else works without it)

## Contributing

The 15-minute setup, project tour, and `good first issue` list live in [CONTRIBUTING.md](CONTRIBUTING.md). The lowest-friction contribution is a [scenario recipe](https://github.com/praveen-palanisamy/autodemo/issues/new/choose).

```bash
bun install && bun run playwright:install
bun test && bun run lint && bun run typecheck
```

## License

[MIT](LICENSE) © Praveen Palanisamy and AutoDemo contributors.

---

<div align="center">
<sub>This README's teaser, the <a href="https://praveen-palanisamy.github.io/autodemo/">product page</a>, and its demo videos are all generated by AutoDemo itself — on every deploy.</sub>
</div>