AgentHUD

Game-style HUD overlay for AI agents. Live cards for every running agent, drawn over your desktop. One-line drop-in for LangChain, OpenAI Agents SDK, Claude Agent SDK, CrewAI, AutoGen. Skin marketplace where creators publish + earn.

The missing observability layer for the AI-agent era. Live, visual, gorgeous, open.

<p align="center"> <img src="docs/screenshots/hero-persona5-stack.png" alt="AgentHUD — three agent cards live on the Persona5 skin showing TPS, tokens, latency, cost, and a sparkline" width="720"> </p>

---

What problem does this solve?

Agent runtimes are everywhere — LangChain, OpenAI Agents SDK, Claude Agent SDK, CrewAI, AutoGen, Hermes, custom Grok wrappers, your in-house framework. Each one rips through thousands of tool calls per minute, burning tokens, racking up dollars, occasionally failing silently.

The dashboards built for this look like accounting software. Boring web UIs. Dropdowns. Charts. Nothing about them inspires anyone to actually watch what their agents are doing.

AgentHUD takes the opposite angle. Game-HUD energy over your desktop. Every agent gets its own card — animated, themed, dragged anywhere you want — showing live TPS, tokens, latency, cost, success rate, last tool call, sparkline of throughput, and whatever else you push. Cards can be anime, matrix code rain, holographic foil, Iron Man HUD rings, Dead Space spine RIG, Borderlands cel-shaded, Cyberpunk glitch, Persona 5 pop-art, steampunk brass plates, neon, RGB hue-cycle — and that's just the 14 skins we ship.

Anyone with Photoshop / Blender / After Effects / Midjourney can ship a custom skin. Anyone with Rust / Go / C / a plot engine can drop a binary plugin in. Anyone publishing through the community registry can earn from their work.

It's how observability for the agent era should feel.

---

60-second install

pip install agenthud[overlay]
python -m agenthud.overlay &           # start the overlay (one terminal)

Then in your agent code, pick the adapter matching your framework:

# LangChain
from agenthud.adapters.langchain import AgentHUDCallbackHandler
executor.invoke({"input": "..."}, config={"callbacks": [AgentHUDCallbackHandler(name="Research")]})

# OpenAI Agents SDK
from agenthud.adapters.openai_agents import AgentHUDHooks
await Runner.run(agent, input="...", hooks=AgentHUDHooks(name="Research"))

# Claude Agent SDK
from agenthud.adapters.claude_agent import agenthud_hooks_config
ClaudeAgentOptions(hooks=agenthud_hooks_config(name="Coder"))

# CrewAI
from agenthud.adapters.crewai import enable_agenthud
enable_agenthud(per_agent=True)         # one card per role

# AutoGen v0.4+
from agenthud.adapters.autogen import AgentHUDObserver
obs = AgentHUDObserver()
async for evt in team.run_stream(task="..."): obs.handle(evt)

Or just the raw SDK if you're on a custom / proprietary framework:

from agenthud import HUD
hud = HUD(agent_id="my_agent", name="My Agent", color="#00d4ff", icon="🔥")
hud.task_start("T1", "Refactoring user module")
hud.tool_call("read_file", target="src/user.py")
hud.metric("tps", 145.3)
hud.metric("cost_usd", 0.012)
hud.task_done("T1", summary="Refactored 4 files")

The SDK is fail-silent — your agent never crashes because the overlay isn't running. Events queue and ship when the overlay appears.

Full adapter docs →

---

What you see live

<table> <tr> <td align="center" width="33%"> <img src="docs/screenshots/skin-anime-fire.png" alt="anime skin"><br> _{<b>anime</b> — Grok-generated dynamic art per agent, live TPS/TOKS/latency, sparkline.} </td> <td align="center" width="33%"> <img src="docs/screenshots/skin-steampunk-brass.png" alt="steampunk skin"><br> _{<b>steampunk</b> — brass-plate backgrounds + drifting steam particle system.} </td> <td align="center" width="33%"> <img src="docs/screenshots/hero-persona5-stack.png" alt="persona5 skin"><br> _{<b>persona5</b> — pop-art comic panels with red+black aesthetic.} </td> </tr> </table>

