claudeers.
// Claude Plugins

spark-hud

✻ An animated HUD for Claude Code, with Claude's mascot: live context window, Max plan 5h/7d limits with pace forecast, cost, subagents and all your Claude w…

Actively maintained
100/100
last commit 17 days ago
last release 25 days ago
releases 4
open issues 0

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up spark-hud (claude-plugin project) into my current project.
Found on https://claudeers.com/spark-hud
Repo: https://github.com/Mel0nidas/spark-hud
Homepage/docs: https://github.com/Mel0nidas/spark-hud#install
Detected install method: claude-plugin → /plugin install spark-hud@Mel0nidas/spark-hud
Category: plugins. Platforms: cli, api.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
active; community-verified: false. Confirm the source before running anything.
// or install directly (claude-plugin)
/plugin marketplace add Mel0nidas/spark-hud
/plugin install spark-hud@Mel0nidas/spark-hud
// or clone
git clone https://github.com/Mel0nidas/spark-hud

// compatibility

Platformscli, api
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageTypeScript

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

✻ Spark HUD

See your context window, your Max plan limits and every agent at a glance, right above the Claude Code prompt.

Spark HUD sitting above the Claude Code prompt

Claude Code tells you a lot, but only when you ask: /context for the window, /cost for the bill, a warning when you are already close to the limit. Spark HUD keeps all of it on screen, live, in two compact lines that stay out of your way. Click one button and it opens into a full dashboard.

It is built for people who run long sessions on a Max subscription and work with many agents and windows at once.

Why you'll want it

Without Spark HUDWith Spark HUD
You find out the context is full when autocompact kicks inA live bar shows how full the context is, and where autocompact will trigger
"Am I going to hit my 5-hour limit?" is a guessA pace forecast compares your usage with the time left and warns you before the window runs out
Subagents are a black box until they report backEach agent's current action shows live, and one click opens its full transcript
Checking your other Claude windows means alt-tabbing through themEvery open Claude Code window shows its project, model, context fill and current action in one list

Features

📊 Context window, live

  • Fill bar with 1/8-cell precision, tokens used / window size, and the autocompact threshold.
  • A breakdown of what fills the window (messages, system tools, MCP tools, memory files) when expanded.
  • A toast when you pass 85%, a good moment to /compact.

⏳ Max plan limits, with pace forecasting

  • 5-hour and 7-day windows with their reset countdowns.
  • Pace forecast: compares the share of the limit you've used with the share of time that has passed, and tells you whether you're comfortable, ahead of pace, or on track to run out before the reset (and when).
  • Toasts at 75% and at 90%.

🤖 Agents, without opening their transcripts

  • Every subagent and teammate in the session, with a spinner, its type, its task and its latest tool call.
  • Tool count and running time for each one; finished agents get ✔, failed ones get ✘.

🔍 Agent viewer: see inside any subagent

  • Click an agent in the HUD (or run /hud-agents) and a panel opens with its live transcript: the task it got, what it is saying, and every tool call with a one-line result (errors in red).
  • Shows the agent's own context usage, its model, tool count and running time.
  • Flip between agents with ◀ ▶ and close it with Esc. It updates every second while the agent runs, and you never leave your current window.
Agent viewer: a subagent's task, messages and tool calls with results, live

🪟 All your windows in one place

  • Every Claude Code session running Spark HUD sends a small heartbeat. Each window then lists the others: project, model, context %, running agents and what each one is doing right now.
  • /hud-panel opens a side panel with the full list, which works well in fullscreen.

💡 Session stats and tips

  • API-equivalent cost, tool calls, last turn duration, cache hit rate and output tokens.
  • Tips based on your numbers: compact soon, switch to Sonnet for simple work, protect your prompt cache, watch out with too many parallel agents.

✨ It's alive (but calm)

  • Claude's mascot lives on the right side of the HUD, away from your numbers. It blinks at rest, dances while Claude works, celebrates when a turn ends and sweats when the context is nearly full. It wears the colors of your theme.
  • Animated gradient rules frame the widget so it never blends into the transcript.
  • A soft glint runs along the bars while a turn is in progress.
Expanded view: context breakdown, Max plan limits with pace, session stats, agents and other windows

Themes

