Projects

A project is the fundamental unit in TumbleTrove Desktop: a named Houdini working directory bound to a specific Houdini build and a list of packages from the TumbleTrove registry. Launching a project starts Houdini with those packages resolved, installed, and wired into the environment.

The lifecycle

A project moves through three states:

1. Defined — exists in the database with metadata (name, scope, Houdini version, package list).
2. Prepared — materialized on disk: packages resolved, installed into the project directory, Python venvs set up, .claude-plugin/marketplace.json written (if any packages declare Claude plugins), Houdini env vars computed.
3. Running — Houdini launched with the prepared environment.

The distinction matters because preparing is the expensive step: HPM resolves dependencies, downloads archives it doesn't already have, links them from its content-addressable store, and provisions Python venvs. Prepare is idempotent — once prepared, launches are fast.

You can re-prepare at any time after editing a project's package list.

Scopes

Every project belongs to a scope:

• Personal — only visible to you, stored locally.
• Team — shared within a team inside an organization.
• Organization — shared across the entire org.

Switch scopes with the scope selector in the launcher header. Resources (projects, packages, licenses) are scoped — a personal project never shows up in a team scope, and vice versa. See scoped resources in the app's settings help for details.

Packages

A project's package list is an ordered set of creator/slug@version identifiers. When you prepare the project:

• HPM reads each package's hpm.toml manifest.
• Dependencies are resolved (deduplicated, version-constrained).
• Archives are pulled from the TumbleTrove registry (or from a creator's own S3/B2 bucket for self-hosted packages).
• Packages materialize into <project_dir>/packages/<creator>__<slug>/.
• Each package's declared env vars are concatenated into the project's Houdini environment.

Packages may also ship Python dependencies (installed into a per-package venv at ~/.hpm/venvs/) and Claude Code plugins (see Claude Code Plugins).

Dev packages

For local package development, add a dev package via the Packages tab's right-click menu or Packages → Dev Packages. A dev package points at a directory on disk (a local clone of a package repo) rather than a registry version, and participates in prepare just like a registry package. Useful for testing changes before publishing.

Sharing projects

Projects in a team or organization scope can be published to sync across members.

• Publish — pushes the project metadata to the TumbleTrove API.
• Pull — fetches projects you have access to from your teams and orgs.

Sync is manual by default (buttons on the Projects view) but can run in the background with the start_background_sync toggle in Settings.

When a team member launches a shared project, their desktop prepares it locally — archives are pulled, Python venvs set up, and Houdini launched — no different from a personal project. Only the definition (package list, Houdini version, banner, etc.) is synced, not the materialized workspace.

Launching

Clicking Launch on a prepared project spawns Houdini (the houdini / Houdini FX / houdinifx.exe binary, depending on platform) with:

• The project directory as the working directory.

• HOUDINI_PATH, PYTHONPATH, HOUDINI_OTLSCAN_PATH, and other env vars from the packages.

• The project-specific .claude-plugin/marketplace.json (if present) registered with the user's Claude Code config.

• A license provisioned via the embedded license server for packages that require one.

• A TT_* context block describing the launch, readable from HDA/Python code:

  Variable	Value
  TT_DEBUG	1 on a dev launch (packages linked to your local workspace), 0 on a production launch
  TT_PROJECT_NAME	The 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 — not set for personal)
  TT_USER_EMAIL	Signed-in user's email
  TT_USER_NAME	Username, falling back to the email's local part

  All of these defer to project env-var overrides — explicitly setting any TT_* key on the project keeps your value, so testing under a fake user/project name still works.

Houdini is spawned as a detached child — closing the launcher won't kill Houdini.

Banner & splash images

Projects carry two independent images, each with its own role:

• Banner — wide 5:1 image rendered behind the project title in the projects list. Tuned for a card-row scrim with negative space on the left, so the title stays legible.
• Splash — 16:9 hero image shown by Houdini at startup (wired as HOUDINI_SPLASH_FILE). Standalone — no scrim or text overlay, so it can fill the frame.

Both are uploaded via the project edit form. Add banner image and Add splash image each open a separate crop window where you can pan and zoom to the right framing before upload (5:1 or 16:9 respectively). Drag-and-drop onto either area uploads the file as-is, the right gesture when you've already cropped externally.

If you only set a banner, the launcher will reuse it as the Houdini splash automatically — projects created before the split keep their splash with no action needed. Upload a dedicated splash whenever you want a different image at Houdini startup than the one shown in the projects list.

Deleting

Delete project removes the definition from the database and the prepared project directory from disk. Any Claude Code marketplace entry registered for it is removed from ~/.claude/plugins/known_marketplaces.json. It does not uninstall shared packages from the HPM content-addressable store — those stay cached for other projects.

Shared projects deleted from the API affect only your view; team/org admins must delete from the source.

Related

• Scripts — run package-declared scripts against a project
• Claude Code Plugins — how plugins from packages wire up