Reference
FrameJam troubleshooting
The common problems, and how to fix them.
localhost:2400 doesn't open
FrameJam runs inside your agent app, so it's only up while the app is open and the FrameJam plugin is on. Check that FrameJam is turned on in your app's plugin list (or MCP settings), then reload the page. You can also start it on its own:
npx -y framejam startPort 2400 is taken
If another FrameJam already has the port, nothing is wrong: every copy shares ~/.framejam, and the first one hosts the page. If a different program has it, pick another port with --port or FRAMEJAM_PORT, in your MCP config too:
npx -y framejam --port 2401If the window that hosted the page closed, the page goes away with it. Start another agent window or run npx -y framejam start.
My agent doesn't react to Finish review
Your agent only hears you while it's inside wait_for_feedback, and the page says Agent listening when it is. If it ended its turn, or stopped waiting after about 10 minutes, your comments are still saved. Paste the line the page shows into the chat:
Apply my FrameJam feedbackIf your agent keeps ending its turn instead of waiting, check that the skill is installed. It tells your agent to call wait_for_feedback right after sharing the link. See What the skill does.
My agent can't find the FrameJam tools
- Restart the agent app after installing: start a new session in Claude, reopen the ChatGPT app, or reload the Cursor window. Apps only load plugins on start.
- Run
npx -y framejam installagain. It installs or updates the plugin in each app it finds and removes an older FrameJam setup, so you don't get the tools twice. - Check that Node 22 or later is on your
PATH: runnode -v. Apps started from the dock sometimes see a different Node than your terminal. - If the server fails to start, use the full path from
which npxas the command in your MCP config. Apps started from the dock may not findnpxon their own. - Run
npx -y framejam --stdioin a terminal. Errors show up there instead of being hidden by the app.
No frame thumbnails in the feedback
Thumbnails are cut from the rendered mp4 with ffmpeg. Install ffmpeg (brew install ffmpeg on a Mac) and make sure your agent passes videoPath to open_review and add_version.
Renders fail
Rendering happens in whatever tool your agent uses, not in FrameJam. If it uses Hyperframes, that needs Node 22 or later and ffmpeg, and downloads its own Chrome on first use. Ask your agent to run npx hyperframes lint first: it catches most composition errors before a render.
Playbooks or styles don't update
FrameJam checks framejam.ai/catalog/v1 for new playbooks and styles when it starts and every few hours after. It verifies each download against a built-in key and keeps the last good copy, so offline or a bad download changes nothing. If a playbook or style is stuck on an old version, check that you didn't copy it into ~/.framejam/playbooks or ~/.framejam/presets: your own copy always wins, and the playbook page tells you when a newer version exists. Set FRAMEJAM_CATALOG_URL=off or FRAMEJAM_NO_UPDATE_CHECK=1 to turn the check off.
Start fresh
Everything FrameJam stores is in ~/.framejam. Delete it to remove every review, comment and style you made. Built-in styles come back on their own.
Still stuck? The review page and MCP tools reference cover the loop, and How to edit videos with Claude walks through a real edit, including a YouTube intro hook and a cleanup that cuts pauses and retakes.
How to edit videos with Claude walks through it step by step, with a video. More in Guides.