Scripts

TumbleTrove Desktop can run scripts that packages declare in their hpm.toml manifest, directly from the launcher UI — no terminal needed. Two flavors:

• Project scripts — run in the context of a prepared project, with the project's full Houdini environment loaded.
• Package scripts — run against a single package directory on disk, handy for package authors iterating on a dev package.

Declaring scripts

In a package's hpm.toml:

[package]
name = "my-package"
version = "1.0.0"

[scripts]
cook = "hython cook_all.py"
lint = "python -m ruff check ."
docs = "mkdocs serve"

Each entry is <name> = "<shell command>". The command runs with the current working directory set to the package's directory.

Project scripts

Project scripts are the union of all [scripts] entries across a project's installed packages. Open a prepared project and go to the Scripts panel to see them grouped by owning package.

Click Run on a script entry and the launcher:

1. Sets the working directory to the package's directory inside the prepared project.
2. Merges the project's Houdini env vars (HOUDINI_PATH, PYTHONPATH, etc.) with the user's current environment.
3. Parses the command into argv (POSIX-style: "…" and '…' quote groups, \ escapes, $VAR / ${VAR} expansion against the merged env) and spawns the program directly — no shell. On Windows the no-console-flash flag is set so no blank terminal pops up. Scripts that use shell features (|, &&, > redirections, ;, etc.) fall back to sh -c / cmd /c.
4. Forwards stdout/stderr to the desktop log file (stderr at warn, stdout at debug) so failed scripts stay diagnosable.

Scripts run in the background. You can run multiple at once. A running script can be cancelled from the UI — the spawned process is terminated.

Requirement: the project must be prepared. Scripts that rely on installed dependencies won't work against a project that's only been defined.

Package scripts

Package scripts run a script directly against a filesystem path, without a surrounding project. You'll use this when developing a package:

• Right-click a dev package in the Packages tab → Run script → pick a script.
• Or open the package's own detail view and run from the Scripts section.

Package scripts get the package's own env vars but not a project-level Houdini environment. If your script needs HOUDINI_PATH, run it as a project script instead.

Environment

Scripts inherit the user's environment plus the merged package/project env vars. Notable additions:

Variable	Source	Meaning
HOUDINI_PATH	project (all packages)	Houdini plugin search path
PYTHONPATH	project (all packages)	Python module search path
HOUDINI_OTLSCAN_PATH	project (all packages)	OTL scan path
TT_CLAUDE_PLUGINS	per-package	Claude Code plugin dirs — see Claude Code Plugins
Custom env vars	per-package hpm.toml	Anything the package author exports

Each package's entries are joined with the platform path separator (: on Unix, ; on Windows).

Cancellation

Running scripts are tracked by the app. Click the cancel button next to any running script to terminate it. The desktop kills the spawned process directly (SIGKILL on macOS/Linux, TerminateProcess on Windows) — child processes the script started are not killed automatically and may be left orphaned. If your script shells out to a long-running tool, take care to clean up explicitly.

Troubleshooting

Script not appearing? Confirm the package is installed and the project is prepared. Project scripts read from the installed copy in the project dir, not from the registry manifest.

Script fails with "command not found"? The launcher resolves the program name against PATH (or treats it as a literal path if it contains a separator). For Python tools, prefer python -m <tool> or invoke via a package-provided venv. HPM sets up ~/.hpm/venvs/<pkg>/ for packages with Python deps; activate it explicitly in your script if needed.

Console window flashes on Windows? The app sets CREATE_NO_WINDOW for all spawned scripts — if you still see a flash, it's likely the script itself re-spawning a cmd/PowerShell. Have the script redirect or use pythonw for GUI-less Python.

Reserved hook names (tt_*)

Script names beginning with tt_ are reserved as TumbleTrove hooks: the desktop runs them itself at specific lifecycle points instead of surfacing them as user-clickable buttons. They never appear in the project or package script menus, and run_project_script / run_package_script reject them outright.

Hooks live in the same [scripts] table as regular scripts — no separate section needed:

[scripts]
cook = "hython cook_all.py"             # regular, user-invocable

tt_setup = "python wizard.py"           # reserved hook

Hook	When it runs	Output	Purpose
tt_setup	Automatically, when the project editor sees an unfilled required variable this package declares; and on demand from the Configure… button on the package card	JSON env vars on stdout → persisted as project overrides	Interactive setup wizard, project-side configuration
tt_install	First prepare_project after the package is added to the project (per-project state, not per-CAS-version). Does not re-fire on a re-enable.	Side-effect only — stdout discarded	Install third-party dependencies (heavy, one-time)
tt_uninstall	First prepare_project after the package is permanently removed from the project. Does not fire on a toggle-off.	Side-effect only	Symmetric cleanup of what tt_install set up
tt_enable	prepare_project after the package is added (right after tt_install) or after it's toggled back on	Side-effect only	Start a service / activate the package (light, per-toggle)
tt_disable	prepare_project after the package is toggled off, or as the first step of a permanent removal of a previously-enabled package	Side-effect only	Stop a service / deactivate the package (light, per-toggle)
tt_prepare	Every launch_project	JSON env vars → ephemeral, merged into the launch process env only	Tokens, runtime-derived paths

JSON output schema (tt_setup, tt_prepare)

These hooks write a single JSON object to stdout. Both shorthand and explicit forms are accepted:

{
  "envVars": {
    "MY_TOKEN": "abc123",                              // shorthand: method = "set"
    "MY_PATH": { "value": "/usr/local/lib", "method": "prepend" }
  }
}

