Run Hermes TUI and Desktop from Git Worktrees

Python code can run from a Hermes worktree, but TUI and desktop surfaces also need Node dependencies. Reinstalling them in every branch is wasteful; sharing them across divergent lockfiles is unsafe.

Operating checklist

• Choose one canonical dependency checkout.
• Resolve the current worktree root before launch.
• Compare lockfiles byte-for-byte before linking dependencies.
• Install locally when lockfiles differ.
• Never replace an existing dependency tree silently.
• Clean fixed ports and orphan child processes on exit.

How the workflow works

Use one checkout for installed root and desktop dependencies. Worktrees borrow those directories only when their lockfile exactly matches. For TUI source development, hermes --tui --dev must not be combined with a prebuilt HERMES_TUI_DIR. Desktop development must point the backend root and cwd at the current worktree, reuse the intended Python environment, manage Vite port 5174, and reap Electron or dashboard children on exit.

Common pitfalls

• Sharing dependencies across different lockfiles.
• Launching the backend from the canonical checkout by accident.
• Leaving port 5174 occupied.
• Assuming Ctrl-C reaps every process.
• Combining source dev with a prebuilt TUI directory.

Verification steps

1. Print the resolved worktree root.
2. Verify matching locks link and changed locks install locally.
3. Make a visible branch-only UI change and observe it.
4. Stop the app and confirm no listeners remain.
5. Run relevant automated UI tests.

Use the official Hermes documentation for the current source of truth.