Plus: matrix (live cascading katakana code rain), holographic (Pokemon-card foil shimmer), jarvis (Iron Man ring HUD with yellow progress arc), deadspace (segmented spine RIG health bar), cyberpunk (RGB-shift glitch lines), borderlands (comic burst on task done), tactical (military scan arc + corner brackets), neon / rgb / amber / ghost (clean gradient defaults).

Each agent shows:

• Identity — name, role, icon, status dot, sub-agent label (rename inline by double-clicking)
• Throughput — TPS, tokens (split in/out), TTFT, latency
• Health — task success rate %, failed count, avg time per task
• Cost — cost_usd live, derived per provider rates
• Activity — last tool name + target, total tool calls, calls/min
• Sparkline — rolling 32-point graph of any metric

All field-configurable per skin — designers pick what shows where. Push any custom field via hud.metric("brain_temp", 87.3) — show it with a manifest text entry. No allow-list.

---

Theme menu — hover to preview, click to apply

<img src="docs/screenshots/menu-community-24hr-badge.png" alt="Theme menu showing built-in, your skins, and Community sections with 24hr NEW badge" width="280" align="right">

Click the chip (≡) → Theme and just hover any skin name. Cards morph in place to preview that skin — agents stay on screen, just the look changes. Click to commit; click outside to revert.

The Theme list is auto-organized:

• Built-in — ships with AgentHUD (neon / rgb / amber / ghost + 10 polished asset skins)
• Your skins — folders you made yourself in ~/.agenthud/skins/
• Community — installed via the registry browser. Skins added in the last 24 hours get a [24hr] badge.

Per-agent skin override: right-click any card → pick a skin just for THAT agent. CORE_DEV runs on matrix, REVENUE on persona5, HERMES on jarvis — your whole team gets its own personality.

---

Community skin registry + creator earnings

<img src="docs/screenshots/menu-skins-extensibility.png" alt="Skins menu with Browse community skins option" width="380" align="right">

Open ≡ → Skins → 🌐 Browse community skins… to browse and one-click install skins published by the community via IAMMARBIT/agenthud-skins.

Free skins: install directly. Tip the creator via the manifest's tip_url.

Paid skins: click "Buy" → opens the creator's own Stripe Payment Link / Gumroad / Ko-fi checkout. AgentHUD takes 0% in v1. Creators keep 100%.

Want to publish your own? Manifest + zip + PR. Publishing guide →

---

Build literally anything — no ceiling

A creator skin is a folder with a manifest.json and some assets. We don't gate the assets:

