Look Dev Tools · agent control guide

Grade with an agent.

Look Dev Tools can be driven by an AI agent sitting next to Resolve. Here is what that means, how to set it up, and what to say to it. Claude Code is what this was built and tested on, and the examples use it, but nothing here is specific to one agent.

Every Look Dev Tools node can take its parameters from an agent session running on the same machine as Resolve. You describe the look in words, the agent writes the values into the nodes, triggers a re-render, and reads the frame back from the viewer to check its own work. Nothing runs in the background, nothing phones home, and the whole thing is off unless you switch it on for a session. This page covers the three pieces involved, the one time setup, and a set of prompts to start from.

← Back to the Look Dev Tools overview

Section 01

How it works

There are three layers, and it helps to know which one is doing what when something looks wrong.

1 · Control channel

The OFX nodes

Every Look Dev Tools node has a small file based control channel built in. The channel is plain files, so any agent that can read and write them can drive it. When it is armed, each node instance watches a folder in your home directory for a grade.json file, applies the values in it to its real Resolve parameters, and writes back an applied.json echo confirming exactly what it now holds. The values land in the node itself, so they save with the project and coexist with anything you trim by hand. When the channel is not armed the nodes do no file work at all and are ordinary effects.

2 · The nudge, and the eyes

Resolve's MCP server

DaVinci Resolve 21 ships its own MCP server, a small program inside the Resolve install that lets an agent run Python scripts against Resolve. Look Dev Tools uses it for two jobs. First, after a value is written, the agent asks Resolve to re-render the current frame. Resolve does not re-render on its own when a plugin changes a value under it, so this one call is what makes the change show up in the viewer. Second, the same server runs the tap reader that ships in the plugin bundle, so the agent can read the rendered frame back without anything else installed on the machine.

3 · The brains

The agent session

An agent running on the same machine as Resolve, with file access and a connection to Resolve's MCP server. Claude Code is the reference setup and what the examples on this page use. It reads two guide files that ship inside the plugin bundle, arms the channel, works out which node is which, writes grades, nudges Resolve, and reads the result back through the T1000 Timeline Agent. Two guides ship in the bundle: a wiring contract that spells out exactly how the channel works and which parameters each node accepts, and a grading playbook that covers what each tool does to a picture and how a brief like "warmer, softer, lift the blacks a touch" turns into values. The guides are Markdown, so they read the same to any agent.

The T1000 Timeline Agent, or the Tap

One node in the suite does no grading. The T1000 Timeline Agent is a pass through you put at the end of the timeline node graph. While the channel is armed, every frame it renders is also written out as a small float snapshot, at most 512 pixels wide. That is how the agent sees what you see in the viewer, display referred, after the whole look and the display transform.

Without it the agent is grading blind. With it, it can read mean RGB, luma percentiles, chroma and per zone warmth off the actual frame and tell you whether the move landed.

Section 02

What you need

  • DaVinci Resolve 21 or later. The MCP server ships inside Resolve from 21 onward. Resolve Studio is what this was built and tested on.
  • Look Dev Tools 2.0.2 or later, installed through the Tool Box Manager or from the portable zip. The control channel and the T1000 Timeline Agent have been in the suite since 2.0.0. 2.0.2 carries the current guides.
  • An agent that can reach your files and Resolve's MCP server, on the same machine as Resolve. The control channel is file based, so the session needs to read and write files on the Resolve machine, and it needs to call the MCP server for renders. A coding agent does that; a plain chat window on its own does not. Claude Code is what this was built and tested on, in a terminal, in the Claude desktop app's Code tab, or in the VS Code extension. Any agent with the same two abilities should work the same way.
  • Nothing else. The tap reader that ships in the plugin bundle runs inside Resolve's MCP server, which has its own Python. There is nothing to install beyond the three items above.
  • A Look Dev Tools tree on a clip. At least one Look Dev Tools node on the clip you want to work on, and the T1000 Timeline Agent on the timeline node graph.
Platform note

Everything below was set up and verified on macOS. The plugin works the same way on Windows and Linux, but the file paths differ. Where a path is macOS only it says so.

Section 03

Setup, once

Four steps. After this, starting a session is one prompt.

Install Look Dev Tools

Use the Tool Box Manager, same as the landing page describes. Restart Resolve. Confirm the guides are in place; this is the same check Claude does to discover the plugin:

Terminal
ls /Library/OFX/Plugins/LookDevTools.ofx.bundle/Contents/Resources/

You should see CLAUDE-CONTROL.md, CLAUDE-LOOKDEV.md and ldt_tap.py. On Windows the bundle lives under C:\Program Files\Common Files\OFX\Plugins\, on Linux under /usr/OFX/Plugins/.

