HUD Extension Guide

This guide walks you through adding a custom panel to the HUD. Each level builds on the previous one.

Read the Architecture doc first

This guide assumes you understand the HUD's data flow and panel contract. Read HUD Architecture before continuing.

Level 1 — Hello World Panel

Create a panel file with the minimum required structure:

# raise_cli/hud/panels/my_panel.py
from textual.app import ComposeResult
from textual.widgets import Static, Widget


class MyPanel(Widget):
    def compose(self) -> ComposeResult:
        yield Static("Hello from MyPanel", id="my-content")

    def update_data(self, **kwargs) -> None:
        pass  # receives data pushes but ignores them for now

Wire it into app.py:

# In RaiseHUD.compose(), add a new TabPane:
with TabPane("My Panel", id="tab-my-panel"):
    yield MyPanel()

Run rai hud — your tab appears in the HUD with static text.

Level 2 — Data-driven Panel

Override update_data to consume the kwargs pushed by HUDDataManager:

class MyPanel(Widget):
    def compose(self) -> ComposeResult:
        yield Static("—", id="my-content")

    def update_data(self, **kwargs) -> None:
        pipeline_runs = kwargs.get("pipeline_runs", [])
        count = len(pipeline_runs)
        self.query_one("#my-content", Static).update(f"{count} pipeline runs")

Register the call in app.py's _push_session_data method:

def _push_session_data(self) -> None:
    # ... existing panel calls ...
    try:
        my_panel = self.query_one(MyPanel)
        my_panel.update_data(pipeline_runs=self._pipeline_runs)
    except Exception:
        logger.debug("MyPanel not ready")

Now your panel updates every time _poll_fast runs (every 5 seconds).

Level 3 — Poll-driven Panel

If your panel needs data not already loaded by HUDDataManager, add the load call to _poll_fast (for live data) or _poll_slow (for aggregations):

def _poll_fast(self) -> None:
    if self._data is None:
        return
    # ... existing loads ...
    self._my_data = self._data.load_pipeline_runs(limit=5)  # example
    try:
        my_panel = self.query_one(MyPanel)
        my_panel.update_data(pipeline_runs=self._my_data)
    except Exception:
        logger.debug("MyPanel not ready")

Choosing the right interval:

Interval	Method	Use when
5 s	_poll_fast	Data changes frequently (sessions, runs, signals)
30 s	_poll_slow	Expensive aggregations or data that changes slowly (KPIs, trends)

Your panel is now a full participant in the HUD poll cycle.