Spectr

See an app. Ship an app.

Turn a screen recording of any iOS app into a production-ready spec.md — exact hex codes, exact font weights, every screen state. Drop it into Claude Code and build the clone.

[](LICENSE) [](https://www.python.org/downloads/) [](https://nodejs.org/) [](https://claude.com/claude-code) [](https://modelcontextprotocol.io/)

spectr.to · Gallery · [Docs](#how-it-works)

---

What it does

Spectr watches a screen recording the way a senior product engineer would, then writes down everything it sees in seven sections:

| Section | What it covers | |---|---| | App Overview | What the app is, who it serves, primary value prop | | Navigation Architecture | Tab structure, modals, screen graph | | Screen Specifications | Every screen visible, with layout, components, states | | Component Library | Reusable UI pieces, props, states | | Design System | Exact hex codes, font families/sizes/weights, spacing scale, radius/shadow tokens | | Implementation Notes | Gotchas, edge cases, Expo / RN baseline assumptions | | Claude Code Prompt | A ready-to-paste prompt to start building |

The output targets Expo SDK 54 / React Native / iPhone 15 baseline by default. Roughly 80–150 KB of structured markdown — big enough to be complete, small enough to fit in a Claude Code context window.

---

Quick start

Three ways to install. Pick one — they all share the same vision pipeline and write the same spec.

1. MCP server (recommended for Claude Code)

claude mcp add spectr -- uvx spectr-mcp

Then in any Claude Code conversation, drop an .mp4 and ask Claude to spec it. Runs on your Claude subscription — no API key required.

2. CLI

npx -y spectr-cli generate ./recording.mp4 --app "Duolingo"

Or install globally:

npm install -g spectr-cli
spectr generate ./recording.mp4 --app "Duolingo"

3. Claude Code skill

npx -y spectr-cli install-skill

Drops a SKILL.md into ~/.claude/skills/spectr/. Mention "spec it" or "use Spectr" in any Claude Code conversation with a recording attached and Claude picks up the skill automatically.

---

Requirements

• Node 18+ (for the CLI / skill installer)
• Python 3.10+ + uv (for the MCP / pipeline)
• ffmpeg on PATH — brew install ffmpeg on macOS
• Authenticated claude CLI or ANTHROPIC_API_KEY in env

Spectr never asks for an API key directly. It uses the credentials already on your machine.

---

How it works

Screen recording (.mp4 / .mov)
        │
        ▼
┌───────────────────────────────────────┐
│ 1. Frame extraction                   │
│    ffmpeg scene-change → pHash dedup  │
│    → 20 unique frames                 │
└───────────────────────────────────────┘
        │
        ▼
┌───────────────────────────────────────┐
│ 2. Vision analysis (parallel)         │
│    • Screen documentation (Haiku)     │
│    • Design token extraction (Haiku)  │
└───────────────────────────────────────┘
        │
        ▼
┌───────────────────────────────────────┐
│ 3. Spec generation (4 lanes parallel) │
│    7 sections (Sonnet)                │
│    → validate → assemble              │
└───────────────────────────────────────┘
        │
        ▼
   spec.md (~80–150 KB)

Typical run: 5–10 minutes for a 30–60 second recording. Cost on your own Anthropic key: ~$0.60–$1.20 per spec at default settings (or $0 on a Claude Pro/Max subscription via the CLI).

The pipeline is deliberately frame-driven, not transcript-driven. Screen recordings have long static periods (loading, reading) — scene-change detection captures every meaningful UI transition while skipping the noise. Perceptual hashing then dedupes near-identical frames so the vision model only sees what's actually new.

---

Repository layout

spectr/
├── bin/spectr.js          # Node CLI wrapper (npm/npx entry point)
├── spectr_mcp/            # Python MCP server + standalone CLI
│   ├── server.py          # FastMCP stdio + streamable-http transports
│   ├── cli.py             # spectr-cli generate 
│   └── pipeline.py        # DB-free orchestrator (calls worker.local_worker)
├── worker/                # Vision pipeline + prompts
│   ├── local_worker.py    # All processing logic
│   └── prompts/           # screen_analysis, design_tokens, legacy_spec
├── claude_skill/spectr/   # SKILL.md for Claude Code
├── mcp_server/            # Dockerfile for hosted streamable-http MCP
├── frontend/              # Next.js 14 app (powers spectr.to)
└── supabase/              # Schema + migrations for the hosted product

The worker pipeline is the heart of the project. Everything else — MCP, CLI, skill, web UI — is a different shape of the same vision passes.

---

Contributing

Issues and PRs welcome. A few principles to follow:

• Don't bypass _resize_frame_for_api() — Claude's vision API rejects images larger than 2000px in multi-image batches. Every frame goes through the resizer.
• Keep prompts in worker/prompts/ — never inline them in local_worker.py.
• Preserve the dual Claude interface (claude_text() / claude_vision()) — both CLI and SDK paths must work.
• Spec sections are 7, in order. Changing the count or order is a coordinated change across legacy_spec.py, assembly logic, and frontend rendering.

See open issues for ideas, or open one to propose changes.

---

License

[MIT](LICENSE). Use it, fork it, ship from it.

---

Built with Claude · spectr.to

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Meliwat
• Source: Meliwat/spectr
• License: MIT
• Homepage: https://www.spectr.to

Install and usage instructions live in the source repository linked above.