Skip to content
TeamHUD Docs

Component Builder

Component Builder is a separate desktop app for designing a TeamHUD component from a written description. You write a structured spec called COMPONENT.md, the builder checks it, and a synthesizer turns it into a Lit web component that follows the TeamHUD design tokens. It is a developer tool: it is not part of the TeamHUD app people install.

Component Builder: files, spec editor, and chat with diagnostics.

Before you start

Section titled “Before you start”
  • A working clone. See Contribute to TeamHUD.
  • For the AI-assisted parts, an LLM provider key. The builder reads a .env file, found by searching up from where you launch it, and saves your provider choice in its own settings.

Run it

Section titled “Run it”
Terminal window
pnpm start:builder

This builds the component SDK, the renderer and the main process, then opens the app. For a live-reload loop, use two terminals in apps/component-builder: pnpm dev in one, and pnpm start:dev in the other once the renderer server (http://localhost:5173) is ready.

The spec

Section titled “The spec”

A COMPONENT.md has sections. Only Identity and Purpose are required. The rest sharpen the result:

Section What it says
Identity id (namespace.kind.slug), short_name, version, author, tags
Classification kind (widget, layout, utility, connector), category
Purpose goal and primary_user_value, one sentence each
Design style, density, chrome, radius and similar hints
ASCII Layout A text sketch of the component
Inputs Config inputs (name, type, default) and data inputs
Actions What the user can do, and whether the runtime or only the UI handles it

The quick reference is apps/component-builder/docs/SCHEMA-GUIDE.md, and three complete examples are in packages/component-sdk/examples/.

A worked example

Section titled “A worked example”

You will make a small “Quick links” widget spec, check it, and synthesize it, using an agent connected to the builder.

  1. Connect your agent to the builder. The builder starts its own MCP server on http://127.0.0.1:3100 (the next free port if 3100 is taken; get_app_info reports it). Add it to your client’s MCP config, the same way as in Connect an agent. It needs no token.

    { "mcpServers": { "component-builder": { "type": "http", "url": "http://localhost:3100" } } }

  2. Create the component. Ask the agent to call create_component with componentId: "teamhud.widget.quick-links". A new COMPONENT.md appears in the open folder and in the file list.

  3. Write the spec. Ask the agent to fetch the format with get_schema_guide, then call write_spec with:

    COMPONENT.md
    ## Identity
    

    id: teamhud.widget.quick-links
    short_name: Quick Links
    version: 0.1.0
    author: you
    tags:
      - links
    

    ## Classification
    

    kind: widget
    category: productivity
    

    ## Purpose
    

    goal: Show a short list of links the user can open with one click.
    primary_user_value: Gets the user to their most-used pages without opening a browser first.
    

    ## Inputs
    

    ### Config Inputs
    

    - name: title
      type: string
      default: "Quick links"
      description: Header text
    

    ## Spec Status
    

    spec_status: synthesis-ready

  4. Validate. Call validate_spec with the markdown, or get_diagnostics for the file open in the editor. Each diagnostic has a severity, a code, a message and a path. Fix errors and call write_spec again.

  5. Synthesize. Call synthesize with the markdown. It returns the generated files, each with a role, and get_synthesis_result shows the last run. The target is a Lit component styled with the --th-* tokens.

You can do the same in the window: open a folder, use the new-component wizard, edit the spec, and use the chat panel. There is also an extract flow that starts a spec from a URL, HTML or an image.

Agent tools

Section titled “Agent tools”
Tool Use
list_components, get_spec, open_component Find and open specs
create_component, write_spec Make and change a spec
get_schema_guide, validate_spec, get_diagnostics Learn the format and check it
synthesize, get_synthesis_result Generate the code
get_app_info, get_app_state, get_recent_logs, get_panel_content, get_panel_dom See what the app is doing

The complete list, with parameters, is in apps/component-builder/CLAUDE.md.

What you’ll see

Section titled “What you’ll see”

The spec shows no error diagnostics, and get_synthesis_result reports success with a list of output files.

If it goes wrong

Section titled “If it goes wrong”
  • The agent cannot connect. The app is not running, or took another port. Read mcpPort from the app info or the console line [MCP] Component Builder MCP server on ....
  • The window does not start after changing code. Run build:preload after build:main. The preload must be built by esbuild as CommonJS.
  • The chat says it is not configured. Set a provider key in .env or in the builder’s LLM settings. get_llm_status shows provider and model, never the key.

Where next

Section titled “Where next”