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	User adds the package to a project (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." 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>].

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