Embody

create at the speed of thought.

embody.tools  ·  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, Codex, Gemini, Cursor, Windsurf, and GitHub Copilot (via VS Code) 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 YAML. 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.

Related MCP server: touch-mcp

Quick Start

Requirements: TouchDesigner 2025.32820 or later (Windows / macOS). No Python setup needed — Envoy installs its own dependencies on first enable. No special folder structure either: Embody works in any project folder, and if you happen to use git, every change is also a clean diff for free.

1. Install

Download the Embody .tox from /release and drag it into your TouchDesigner project. The Setup Wizard opens and walks you through the choices that matter — how much autonomy Embody gets, whether to enable the AI assistant (Envoy) and for which tool, permissions, and where config files live. Nothing changes until the final click, and you can re-run it anytime via the Setup Wizard pulse on the Embody COMP.

Updating Embody: delete the old Embody COMP and drag the new .tox in its place. Your settings and tracked externalizations live on disk, so the new version picks them up automatically — and offers a quick re-scan to validate everything it's tracking.

2. Tag and Work

1. Tag operators — hover any COMP or DAT and press lctrl twice to open the tagger (pick a strategy for a COMP, a file format for a DAT)

2. Work normally — press ctrl + shift + u to update all externalizations, or ctrl + alt + u to update only the current COMP. Externalized files are written on save; on open, the .toe stays authoritative by default (Export-on-Save), while Roundtrip mode also reconstructs TDN-strategy COMPs from disk

Tip: Externalization is opt-in — nothing is written to disk until you tag it. To capture your AI assistant's work automatically, set Auto-Externalize New Ops (Envoy parameter page) and everything it creates through Envoy is tagged and externalized as it's built.

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. Pick an AI assistant in the Setup Wizard — it opens on first install, or re-run it anytime (the Setup Wizard pulse on the Embody COMP). Prefer parameters? Toggling Envoy Enable (Envoyenable) does the same thing with your current settings

2. Server starts on 127.0.0.1:9870 (configurable via Envoyport; if the port is taken by another instance, Envoy scans forward automatically)

3. Auto-configuration — Envoy writes a .mcp.json (STDIO bridge, so tools are available even before TD is running) at your AI project root. By default that's the git repo root; the wizard's config-location step — or the Aiprojectroot parameter — can point it at the .toe folder or a custom path instead. Projects without a git repo still get config generated in the .toe folder

4. Connect — open a Claude Code session (or restart your IDE) at that root — it picks up .mcp.json automatically

The generated config runs Envoy's bridged STDIO transport (recommended — it can launch and restart TD for you). If you'd rather wire a client by hand, the direct HTTP transport works whenever TD is running:

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

Tools at a Glance

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

When Envoy starts, it always generates an AGENTS.md file in your project root with TD development patterns and project-specific guidance. It also writes a client-specific config for whichever assistant you select in the Aiclient parameter (CLAUDE.md + .claude/ for Claude Code, Cursor/Windsurf rules, Copilot instructions, GEMINI.md for Gemini; Codex reads AGENTS.md directly).

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 YAML file. Your AI agent can read it. You can read it. Any text tool can diff it. The network can rebuild itself from it.

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.

Keyboard Shortcuts

These are the defaults — every shortcut is editable on the Embody COMP's Shortcuts parameter page (type a combo, or pulse Record and press the keys; empty disables it). See Keyboard Shortcuts.

Embody writes externalized files relative to your .toe location, mirroring your network hierarchy — no special folder structure required:

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 YAML)
│   └── text1.py         ← DAT
└── ...

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 92 test suites (2,092 tests) covering core externalization, MCP tools, TDN format, the Envoy server/bridge, launch/config generation, install/uninstall paths, and palette catalogs. Tests run inside TouchDesigner using a custom test runner with sandbox isolation. Destructive whole-project suites are segregated and run only via the save-gated RunDestructiveTests.

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:

