Embody + Envoy - AI Instructions

This project uses Embody (TouchDesigner externalization) and Envoy (MCP server for AI coding tools).

• Embody externalizes TouchDesigner operators to version-controlled files (.py, .tox, .tdxn, .json, etc.)
• Envoy provides MCP tools for AI assistants to inspect and modify the live TD network
• Use the Configure For toggles on the Embody COMP's Envoy page to regenerate these files for your AI tool (more than one client can be on at once)

Note: For Claude Code users, a CLAUDE.md with modular .claude/rules/ and .claude/skills/ is also generated. This AGENTS.md is the universal fallback read by Codex, Cursor, GitHub Copilot, Windsurf, Gemini, and others.

Skills: the same workflow skills ship as SKILL.md folders -- .claude/skills/ (Claude Code, OpenCode) and .agents/skills/ (Codex, Cursor, Gemini CLI, Antigravity). Read the matching skill BEFORE the action it governs: create-operator before creating or moving operators, td-api-reference before writing TD Python, mcp-tools-reference before the first MCP call, manage-annotations, create-extension, externalize-operator, parameter-design, visual-aesthetics, pop-networks, movie-export, debug-operator, td-recovery, multi-session-etiquette, merge-divergent-tox, glsl-shaders, operator-gotchas, testing, brief (user-invoked), collab (user-invoked). A client with no skills folder gets the identical text over MCP: get_guidance() lists topics, get_guidance(topic='create-operator') returns one.

No Envoy MCP tools? (fresh clone or handed-over project)

MCP config is deliberately not committed: every client's config file hard-codes absolute paths to one machine's Python venv and Envoy bridge. A clone arrives with this file and the rules/skills folders but no MCP config. Which file is missing depends on the client -- .mcp.json (Claude Code, and the baseline Embody always writes), .cursor/mcp.json, .vscode/mcp.json (VS Code, Copilot), .gemini/settings.json, .codex/config.toml, .agents/mcp_config.json (Antigravity), opencode.json.

A missing MCP config never means "this project has no path into TD." It means Envoy has not run on this machine yet. Tell the user:

1. Open the project's .toe in TouchDesigner.
2. Envoy should start by itself -- the sender's committed .embody/project.json declares it, and a machine with no local settings adopts that. If the toolbar shows no port, turn on Enable Envoy on the Embody COMP by hand (the project may predate the declaration).
3. Restart the AI client once the Embody toolbar shows a port.

If nothing is written: Embody Mode on Advanced - ask first defers config writes during project open (a log breadcrumb says so), and Configure For on None writes no MCP config at all. op.Embody.InitEnvoy() applies the deferred writes -- an extension method, not a button.

Windsurf is the exception. Cascade reads only ~/.codeium/windsurf/mcp_config.json, which is shared by every project the user opens, so Embody never writes it -- pointing one global file at this project's bridge would hijack all their other projects. That config is always a one-time manual paste.

Critical Rules

1. Prefer the externalized network file for reading TDXN-externalized COMPs - these are YAML on disk with complete network structure (operators, parameters, connections, positions, flags, DAT content, annotations). Reading them directly is faster than MCP round-trips. Never glob for an extension: Embody writes .tdxn, and keeps writing .tdn for any COMP externalized before Embody 6.1 - both are read and round-tripped forever, so a project can hold a mix. Let externalizations.tsv or get_externalizations name the exact file instead. The strategy column value is tdxn - it read tdn before 6.2.30, and both are accepted on read. To edit: modify the file on disk, then call import_network via MCP with the COMP path, the parsed network, and clear_first=True to reload it in TD. Use MCP when you need live runtime state (evaluated expressions, cook errors) or for non-TDXN operators.
2. Use Envoy MCP tools for live TD state and non-TDXN operators - never say "I can't access that binary file." For operators not externalized as TDXN, use MCP tools to inspect and modify them.
3. Do NOT assume network paths - use query_network on / to discover the actual root structure.
4. Default new COMPs to Embody's container - execute_python with result = op.Embody.parent().path returns the same home every run. Build in ui.panes.current.owner.path only when you have deliberately navigated into a content network, and never treat the bare root / as that home.
5. Never edit externalizations.tsv directly - managed exclusively by Embody's tracking system.
6. Always use forward slashes in file paths.
7. Check for errors and warnings after each group of operator creations -- get_op_errors with recurse=true once the group is wired/positioned.
8. Batch repetitive MCP operations -- never make 3+ individual calls to the same tool. Use batch_operations for repeated positioning, connecting, parameter, or flag edits; use execute_python for computed or looped logic.
9. Thread boundary: MCP server worker thread must never import TD modules. All TD access goes through _execute_in_td().

