DemoForge

You built it. We'll make it impossible to ignore.

https://github.com/user-attachments/assets/e88bb7ea-4669-4621-be42-62bd48af867a

DemoForge turns a public GitHub repository into a 20–30 second vertical (9:16) promo video. It launches the app, films the real UI, writes a grounded summary and storyboard, generates cinematic scenes with Higgsfield, and cuts the result together with FFmpeg.

GitHub URL → clone → analyse (Gemini) → install → launch → discover routes → Playwright screenshots
           → summary.md + storyboard.json (validated) → Higgsfield MCP scenes → FFmpeg → final-demo.mp4

Quick start

Requirements: Node 20+, FFmpeg/ffprobe on PATH, and a Chromium for Playwright (npx playwright install chromium). Docker is optional but recommended.

npm install
cp .env.example .env          # add GEMINI_API_KEY and HF_CREDENTIALS (Higgsfield KEY_ID:KEY_SECRET)
npm run dev:all               # web on :3000 + generation worker

Open http://localhost:3000, paste a repo URL and press Generate Demo. The worker can also run on its own (npm run dev + npm run worker).

On Windows, npm run service:install builds the app and registers a background service (a per-user Scheduled Task, started at logon) running the production web server and worker (npm run start:all), logging to outputs/service.log. Manage it with powershell -File scripts/service.ps1 status|stop|start|restart; remove it with npm run service:uninstall. Re-run service:install after pulling changes so it rebuilds.

To run one generation without the web UI:

npm run once -- https://github.com/owner/repo
npm run once -- --local tests/fixtures/launchpad   # bundled fixture app, no cloning

Environment variables

Variable	Purpose
GEMINI_API_KEY	Gemini repository analysis, summary.md and storyboard. Without it, deterministic templates are used and labelled as such.
GEMINI_MODEL	Defaults to gemini-3.5-flash.
GEMINI_FALLBACK_MODEL	Optional. Retried when the main model is rate-limited or returns a server error, e.g. gemini-3.5-flash-lite.
HF_CREDENTIALS	Recommended. Higgsfield developer API key pair from console.higgsfield.ai, as KEY_ID:KEY_SECRET. When set, it is used instead of MCP. Check it for free with npx tsx scripts/check-higgsfield.ts.
HIGGSFIELD_MODEL	Text-to-video model path for the developer API. Default kling-video/v3.0/std/text-to-video; Seedance 2.5 is bytedance/seedance-2.5/text-to-video.
HIGGSFIELD_API_BASE	Defaults to https://api.higgsfield.ai.
HIGGSFIELD_END_FRAME_PARAM	Request field for the last frame when Blend screenshots is on (each animated screenshot morphs into the next). Default end_image_url. If the model rejects it, the clip is re-requested without a blend.
HIGGSFIELD_MCP_URL	MCP fallback only. Defaults to https://mcp.higgsfield.ai/mcp.
HIGGSFIELD_API_KEY	MCP fallback only: bearer token for the MCP server (the hosted server expects OAuth, so prefer HF_CREDENTIALS). Can also be set from /settings (stored server-side in data/secrets/).
HIGGSFIELD_VIDEO_TOOL / HIGGSFIELD_STATUS_TOOL	Pin tool names if auto-discovery picks the wrong ones.
HIGGSFIELD_MAX_SCENES	Cap Higgsfield calls per video (credits). Default 2.
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET	Optional. GitHub OAuth App enabling Sign in with GitHub for private repos. Create it at github.com/settings/developers with callback URL http://localhost:3000/api/auth/github/callback. The token is stored in and only used to clone and read repo metadata.

Secrets are only read server-side. They are never sent to the browser, never placed in Gemini prompts, and never passed to repository processes.

Use it from an agent (MCP)

DemoForge ships an MCP server, so Claude Code, Claude Desktop or any MCP client can make videos for you: "make a 16:9 demo of github.com/owner/repo with a hype narrator".

It talks to the running app (DEMOFORGE_URL, default http://localhost:3000), so keep the service or npm run dev:all running. Claude Code picks it up from .mcp.json when you open this project. For other clients, run it over stdio:

{ "mcpServers": { "demoforge": { "command": "node", "args": ["<repo>/node_modules/tsx/dist/cli.mjs", "<repo>/mcp/demoforge-server.ts"] } } }

Tool	What it does
generate_demo	Queue a video: repo URL plus the same options as the home page (aspect, length, scenes, camera, filter, blend, instructions, voice, tone).
wait_for_job	Wait (up to 10 min per call) and return stages, notices, scenes and the video URL + local path.
get_job / list_jobs	Inspect jobs.
edit_scene	Change a scene's caption, length, transition, motion prompt or narration (optionally re-animate it), then re-render.
regenerate_job / delete_job	Start over with the same settings / remove a job and its files.
demoforge_status	Worker and integration health.

This is the beginning of the README. Read the rest at the original. Read the full README ↗