Skip to content
nodemode-ai edited this page Nov 8, 2026 · 1 revision

Agents

Outside agents (Claude Code, Codex, Cursor and any MCP client) edit what is open in the window through three layers that share one set of rules: the MCP tools, the command catalogue and Agent Connect.

Source path What lives there
backend/app/routers/mcp.py The MCP server (/mcp): 134 tools, each description ending in a "Use when" line; /mcp?tools=core lists the 31 most used for clients that cap tools
frontend/src/automation/agent-bridge.ts The window side: polls the engine for tool calls, runs them through the engine and the catalogue, answers
frontend/src/automation/catalogue.ts, command-meta.ts The command catalogue: every registered command, tool.select.*, tool.options.* and seven exact actions (paint.stroke, select.rect, select.ellipse, select.lasso, layer.set, adjust.apply, filter.apply); the words for each id live in command-meta.ts
backend/app/routers/commands.py POST /api/commands/catalogue (the window mirrors its catalogue to commands-catalogue.json in the data folder), GET /api/commands, GET /api/commands/{id}, POST /api/commands/{id}
setup/cli.py, setup/cli_offline.py `./formvis cli list
backend/app/services/agents.py, routers/agents.py Agent Connect: master switch, a policy per client (allow, ask, deny), sessions, approvals that time out after 120 seconds, an activity log of 200 entries, and a WebSocket at /api/agents/stream
frontend/src/ui/panels/agent-connect.ts The panel: master switch, a row per agent with its policy, approval sheet, activity feed, Follow Agent, Stop
setup/agents.py ./formvis agents install sets up the three clients with every skill; sync regenerates the references that follow the code and mirrors .claude/skills to .agents/skills; sync --check fails on drift and on a skill file over the upload gates

Skills

  • formvis-harness for changing formvis's code, with a sub-skill per subsystem.
  • formvis-driving for editing pictures through the MCP tools, with a sub-skill per action family.
  • formvis-colour-science for profile, intent, CMYK and Lab questions.
  • formvis-editing is a pointer to formvis-driving and holds the generated tool reference.

Generated by ./formvis agents sync and never edited by hand: formvis-editing/references/tools.md, formvis-driving/references/commands.md, formvis-harness/references/command-map.md and tool-map.md. The commands references need the window to have run once, because the catalogue is built there.

Rules

  • Every agent step is an undoable step in the window; a list of commands is one step.
  • Under Ask, a step that writes a file or that undo cannot reverse waits for the person.
  • Only this computer can connect; /mcp checks the Origin header.
  • After changing the tools in mcp.py or the commands in the window, run ./formvis agents sync (with backend/venv/bin first on the path); the engine tests run --check.

Clone this wiki locally