Embody

Embody

create at the speed of thought.

[](https://github.com/dylanroscover/Embody/releases/latest) [](https://derivative.ca/) [](https://modelcontextprotocol.io/) [](LICENSE) [](https://github.com/dylanroscover/Embody/stargazers)

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

| | What | Why it matters | |---|---|---| | 🤖 | Envoy MCP Server | 49 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 YAML)
│   └── text1.py         ← DAT
└── ...

2. Install and Tag

1. Download the Embody .tox from [/release](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 YAML | | 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 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 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.

---

Logging

Embody provides a multi-destination logging system:

• File logging (default): dev/logs/_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')

Testing

Embody includes 74 test suites (1,727 tests) covering core externalization, MCP tools, TDN format, the Envoy server/bridge, and palette catalogs. 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.

Troubleshooting

• 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.61: An Embot polish pass that kills the spawn-time frame drops. Copying an annotateCOMP into the network you're viewing pays a ~280ms in-viewport redraw (and a block copy of all 9 parts crashes TD outright -- copyOPs, ui.pasteOPs, and a redraw-suppressed block all crash on repeat into a displayed net), but copying it outside the viewport costs ~100ms; so Embot now assembles at an off-view staging point and swoops in once whole, turning a multi-second fps sag into a clean entrance (dives still snap in place, already cheap). Plus paced/ordered assembly (body -> head -> speech -> limbs -> eyes, one part every 32 frames so hitches stay isolated), an occasional happy squint (eyes flatten + spread every ~9-17s; eyes bumped to 12x13 so the squint clears TD's 10px annotation-size floor), and a shrug that lifts the arms instead of stretching them. Runtime character/camera behavior in EnvoyExt; test suite unchanged at 74 suites / 1,727 tests.
• 6.0.57: A live-build-visualization split plus a major embody.tools Collection upgrade. In TouchDesigner, the opt-in build visualization (v6.0.54) becomes two independent toggles -- Embot (the builder character that stands on each operator and narrates, in past tense, what he just did) and Envoy Follow (the network-editor camera that pans to the active op) -- and the camera now frames the operator, so it follows Envoy's work with or without the character shown. A new _ensureVizParams() recreates both toggles if missing so the feature survives a restart (they were added live and vanished); Embot's per-frame assembly is restored over a block copyOPs implicated in crashes; and follow no longer freezes for ~6s when TD auto-frames a freshly-spawned node. On the web: specimens gain multiple categories (up to 3, via a new specimen_categories join table + D1 migration 0010, ANY-match facet filtering), private drafts with a one-click publish/unpublish toggle and an owner profile that splits public/private with a list/gallery view + inline edit/delete, a fixed license picker (SPDX vocabulary replacing free text), a better TDN editor (search match counter, go-to-line, paste-unwrap) and viewer (operator/annotation jump menu), an optional edit-time cover image, and a privacy pass that self-hosts Inter (drops the Google Fonts CDN) alongside new cookie + copyright/DMCA pages. Test suite 74 suites / 1,727 tests (the visualization split is runtime UI; +2 web e2e cases).
• 6.0.55: A clipboard UX fix. Copying a COMP's network with Ctrl+Shift+C no longer immediately prompts to paste it back into TouchDesigner -- the clipboard watcher now distinguishes your own outbound copy (exported to share or paste elsewhere) from an inbound TDN (the web "embody it" button). CopyNetworkToClipboard seeds the watcher's last-seen signature with what it just wrote, so an outbound copy is skipped while a genuinely new inbound TDN still prompts. Smoke-tested clean in the shipped .tox. New test_outbound_copy_does_not_prompt + test_inbound_after_outbound_still_prompts. Test suite 74 suites / 1,727 tests, all green.
• 6.0.54: A crash-resilience build. Embody now writes a cheap .tdn checkpoint of whatever changed after the agent (or you) goes idle -- no full project save, no TDN strip/restore, no frame freeze -- so a crash (often agent-induced during a heavy build) loses little unsaved work, and the checkpointed COMPs rebuild on next open. The trick was that a normal export's cost is the rglob stale-file scan, not the write, so a new skip_cleanup=True path makes a single-COMP checkpoint ~3-6 ms synchronous; it triggers on a ~1s idle-settle (and before a destructive delete_op), recovers crash-lost COMPs from disk (the tracking table is a syncfile, so rows persist without a save), is bypassed in Perform Mode and during saves, and self-heals its Auto-Save Checkpoints toggle onto older .toes. A 20-agent adversarial review (10 codex + 10 claude) caught and fixed real data-loss / crash / perf defects pre-merge. Also: an opt-in Envoy Follow live build visualization (the network editor glides/navigates to follow Claude's work, with a little builder-bot that hops between nodes), agent threading guidance (Web Client DAT / Thread Manager, not worker threads), and a web contribute-form fix. New test_autosave (18). Test suite 74 suites / 1,725 tests, all green.
• 6.0.49: A generated-file-safety + web-polish build. Re-running Envoy's config generation now PRESERVES your edits to generated rules/skills instead of clobbering them -- _writeTemplate records a SHA-256 of each generated file in .embody/generated-hashes.json and skips any whose on-disk content drifted (delete the file to opt back in); files stay byte-identical to their templates. The v6.0.47 annotation dedup reached Embody's own self-externalized .tdn files (9 redundant annotateCOMP operator copies + dead templates dropped, 840 lines, every annotation byte-identical -- confirmed a safe dedup by a 20-agent adversarial review). embody.tools got a deep polish pass: correct TD family colors and dotted op-reference edges in the network viewer, always-prevented node overlap + wires that arc over same-row nodes, a "by user" Collection filter, foldable operators: / annotations: in the raw-TDN YAML viewer, a sidebar specimen layout, and a fixed 3-10s page-load freeze. New tests B08-B12 in test_claude_config. Test suite 73 suites / 1,707 tests, all green.
• 6.0.47: A TDN-format cleanup. Annotation COMPs are no longer double-captured in .tdn exports -- a stock TD annotate is a palette clone with an extension and ~40 custom parameters, so the exporter was writing it both as a 100-205 line operators: entry and in the compact annotations: array; _exportChildren now skips annotateCOMP children (the importer already rebuilds them from annotations:, Phase 7a). build: null is omitted from the header for untracked/portable networks, and all 12 gallery specimens were cleaned (-2,887 lines, pure deletion, validated by live re-import and clean reconstruction on project open). Save UX: the at-risk content check no longer logs a misleading [test] warning on every Ctrl+S -- the test gate and the save gate are now separate (a real test still warns; a save stays quiet). New test_tdn_annotation_export (7) + 2 test_dialog_suppression tests; the shipped Embody-v6.0.47.tox passed a fresh-install smoke test with both TDN fixes confirmed running live. Test suite 73 suites / 1,702 tests, all green.
• 6.0.46: A docs-accuracy + web-polish build. A multi-agent audit reconciled the entire docs site, the AI machine-files (llms/for-ai), and this README to the live source: the stale "inert by default" community-paste wording is now the real clean/flagged/blocked verdict model; counts corrected (72 suites / 1,693 tests; 49 MCP tools); API/shortcut examples fixed in the docs and the shipped AGENTS template (Ctrl+Shift+O opens the Manager, getExternalizedOps(COMP)); and llms-full.txt's embedded TDN spec regenerated to v2.0 (ASCII-folded, application/yaml). embody.tools gained an app-native report dialog, a simplified specimen network-preview header, a centred /contribute form (renamed from /submit), and a theme

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dylanroscover
• Source: dylanroscover/Embody
• License: MIT
• Homepage: https://embody.tools

Install and usage instructions live in the source repository linked above.