A HUD is a heads-up display: the health bars and quest line a game keeps on screen while you
play. Quest HUD is a Claude Code mod that draws your session that way, above the prompt:
[avatar] The anvil is hot. Strike while it lasts.
⚔ gku:implement Forge task 2/5 · Write the CSV writer tests
♥ HP █████████░░░░░ 62% week · heals in 2d 4h ✦ MP ████████░░░░░░ 59% ctx · 82k/200k
- ♥ HP: what is left of your weekly usage window. It turns yellow below 40% and red below 20%.
- ✦ MP: what is left of the context window.
- ⏾: what is left of your 5-hour window, and the time it resets, as
⏾ 30% · 14:30: the power
sleep symbol, as even a wizard needs to rest. It shows once it runs low (under 40% left, or less
than HP) and takes HP's colours; bars = all shows it always.
- ⚔ the quest: the running skill, from any plugin, and its zone, with Claude Code's task list.
- The line above it: a tip when this session calls for one, otherwise a word from the zone. It changes at each turn, and
flavor = off removes it.
It costs nothing: no model calls, nothing added to the context, and nothing written into your
project. It reads your past sessions only if you ask it to, with
/quest-hud:level, and then keeps counts, not what they said. It uses the network
only if you ask it to, with /quest-hud:quests, through your own gh.
Try it live in your browser: the settings and commands, on the mod's real drawing code and an invented session.
Install · Update · Settings · Commands · Your level · The Quest Board · The Road · Without mods · Art · Development · License
Install
At the prompt of a Claude Code session:
/plugin install quest-hud --marketplace matasarei/quest-hud
Answer y to add the marketplace, then pick a scope. From a shell:
claude plugin install quest-hud --marketplace matasarei/quest-hud.
Requires Claude Code 2.1.316 or later. The mod API is early access and may change between
releases.
Update
claude plugin marketplace update quest-hud
claude plugin update quest-hud@quest-hud
Then restart Claude Code.
An update can't reach a status line you copied to ~/.claude/hud-line.sh, and an older copy
silently ignores --all. To update it, copy the script again: /quest-hud:statusline prints the
command.
Settings
Run /plugin configure quest-hud@quest-hud, then /reload-plugins.
| Option | Values | Default | What it does |
|---|
detail | off, status, band, pane | band | nothing; dim bars on the hint line under the prompt (terminal only, so use band in the desktop app); the band above the prompt; or the band, with the Road opened when the session starts (placed from 144 columns) |
bars | hpmp, all | hpmp | hpmp adds the 5-hour window (⏾) once it runs low; all shows it always, with the session cost (◉) |
avatar | wizard, claude, octocat | wizard | who the band's portrait shows: the wizard, Claude's mascot or GitHub's Octocat. The Road keeps its own cast |
flavor | on, off | on | one dim line above the quest on the band: a tip when this session calls for one (a standing monster, MP or HP below 20%), otherwise a word from the zone. It changes at each turn |
zones | name=zone, … | empty | extra skill-to-zone rules, e.g. quest=forge, triage=map |
graphics | auto, cells, images | auto | how a terminal draws the Road's scene: found out once a session, or always cells, or always images |
Zones: watchtower, harbour, dungeon, arena, forge, map, camp, wilds. A name
is a skill's full name (gku:plan) or the part after the plugin prefix (plan).
Commands
| Command | What it does |
|---|
/quest-hud:status | prints the current state, what the zone means, and the task list |
/quest-hud:pane | opens the Road at any width |
/quest-hud:level | reads your setup and sessions, as counts, and scores the harness from 1 to 10 |
/quest-hud:level-up | quests for the next level: what to add, picked from what you work on |
/quest-hud:quests | your open GitHub work and alerts as quests on the Quest Board, ranked and linked |
/quest-hud:statusline | prints the setup for the status line |
/quest-hud:off | hides the band, the hint-line bars and the Road in every session, until on; it comes back up to date |
/quest-hud:on | brings them back, with the Road if off closed it |
/quest-hud:help | lists the commands and the options, with the values in force |
The mod answers each one itself, with no model call. /quest-hud pane with a space works too,
and a word /quest-hud does not know shows the list. A typo after the colon, such as
/quest-hud:pan, reaches the model as an ordinary message.
The only file the mod writes is a small JSON file in Claude Code's configuration folder: off's
switch, and your level with the counts behind it.
Your level
/quest-hud:level scores your Claude Code setup from 1 (Novice) to 10 (Grand Wizard) and shows
the level on the Road, beside the bars. It describes the environment, not you, and the scale is
this game's own, not a benchmark.
| Part | What raises it |
|---|
| Instructions | a CLAUDE.md or AGENTS.md in the projects you work in |
| Memory | notes kept across projects |
| Skills | skills you run, not only ones installed, and one of your own |
| Checks | test and lint runs in the sessions that edit code |
| Guardrails | hooks and deny rules |
| Tools | a language server for your main language, and an MCP server in use |
| Delegation | subagents in use, and one of your own |
This is the beginning of the README. Read the rest at the original. Read the full README ↗
