Python Script Tools

Run an existing Python script as a reusable ThinkForge Tool. Each deployment can use its own interpreter, script, arguments, input, and save destination.

Prepare the script

You need a Python installation, an existing .py file, and any packages it requires already installed for that interpreter.

ThinkForge does not install Python or packages, manage environments, or repair scripts. Select the interpreter you want to use by its absolute path. To use a virtual environment, choose its interpreter directly; you do not need to activate it first.

Add Python Script Runner

  1. Open the project that should own the Tool.
  2. Open Tools and choose Add from Library.
  3. Select Python Script Runner from Scripts.
  4. Open Tool settings on the new deployment.
  5. Choose the interpreter and script, then configure the required options.
  6. Review the script and enable Trust this interpreter and script version.
  7. Save the settings, add the input, and run a small test.

These settings belong to the selected deployment. Another placement can use a different script or interpreter.

After you select Save, ThinkForge remembers a valid interpreter path and offers it to another Python Tool with no selection. A Tool with its own saved interpreter keeps that choice. A run with no interpreter selected tries the remembered path.

A Tool can contain one Python action. Use separate Tools connected by an automation when you need several scripts.

Choose the Python settings

Python Interpreter is the absolute path to the executable to launch.

Python Script is an existing .py file. A project-relative path must stay inside the project used for the run.

Arguments is a JSON array of strings. Each item becomes one argument. For example:

["--input", "{source}", "--output", "{output}"]

Working Directory is optional and defaults to the script's folder.

Input Mode chooses how the script receives ThinkForge context:

  • bindings inserts file, folder, output, or project paths into the arguments.
  • stdin_json sends the Tool's structured input to the script's standard input.
  • none passes only the configured arguments.

Timeout Seconds limits how long the script can run. 0 disables the timeout; use a positive limit for unattended runs.

Do not put credentials in Arguments.

Use context bindings

In bindings mode, an argument can be exactly one of these values:

  • {source} — the primary file or folder path
  • {sources} — all source paths, each as a separate argument
  • {output} — the output folder
  • {project} — the project root

A binding must have a value when the Tool runs. If no source is supplied, {source} fails before the script starts.

A file watch for Added or Modified uses that file. A Deleted watch supplies its former path and event information; there is no file left to read.

A Python-only Tool cannot use saved AI reference files. It warns and continues without them. If the Tool also contains AI actions, those actions can read references as supporting context. See Context and Input.

Review results or stop the script

The result shows completion status, the exit code, output, and errors. Exit code 0 means success. A non-zero code, timeout, or stop ends the run and prevents later actions from starting.

Stopping an active Python action terminates its process and child processes. Captured output remains available, although very long output can be truncated.

Review trust after changing a script

Scripts run with your user-account permissions. They can read, change, or delete files, use the network, and start other programs. Only run code you trust.

Changing the interpreter, script path, or script contents invalidates the saved approval. Open Tool Configuration, review the change, enable Trust this interpreter and script version, save, then resume any paused triggers.

Approval covers the selected script, not imported modules or packages.

Fix a failed run

If the interpreter or script is missing, choose a valid path in Tool Configuration.

If a context binding is unavailable, supply the required input or destination, or remove the binding.

For ModuleNotFoundError, install the package for the selected interpreter outside ThinkForge. For other script failures, read the captured error and correct the script.

If the Tool works on another computer, recheck the interpreter path and approve the configuration on this computer.