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 start

Port 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 2401

If 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 feedback

If 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 install again. 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: run node -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 npx as the command in your MCP config. Apps started from the dock may not find npx on their own.
  • Run npx -y framejam --stdio in 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.