TD Python Rules

• Always use .eval() to get a parameter's current runtime value. .val only returns the constant-mode value.
• Setting .val silently switches mode to CONSTANT - destroys any active expression.
• Toggle parameters use 0/1 (not "True"/"False").
• Use opex() when the operator must exist - raises immediately with a clear error. op() returns None silently.
• Never call op(), parent(), or access TD objects at module level - defer to methods.
• NEVER access TD objects from a worker thread - all TD operations must go through main-thread hooks.
• fetch() searches UP the parent hierarchy by default - pass search=False for local-only lookup.
• tdu.Dependency: Assign to .val (dep.val = 5), NOT the object itself. Call .modified() after mutating contents.

Network Layout Rules

• 200-unit grid: All positions snap to multiples of 200. Never place at arbitrary coordinates.
• 200 units horizontal between connected operators in a chain.
• Left to right signal flow: inputs on the left, outputs on the right.
• NEVER place an operator on top of another -- scan with query_network before placing, then verify the whole created/moved group with get_network_layout.
• Visual TOP work is output-first: create an Out TOP out1 and turn its display flag on BEFORE building the chain, then keep the working chain wired into it -- the user watches live in the network backdrop.
• Every logical group gets an annotation - use create_annotation around each cluster of related operators.
• Annotations must enclose their operators: nodeX/nodeY is the bottom-left corner - nodeY must be below (less than) the lowest operator's Y.
• TD Y-axis increases upward - new rows go downward (decreasing Y).

MCP Server Safety Rules

• Envoy must bind to 127.0.0.1, NEVER 0.0.0.0.
• _execute_in_td() times out at 30 seconds.
• The MCP server runs as a standalone=True TDTask (long-lived, outside the worker pool).
• Uses threading.Event + Queue rather than locks because TD's cook cycle is frame-based.

Project Structure

Embody/
+-- AGENTS.md                              # This file - universal AI instructions
+-- CLAUDE.md                              # Claude Code specific instructions (if using Claude)
+-- dev/
|   +-- embody/
|   |   +-- externalizations.tsv          # Tracking table (NEVER edit directly)
|   |   \-- Embody/                       # Main extension source
|   |       +-- EmbodyExt.py              # Core externalization engine
|   |       +-- EnvoyExt.py               # MCP server extension
|   |       \-- TDXNExt.py                 # TDXN network format export/import
\-- release/
    \-- Embody-v*.tox                     # Latest release build

Extension Referencing

Three tiers. TD promotes every capitalized member, so the capital letter is the access modifier:

# Tier 1, public API (UpperCamelCase) - called on the COMP:
op.Embody.Update()
op.Embody.Refresh()
op.Embody.Save('/path/to/op')          # opPath is REQUIRED
op.Embody.ExportPortableTox(target=some_comp, save_path='/out.tox')

# Tier 2, wiring (lowerCamelCase) - through ext, from the COMP's own callback DATs:
op.Embody.ext.Embody.getExternalizedOps(COMP)

# Tier 3, private (_lowerCamelCase) - inside the class only.

.ext.<Name> resolves by the Extension Name parameter, not the class name: the extensions are named Embody/Envoy/TDXN/CatalogManager against classes EmbodyExt/EnvoyExt/TDXNExt/CatalogManagerExt, so op.Embody.ext.Embody.x() works and op.Embody.ext.EmbodyExt.x() raises.

NEVER cache extension references in variables - always call inline.

Third-Party Python Packages

The project shares Embody's uv-managed venv (.venv/ beside the .toe); its site-packages is importable from any DAT or extension - wired pre-cook via TD's TDPyEnvManagerContext.yaml (Embody authors it) so even module-level extension imports work on a cold open, with Embody's init as the fallback. To add a package, ASK THE USER FIRST (installs execute code and persist across sessions), then call op.Embody.InstallPackages(['pkg>=1.0']) via execute_python - it accepts plain name-based requirements only (never URLs, git refs, or file paths), validates against Embody's core pins and TD's bundled packages, records the request in the committed .embody/project.json, and installs wheels-only in the background (watch the Embody log for completion). Packages declared by OTHER machines via git do not auto-install: they surface as a warning and need the user's explicit op.Embody.ApplyDeclaredExtras(). Never INSTALL into .venv by calling pip/uv yourself - installs go through InstallPackages only (removal is the one sanctioned direct call: uv pip uninstall <name> --python <VenvPython>, and only when the user asks). Never install packages TD bundles (numpy, opencv - crash class), and treat a logged "restart TouchDesigner" notice as authoritative. External scripts run under op.Embody.VenvPython.