Reference

Troubleshooting

The common problems, and how to fix them.

localhost:2400 doesn't open

Frame Jam runs inside your agent app, so it's only up while the app is open and the MCP server is connected. Check that framejam shows as connected in your app's MCP settings, then reload the page. You can also start it on its own:

Port 2400 is taken

If another Frame Jam 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:

If the window that hosted the page closed, the page goes away with it. Start another agent window or run npx -y framejam.

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, your comments are still saved. Paste the line the page shows into the chat:

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 Frame Jam tools

• Restart the agent app after adding the MCP server. Most apps only load servers on start.
• 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.
• 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

Your agent renders with the Hyperframes CLI, which 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.

Clicking the video doesn't pick an element

Element clicks need a Hyperframes composition: your agent passes compositionDir. A plain mp4 still takes pins, times and ranges. Only the latest version is live; older versions play their mp4.

Start fresh

Everything Frame Jam stores is in ~/.framejam. Delete it to remove every review, comment and style you made. Built-in styles come back on their own.