Python Script Tools

Python Script Tools let an Agent Tool run an existing local .py file through the normal ThinkForge tool runtime.

This turns code you already own into a reusable ThinkForge capability. Configure a script once, then deploy or attach the tool where the work happens: the Tools page, Power Strip, Ribbon, Mobile Dashboard, tool triggers, or an Automation. The surface that starts the run supplies the project, files, folders, browser capture, or other context.

There is no separate Python-agent system. Python execution is one skill inside the existing Agent Tool model, so script-backed tools use the same deployments, context, output routing, execution feedback, and composition as other tools.

Why This Matters

A standalone script normally depends on someone finding it, opening a terminal, assembling arguments, choosing the right working directory, and remembering when to run it.

A Python Script Tool can make that script:

  • A repeatable command for a project
  • A drop target for files, folders, or text
  • A context-aware action attached to a Power Strip command
  • A scheduled job or new-file watcher
  • A step inside a larger sequence of AI, deterministic, connected-service, and script-backed tools
  • A remotely started tool from the Mobile Dashboard
  • A non-AI tool when the work is completely deterministic

The Python file stays an ordinary file. ThinkForge provides the attachment and execution layer around it.

Requirements

Before configuring a Python tool, you need:

  • An existing Python installation or virtual environment
  • The exact path to the Python interpreter you want to use
  • An existing .py script
  • Any packages the script needs already installed for that interpreter

ThinkForge does not bundle Python, choose an interpreter from PATH, create virtual environments, run pip, install dependencies, or repair scripts.

To use a project virtual environment, select its interpreter directly, for example:

C:\MyProject\.venv\Scripts\python.exe

You do not need to activate the environment first.

Quick Start with Python Script Runner

Release builds include Python Script Runner in the Tool Browser's Scripts folder. It is a normal Agent Tool with one RunPythonScript step and no AI model requirement.

  1. Open the project that should own the deployment.
  2. Open the Tools page.
  3. Select Add from Library.
  4. Choose Python Script Runner from Scripts.
  5. Open Tool settings on the new deployment.
  6. Select the Python interpreter and script.
  7. Configure arguments, input mode, working directory, and timeout.
  8. Review the executable-code warning and enable Trust this interpreter and script version.
  9. Save Tool settings.
  10. Add input and output context for the deployment, then run it.

These Python settings belong to the selected deployment. Another deployment of Python Script Runner can use a different script, interpreter, arguments, timeout, and trust record. Settings opened on a reusable definition supply defaults for deployments created later.

You can also ask the tool creator to build a workflow containing the RunPythonScript skill. A tool may place other skills before or after the Python step, but it can contain only one RunPythonScript step.

Python Settings

Python Interpreter — The exact python.exe to launch. The path must be absolute.

Python Script — An existing .py file. An absolute path works anywhere. A project-relative path works when the run can resolve a ThinkForge project and must remain inside that project.

Arguments — A JSON array of strings. Each item is passed as one argument without shell parsing.

For example:

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

Working Directory — Optional. When empty, ThinkForge uses the script's folder.

Input Mode — Controls how ThinkForge context reaches the process:

  • bindings expands context tokens in the configured argument array.
  • stdin_json writes the current structured tool envelope to standard input and leaves the arguments unchanged.
  • none passes no tool context; the configured arguments still apply.

Timeout Seconds — A non-negative integer. 0 disables the automatic timeout. Use a positive timeout for unattended runs.

Trust this interpreter and script version — Records approval for the selected interpreter, script path, and current script contents.

Do not place credentials or secrets in the Arguments field. Tool settings are not a secrets vault.

Binding Context into Arguments

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

  • {source} — The primary resolved file or folder path
  • {sources} — Every resolved source path, passed as separate arguments
  • {output} — The resolved output folder
  • {project} — The resolved ThinkForge project root

Token expansion preserves argument boundaries. ThinkForge launches the selected interpreter directly and does not construct a command for Command Prompt or PowerShell.

