TDN — the substrate that makes both possible. TouchDesigner networks exported as human-readable JSON. The format is what lets your AI agent understand what's on the screen, what lets you diff one attempt against another, and what lets a network reconstruct itself from text on the next project open. TDN is what makes the rest of this possible.

| | What | Why it matters | |---|---|---| | 🤖 | Envoy MCP Server | 47 tools let your AI assistant build, wire, parameterize, and debug live networks. The first time you watch it happen, you stop typing operator names by hand for good. | | 📄 | TDN Network Format | Networks become text. Diff two versions, revisit any version, hand an LLM a complete picture of what's on screen — all from a single .tdn file. | | 📦 | Automatic Restoration | Externalized operators rebuild themselves from disk on every project open. The .toe is no longer the source of truth — your files are. | | 📤 | Portable Tox Export | Pull any COMP out as a self-contained .tox with external references stripped. Ship a piece of your project anywhere. |

Quick Start

1. Project Setup

Embody writes externalized files relative to your .toe location — no special folder structure required. Embody works in any project folder; if you happen to use git, every change is also a clean diff for free.

my-project/              ← project folder (optionally a git repo)
├── my-project.toe       ← your TouchDesigner project
├── base1/               ← externalized operators
│   ├── base2.tox        ← COMP (TOX strategy)
│   ├── base3.tdn        ← COMP (TDN strategy — diffable JSON)
│   └── text1.py         ← DAT
└── ...

2. Install and Tag

1. Download the Embody .tox from /release and drag it into your TouchDesigner project
2. Tag operators — select any COMP or DAT and press lctrl twice to tag and externalize it
3. Work normally — press ctrl + shift + u to update all externalizations, or ctrl + alt + u to update only the current COMP. On project open, Embody restores everything from disk automatically

Tip: If no operators are tagged, Embody will externalize all eligible COMPs and DATs, which may slow down complex projects. Tagging selectively is recommended.

3. Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | lctrl + lctrl | Tag or manage the operator under the cursor | | ctrl + shift + u | Update all externalizations | | ctrl + alt + u | Update only the current COMP | | ctrl + shift + r | Refresh tracking state | | ctrl + shift + o | Open the Manager UI | | ctrl + shift + e | Export entire project to .tdn file | | ctrl + alt + e | Export current COMP to .tdn file |

For supported formats, folder configuration, duplicate handling, Manager UI, and more — see the Embody docs.

Envoy MCP Server

Embody includes Envoy, an embedded MCP server that gives AI coding assistants direct access to your live TouchDesigner session.

Setup

1. Enable Envoy — toggle the Envoyenable parameter on the Embody COMP
2. Server starts on localhost:9870 (configurable via Envoyport)
3. Auto-configuration — Envoy creates a .mcp.json in your git repo root
4. Connect — open a Claude Code session (or restart your IDE) in the repo root — it picks up .mcp.json automatically

If your project isn't in a git repo, add .mcp.json manually to your project root:

{
  "mcpServers": {
    "envoy": {
      "type": "http",
      "url": "http://localhost:9870/mcp"
    }
  }
}

Tools at a Glance

| Tool | What It Does | |------|-------------| | create_op | Create any operator type in any network | | set_parameter | Set values, expressions, or bind modes on any parameter | | connect_ops | Wire operators together | | execute_python | Run arbitrary Python in TD's main thread | | export_network | Export networks to diffable .tdn JSON | | create_extension | Scaffold a full extension (COMP + DAT + wiring) | | get_op_errors | Inspect errors on any operator and its children |

...and 37 more. See the full tools reference.

When Envoy starts, it generates a CLAUDE.md file in your project root with TD development patterns, the complete MCP tool reference, and project-specific guidance.

TDN Network Format

TDN (TouchDesigner Network) is the file format that makes the rest of Embody possible. It exports an entire operator network — operators, connections, parameters, layout, annotations, DAT content — as a single human-readable JSON file. Your AI agent can read it. You can read it. Any text tool can diff it. The network can rebuild itself from it on the next project open.

This is the substrate. Every other capability — AI-driven building, version control, automatic restoration — builds on top of it.

• Entire project: ctrl + shift + e
• Current COMP: ctrl + alt + e
• Via Envoy: export_network / import_network MCP tools

See the full TDN specification for format details, import process, and round-trip guarantees.

Embody provides a multi-destination logging system:

• File logging (default): dev/logs/<project_name>_YYMMDD.log, auto-rotates at 10 MB
• FIFO DAT: Recent entries visible in the TD network editor
• Textport: Enable the Print parameter to echo logs
• Ring buffer: Last 200 entries via the Envoy get_logs MCP tool

op.Embody.Log('Something happened', 'INFO')
op.Embody.Warn('Check this out')
op.Embody.Error('Something broke')

Embody includes 49 test suites covering core externalization, MCP tools, TDN format, and server lifecycle. Tests run inside TouchDesigner using a custom test runner with sandbox isolation.

op.unit_tests.RunTests()                              # All tests (non-blocking)
op.unit_tests.RunTests(suite_name='test_path_utils')   # Single suite
op.unit_tests.RunTestsSync()                           # All in one frame (blocks TD)

Via Envoy MCP: use the run_tests tool. See the full testing docs for coverage details and how to write new tests.

• Timeline Paused: Embody requires the timeline to be running. An error appears if paused.
• Clone/Replicant Operators: Cannot be externalized. Embody warns if you try to tag them.
• Engine COMPs: Engine, time, and annotate COMPs are not supported for externalization.

For more, see Troubleshooting.

Version History

See the full changelog for detailed version history.

Recent releases:

• 5.0.403: Hotfix for v5.0.402 — EmbodyExt.Update() rename-detection used self.ownerComp (an EnvoyExt-only attribute) instead of self.my. Every Update tick during a save threw AttributeError, which got caught and logged at WARNING but meant the rename-detect path never actually fired. Layer 2 walk-forward in the bridge masked the symptom (lookups still resolved correctly), but the registry would have stayed perpetually keyed to the previous version. One-character fix.
• 5.0.402: Three follow-on registry fixes after v5.0.401 verification surfaced edge cases. _writeEnvoyConfig now garbage-collects dead-PID rows on every write — registries that previously accumulated dead entries across sessions (hard kills, force-quits, crashes) collapse to live-only on the next save (verified: 28 rows → 1 in one cycle). EmbodyExt.Update() caches _last_toe_name and triggers RefreshRegistry() on basename mismatch — defensive backstop for execute.py's postSave hook in case it didn't reload. Bridge handle_launch_td adds a PID-aware slow-path scan after the fast-path key