| You make in… | Ships as… | Plays in AgentHUD | |---|---|---| | Photoshop / Figma / Procreate | PNG / JPG | ✓ static card background | | After Effects / Premiere | GIF / WebP / MP4 / WebM / MOV / ProRes 4444 (alpha) | ✓ animated / looped video bg | | Blender / C4D / Houdini | rendered MP4 or sprite-sheet PNG | ✓ AAA-grade backgrounds | | Midjourney / Grok / DALL-E / SD | PNG | ✓ AI-generated art | | QML + JavaScript | .qml files loaded via QQuickWidget | ✓ declarative animation | | GLSL shaders | via QOpenGLWidget plugin | ✓ bloom, scanlines, chromatic aberration, CRT | | Rust / Go / Zig / C / C++ / Node / Bash | standalone binary in the skin folder | ✓ native_plugin — zero Python required | | Python | widgets/*.py plugin file | ✓ full QPainter + Qt access |

The native_plugin type spawns your binary, sets AGENTHUD_FRAME_PATH + AGENTHUD_STATE_PATH env vars, and reads PNG frames your binary writes (atomic rename). 30 lines of Rust, you ship an AAA HUD. Rust + Go starter code →

---

Programmatic skin control — agents customize their own HUD

Your agent can generate a skin from a user prompt and apply it immediately, no menu clicks:

hud = HUD(agent_id="my_agent", name="My Agent")

# Let the LLM design + drop a custom skin folder
my_llm.generate_skin_folder(
    prompt="cyberpunk red+cyan dashboard",
    output_dir="~/.agenthud/skins/my_custom/"
)

# Apply it
hud.switch_skin("my_custom")            # global → all cards morph
hud.set_card_skin("anime")              # pin THIS agent's card to anime
hud.rename_card("PRIMARY OPERATOR")     # relabel

That's the killer demo: "Claude, build a cyberpunk dashboard for my swarm and apply it" → done in one prompt.

---

Why this matters

The $200B AI infrastructure market has built dashboards for AI operators. AgentHUD is the missing visual layer between an AI engineer and what their agents are actually doing.

Three reasons it'll stick:

1. Drop-in for the frameworks devs already use. 5 adapters cover ~90% of the agent dev market. pip install agenthud + 3 lines of code = working HUD.
2. Beautiful by default. 14 polished bundled skins set the bar so creators want to one-up them. The skins are the demo.
3. Creator-economy hook from day one. Anyone can publish + earn. Tip URLs in v1, Stripe Connect 70/30 marketplace planned for v2.

The boring observability tools (Langfuse / LangSmith / Helicone / AgentOps / Phoenix) own the enterprise dashboard space. AgentHUD owns the live-visibility-on-your-desktop space + the creator economy around it. Different market, different feel, complementary not competitive.

---

Architecture

   ┌─────────────────────┐
   │   YOUR AGENT CODE   │  ← LangChain / OpenAI Agents / Claude SDK /
   │                     │    CrewAI / AutoGen / Hermes / Grok / custom
   │   hud = HUD(...)    │
   │   hud.task_start()  │
   │   hud.tool_call()   │
   │   hud.metric()      │
   └──────────┬──────────┘
              │
              │   WebSocket events (localhost:8765)
              │   JSON: agent_spawn / task_* / tool_call / metric / ...
              ▼
   ┌─────────────────────┐
   │   agenthud.overlay  │  ← PyQt6 transparent always-on-top windows
   │                     │
   │   ┌───┐ ┌───┐ ┌───┐ │  ← one card per agent, drawn per active skin
   │   │ A │ │ B │ │ C │ │     drag anywhere, double-click to rename,
   │   └───┘ └───┘ └───┘ │     right-click for per-agent skin override
   │                     │
   │   chip (≡) + watermark (live TOK/s counter)
   └─────────────────────┘

• Localhost-only WS by default (127.0.0.1:8765). No remote traffic unless you explicitly install a community skin.
• No telemetry, no analytics, no phone-home. Full threat model →
• Fail-silent SDK. Overlay down? Your agents don't even notice.

---

Docs

| Topic | Where | |---|---| | Framework adapters install | docs/ADAPTERS.md | | Build / publish a skin (free or paid) | docs/PUBLISHING.md | | Manifest format + asset skin system | docs/SKINS.md | | Plugin widgets (Python) | docs/PLUGINS.md | | No-ceiling extensibility (Rust / Go / GLSL / video / sprite sheets / sound) | docs/EXTENSIONS.md | | Security model | SECURITY.md |

---

Roadmap

• v0.2 (now) — core overlay, 14 skins, 5 adapters, community registry browser, native plugins, video bg
• v0.3 — Hermes / OpenClaw / Grok adapter PRs, more compact-strip skins, sound effect library
• v1.0 — Stripe Connect 70/30 marketplace, hosted team dashboards (enterprise)
• future — multi-monitor coordination, OBS / Twitch streaming integration, mobile remote display

---

Contributing

PRs welcome. The codebase is intentionally readable + the plugin / skin system means most contributions don't even need code changes — just drop a folder in the registry.

git clone https://github.com/IAMMARBIT/AgentHUD
cd AgentHUD
pip install -e ".[overlay,dev]"
python -m agenthud.overlay &
python examples/demo_three_agents.py  # 3 agents working live

To bake a custom skin into the registry, see PUBLISHING.md.

---

Tags

#ai-agents #agent-observability #llm-monitoring #agent-dashboard #langchain-dashboard #openai-agents #claude-agent-sdk #crewai #autogen #hud #pyqt6 #overlay #developer-tools #ai-infrastructure #open-source

---

License

MIT © AgentHUD contributors.

Built by IAMMARBIT. Companion repo: agenthud-skins (community registry).