Turn on external scripting in Resolve

Resolve's scripting API is off by default. In Resolve open Preferences, then System, then General, and set External scripting using to Local. Restart Resolve. This is what lets the MCP server talk to the running app.

Point your agent at Resolve's MCP server

The server is a single executable inside the Resolve application. On macOS it is:

Path · macOS
/Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Applications/ResolveMCP

Add it to your agent as an MCP server named DaVinci Resolve with that path as the command and no arguments. In Claude Code, from a terminal:

Terminal · bash
claude mcp add "DaVinci Resolve" -- "/Applications/DaVinci Resolve/DaVinci Resolve.app/Contents/Applications/ResolveMCP"

Restart the agent. With Resolve running, the server announces itself at the start of a session and the agent gets a run_script tool. That tool is the nudge. Other agents take the same command and path in whatever MCP config they use.

The server also carries its own Python, and that is what runs the tap reader from the plugin bundle. You do not need Python on the machine.

Platform note

The Windows and Linux paths for the ResolveMCP executable are inside the Resolve install in the same way. Check the Resolve 21 documentation for the exact location on your platform.

Put the T1000 Timeline Agent on the timeline

On the Color page switch the node graph to Timeline, add a node at the very end, after everything, and drop T1000 Timeline Agent on it from the OpenFX list under Look Dev Tools. Leave its one control, Tap Slot, at 1. It passes pixels through untouched, so it is safe to leave there permanently.

Section 04

Your first session

Open the clip you want to work on in the Color page with the playhead on a representative frame. Start your agent in any folder; the working folder does not matter, the plugin's files live in your home directory. Then paste the session start prompt from the next section.

  1. The agent reads the two guides out of the plugin bundle. It will tell you it has found them.
  2. It arms the channel. That is one empty file, armed, in ~/.ofx-lookdevtools/. From this moment the nodes start writing heartbeats and the Tap starts publishing.
  3. It works out which node is which. Every armed node on the current clip heartbeats on a render, so the agent nudges Resolve once and watches which folders wake up. Then it sends each one an empty read and gets back its tool tag and every current value. A tree with S1 Balance, 4B Simple Contrast and the rest will show several nodes at once. That is correct.
  4. It reads your working spaces and the OpenDRT setup and tells you if anything disagrees with itself before touching the picture.
  5. It takes a baseline from the Tap: stats, and a small before preview.
  6. You grade in words. Each move is one write, one nudge, one read of the Tap. The nudge and the read both go through Resolve's MCP server, usually in a single call. The agent reports what it changed and what the frame did.
  7. You end the session and the agent disarms and cleans up. The nodes keep their values in the project; only the channel goes quiet.
Your sliders, still yours

The values the agent writes are the node's real parameters. Open the node in the inspector and you will see the sliders where it left them. Trim by hand any time; the next read tells the agent what you did.

Section 05

Starter prompts

Copy, paste, adjust. The connect prompts come first because nothing else works until the channel is armed and the nodes are bound. Once the agent is connected, the briefs below are where the real work happens.

Step 1Connect the session

Session start

always first
Prompt
Read CLAUDE-CONTROL.md and CLAUDE-LOOKDEV.md from
/Library/OFX/Plugins/LookDevTools.ofx.bundle/Contents/Resources/ and follow them.
Arm the control channel, bind every Look Dev Tools node on the current clip, and tell me
which tools are on it, their working spaces, and the OpenDRT input and display settings.
Take a baseline from the Tap. Do not change any values yet.

Session start, layered node graph

the long one

If your timeline is built in layers, this is the one to use. It tells the agent which layer it owns, which nodes to identify and leave alone, and the exact loop to work in.

Prompt
I have an agent control channel built into my LookDevTools OFX suite in DaVinci Resolve. The six look tools plus a timeline Tap node are on the current clip in the correct order. I want you to grade this shot through the channel.

Node graph architecture, respect it strictly:

Node layer 3 is the look dev chain (the six LookDevTools nodes). This is the ONLY layer you write to when building a look. The goal is one shared look: every clip in the timeline will carry these same Level 3 settings.
Node layer 1 is shot-level balancing and matching (a BalanceX instance plus saturation controls). Its nodes are also channel-enabled, so they WILL show up as extra heartbeats when you bind. Identify them with an empty-params read, note their uuids as off-limits, and do not touch them unless I explicitly ask for a shot-level adjustment.
Node layer 2 is creative work like power windows, no channel-enabled tools live there. You will not see it on the channel; leave it alone.