• 6.0.131: Issue #57 (Windows MCP transport) -- the STDIO bridge and the HTTP-fallback config target 127.0.0.1 instead of localhost (Windows resolves localhost to ::1 first while Envoy binds IPv4-only; on firewalls that stealth-drop loopback SYNs every MCP call burned ~2s and a full drop became the reported multi-minute create_op hang -- measured 2.1s -> 0.07-0.27s per call after the fix); Envoy no longer restart-storms when its base port is held by another TD instance (observed 575-attempt loop: generation-stamped restart scheduling, in-flight-start guards, ownership-checked force-close, loud dead-on-arrival diagnostics); bridge liveness is instance-aware -- the active instance's image-verified registered PID or its answering port, never "any TouchDesigner process exists" -- and restart_td can no longer quit a different project's TD on multi-instance machines; delete_op purges tracking rows and files for every strategy (clone/shared-file guarded); TDN renames no longer leak the old .tdn on Windows (Path.replace overwrite parity); bridge tools/list augmentation is idempotent (template/fallback drift healed); launch scripts emit forward-slash paths on every platform. Full Windows suite green for the first time: 2,085 passed / 0 failed (7 platform skips). Fresh-install smoke-tested from the shipped .tox. 92 suites / 2,092 tests.

• 6.0.128: Issue #60 (Embody in a default startup file) -- the first-launch palette catalog scan no longer un-pauses a timeline the user paused mid-scan (per-chunk snapshot bracket), checkpoints every 25 components and resumes on the next launch instead of restarting from zero when TD is closed mid-scan (atomic writes; can't wedge, can't re-enable a Disabled Embody); the "Dropped .tox Expression Detected" sweep and Externalize Full Project now honor tdn_exclude ancestry-wide, plain Ignore holds for the session, and Toxdropexpr persists so "Always" answers survive new untitled projects (Envoy opt-in honors restored config the same way); the venv probe runs once per session per venv path and a timeout no longer deletes a healthy venv. New shipped rule: worktree-td-safety. 92 suites / 2,090+ tests.

• 6.0.126: Two field-reported fixes -- the TDN save-time Locked Content Warning now stops at nested externalization boundaries (#53): a locked TOP/CHOP/SOP inside a tox/tdn-tagged child COMP (or exclude-tagged subtree) is that boundary's own concern, so saving the TDN parent no longer pops a false positive; and non-file-backed DATs (selectDAT, mergeDAT, ...) at a tracked path no longer crash Refresh() with td.tdAttributeError (#54) -- getExternalPath returns '' so the continuity check routes the row through the existing "replaced" recovery prompt, and RemoveListerRow completes its cleanup on such DATs (a residual sibling caught by the fresh-install smoke test). 92 suites / 2,090 tests.

• 6.0.123: Editable keyboard shortcuts (#50) -- every binding is now a Str par on a new Shortcuts page: type a combo or pulse Record and press the keys (first non-modifier keydown commits, Esc cancels, 10s auto-disarm); empty disables; conflicts with other Embody bindings or TD built-ins warn without blocking; the tagger double-tap key is a menu; bindings persist across upgrades; ctrl and cmd are distinct physical keys on macOS while Mac-authored cmd bindings fold to Ctrl on PC (values never rewritten -- portable both ways); duplicates are blocked. 92 suites / 2,080 tests.

• 6.0.116: Two field-reported fixes -- removing a TDN externalization now sticks (#48): the manager's X button strips the tdn tag / color / tracker entry so the save-time Update sweep can no longer resurrect the row and .tdn file it just deleted; and Envoy no longer restart-loops on TD builds whose Textport stdout lacks isatty() (confirmed 2025.32460 on Windows) -- uvicorn.Config now gets use_colors=False so the formatter never probes it. Plus self-rewriting version/minimum-build doc statements on every save (guarded by a new test_version_sync suite), a CONTRIBUTING.md for TD-mediated contributions, and five new specimen briefs (Riley, Rutt-Etra, Molnar, Calder, Ikeda). Fresh-install smoke-tested from the shipped .tox. 91 suites / 2,032 tests.

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.

Want to help? Start with CONTRIBUTING.md — this repo works differently from a typical Python project (TouchDesigner writes many of the files), and that page explains what is safe to change and how to run the tests.

License

MIT License