td-atlas RU·EN Try it

Install

Перевод английской документации от 15.09·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

Install

Three things have to be there first.

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.

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

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

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

By hand, or on Windows, the same sequence step by step

The block below uses uv, a fast installer for Python packages. Each line carries a second form in the comment beside it, and that one runs on the python3 you already have.

bash
git clone https://github.com/grigabyte/td-atlas
cd td-atlas
uv venv                     # or: python3 -m venv .venv
uv pip install -e .         # or: .venv/bin/pip install -e .

There is no package on PyPI. pip install td-atlas and uvx td-atlas will find nothing. Then, from the checkout:

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

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

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

bash
td-atlas probe

This pass adds the facts only a running instance knows.

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

bash
td-atlas doctor

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

shell
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.32460
probe         : 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:

bash
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:

What you say to the agent What it calls
What you say to the agent "Which operator displaces an image with noise? Give me the exact parameter names before you build anything." What it calls td_search_operators, then td_operator_schema
What you say to the agent "Build a noise into a blur into an out TOP in the project I have open, and check nothing is silently dead." What it calls td_build — one undo block — then td_health
What you say to the agent "It looks like nothing is happening." What it calls td_health, then td_flags on whatever it names
What you say to the agent "Show me what that looks like right now, and the motion over a second." What it calls td_render, and a contact sheet for the motion
What you say to the agent "What is inside /project1 of myproject.toe? TouchDesigner is closed." What it calls td_project_read — the file is copied to a cache and read there
What you say to the agent "What did you change since we started?" What it calls td_snapshot before and after, then td_project_diff on the two — components in ~/.td-atlas, never your own file
What you say to the agent "Undo that." What it calls td_undo — a whole td_build batch is one step

41 tools in three groups. 9 index tools work offline, 23 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:

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

Document For
Document plugin/skills/touchdesigner/SKILL.md For Agents using the connector
Document plugin/skills/touchdesigner/references/gotchas.md For Every trap that produced no error
Document plugin/skills/touchdesigner/references/tools.md For All 41 MCP tools
Document AGENTS.md For Agents contributing to this repository
Document CONTRIBUTING.md For How to run the tests and the linter before a pull request
Document CHANGELOG.md For What changed per version, and every protocol change without fail
Document docs/architecture.md For How the three layers fit together, and why
Document docs/cli.md For Every td-atlas subcommand and flag, and what each one needs
Document docs/formats.md For The reverse-engineered .toe/.tox format, with evidence
Document docs/atom-index.md For The two passes that build the index, and what each source yields
Document docs/bridge.md For The component that runs inside TouchDesigner, and what it adds beyond exec
Document docs/health.md For What TouchDesigner does not report, and what td_health prints instead
Document docs/journal.md For The call journal: what is written, by whom, and what is kept out
Document docs/offline-projects.md For Reading, searching and comparing a .toe with TouchDesigner closed
Document docs/network-text.md For The diffable text written beside the .toe, and the seven known differences
Document docs/compatibility.md For Builds, Python, operating systems, and what this can change in your project
Document docs/skill.md For The agent skill, and installing it as a plugin
Document docs/bundle.md For Building the .mcpb, and what publishing it would mean
Document docs/troubleshooting.md For Every symptom, what it is, and what to run
Document docs/development.md For The test suite and the invariant it holds
Document docs/layout.md For Every directory in the repository and what lives there

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.