TUI & Desktop from Worktrees
TUI & Desktop from Worktrees
Start with meaning, then move to detail.
This lesson explains TUI & Desktop from Worktrees as part of Hermes internals and extension points. You will learn what it does, when it matters, and the smallest safe test that proves it works.
If you are new, do not memorize names. Focus on three questions: what problem does this solve, what access does it need, and how can you verify the result?
For practice, inspect the first example, identify its effects, run it on test data, and compare the result with the source claim.
For advanced readers, inspect The deps-sharing model, htui — TUI from the worktree, hgui — desktop app from the worktree, then verify failure modes and version compatibility.
Know Python, Git, and basic project structure before changing code.
A clear outcome before you read.
- Understand TUI & Desktop from Worktrees without assumed prior knowledge.
- Separate the source description from what still needs testing in your environment.
- Read the first command and identify its inputs and outputs before copying it.
Short definitions before the details.
- Provider
- The service that runs or provides access and authentication to a model.
Run the Ink TUI and Electron desktop app from a git worktree without a full npm install per checkout
What does the source say, and in what order?
- 01The deps-sharing model
Start here to understand the core idea or structure.
- 02htui — TUI from the worktree
Read this after the foundation, then connect it to the previous step.
- 03hgui — desktop app from the worktree
Read this after the foundation, then connect it to the previous step.
- 04Shared helpers
Read this after the foundation, then connect it to the previous step.
- 05See also
Finish here to verify the result and special cases.
Copy only after you understand the effect.
Two env vars name the canonical checkout:
| Variable | Meaning |
|----------|---------|
| `HERMES_MAIN_CHECKOUT` | The deps checkout — where `node_modules` really lives, and whose `.venv/bin/python` runs the backend. |
| `HERMES_GUI_DEPS_CHECKOUT` | Where the desktop deps (`apps/desktop/node_modules`) live. Defaults to `HERMES_MAIN_CHECKOUT`; override only if you keep desktop deps elsewhere. |
Neither is read by Hermes itself — they're private to these helpers. The variables Hermes *does* read are covered in [Environment Variables](../reference/environment-variables.md).
## `htui` — TUI fro`--dev` compiles from source, so it links `ui-tui/node_modules` from `HERMES_MAIN_CHECKOUT` when the root lockfile matches and installs locally otherwise (see [`_hermes_root` / linking helpers](#shared-helpers)).
:::warning `--dev` and `HERMES_TUI_DIR` are mutually exclusive
`HERMES_TUI_DIR` points Hermes at a *prebuilt* bundle (Nix, system packages), which has no source to hot-reload. If it's set in your shell, `hermes --tui --dev` exits with an error. Run `unset HERMES_TUI_DIR` before `htui`.
:::
## `hgui` — desktop app from the worktree
The desktop app is heavier: it needs `node_modules`The desktop env vars it sets are all real backend-resolution knobs:
| Variable | Role in `hgui` |
|----------|----------------|
| `HERMES_DESKTOP_HERMES_ROOT` | Runs the backend from **this worktree**, not the packaged/PATH `hermes`. |
| `HERMES_DESKTOP_PYTHON` | Reuses the deps checkout's venv instead of re-resolving a Python. |
| `HERMES_DESKTOP_IGNORE_EXISTING` | Ignores any `hermes` on `PATH` so it can't shadow the worktree. |
| `HERMES_DESKTOP_CWD` | Opens the desktop chat rooted at the worktree. |
Two footguns `hgui` handles that a bare `npm run dev` does not:
- **Port `5174` is fixedRead the first command and identify its inputs and outputs before copying it.
Match every command to your installed Hermes version, review the files and accounts it can reach, and use non-sensitive data for the first test. If this explanation differs from the source, the official source wins.