Embody

Create at the speed of thought.

Full Documentation  |  Manifesto  |  Changelog

Embody puts your ideas on screen as fast as you can describe them. Operators, connections, parameters, the works. Want to try a different direction? Spin up a new approach in seconds. Compare attempts side by side. Branch off the one that works. The tool keeps up with you, instead of the other way around.

Three Tools, One Idea

Envoy — forward velocity. An embedded MCP server lets Claude Code, Cursor, and Windsurf talk directly to your live TouchDesigner session. Create operators, wire them up, set parameters, write extensions, debug errors — by saying what you want. No copy-pasting code. No describing your network in chat. Idea → operators in seconds.

Embody — lateral velocity. Tag any operator and Embody externalizes it to files on disk that mirror your network hierarchy. Try a new direction, branch off a good one, restore the state from yesterday — all in seconds. Your externalized files are the source of truth, so every project opens already in flow.

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.

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

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

...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.

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

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)

Version History

See the full changelog for detailed version history.

Recent releases:

• 5.0.392: Critical Windows-only fix — subprocess.run from inside TD raised [WinError 50] The request is not supported because TD's GUI process stdin handle isn't duplicatable, causing Embody's venv-verify to falsely flag healthy venvs as corrupt and shutil.rmtree them on every TD restart. Fixed by passing stdin=subprocess.DEVNULL on the 5 affected subprocess.run sites in the bootstrap and verify-venv paths
• 5.0.391: Per-project TouchDesigner build pinning (committed .embody/project.json + Envoy bridge auto-discovers the matching install on fresh clones), thread-conflict fix in the MCP update checker, and a 21-assertion cleanup of bridge tests that had been silently broken since the bridge v2 refactor — bridge tests now 148/151 passing, zero failures
• 5.0.386: Batch-confirm prompt for duplicate path detection — when multiple groups remain unresolved, one dialog offers Auto-resolve all / Review individually / Dismiss instead of a separate modal per group
• 5.0.383: Clone detection fix for self-referencing masters (reusable UI components using iop.* expressions), and a cleaner list UI moving the tree expand/collapse indicator into a dedicated column
• 5.0.381: Global Perform Mode toggle disables Embody/Envoy/TDN compute during TD performance (Issue #13), auto-resolve duplicate DATs inside active clones without prompting (Issue #15), ancestor-rename disk handling now uses the externalizations folder prefix so Move no longer fails with "source folder not found" (Issue #16), new render-coordinate-system rules for TD's bottom-left origin convention (Issue #14)
• 5.0.376: Palette scan skips invasive palettes (TDVR framerate popup, AutoUI widget dialog) on fresh-build startup, rebaked palette catalog covers TD 2025.32460, and false "locked content" warnings suppressed inside clones/replicants (Issue #12)
• 5.0.372: TDN three-mode master switch (Off/Export-on-Save/Roundtrip), read_tdn MCP tool (~20-90× fewer tokens than get_op walks), combined DAT+storage Content Safety dialog with "Never Ask" footgun removed, palette detection fix for native buttonCOMP operators, migration nudge for upgrading users, docs + landing page rewrite
• 5.0.362: Palette handling control (Ask/Black Box/Full Export) during TDN export, CatalogManager fires on fresh project drops, palette catalog portability + log-level fixes
• 5.0.356: Palette catalog detection, animationCOMP keyframe preservation, external wire preservation across TDN strip/rebuild
• 5.0.354: Consolidate runtime files into .embody/ folder, fix bridge path resolution
• 5.0.352: Fix Envoy failing to start after Embody upgrade (restart counter, port race, reclaim timeout)
• 5.0.351: Creation-defaults catalog, stdin-based bridge lifecycle, Envoy resilience hardening
• 5.0.336: Batch MCP operations, Envoy auto-restart on crash and save, 46 MCP tools
• 5.0.330: Envoy bridge v2 — proactive reconciliation, multi-session safety, zero forced restarts
• 5.0.320: TDN v1.3 — parameter sequence round-trip + companion DAT handling (GLSL/Timer/Script/Ramp companions)
• 5.0.310: Fix first-time Envoy setup stuck on "Disabled" (issues #8, #9), git config generation on fresh install
• 5.0.305: Replicant duplicate detection fix (issue #4), TDN export improvements, ExternalizeProject dialog
• 5.0.302: Fix duplicate path clone detection (issue #4), config file location (issue #5), Envoy startup flow
• 5.0.278: Fix folder change crash (issue #3), regression tests
• 5.0.277: Manager UI improvements, Ctrl+Shift+R shortcut, consistent "Update" terminology
• 5.0.275: TDN export keyboard shortcut pars, keyboard shortcuts documentation
• 5.0.274: Settings persistence across upgrades, extension initialization timing docs
• 5.0.263: DAT content safety, palette clone fidelity, recursive TDN fingerprinting, venv validation
• 5.0.259: Mandatory operator layout rules, /local path prohibition, TD connectivity recovery
• 5.0.258: Multi-instance Envoy support, switch_instance tool, auto-suffix collision avoidance
• 5.0.252: Windows process-kill fix, reconstruction verification fix
• 5.0.251: Nested TDN child-skip on import, depth-sorted reconstruction ordering
• 5.0.243: Headless smoke testing, file cleanup preferences, specialized COMP support, portable .tox hardening
• 5.0.237: TDN v1.1 format, import error surfacing, save-cycle pane restoration, Envoy troubleshooting docs
• 5.0.235: restart_td meta-tool, local MCP handshake, operator overlap warnings
• 5.0.233: Project-level performance monitoring, /validate command, test runner dialog fix
• 5.0.228: macOS timezone fix, toolbar hover highlight
• 5.0.227: TDN crash safety — atomic writes, backup rotation, content-equal skip, About page filtering
• 5.0.222: Rename tag_for_externalization → externalize_op, clarify single-step workflow
• 5.0.221: TDN annotation properties, GitHub release rule, templates cleanup
• 5.0.220: Network layout rewrite, commit-push checklist rule, expanded MCP tool allowlist, tooltip fix
• 5.0.217: TDN target COMP parameter preservation, user-prompted file cleanup, dock safety, git init hardening
• 5.0.210: DAT restoration on startup, continuity check hardening, manager list row limiting
• 5.0.208: Settings auto-deploy, bridge template, Envoy startup resilience
• 5.0.206: Metadata reconciliation, network layout tool, TDN companion dedup
• 5.0.204: Custom window header, path portability, TDN cleanup
• 5.0.201: Robust first-install init, table schema expansion, release build hardening
• 5.0.190: Automatic restoration — TOX and TDN strategy COMPs fully restored from disk on project open
• 5.0: Envoy MCP server (46 tools), TDN format, test framework (38 suites), macOS support

Contributors

Originally derived from External Tox Saver by Tim Franklin. Refactored entirely by Dylan Roscover, with inspiration and guidance from Elburz Sorkhabi, Matthew Ragan and Wieland Hilker.

License

MIT License