Your Nuke comp opens, but several Read nodes still point to the old footage location. A simple folder replacement might repair those paths, yet it can also mishandle image sequences, miss nodes inside Groups, or overwrite expressions that should remain intact.

Claude Code can help turn that repetitive task into a tested Python tool. The workflow starts with a path audit, separates proposed changes from approved edits, and verifies the result in Nuke before saving a revised comp.

This guide develops a small Read-path remapping tool, tests its independent Python logic, and checks its audit, apply, and save behavior in the actual Nuke runtime. The scope stays narrow: approved footage-root changes, with node connections and unrelated settings preserved.

On Vagon Cloud Computer, Nuke, Claude Code, test media, and development tools can share a Windows workspace. You can build the automation, inspect the saved comp, and continue compositing without moving the project to another environment.

Source: Foundry

Define the Tool’s Scope and Change Contract

Our tool will inspect Read nodes in an existing comp and propose one directory-prefix mapping:

It should preserve the remaining path and supported sequence notation. For example, plates/shot010.%04d.exr stays unchanged after the root is replaced.

The mapping must respect directory boundaries. A path under P:/show/seq010_archive/ is not part of the approved location.

For the first version, support ordinary absolute paths and the sequence tokens %04d and ####. Flag expressions, unresolved variables, view tokens, and other unsupported forms for review. Leave proxy paths unchanged.

Source: Foundry

Separate Findings from Permission to Edit

The tool produces two different artifacts.

The audit report records every inspected Read node, its original path, any proposed replacement, and the reason for its status. A proposal is not authorization to modify the comp.

The approved change plan contains only the entries you have accepted. Each entry identifies the target precisely:

Use full node paths so a Read inside a Group cannot be confused with a similarly named node elsewhere. Before applying anything, the adapter must confirm the source comp and every expected old value. A mismatch stops the operation before edits begin.

Keep the First Assignment Narrow

The tool will change only approved full-resolution Read file paths. It will preserve node connections, colorspaces, frame ranges, proxy paths, and Write destinations.

Keep media availability separate from mapping correctness. A valid prefix replacement does not establish that the destination sequence exists or contains the expected images. Any availability report must state which frames were checked.

Finally, distinguish the deliverables: .py files contain the automation code, while .nk files contain the compositing projects Nuke opens and saves.

The contract is simple: report broadly, edit narrowly, and save separately. This gives Claude Code clear behavior to implement and gives the tests concrete expectations to enforce.

Prepare the Nuke Workspace on Vagon Cloud Computer

Run Nuke, Claude Code, and the development tools inside the same Vagon Windows desktop. Keep the test media there too, so the paths checked by the tool refer to files available to the Nuke process.

Choose resources using Foundry’s system requirements and your actual footage. Path mapping is lightweight; loading large sequences, processing complex comps, and rendering can require substantially more memory and processing capacity.

Use application selection for available tools. If your required Nuke release is not listed, install it through your authorized Foundry installer and complete activation. Confirm Claude Code access separately.

Record the Runtime You Will Test

This walkthrough targets a full commercial Nuke, NukeX, or Nuke Studio installation with the required Python API access. Indie and Non-commercial have API and file-format restrictions, so do not assume identical behavior.

In Nuke’s Script Editor, record the application and Python versions:

Verify licensing for the intended terminal mode as well as interactive use.

Source: Foundry

Give Code, Fixtures, and Outputs Separate Locations

Transfer a trusted project copy and its dependencies through Vagon Files. Include required gizmos, plugins, and color configuration where authorized.

Use this project structure:

nuke-tool/
    pyproject.toml
    src/
        nuke_path_tool/
            __init__

nuke-tool/
    pyproject.toml
    src/
        nuke_path_tool/
            __init__

Keep production originals outside the tool’s output locations. Fixtures should contain small, readable test images and a comp designed specifically for verification.

Use a separate Python virtual environment for standalone tests. Do not install its packages into Nuke’s bundled Python. We will configure package discovery explicitly for both environments.