Seven calm palettes: a dark neutral plus one accent color, starting with Claude orange. The theme only changes when you ask: press 🎨 theme or run /hud-theme to switch to the next one, and your pick is remembered for new sessions.

The seven themes: Claude, Black & Red, Graphite & Amber, Slate & Blue, Forest, Ink & Bone, Wine

Install

In Claude Code, run:

/plugin install spark-hud --marketplace Mel0nidas/spark-hud

Answer y to add the marketplace and pick the user scope. The HUD appears right away and in every new session. There is nothing to configure.

Install from a local clone
git clone https://github.com/Mel0nidas/spark-hud.git
claude plugin marketplace add ./spark-hud
claude plugin install spark-hud@agus-mods --scope user

Claude Code reads a folder marketplace straight from disk. After you edit the files, run /reload-plugins.

Usage

Command / controlWhat it does
▾ more / ▴ less or /hudExpand or collapse the dashboard
Click an agent or /hud-agentsOpen the agent viewer with its live transcript (◀ ▶ switch, Esc closes)
◫ panel or /hud-panelOpen the side panel with all agents and windows
🎨 theme or /hud-themeSwitch to the next color theme
ctrl+x tabFocus the HUD to use its buttons from the keyboard

The layout adapts to the terminal width. On narrow terminals the bars get shorter and the secondary figures are hidden.

How it works

Spark HUD is a Claude Code mod: a single TypeScript hooks module that runs inside Claude Code's plugin sandbox. It has no Node, no network access and no background process of its own.

DataSource
Context, limits, cost$.session.usage() and the session.measure event: the same figures as the status line, pushed when they change
Context breakdown$.session.usage({ breakdown: 'summary' }), a local estimate that makes no API calls
Agents$.agent.list() plus each tool.call that carries an agentId
Agent viewer$.session.messages({ agentId }) (the subagent's own transcript) and each turn.step's usage for its context
Other windowsA small JSON heartbeat per session in ~/.claude/spark-hud/sessions/, written every ~5 s
AnimationOne timer: ~4.5 fps while Claude works, ~1 fps at rest

Privacy: everything stays on your machine. The only file Spark HUD writes is its heartbeat (project folder name, model, context %, last action), and it never sends data anywhere.

Requirements

  • Claude Code 2.1.295 or newer (function-hook mods).
  • Rate-limit bars appear on Claude subscriptions (Pro / Max) after the first response; API-key users still get context, cost, agents and windows.

Development

claude plugin validate .   # manifest + hooks module, as the engine reads them
claude plugin test .       # runs tests/*.test.ts against the engine

To hot-reload while you edit, run claude --plugin-dir ./spark-hud. Saving a file reloads the mod.

Roadmap

  • Sparkline of context growth per turn
  • Click a window in the list to bring it to the front

Ideas and PRs are welcome. Open an issue!

License

MIT © agusneocube

Made with ✻ and Claude Code.

// faq

What is spark-hud?

✻ An animated HUD for Claude Code, with Claude's mascot: live context window, Max plan 5h/7d limits with pace forecast, cost, subagents and all your Claude windows, right above the prompt.. It is open-source on GitHub.

Is spark-hud free to use?

spark-hud is open-source under the MIT license, so it is free to use.

What category does spark-hud belong to?

spark-hud is listed under plugins in the Claudeers registry of Claude-compatible tools.

4 views
★ 14 stars
unclaimed
updated about 1 month ago

// embed badge

spark-hud on Claudeers
[![Claudeers](https://claudeers.com/api/badge/spark-hud.svg)](https://claudeers.com/spark-hud)

// retro hit counter

spark-hud hit counter
[![Hits](https://claudeers.com/api/counter/spark-hud.svg)](https://claudeers.com/spark-hud)

// reviews

// guestbook

0/500

// related in Claude Plugins

🔓

A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls.

// pluginsmultica-ai/★ 230,631[ claude ]
🔓

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explainin…

// pluginsanthropics/⟨Python⟩★ 156,472[ claude ]
🔓

"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/

// pluginsHKUDS/⟨Python⟩★ 58,467◷ Apache-2.0[ claude ]
🔓

financial-services — a Claude ecosystem project on GitHub.

// pluginsanthropics/⟨Python⟩★ 41,409◷ Apache-2.0[ claude ]
→ see how spark-hud connects across the ecosystem