What it does

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

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 <mp4>
│   └── 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. Use it, fork it, ship from it.