Before automating, open the working comp manually and resolve missing dependencies. That establishes a usable baseline and leaves the same workspace ready for development, testing, and continued compositing.

Separate the Python Package from the Nuke Adapter

Keep the mapping logic independent of Nuke. The pathmap.py module will accept path strings and return mapping results. It must not import nuke, open a comp, or modify application state.

The adapter.py module handles Nuke operations: collecting Read-node data, checking an approved plan, changing permitted knobs, and saving the output comp. Import it only when running inside the appropriate Nuke environment.

This separation gives each test a clear purpose:

Make the Package Importable

Create the empty __init__.py shown in the project structure and add this minimal pyproject.toml:

[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"

[project]
name = "nuke-path-tool"
version = "0.1.0"

[tool.setuptools.packages.find]
where = ["src"]

[tool.pytest.ini_options]
testpaths = ["tests/unit"]

[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"

[project]
name = "nuke-path-tool"
version = "0.1.0"

[tool.setuptools.packages.find]
where = ["src"]

[tool.pytest.ini_options]
testpaths = ["tests/unit"]

From the project root, prepare the standalone test environment:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e . pytest
.\.

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e . pytest
.\.

The editable installation makes imports such as this available to that environment:

Selecting tests/unit prevents the default test run from collecting Nuke integration checks. At this stage, pytest may report that no tests exist; we will add them next.

Pytest’s integration guidance explains package installation and test discovery in more detail.

Configure Nuke’s Imports Separately

The editable installation belongs to .venv. It does not automatically make the package available to Nuke’s embedded Python.

Our integration runner will locate the repository from its own file path and explicitly add the project’s src directory before importing the package. That avoids modifying Nuke’s installation or relying on whichever directory launched the process.

Test pure logic without Nuke, then test application behavior with Nuke. Mocks can exercise selected error paths, but only the second layer establishes that real nodes and saved comps behave as expected.

Source: Anthropic

Build a Report-Only Read-Node Audit

Before asking Claude Code to repair paths, have it build an inventory of the comp’s Read nodes. This gives you a baseline for identifying candidates and checking that later changes stay within scope.

A useful first prompt is:

In adapter.py, collect every standard Read node, including Reads inside Groups. Record its full node path, stored file text, and proxy text. Do not evaluate expressions, change knobs, save the comp, or start a render.

Nuke’s allNodes function supports recursive Group traversal. A small collector can start like this:

Place this function in adapter.py and call it inside Nuke. It collects data only. Classification, path proposals, and report writing remain separate responsibilities.

Source: Foundry

Preserve Stored Paths Before Resolving Them

A Read node’s file text might contain an image-sequence token, a variable, or a Tcl expression. Keep that original text in the report.

An evaluated filename answers a different question: what file does Nuke resolve under the current context? For example, nuke.filename can resolve variables and take proxy mode into account. That can support media checks, but its result should not automatically replace the stored path.

Have Claude Code classify each collected record into three outcomes:

• Candidate: an ordinary absolute path beneath the approved old root.

• Unchanged: a supported path outside that root.

• Needs review: an expression, unresolved variable, or unsupported path pattern.

The completed audit should include the source comp, original file text, proposed replacement where applicable, and classification reason. Proxy paths remain visible but unchanged.

Keep media availability separate from mapping eligibility. A correctly mapped sequence can still have missing frames, and finding one readable frame does not establish complete coverage.

Write and Test the Path-Mapping Logic

With the inventory collected, move the replacement logic into pathmap.py. This function should work without Nuke, making it easier to test before it touches a comp.

Avoid a global string replacement. The mapping must match a directory boundary, so P:/show/seq010/ does not accidentally match P:/show/seq010_archive/.

For paths already classified as supported, a small implementation is enough:

def remap_prefix(path, old_root, new_root):
    """Map a validated Windows path, preserving its filename tokens."""
    normalized = path.replace("\\", "/")
    old = old_root.replace("\\", "/").rstrip("/")
    new = new_root.replace("\\

def remap_prefix(path, old_root, new_root):
    """Map a validated Windows path, preserving its filename tokens."""
    normalized = path.replace("\\", "/")
    old = old_root.replace("\\", "/").rstrip("/")
    new = new_root.replace("\\

This performs a case-insensitive Windows prefix comparison and emits forward slashes for mapped paths. It leaves unmatched inputs unchanged and preserves sequence tokens in the suffix.

It is a mapping function, not a path validator. The classification layer must exclude expressions, unresolved variables, unsupported tokens, and paths containing .. segments before calling it. Otherwise, an apparently matching path could resolve outside the intended directory.

Test the Boundaries, Not Just the Happy Path

Ask Claude Code to create tests/unit/test_pathmap.py:

import pytest

from nuke_path_tool.pathmap import remap_prefix


@pytest.mark.parametrize("source, expected", [
    (
        "P:/show/seq010/plates/shot.%04d.exr",
        "D:/projects/show/seq010/plates/shot.%04d.exr",
    ),
    (
        r"p:\show\seq010\plates\shot.####.exr",
        "D:/projects/show/seq010/plates/shot.####.exr",
    ),
    (
        "P:/show/seq010_archive/shot.exr",
        "P:/show/seq010_archive/shot.exr",
    ),
    (
        "P:/other/shot.exr",
        "P:/other/shot.exr",
    ),
]

import pytest

from nuke_path_tool.pathmap import remap_prefix


@pytest.mark.parametrize("source, expected", [
    (
        "P:/show/seq010/plates/shot.%04d.exr",
        "D:/projects/show/seq010/plates/shot.%04d.exr",
    ),
    (
        r"p:\show\seq010\plates\shot.####.exr",
        "D:/projects/show/seq010/plates/shot.####.exr",
    ),
    (
        "P:/show/seq010_archive/shot.exr",
        "P:/show/seq010_archive/shot.exr",
    ),
    (
        "P:/other/shot.exr",
        "P:/other/shot.exr",
    ),
]

Run the tests from the repository root:

.\.

.\.

Also require classification tests showing that expressions, unsupported view tokens, and parent-directory traversal produce a review status rather than a replacement.

Passing these tests establishes the string-mapping behavior. It does not establish that the destination footage exists or that Nuke can read it. Those checks belong in the integration stage, using actual fixture media.

Source: Foundry

Test the Tool Inside Nuke Before Using a Production Comp

The unit tests check path strings. Integration tests must establish that the adapter finds the right nodes, preserves unrelated settings, and produces a comp that reopens correctly.

Create a small fixture comp containing:

• A top-level Read and another Read inside a Group.

• A path outside the approved root.

• An expression-based path that requires review.

• A populated proxy path and a connected Write node.

Use a short, readable image sequence as fixture media. Empty files with .exr extensions cannot establish that Nuke can read the results.

Source: Foundry

Run the Adapter in Nuke’s Python Runtime

Create tests/integration/integration_nuke.py. Its bootstrap can locate the package independently of your standalone virtual environment:

from pathlib import Path
import sys

repo = Path(__file__).resolve().parents[2]
sys.path.insert(0, str(repo / "src"))

import nuke
from nuke_path_tool.adapter import collect_reads

nuke.scriptOpen(str(repo / "fixtures" / "read_paths.nk"))

before = {
    node.fullName(): node["file"].getText()
    for node in nuke.allNodes(
        "Read", group=nuke.root(), recurseGroups=True
    )
}

records = collect_reads()

after = {
    node.fullName(): node["file"].getText()
    for node in nuke.allNodes(
        "Read", group=nuke.root(), recurseGroups=True
    )
}

assert before == after, "Audit changed a Read path"
assert {row["node_path"]

from pathlib import Path
import sys

repo = Path(__file__).resolve().parents[2]
sys.path.insert(0, str(repo / "src"))

import nuke
from nuke_path_tool.adapter import collect_reads

nuke.scriptOpen(str(repo / "fixtures" / "read_paths.nk"))

before = {
    node.fullName(): node["file"].getText()
    for node in nuke.allNodes(
        "Read", group=nuke.root(), recurseGroups=True
    )
}

records = collect_reads()

after = {
    node.fullName(): node["file"].getText()
    for node in nuke.allNodes(
        "Read", group=nuke.root(), recurseGroups=True
    )
}

assert before == after, "Audit changed a Read path"
assert {row["node_path"]

This is a starting check, not the complete integration suite. Add assertions against the fixture’s known node names so an empty or incomplete fixture cannot silently pass.

Launch the runner using your installed Nuke executable and its terminal mode:

Adjust the executable path to your installation. The -t flag runs without the GUI; it does not itself request a render.

Include an Apply, Save, and Reopen Test

The second integration case should use an explicitly approved plan against a fresh fixture copy. Require Claude Code to verify that:

1. Only the approved file knobs change.

2. Proxy paths, connections, frame ranges, and colorspaces remain intact.

3. The result saves to a new output file.

4. Reopening that output preserves the expected changes.

5. A deliberately incorrect expected_old_value stops the operation before any planned edit.

Keep this separate from the report-only case. A successful audit does not prove that editing and saving work, and an in-memory change does not prove that the saved deliverable is correct.

Apply an Approved Plan and Save a Separate Comp

Once the integration checks pass, let Claude Code build the apply operation around the approved plan, not around a fresh scan of everything that could change.

A plan entry should identify one exact edit:

Here, the node path identifies the Read inside its Group, while expected_old_value protects against applying an outdated proposal to a changed comp.

Validate the Whole Plan Before Editing

Give Claude Code a precise implementation request:

Implement apply_plan in adapter.py. Before changing any knob, validate every entry against the open source comp. Require an existing standard Read node, the file knob, an exact expected-old-value match, and a replacement consistent with the approved root mapping. Reject duplicate targets and unsupported paths. If any validation fails, make no edits. Do not modify proxy paths or execute Write nodes.

Validate the output destination at the same time. It must differ from the source, have an existing parent directory, and not already contain a file.

Only after the complete preflight succeeds should the adapter assign the new values and save through nuke.scriptSaveAs() with an explicit destination and overwriting disabled.

Preflight is not a transaction. A runtime error can still occur after an edit begins. If application or saving fails, report the failure and discard that working session without saving over the source.

Check the Saved Deliverable

Reopen the output in a fresh Nuke session and compare it against the plan. Record the changed node paths, final stored values, output location, and verification results.

Then inspect representative frames in the Viewer, including frames near sequence boundaries. Confirm the intended footage, resolution, and color interpretation. Keep any test render explicit and limited to a designated output.

The result should be a revised comp plus a traceable change report, not simply a message saying the script completed.

Source: Foundry

Add MCP or Computer Use Where They Help

The script-and-test workflow does not require a live connection between Claude Code and Nuke. Claude Code can edit the package, run unit tests, and launch the integration runner through the terminal.

Add another connection only when it removes a specific manual step.

Use MCP for Structured Access to the Open Comp

A compatible MCP server can expose Nuke operations as tools, allowing Claude Code to inspect application state without relying on screenshots.

The third-party nuke-mcp project provides a Nuke integration with node-graph inspection and manipulation tools. Check its supported versions, installation requirements, and exposed operations before connecting it to a working comp.

For this tool, start with a narrow assignment:

Inspect the open comp and report the full paths and stored file values of standard Read nodes. Do not modify nodes, save the script, or render.

Compare that response with the Python audit. Differences can reveal a Group-traversal issue, a different open comp, or inconsistent handling of file text. Keep the tested adapter responsible for applying the approved plan rather than introducing a second, independently generated editing method.

Use Computer Use for Visible Application Checks

Where supported and enabled, Claude Code’s computer use can help with interface tasks such as opening the saved output, navigating to a reported node, and capturing a Viewer frame for review.

The desktop-control session must target the Windows environment where Nuke is running. Controlling your personal computer does not automatically provide access to applications inside the remote workspace.

A useful bounded prompt is:

Open the verified output comp, navigate to PlateGroup.Read1, and capture its file settings and Viewer at frame 1001. Do not change settings or start a render.

Use these observations alongside the test report. A screenshot can show that footage appears, but it cannot establish that every sequence frame exists or that unrelated knobs remained unchanged. Structured checks verify the edit; application review checks the visible result.

Source: Foundry

Troubleshoot the Failing Layer

When a test fails, give Claude Code the exact command, traceback, and relevant report. Ask it to identify the failing layer before changing the implementation.

The Package Imports in Python but Not in Nuke

An editable installation in .venv does not make the package available to Nuke’s separate interpreter.

Check that the integration runner adds the repository’s src directory before importing the adapter. Also compare Python versions if the error concerns syntax or a dependency. Avoid installing packages into Nuke’s bundled environment simply to fix a missing project path.

The Mapping Looks Correct, but Footage Is Missing

Separate the stored path from filesystem access. Check whether the destination sequence actually exists and whether the Windows session running Nuke can access it.

A mapped drive available in one session may not be available in another. Confirm the destination from the same environment that launches the integration test.

Ask Claude Code to report the frame numbers checked and any missing files. A successful prefix replacement is not a successful media check.

A Read Inside a Group Is Missing

Confirm that the collector starts at the root and enables recursive Group traversal. Identify nodes by full paths, not short names that can repeat in different Groups.

Also check the node class. The collector deliberately targets standard Read nodes, not every custom gizmo or plug-in that might reference media.

Source: Foundry

The Saved Comp Differs from the In-Memory Result

Reopen the exact output path recorded in the report. Check for stale outputs, failed saves, and startup callbacks or plug-ins that alter the comp when it loads.

Keep a failing example as a regression fixture. Once Claude Code proposes a correction, rerun the unit tests and both integration cases. That turns troubleshooting into a permanent improvement rather than another one-off repair.

Final Thoughts

The useful outcome is not a Python script that works once. It is a repeatable tool with a clear scope, tested mapping logic, an approved change plan, and a saved comp you can verify.

Claude Code can help build and maintain that tool. Nuke supplies the application runtime, while your tests establish which behaviors actually work. MCP and computer use can support inspection without replacing those checks.

Vagon Cloud Computer brings development and compositing into the same Windows workspace. Keep the repository, fixture media, reports, and configured Nuke installation together, then move from testing to reviewing the comp without transferring the workflow to another machine.

Start with one fixture and one footage-root mapping. Once the audit, apply, and reopen checks pass, use the tool on a working copy of a real shot. Expand its scope only when the next requirement has a corresponding test.

FAQs

Can Claude Code write Nuke Python scripts?

Yes. Claude Code can help write scripts, organize a Python package, and run tests. Code that imports nuke must execute in Nuke’s Python runtime, not an ordinary standalone interpreter.

Do I need an MCP server for this workflow?

No. Claude Code can edit files and launch a Nuke integration runner through the terminal. MCP is optional when you want structured access to an open Nuke session.

Can I test Nuke scripts with pytest?

Use pytest for application-independent logic such as path mapping and report formatting. Test node access, knob changes, and comp saving inside Nuke. Mocking the nuke module does not establish that those operations work in the application.

Does Nuke terminal mode automatically render the comp?

No. The -t flag starts terminal mode. Rendering requires an additional action, such as executing a Write node from Python. An audit runner should contain no render calls.

Is Nuke preinstalled on Vagon Cloud Computer?

Check the current application selection before starting. If Nuke is unavailable, install it using an authorized Foundry installer and configure your license separately. Do not assume application availability includes a license.

Will the tool handle expressions and stereo paths?

Not in the initial scope described here. Flag expressions, unresolved variables, and unsupported view tokens for review. Add support only after defining the expected behavior and creating fixtures that test it.

Can I use Nuke Indie or Non-commercial for the same automation?

Do not assume identical behavior. These editions have licensing and technical restrictions that can affect scripting and file compatibility. Check your edition’s requirements before adopting a workflow developed for full Nuke.

Does a successful test mean the comp is production-ready?

No. Tests establish specific behaviors, such as approved path changes and preservation of selected settings. You still need to review the footage, sequence coverage, color interpretation, and final comp against the shot requirements.