Skip to content
Skip to content
Resources

Chorono setup and MCP troubleshooting

Run diagnostics from the editor checkout. Use the same --project and --agent values you used for setup:

npm run --silent chorono -- doctor --json

Doctor is read-only and exits with code 1 until ready. Inspect checks, nextSteps and the server's connectedEditors count. A working webpage and a loaded skill do not by themselves make scene tools available.

Find the failing step#

Symptom or reported stateWhat to do
node, npm or git not foundInstall the prerequisite and reopen the terminal; the Chorono CLI requires Node.js 20+
Skill bundle missingRun npm run cli:build from the source checkout
Dependencies or build outputs missingStop any running Next server, then run setup again
Setup refuses to build on a busy portStop the server in its original terminal, or use CLI stop for its managed background process
Server offlineRun npm run chorono -- start --background --open
Server disabled or legacy-serverStop the older/manual server and start with the MCP-enabled CLI lifecycle
Server other-service, different-editor or different-projectVerify the project/editor/port selection; do not kill an unrelated process
Server running, connectedEditors: 0In the browser choose MCP → Connect this editor; reconnect after each page reload
Server unpaired, unauthorized or unreachable-bridgeCheck local setup, MCP-enabled server and browser connection; inspect nextSteps and the local server log
Client stale or unverifiedReview its existing Chorono entry against the generated snippet; setup preserves it
Doctor ready, but this chat has no Chorono toolsReload client MCP connections or start a new agent session; check list_sessions
Skill modified or foreignReview local changes or the original installer; automatic updates preserve the copy

Check the selected project and client#

If you configured only Codex, check only that client:

npm run --silent chorono -- doctor --project "../my-animation" --agent codex --json

Replace the project path with the one used during setup. Doctor defaults to all clients, so an unconfigured additional client can keep an otherwise working single-client installation from reporting ready.

Setup writes configuration examples under <editor>/.chorono/client-configs/: codex.toml, claude-code.json and claude-desktop.json. Compare the Chorono entry's executable, bridge path, editor URL and project path with the selected client's settings. Preserve unrelated entries. Configuration locations are listed in the installation guide.

Change the port#

If port 2000 belongs to another service, select a free port between 1024 and 65535. After stopping any managed server for this checkout:

npm run chorono -- setup --port 2345 --agent codex
npm run chorono -- start --port 2345 --background --open
npm run chorono -- doctor --port 2345 --agent codex

A changed port can make an existing client entry stale. Review it against the regenerated snippet and reload client MCP connections. For separate animation projects, include the same --project path on all three commands. One checkout has one managed server; use another checkout for a second independent server.

Rebuild after a source change#

Check the latest release notes when comparing versions and requirements. After the server is ready, follow Connect your AI agent with MCP to confirm that the browser tab is visible to the client.

Stop the running Next server first. For a CLI-managed background server:

npm run chorono -- stop
npm run chorono -- setup --rebuild
npm run chorono -- start --background --open

For a manual dev/production server, stop it in its original terminal. Add --reinstall to setup only when dependencies also need refreshing. If authoring instructions changed, rebuild the skill bundle with npm run cli:build before setup or skill updates.

Read logs and share useful diagnostics#

Background server logs are in <editor>/.chorono/editor.log; startup errors also report the actual log path. Share the command, error, selected project/client, Node version, relevant doctor statuses and a small relevant log excerpt. Keep .chorono/mcp-token, client configuration backups and unrelated credentials private.

If an npm command cannot find @codie1982/chorono, use the GitHub checkout installation or a local CLI tarball from the distribution guide; local packaging does not publish to npm. See the MCP reference for protocol checks and tool limits.

A good place to start
Getting started / Chorono documentationChorono documentationLearn Chorono with editable animation examples. Install the editor, edit keyframes, build loops and connect Claude Code or Codex through MCP. Cre…Getting started / Install ChoronoInstall ChoronoSet up the free, open-source animation editor on your computer and start a local browser session. This guide installs the browser editor, its loc…Getting started / Create your first editable animationCreate your first editable animationOpen an editable Chorono example, change its text and colors, inspect the timeline, then save and reopen your first 2D animation. Start with a re…Workspace / Chorono editor workspaceChorono editor workspaceFind the canvas, layers, properties, timeline and resource tools in the Chorono editor. Choose a guide for each part of your animation workflow.…Workspace / Canvas and drawing toolsCanvas and drawing toolsNavigate the canvas, draw shapes and splines, use snapping and edit motion keys in Chorono. Use the canvas to arrange the objects in your composi…Workspace / Choose a drawing or transform toolChoose a drawing or transform toolUse Select, Pan, Pen, Move, Rotate, Scale and Anchor tools without losing track of the active editing mode. Choose the tool that matches the edit…Workspace / Select exactly the objects you needSelect exactly the objects you needUse box, lasso, circle, paint and rule-based selection to work with several animation layers. When several objects overlap, clicking each one can…Workspace / Align objects with guides and snappingAlign objects with guides and snappingSet grid, object, point, guide, pixel, angle and scale snapping for precise placement in Chorono. Snapping helps a dragged object settle on an ex…Workspace / Edit Bézier points and spline curvesEdit Bézier points and spline curvesDraw editable paths, adjust points and handles, and extend or close a spline in Chorono. A curve is easier to control when you can see the points…Workspace / Edit animation positions on the canvasEdit animation positions on the canvasUse Motion Keys to adjust position keys, draw a movement and control how the path is timed. Motion Keys bring position editing onto the canvas. T…Workspace / Layers and scene hierarchyLayers and scene hierarchySelect, name, group and organize scene objects in Chorono using the Layers panel and Scene Explorer. A layer is an editable object in your Choron…Workspace / Draw and edit basic shapesDraw and edit basic shapesCreate rectangles, circles, polygons and procedural shapes, then adjust their geometry in Properties. Basic shapes are a useful starting point fo…
Explore the docs