Empty stdout (zero exit) is allowed and means "no env var changes" — this is also how an interactive wizard reports that the user cancelled (see below). Non-zero exit or malformed JSON: tt_setup surfaces the error in the form UI and blocks the configure action; tt_prepare logs the failure but does not abort the launch (a stale env var from a flaky hook is usually less harmful than a refused launch). Stderr always streams to the desktop log under [<hook>:<package>].

Requiring a value your package can't know

A [runtime] entry declared with required = true and no value is a placeholder the project has to fill:

[runtime]
TH_LICENSE_SERVER = { method = "set", required = true }

Omit value entirely — value = "" is a value, so hpm treats the entry as satisfied, installs cleanly, and hands Houdini an empty variable. An empty default is the easy way to ship a requirement nobody is told about.

Installing a project that hasn't supplied one fails outright — hpm won't generate Houdini's package.json without it. The desktop asks for it up front: the project editor renders the key as an empty row flagged required and warns until it has a value. That only works for prerequisites you declare this way, though; a value your package needs but never declares is invisible to the editor, and the user meets it as a failed install.

A tt_setup wizard is the natural partner for one. Declare the placeholder so the requirement is visible even before anyone runs anything, and have the wizard return that same key.

Declaring the pair is also what triggers the wizard on its own: the project editor runs tt_setup unprompted as soon as it sees an unfilled required key that the same package declares, rather than leaving the user to find the Configure… button. It fires only for the declaring package's own unfilled keys, skips a package the user has disabled, and runs at most once per package per editor session — so a wizard the user closes without completing is not reopened, and the button remains the way to run it again. Two consequences for authors: your wizard can be opened without an explicit click, so it must be safe to cancel; and if it exits without emitting the key it was called for, nothing retries it that session.

Exit 0 with empty stdout when the user cancels. That is the contract's "no env var changes", and it is the only way to signal a decline. A non-zero exit means the hook failed and is reported to the user as Configure failed for <package> — so exiting non-zero on cancel hands them an error for their own choice, and under autorun, for a window they never asked to open. Keep non-zero for real failures (your wizard couldn't start, a template was missing), and write the decline to stderr if you want it in the desktop log.

For tt_setup, where a returned value lands in the project editor depends on whether any of the project's packages declares that key in its [runtime] table. A declared key becomes an override row on the declaring package's own card, and is retired with the package if the user removes it from the project. A key nothing declares — a license-server host, a studio share path, anything your wizard derives rather than declares — becomes an ordinary project environment variable under Environment Variables. Both are saved with the project either way; declaring the keys your wizard writes is what keeps them grouped with your package.

For tt_prepare, returned values stack on top of project-level env vars in memory only — they're never written back to the project on disk, so tokens and runtime-derived paths can't go stale.

The hooks spawn through the same path as user scripts (argv-direct for <exe> <args> shapes, shell fallback only when the source uses pipes/redirections/etc.), with HPM_PACKAGE_ROOT set and CWD pinned to the package directory. Wizards can open their own UI window — the desktop only watches stdout for the final JSON payload.

Context vars in tt_prepare

tt_prepare runs at launch, so the desktop forwards the project's TT_* context block as part of the hook's environment — handy when a hook needs to fetch a per-user secret or shape its output by project name without re-querying the API:

Variable	Value
TT_DEBUG	1 on a dev launch (packages linked to your local workspace), 0 on a production launch
TT_PROJECT_NAME	The launching project's display name
TT_PROJECT_DIR	Absolute path to the prepared project directory
TT_HOUDINI_VERSION	The version string the project is pinned to
TT_PROJECT_SCOPE	personal for local projects, team for shared/team projects
TT_ORGANIZATION_SLUG	Org slug (team projects only — unset for personal)
TT_USER_EMAIL	Signed-in user's email
TT_USER_NAME	Username, falling back to the email's local part

If a project explicitly sets one of these in its env-var overrides, the hook sees the override (same precedence as Houdini does). tt_setup, tt_install, tt_uninstall, tt_enable, and tt_disable do not receive TT_* — they run outside launch context.

Lifecycle hooks (tt_install, tt_uninstall, tt_enable, tt_disable)

The four lifecycle hooks pair up by purpose: tt_install / tt_uninstall are heavy one-time setup and teardown for 3rd-party tools that live outside the HPM-managed package dir; tt_enable / tt_disable are light per-toggle activate and deactivate of services. All four are fire-and-side-effect — their stdout is discarded.

Each project has a <project_dir>/.tt_install_state.json file tracking which packages have had tt_install run (installed) and which of those are currently enabled (enabled). On every prepare the desktop diffs that record against the project's current package list + per-package toggles and fires hooks accordingly:

• Package newly added (and enabled): tt_install runs (post-sync, files present), then tt_enable. On success the package is added to both installed and enabled. Failed tt_install logs a warning and keeps the package out of the state file; the next prepare retries.
• Package toggled off: tt_disable runs (pre-sync, files still on disk). The package moves out of enabled but stays in installed.
• Package toggled back on: tt_enable runs (post-sync, files freshly reinstalled). tt_install does not re-fire — the heavy external setup persists across toggle cycles. The package moves back into enabled.
• Package permanently removed while enabled: tt_disable runs first (deactivate), then tt_uninstall (cleanup). The package is dropped from both installed and enabled.
• Package permanently removed while disabled: tt_uninstall cannot run — the package's files were wiped on the toggle-off prepare. The desktop logs a warning. If your package needs permanent-removal cleanup, put it in tt_disable rather than tt_uninstall, since tt_disable always runs while files are still on disk.

Project deletion does not run any of these hooks — the project files are deleted directly. If your package needs cleanup at project-deletion time, design tt_uninstall so it's also safe to not run (e.g. only writing into the project dir, which gets deleted with it).

Related

• Projects — scripts run in the context of a prepared project
• Claude Code Plugins — a special case of package-shipped automation