Build

Overview

Two ways to build a TeamHUD widget, and which to pick.

Most of TeamHUD’s UI is overlay widgets: a draggable hub button that opens a panel. Pick the way to build one by what your widget needs.

Two authoring paths

Custom widget: a drop-a-folder UI (index.html + widget.json). No build step, hot-reloaded, and locked down by default. It gets a limited set of capabilities declared in its manifest (and can run a restricted Node.js backend), but it can’t extend TeamHUD’s internals or reach native code. Best for standalone panels, tools, and dashboards.
Plugin: a TypeScript package (BasePlugin) that provides a widget and runs in-app with full trust. A widget is one of the things a plugin can add. Reach for a plugin when your widget needs to extend TeamHUD’s internals rather than run in the locked-down tier.

	Custom widget	Plugin
You write	`index.html` + `widget.json`	a TypeScript package (`BasePlugin`)
Build step	none (hot-reloaded)	`tsc` / bundle build
Backend	optional, Node.js w/ limited access to TeamHUD internals	full Node, in-process
Capabilities	limited, granted per manifest — locked down by default	full trust; extends TeamHUD internals
Start here	Build your first custom widget	Build your first plugin

QuickstartSee a widget on screen in five minutes.

Contribute to TeamHUDSet up the repo, run the app, make a first change.

Build an overlay widgetA full TypeScript/Lit widget, registered and tested.

Create a themeDesign a look in the theme editor, export and share it.

Write a backdrop shaderA WGSL shader behind your hubs or as a live wallpaper.

Component BuilderDescribe a widget in a COMPONENT.md and have it turned into Lit code.

Add an MCP toolLet agents and the AI chat call your plugin.

Connect an agentPoint Claude Code or another MCP client at your running TeamHUD.

Test and debugUnit and e2e tests, logs, MCP state tools, contract checks.

Package and shareWhat you can hand to someone else today.