Skip to content
nodemode-ai edited this page Oct 29, 2026 · 1 revision

Agents

formvfx exposes all of its commands to agents. Changes they make appear in the window live and are ordinary undo steps.

In the terminal dock

The terminal dock (Cmd or Ctrl+J) sits under the panels and holds tabs: shells in formvfx's agent workspace (~/Formvfx/agent-workspace), Claude Code tabs and one Chat tab. The robot button starts Claude Code there, and More agents starts Codex or Cursor when installed; each finds the formvfx MCP server and the formvfx-harness skill in the folder. Agents started here are trusted and never see a permission prompt. Tabs keep running while the dock is hidden, and Restart runs a tab's program again.

Window > Start Claude Code (Shift+Cmd or Ctrl+J) opens the dock with a Claude Code tab in one step; the line under the dock sends it a request in plain words. The title bar's Agent button has the same entries.

The Chat tab

Window > Chat with Claude (Alt+Cmd or Ctrl+J) opens a chat that answers in formatted text and shows each formvfx tool it uses as it goes, for people who would rather not use a terminal. Its bar shows how much of Claude's memory the conversation uses and what it has cost, stops a reply, starts a new chat, continues the conversation in a Claude Code tab (Open in Claude Code) or brings one in from a Claude Code tab (From Claude Code...). It needs Claude Code installed and signed in; its changes are undo steps like any other.

From this repository or anywhere

  • In the repository, .mcp.json (Claude Code), .codex/config.toml (Codex) and .cursor/mcp.json (Cursor) run ./formvfx mcp.
  • ./formvfx agents install (or Install in the Agents panel) adds the MCP server and the skill to your Claude Code, Codex and Cursor setup, backing up any file it changes.
  • The first change from an outside agent asks once in the formvfx window: Allow, Allow Always or Don't Allow. FORMVFX_AGENTS=allow or deny on the engine changes the policy; for headless agents with no window, start the engine with FORMVFX_AGENTS=allow ./formvfx serve.

The tools

status, list_commands, describe_command, execute, batch, get_comp, get_layer, get_property, set_property, set_keyframes, apply_effect, list_effects, text_preset, shapes_from_svg, planar_track, object_matte, render_frame, contact_sheet, render, dynamic_link, project, import_files, history, ui, wait, run_script, guide. The full reference is .claude/skills/formvfx-harness/references/tools.md.

Command line

./formvfx state
./formvfx commands layer.new
./formvfx describe layer.newText
./formvfx exec comp.new '{"name": "Promo", "width": 1920, "height": 1080, "duration": 6}'
./formvfx batch '[{"command": "layer.newText", "params": {"text": "Hello"}}]'
./formvfx frame out.png --time 1.5

The skill

.claude/skills/formvfx-harness (mirrored to .agents/skills) teaches agents the model, the build loop and each area of the application, with recipes that were run against the engine. Its references for commands, effects, property paths and tools are generated by ./formvfx agents sync from the engine itself.

Clone this wiki locally