Contribute to TeamHUD

Clone the repository, install, and pnpm start runs the full app from source with live reload. This page takes you from nothing to a first change with the checks green.

Node 24 the version in .nvmrc
pnpm 10 the repository pins pnpm@10.28.0
pnpm start runs the app from source
pnpm start:2 a second, separate instance

Before you start

Node.js 24. The repository’s .nvmrc says v24.18.0. With nvm, run nvm install and nvm use in the repository.
pnpm 10. Install it with corepack enable, or npm install -g pnpm.
Git.
Native build tools, because some packages compile native code:

Xcode Command Line Tools: xcode-select --install. See docs/BUILD_OSX.md in the repository.

Visual Studio Build Tools with the C++ workload. See docs/WINDOWS_SETUP.md.

A C++ toolchain and the system development packages listed in BUILD_LINUX.md.

Clone.

git clone git@github.com:arimus/teamhud.git teamhud
cd teamhud

Install. The first run takes a few minutes.
Terminal window
```
pnpm install
```
Run the app. This builds the main process, starts the renderer dev server and opens TeamHUD. Editing renderer code reloads live. Editing main-process code restarts the app.
Terminal window
```
pnpm start
```
If it stops with a message about missing build output from a package, build the app’s dependencies once and start again:
Terminal window
```
pnpm build:desktop-deps
pnpm start
```
Run a second instance when you need two people, for a call or messaging. Use the numbered script, which gives the second app its own profile and ports:
Terminal window
```
pnpm start:2
```
Scripts exist for instances 2 to 12, each with a :mock twin (pnpm start:2:mock) that fakes team state. Two instances must never share a number. Under the hood this sets TEAMHUD_INSTANCE=N, which isolates the profile folder, ports, MCP server and single-instance lock. Write the number through the script, not by hand.
Make a first change. Open a widget that is already in the app, such as plugins/widget-window-focus/src/components/widget-window-focus-widget.ts, change a visible label and save. The running app updates. For a real project, follow Build an overlay widget.
Run the checks for what you touched. Run them for one package, not the whole repository:
Terminal window
```
pnpm --filter <package-name> type-check
pnpm --filter <package-name> lint
pnpm --filter <package-name> test
```
Then, for any UI change, from the repository root:
Terminal window
```
pnpm check:widget-contract
pnpm check:theme-tokens
pnpm check:src-artifacts
```
See Test and debug for end-to-end tests and logs.

What you’ll see

pnpm start opens TeamHUD and its overlay. pnpm start:2 opens a second copy with its own sign-in and settings. The checks print nothing, or a short list of files to fix.

If it goes wrong

Wrong Node version. Install fails or native modules do not build. Run nvm use, then delete node_modules and run pnpm install again.
“Edits don’t take effect”. Stale build output next to a source file. Run pnpm check:src-artifacts, delete what it lists and restart.
A package’s build output is old. After pulling many commits, run pnpm build:desktop-deps.
Two instances fight or lose data. They share a number. Stop both and start each with its own pnpm start:N.

Other tools in the repository

Command	What it is
`pnpm start:builder`	Component Builder
`pnpm docs:dev`	This documentation site, live
`pnpm start:daily`	Build once and run without file watching

Where next

Build an overlay widgetA draggable widget in TypeScript.

Test and debugChecks, end-to-end tests, logs.

Connect an agentDrive the running app from Claude Code.