Download the PHP package dan/ai-loom-planner without Composer

AI Loom Planner

Generate ready-to-use AI agent prompts from Loom video walkthroughs — right from the command line.

This Laravel package extracts a Loom transcript and screenshots, builds a structured context file, and prints a copy-pastable prompt for your preferred AI agent (Warp, Cursor, Copilot, etc.) to turn into an implementation plan.

Features

• Transcript extraction — pulls Loom transcripts via oEmbed, page scraping, API fallback, and Playwright (automatic cascade)
• Screenshot capture — grabs frames at configurable intervals with perceptual-hash deduplication
• Prompt building — assembles a structured context file with transcript, metadata, and screenshot references
• Prompt templates — ships with feature, bug, epic, and documentation templates; fully customisable via publish
• Two commands — loom:plan for context + prompt output; loom:transcript for quick transcript access

Requirements

No AI provider or API key is required — the command builds the context and prints a prompt for you to paste into your preferred AI agent (Warp, Cursor, Copilot, etc.).

Playwright is only needed if you use screenshot capture (--screenshots) or if static transcript scraping fails (Playwright is the final fallback for transcript extraction). The package works without it — you'll just get fewer features.

Installation

Publish the config file:

Optionally publish the prompt templates if you want to customise them:

Playwright setup (optional)

If you want screenshot capture or the Playwright transcript fallback:

Configuration

After publishing, edit config/loom-planner.php:

Environment variables

Usage

loom:plan — Generate an implementation plan

Options

Workflow

The command fetches the transcript, captures screenshots, writes a context file, and prints a copy-pastable agent prompt:

loom:transcript — Fetch a transcript

Options

How It Works

1. Video data extraction (LoomVideoService)

The service tries multiple strategies in order:

1. oEmbed API — fetches title, thumbnail, and duration (no auth required)
2. Page scraping — loads the share page HTML and searches for transcript data in:
   • Apollo state (__APOLLO_STATE__)
   • Next.js data (__NEXT_DATA__)
   • Generic <script> tags containing video JSON
3. Transcription API — tries Loom's direct /v1/videos/{id}/transcriptions endpoint
4. Playwright (final fallback) — launches a headless browser, loads the page with full JS execution, and extracts the transcript from the rendered DOM or intercepted API calls

2. Screenshot capture (LoomScreenshotService)

When screenshots are enabled, a Node.js/Playwright script:

• Opens the Loom embed in a headless Chromium browser
• Seeks the video to each target timestamp and takes a screenshot
• Computes a perceptual hash (aHash) for each frame in the browser
• Deduplicates consecutive identical/near-identical frames (Hamming distance ≤ 5)
• Returns only unique frames as JPEG files

Screenshots are saved with contextual filenames derived from the nearest transcript segment:

3. Context + prompt output (LoomPlanService)

The service assembles a structured context prompt containing:

• Video metadata (title, duration, URL)
• Full timestamped transcript
• Screenshot labels and timestamps
• Your project's tech stack description

This is saved as a context markdown file and its path is printed alongside a ready-to-paste agent instruction. Paste both into your AI agent of choice to generate the plan.

Templates

The package ships with four prompt templates in resources/templates/:

Customising templates

After publishing (vendor:publish --tag=loom-planner-templates), templates are copied to resources/views/vendor/loom-planner/. Each template receives two variables:

• $planPath — the file path where the plan should be saved
• $screenshotLine — a sentence about attached screenshots (empty string if none)

Example custom template:

Output Structure

All generated files are saved under the configured output_dir (default: docs-and-plans/loom/):

Architecture

The Playwright helper scripts (resources/scripts/loom-transcript.cjs and loom-screenshot.cjs) intentionally use the .cjs extension so Node loads them as CommonJS even when the consumer project's package.json declares "type": "module". See Troubleshooting for context.

Troubleshooting

ReferenceError: require is not defined in ES module scope

Fixed in v1.0.1. If you are pinned to v1.0.0 and your project's package.json declares "type": "module", the bundled .js Playwright scripts will fail with this error because Node treats every .js file as ESM. Bump to ^1.0.1 (composer update dan/ai-loom-planner) — the scripts now ship as .cjs so Node always parses them as CommonJS.

Cannot find module '@playwright/test'

Install Playwright in your consuming project (the package looks up @playwright/test via NODE_PATH=<your-project>/node_modules):

This is only required if you use --screenshots or hit the Playwright transcript fallback.

node not found — cannot run Playwright transcript extraction

The package looks for node via which node, then falls back to /usr/local/bin/node, /opt/homebrew/bin/node, and /usr/bin/node. If your Node.js binary is somewhere else (e.g. nvm-managed), make sure that path is on the PHP process's PATH (Laravel Herd / valet / Octane workers may have a different PATH from your interactive shell).

Testing

The test suite covers:

• Unit tests — service-level logic (URL parsing, prompt building, transcript normalisation, config)
• Feature tests — full command execution with mocked services

See tests/ for the complete test suite.

Versioning

This package follows Semantic Versioning. The public API surface — artisan command signatures, service class signatures, config keys, and publish tags — is covered by semver from v1.0.0 onwards. See CHANGELOG.md for release notes.

License

MIT — see LICENSE for the full text.