TouchDesigner Atlas

English | Русский | 简体中文

td-atlas gives an agent three things. The exact operator and parameter names from this machine. Hands inside a running instance, with one step of undo. And a way to read a saved project without opening it.

What it does

• The atom index is the name list. Two passes read every operator and parameter out of your own copy of the application into one SQLite file. The values in it are the values that copy reports.
• The bridge lets an agent change your project while TouchDesigner is running. A script builds it there out of four ordinary nodes: a Web Server DAT, a callbacks DAT, a status panel, and an Execute DAT that fires when you save. You can read it, see its changes in git, and upgrade it in place.
• What TouchDesigner does not report. errors covers what TouchDesigner itself calls an error, and td_health covers the breakage it stays quiet about.
• The call journal writes one line per bridge call to a file on disk, and it outlives the session.
• Reading projects offline inspects, searches and compares a project with TouchDesigner closed, and the original file is left alone.
• The network text, written on save is what the bridge can put beside the .toe on every save, so a project gets a diffable history in git.

Install

Three things have to be there first.

• TouchDesigner, already installed. The index is built from your copy of the application and holds the values that copy reports. There is nothing to download.
• Python 3.11 or newer, on the same computer as TouchDesigner.
• An AI agent that speaks MCP. The agent is what calls these tools. td-atlas was built and measured against Claude Code, whose command is the claude mcp add line further down. Any MCP client reaches the same tools.

Compatibility lists the platforms and what the connector can change in your project.

On macOS, one line from a terminal. The installer is a POSIX shell script, so Windows takes the step-by-step sequence below.

curl -fsSL https://grigabyte.github.io/td-atlas/i | sh

If that address does not answer, the same script comes out of the repository:

curl -fsSL https://raw.githubusercontent.com/grigabyte/td-atlas/main/install.sh | sh

install.sh finds a Python, clones the repository, makes a virtualenv beside it, installs the package, builds the index and stages the bridge. Every command is printed before it runs.

It asks two questions: where to clone, and whether to build the index now. The default answer to the first is ~/td-atlas. With no terminal to ask, it takes the default for both.

Two directories end up on disk: the checkout, ~/td-atlas unless you named another, and ~/.td-atlas. Besides those, uv or pip fills its own package cache, as it does for any package. No sudo. System directories and your shell startup files are left alone. Run it again on an existing checkout and it updates that checkout.

git clone https://github.com/grigabyte/td-atlascd td-atlasuv venv                     # or: python3 -m venv .venvuv pip install -e .         # or: .venv/bin/pip install -e .

.venv/bin/td-atlas build      # offline index, 13–16 s, no TouchDesigner process.venv/bin/td-atlas install    # stage the bridge, print the bootstrap and MCP lines

Commands from here on are written td-atlas for short. Unless the virtualenv is activated, call it by path. In the checkout that path is .venv/bin/td-atlas. From anywhere else it is the whole path, ~/td-atlas/.venv/bin/td-atlas for the default directory. On Windows it is .venv\Scripts\td-atlas. A system Python does not see the package.

td-atlas install prints two things to paste. The curl line ran it for you, so both are already at the end of what it printed; running it again prints them again. First, into TouchDesigner's textport (Dialogs → Textport and DATs), once per project:

exec(open('/Users/you/.td-atlas/bootstrap.py').read())

The textport answers with [td-atlas] lines. The last one names your TouchDesigner build and the project the bridge attached to.

[td-atlas] registered as /Users/you/.td-atlas/instances/9977.json[td-atlas] bridge ready at /tdatlas on port 9977 (auth: token)[td-atlas] TouchDesigner 2025.32460, project 'NewProject.1.toe'

Second, a claude mcp add line for your MCP client. See As an MCP server. To also write that same entry into DIR/.mcp.json, or merge it into one that is already there, pass --write-mcp-json DIR.

Once the textport has answered, finish the index.

td-atlas probe

This pass adds the facts only a running instance knows.

Last, check the install. If you came in halfway, start here.

td-atlas doctor

A finished install answers with every link ok, and one closing line.

environment   : ok — running from /Users/you/td-atlas/.venv …touchdesigner : ok — build 2025.32460 at /Applications/TouchDesigner.app …index         : ok — 667 ops, 24251 params, 2060 articles …index build   : ok — index and installation agree: 2025.32460probe         : ok — runtime pass complete: 647 ops probed …bridge        : ok — connected on port 9977 to 'NewProject.1.toe' …mcp server    : ok — 'claude mcp add …' launches …
every link checked out.

The counts come off your own copy of TouchDesigner, so yours will differ. Every link that is not ok comes with its repair, and a broken one makes the command exit non-zero. Before the index is built you see index : FAIL … fix: td-atlas build, and before the bridge is staged, bridge : warn … fix: td-atlas install.

As an MCP server

Run td-atlas install and paste the claude mcp add … line it prints. That line names the interpreter by absolute path, so it keeps working from any working directory, with or without an activated virtualenv. Wiring it in by hand looks like this:

claude mcp add td-atlas -- /path/to/python -m td_atlas.cli mcp

From here you say what you want in plain language. Here is what the agent calls on it:

47 tools in three groups. 9 index tools work offline, 29 live tools act on a running instance, and 9 project-file tools read and write .toe/.tox from disk. Each one, with its arguments and what it is for, is in plugin/skills/touchdesigner/references/tools.md, and a test holds that list to the code.

td_build and td_set_params check parameter names against the index before sending, so the usual mistakes come back as corrections:

- t: is a parameter group, not a settable parameter (try: tx, ty, tz)- typ: no such parameter (try: type, ty)- type: 'simplex5d' is not a valid menu entry        (try: simplex4d, simplex3d, simplex2d, sparse, perlin4d)- period: -3 is below the clamped minimum 0.0

Documentation

Licence

MIT, and the full text is in LICENSE. TouchDesigner is a product of Derivative Inc. This project is not affiliated with them and redistributes nothing from the installation. It only reads what is already on your machine.