Setup, in this order, before touching any parameter:

1. Discover control-enabled plugins: ls /Library/OFX/Plugins/*.ofx.bundle/Contents/Resources/CLAUDE-CONTROL.md
2. Read the LookDevTools CLAUDE-CONTROL.md fully (the wiring contract), then CLAUDE-LOOKDEV.md fully (the grading playbook). Both live in the same Resources folder along with ldt_tap.py. Do not grade from memory of a previous session, the docs are the source of truth.
3. Arm and bind: touch ~/.ofx-lookdevtools/armed, snapshot every uuid dir's heartbeat mtime, trigger exactly one re-render through your Resolve scripting access (the Resolve MCP if you have one, otherwise a local Python call into DaVinciResolveScript) with tl.SetCurrentTimecode(tl.GetCurrentTimecode()), then bind every uuid whose heartbeat bumped. Expect one heartbeat per node on the clip, not just one.
4. Identify each bound uuid with an empty-params read ({"seq": N, "params": {}}). The applied.json echo returns the tool tag and every current value. That echo is also your undo snapshot, keep it. Sort the bound uuids into the look chain (Level 3, writable) and the shot-level nodes (Level 1, read-only for this task) before any grading write.
5. Verify the facts before taste: working spaces, the OpenDRT input and display config, and any model or engine dropdowns whose value gates other params.

The working loop, no exceptions: one node per seq, write grade.json atomically (mkstemp in the same dir then rename), wait for the applied.json echo, then one nudge, then verify on ldt_tap.py stats --slot 1 --min-seq <S> --wait 3. Pull a PNG only when you need to judge a qualitative word, and only into ~/.ofx-lookdevtools/preview/ with the fixed names. Small moves, read every echo back for clamps and preset rewrites.

Hard rules: never start a daemon of any kind. If a nudge times out, stop and report. Never write to a uuid that has not proven itself by heartbeat this session. At session end, even after a failure, always rm ~/.ofx-lookdevtools/armed and run ldt_tap.py purge.
Step 2Once connected, grade in words

These are the ones you will actually reuse. They assume the channel is armed, every node is bound, and the agent has a baseline to compare against.

Build a look from a brief

Prompt
Build me a warm filmic look on this clip. Leave S1 Balance and OpenDRT alone. Work one
node at a time, read the Tap after each move, and tell me the before and after stats
for luma, chroma and shadow warmth when you are done.
Prompt
Teal and orange, but keep skin honest. Shadows cool, highlights warm, skin should still
read as skin on the Tap. Do not touch the display transform.
Prompt
Faded and lifted, a little vintage. Blacks up, whites down, saturation pulled back.
Keep the neutrals neutral.

Adjust what is there

Prompt
More contrast, but roll the highlights off so nothing clips. Read the clip fraction on
the Tap before and after.
Prompt
Skin is too pink. Fix it in 1F Hue Remix Pro, smallest move that works, and confirm on
the Tap with a region over the face.
Prompt
The greens are neon. Calm them down without killing the rest of the palette.
Prompt
Whole image a touch cooler, neutrals included.

Shot balance

Prompt
Read S1 Balance on this clip and the current values. This shot is under compared to
the previous one. Bring it up with master gain only, one stop at most, and show me slot
0 and slot 1 percentiles before and after.
Prompt
Match this shot to the hero shot I just graded. Balance in S1 only: master gain to
match mid grey, then channel gains to match the neutrals, then offset only if the
blacks still differ. Two passes maximum, then stop and report.

Read back and undo

Prompt
Read every node on this clip and give me the full current state as a table, one row per
parameter that is not at its default.
Prompt
Put every node back to the values from the baseline you took at the start of the
session.

Session end

Prompt
We are done. Disarm the control channel, purge the previews, and confirm the root is
clean.
The baseline is your undo

The agent keeps the baseline echo from the start of the session. That is your undo. If a look goes sideways, ask for the baseline back rather than trying to reverse the moves one by one.

Section 06

What the agent will and will not do

The guides in the bundle carry hard rules. They are there so a session cannot leave a mess on your machine or fight Resolve. A reader should know them so nothing looks surprising.

Will
  • Write only the parameters each node has agreed to expose. Anything else is rejected by the node with an error, and a file with one bad key applies nothing at all.
  • Clamp any value to the node's real range, so an oversized number lands at the limit rather than breaking anything.
  • Wait for the echo from the node before trusting that a value landed.
  • Trigger exactly one re-render per write, and read the Tap back, both through the Resolve MCP server. If it ever has to fall back to a shell for the tap reader, it uses the bundled script with the system Python 3, which macOS ships. Windows and Linux readers should not see that fallback.
  • Keep every preview image in ~/.ofx-lookdevtools/preview/ under a fixed set of names, never more than a handful of files, and delete them at the end of the session.
  • Disarm the channel at the end of every session, including one that failed.
  • Leave OpenDRT alone unless you explicitly bring the display transform into play. The playbook treats the DRT as part of the pipeline, not the look.
Will not
  • Start any daemon, watcher or background loop. There is one nudge mechanism and it is a single scripting call.
  • Write to a node it has not identified by heartbeat in the current session.
  • Keep a tap preview as a deliverable. If you want a still, export it from Resolve.
  • Write tap images into your project folder, Desktop, Downloads or a repo.
  • Retry a nudge that timed out. It stops and tells you.
  • Touch anything when the channel is not armed. Disarmed, the plugin does no file work and the nodes behave like any other effect.

Section 07

Troubleshooting

The agent says it cannot find the guides.

The bundle is not installed where the agent looked, or Resolve has not been restarted since the install. Run the ls from Setup step 1 yourself. If the files are there and the agent still cannot see them, the bundle may not be readable by your user; a fresh install through the Tool Box Manager fixes that.

No node heartbeats after the nudge.

Three usual causes, in order. The channel is not armed. The MCP server is not connected, so the nudge never happened; check that Resolve is running, external scripting is set to Local, and your agent lists the DaVinci Resolve server. Or the playhead is not on a clip that has any Look Dev Tools nodes.

The agent says it cannot find python3.

It tried to run the tap reader in a shell instead of through Resolve's MCP server. Tell it: "Run ldt_tap.py through the Resolve MCP server's run_script_unsafe tool, not in a shell." No Python install is needed on any platform.

The agent wrote a value, the node echoed it, but the viewer did not change.

Resolve caches the output of a node graph layer once the current frame has rendered, and a same frame nudge will not re-render a cached node. This shows up on S1 Balance, which lives on the per clip layer. The guides know about this: the agent toggles the node off and on through the scripting API in the same call as the nudge, which invalidates the cache. If you are watching and it seems stuck, ask it to check the node's heartbeat. An unchanged heartbeat means the node never rendered, not that the values were wrong.

The Tap stats look like a different frame.

Resolve renders thumbnails through the same nodes, so the Tap can briefly publish a frame from another time. The agent checks the frame time in the Tap metadata against the playhead before it trusts a number. If you moved the playhead mid session, say so and it will retake the baseline.

Several nodes answered when I only expected one.

Every Look Dev Tools node on the clip heartbeats on every render, and the T1000 on the timeline does too. That is how it should be. The agent reads each one to learn which tool it is.

OpenDRT values reset after the agent re-armed.

Known behaviour. If a session re-arms mid way, re-send the OpenDRT settings you had confirmed. The playbook lists this as a trap and the agent will re-read the node.

I want to stop everything right now.

Delete the armed file in ~/.ofx-lookdevtools/ or ask the agent to disarm. Nothing else is running. The nodes keep whatever values they have and behave normally.

Section 08

Glossary

Control channel
The file based link between an agent session and a Look Dev Tools node. Lives in ~/.ofx-lookdevtools/. Active only while armed exists there.
Armed
The channel is on. A single empty file. Remove it and everything stops.
Bind
How the agent works out which folder belongs to which node: nudge once, see which heartbeats moved, read each one's tool tag.
Nudge
One Resolve scripting call that re-renders the current frame. Made through the Resolve MCP server. The only re-render trigger the agent uses.
MCP
Model Context Protocol. The standard way a tool like Resolve exposes functions to an agent session. Resolve 21 ships its own MCP server, with its own Python, and Look Dev Tools uses it both to trigger renders and to run the bundled tap reader.
Echo
The applied.json a node writes after a grade lands, listing every value it now holds. The agent never assumes a write worked without it.
Tap, T1000 Timeline Agent
The pass through node on the timeline that publishes the frame the viewer is showing. Slot 1 is the default and is the frame to judge a look from.
Slot 0
A reference tap: while armed, S1 Balance publishes its own input here, so the agent can balance shots against what came in rather than what came out.
Baseline
The full state read and Tap stats the agent takes at the start of a session. Your undo.
Working space
Each node's declaration of what the footage actually is. The first thing the agent reads and the last thing it changes.

Nothing extra to download.

Look Dev Tools installs in a couple of clicks through the Tool Box Manager. The agent guides are already inside the bundle; there is nothing extra to download.

Get the Tool Box Manager → Back to Look Dev Tools