Live HUD

Watch your agent run live on top of your app with foglamp/hud.

The HUD is a floating overlay for development. It streams your agent’s execution live on top of your running app: steps, tool calls, tokens, and cost. It uses the same telemetry Foglamp already collects, so you watch your tools run (and fail, and recover) without leaving your app.

The HUD does not need an API key. With hud: true and no apiKey, traces stream to the overlay but aren’t sent to the backend. If you have a key, both happen at once.

What you need

• A React app (the overlay is a React component). Nothing to install beyond foglamp.
• A server running on Node. The overlay connects to a small localhost event server that foglamp({ hud: true }) starts inside your process. It does not work on edge or serverless (see Caveats).

1. Install

If you already use Foglamp, you have everything. Otherwise:

npm

npm i foglamp

2. Turn the HUD on (server)

Pass hud: true where you create the collector:

import { foglamp } from "foglamp";

const fog = foglamp({ hud: true });

That’s the first line. Everything else, like fog.integration(...) on your calls, stays the same. The HUD uses the telemetry you already send.

3. Drop in the overlay (client)

Render <FoglampHUD /> once near the root of your client app, for example in your root layout. Its styles are isolated from yours, and it does nothing unless the local event server is running, so it’s safe to leave in.

import { FoglampHUD } from "foglamp/hud";

export default function RootLayout({ children }) {
  return (
    <>
      {children}
      <FoglampHUD />
    </>
  );
}

That’s the second line. Run your app, trigger an AI flow, and watch it stream.

<FoglampHUD /> props

Prop	Type	Default	Description
port	number	8517	Event server port. Must match foglamp({ hudPort }) if you changed it.
url	string	none	Full event endpoint (absolute URL or same-origin path like /hud/events). Overrides port. Useful when reaching the server through a proxy.
defaultOpen	boolean	false	Start expanded instead of as a collapsed pill.
theme	"light" | "dark" | "system"	"system"	Color theme. "system" follows your app’s .dark class or the OS.
redact	boolean	false	Hide prompt, response, and tool payloads on screen. Turn on before recording or screen sharing.

Server options

Two fields on foglamp(config) control the event server. See Configuration for the full table.

Option	Type	Default	Description
hud	boolean	false	Start the local HUD event server. Can also be set with FOGLAMP_HUD=1.
hudPort	number	8517	Port for the event server. Also FOGLAMP_HUD_PORT.

The client port and the server hudPort must match. If you run more than one HUD-enabled process locally, give each its own port and point its <FoglampHUD port={…} /> at it.

Recording a demo

Set redact before you record or screen share. It hides every prompt, response, and tool payload while keeping the timing, token, and cost view:

<FoglampHUD redact />

Caveats

The HUD is for local development only. hud: true is ignored in production and on edge or serverless runtimes, because the event server needs a long-lived Node process. Your normal telemetry is unaffected; only the overlay is turned off.

• Node runtime, not edge. On Next.js, the route or handler that creates foglamp({ hud: true }) must run on the Node runtime (the default), not export const runtime = "edge".

• No production cost. The HUD’s server code is loaded lazily and never enters your edge or browser bundle. The core foglamp entry stays free of React and HTTP code.

• Safe to commit. <FoglampHUD /> does nothing unless the event server is running, so leaving both lines in is harmless. To be explicit, gate it to dev:

  const fog = foglamp({ hud: process.env.NODE_ENV !== "production" });