A token must have a value at run time. For example, {source} fails before Python starts if the calling surface supplies no source. Arguments that contain no tokens are always passed unchanged.

How Surfaces Supply Context

A Python Script Tool follows the same context rules as any other Agent Tool.

  • Tools page — Uses saved deployment Input Sources and Output Folder, or a per-run override from the runner.
  • Power Strip Agent — Uses its deployment context on a normal run. A dropped file, folder, or text becomes the explicit input.
  • Power Strip attachment or hook — Can receive context implied by the host command. For example, a tool attached to a Folder command can receive that folder.
  • Power Strip Browser Agent — Receives the captured active Chrome page.
  • Ribbon — Runs its own deployment and saved context.
  • Mobile Dashboard — Uses deployment context or temporary per-run input and output overrides.
  • Schedule trigger — Uses the deployment's saved Input Sources and Output Folder.
  • File Watch trigger — Uses the newly created matching file as the primary source.
  • Automation — Receives the previous tool's structured result and returns a normal structured result to the next tool.
  • Chrome extension — Can start a named tool with supplied page or text content, but does not show the completed result.

ThinkForge MCP does not list or run user-created tools.

When several scripts form one workflow, create one configured tool per script and connect those tools in an Automation. This avoids shared-setting ambiguity and lets each script keep its own interpreter, arguments, trust, and timeout.

Results, Failures, and Stop

ThinkForge captures:

  • Completion status and exit code
  • Standard output and standard error
  • Start time, completion time, and duration
  • Timeout and stopped status
  • Whether captured output was truncated
  • The resolved interpreter, script, working directory, and arguments

Exit code 0 is success. A non-zero exit code, timeout, or Stop produces a failed tool result with the captured process evidence and prevents later steps from starting.

Standard output and standard error are each retained up to 1 MiB. ThinkForge continues draining both streams after that limit so a noisy process does not block, and marks the retained result as truncated.

Unlike most skills, an active Python process can be interrupted. Stop or timeout terminates the Python process and its child process tree, captures the available output, and prevents later tool steps from running.

Trust and Safety

Python tools run arbitrary local code with your Windows account permissions. A script can read, change, or delete files, access local data or the network, start other programs, and continue running until it exits, is stopped, or reaches its timeout.

ThinkForge does not sandbox, inspect, diagnose, or repair the script. Only run code you trust.

Trust records the selected interpreter path, script path, and a SHA-256 hash of the script contents. Changing the interpreter, the script path, or the script file invalidates trust.

For a changed script:

  1. Open Tool Configuration.
  2. Review the new script version and interpreter.
  3. Enable Trust this interpreter and script version.
  4. Save the settings.
  5. Resume any Schedule or File Watch trigger that was paused.

The content hash covers the selected script only. It does not verify imported modules, packages, child programs, or the script's complete dependency tree.

Troubleshooting

Python interpreter not configured — Select the exact interpreter executable in Tool Configuration.

Python script not configured or not found — Select an existing .py file. If using a project-relative path, make sure the run resolves the intended project.

A binding could not be resolved — The calling surface did not provide the source, output folder, or project required by that token. Supply the missing context or remove the token.

ModuleNotFoundError or another dependency error — Install the dependency into the selected interpreter outside ThinkForge, then run the tool again.

Script changed — review and trust the new version — Review the code, trust the current version in Tool Configuration, save, and resume any paused trigger.

Python exited with a non-zero code — Inspect standard error and standard output in the tool result. ThinkForge reports Python's failure but does not repair it.

A tool works on one computer but not another — Interpreter paths are machine-specific. Select an interpreter available on the current computer and trust the configuration again.

Current Boundaries

  • Windows only
  • One RunPythonScript step per tool
  • No bundled Python runtime
  • No environment or package management
  • No script editor, debugger, terminal, or dependency repair
  • No automatic sandbox
  • Deployment-aware Python settings are independent; changing the reusable definition affects defaults for future deployments, not an existing deployment's saved configuration
  • Saved Reference sources are still displayed but not read during execution
  • Tool triggers require ThinkForge Desktop to be running