VisualHUD

A themeable visual status engine for Claude Code, Codex, and iTerm2.

Watch your terminal transform in real-time as your agent works — colors shift, backgrounds swap, and tab titles update to show exactly where things stand. Ship with themes or build your own.

Install

Codex on macOS/iTerm2, Windows Terminal/PowerShell, or WezTerm, from the repo you want to skin:

npx -y visualhud@latest
codex --yolo

That installs VisualHUD into the current Git repo only. It writes .codex/, .visualhud/, and .agents/skills/visualhud-* in that repo; it does not install a global Codex or Claude hook.

VisualHUD setup/update skills should run platform setup helpers themselves. For example, when a Windows repo should use WezTerm for live colors/backgrounds, the skill should install with --platform wezterm, run setup-wezterm.ps1, and handle straightforward config merges instead of sending you manual follow-up commands.

On macOS/iTerm2, if iTerm2 has not been configured for tab colors and pane background images yet, run this once after install, then quit and reopen iTerm2:

./.visualhud/setup-iterm2.sh

When developing from this source checkout, the equivalent local command is ./setup-iterm2.sh.

On Windows/WezTerm, install with the WezTerm renderer and run the setup helper once:

npx -y visualhud@latest install codex --platform wezterm
powershell -ExecutionPolicy Bypass -File ./.visualhud/setup-wezterm.ps1

Screenshots

Pokemon is the polished default for clean consumer installs:

Common Commands

Install into a specific repo from anywhere:

npx -y visualhud@latest install codex --target /path/to/other-repo

Choose TMNT during install:

npx -y visualhud@latest --theme tmnt

Switch themes after install; the next hook picks it up without restarting Codex:

./.visualhud/visualhud theme list
./.visualhud/visualhud theme set pokemon
./.visualhud/visualhud theme set tmnt
./.visualhud/visualhud theme current

Calibrate a theme:

./.visualhud/visualhud theme calibrate tmnt
./.visualhud/visualhud theme calibrate tmnt --live --delay 1

Development checkout install:

./visualhud install codex --target /path/to/other-repo

The installer writes:

/path/to/repo/
  .codex/hooks.json
  .codex/hooks/visualhud-codex.sh
  .visualhud/
    engine.sh
    set_bg.py
    setup-iterm2.sh
    setup-wezterm.ps1
    visualhud
    wezterm/
    themes/
  .agents/skills/
    visualhud-setup/
    visualhud-update/
    visualhud-theme/
    visualhud-feedback/

Claude support is repo-local and separate from Codex. Claude projects wire .claude/settings.json to .claude/hooks/visualhud-claude.sh; Codex projects wire .codex/hooks.json to .codex/hooks/visualhud-codex.sh.

Windows Terminal/PowerShell uses a separate renderer track for tab title and progress status. WezTerm is the Windows path for live VisualHUD backgrounds: VisualHUD emits a visualhudState user var and the WezTerm Lua module applies per-window background/color overrides. Dynamic background images remain unsupported in Windows Terminal because it exposes background images through profile settings, not a per-hook escape sequence.

Release To npm

scripts/release-npm.sh --dry-run

That command checks npm auth, runs the full test suite, and runs npm publish --dry-run without publishing.

Publish only after the dry-run is clean and npm auth is active:

scripts/release-npm.sh --publish

The publish path repeats the full test gate, repeats the npm dry-run, publishes, then verifies the exact package version on the registry. If npm whoami fails, run npm login in your shell and retry.

First publish bootstrap: npm requires account authentication for the initial package publish. If your npm account requires two-factor auth, the first scripts/release-npm.sh --publish may ask for an OTP or npm web auth.

After the package exists on npm, configure npm Trusted Publishing from this repo with:

npm run release:trust

That workflow publishes on version tags with GitHub OIDC (id-token: write) and does not use NPM_TOKEN. Normal future releases should be version-bump, test, commit, tag, and push the v* tag; the workflow runs npm ci, npm test, and npm publish --access public.

Create A Theme

Themes are data packs. A normal new theme should not require editing engine.sh.

Tell your agent to follow THEMES.md and keep the work under this shape:

themes/<name>/theme.json
themes/<name>/sprites/

Minimum workflow:

mkdir -p themes/<name>/sprites
$EDITOR themes/<name>/theme.json
./visualhud theme set <name>
./visualhud theme calibrate <name>
bash tests/test-theme-system.sh
bash tests/test-theme-calibration.sh

For branded/character themes, add real source-backed sprite assets and a contact-sheet proof. Do not ship generated placeholders as final art. If adding a theme requires engine changes, treat that as a theme-system contract change: write the failing test first, update the JSON contract deliberately, then run the full proof set in THEMES.md.

Future work: a dedicated theme creator workflow should scaffold the JSON, sprite folders, calibration sheet, and TODO checklist automatically. Until that exists, THEMES.md is the source of truth for agents and humans creating Batman, Sonic, Power Rangers, or any third-party theme.

5. Use With Claude Code

Claude Code is wired separately through:

.claude/settings.json
.claude/hooks/visualhud-claude.sh

Start or restart Claude Code from this repo. The Claude adapter defaults to the Pokemon theme and preserves the existing SDLC/TDD hooks.

To use TMNT for this repo, run:

./visualhud theme set tmnt

The next hook picks up the selected theme. To override only one Claude process:

VISUALHUD_THEME=tmnt claude

5. Verify

Run the contract tests before calling an install or theme change done:

bash tests/test-visualhud-cli.sh
bash tests/test-visualhud-install.sh
bash tests/test-theme-system.sh
bash tests/test-visualhud-skills.sh
bash tests/test-theme-calibration.sh
bash tests/test-codex-visualhud.sh
bash tests/test-claude-visualhud.sh
bash tests/test-cooking-status.sh

For visual changes, also review a screenshot, generated contact sheet, or a calibration walk. Shell tests prove hook output and state transitions; they do not prove aesthetics by themselves.

Generate the full ordered calibration list when a theme has too many visual states to inspect ad hoc:

./visualhud theme calibrate tmnt
./visualhud theme calibrate tmnt --json

From a real iTerm2 pane, walk the same cycle one step at a time and correct specific step numbers:

./visualhud theme calibrate tmnt --live --delay 1
./visualhud theme calibrate tmnt --live --pause

Windows Status

Windows Terminal/PowerShell is supported for Codex hook install, title updates, and Windows Terminal progress status. The theme JSON contract is portable and the runtime does not require jq; JSON handling is done by the bundled Node helper under scripts/.

WezTerm is supported for Codex hook install, title updates, and live background/color changes. The WezTerm renderer sends a visualhudState user var to wezterm/visualhud.lua, which updates the current window with window:set_config_overrides().

Windows Terminal background images are still static profile settings. Use the WezTerm renderer for live sprite changes on Windows.

How It Works

Claude Code and Codex fire lifecycle hooks on prompt, tool use, permission request, and stop events. VisualHUD intercepts those hooks and drives the terminal through a progression of stages — each with its own colors, background image where supported, and title.

Hook fires → adapter normalizes event → counter increments → stage advances → terminal renderer updates

Each terminal session is isolated via ITERM_SESSION_ID, WT_SESSION, or the hook payload session id, so multiple windows don't stomp each other.

Review work is a separate lifecycle state from done. If a Codex/Claude code review or background verification task is still running, VisualHUD shows the theme's review state and keeps done/Mew/Pizza Party reserved for when that review task completes.

Themes

A theme is a directory with a config file and optional assets:

themes/
  pokemon/
    theme.json
    sprites/
      charmander.png
      charmeleon.png
      ...
  tmnt/
    theme.json
    sprites/
      tmnt-leonardo.png
      tmnt-michelangelo.png
      ...
  custom/
    theme.json

Theme Config (theme.json)

See THEMES.md for the complete contract and required tests.

{
  "name": "Example Theme",
  "progress_bar": ["A", "B", "C"],
  "stages": [
    {
      "max": 2,
      "sprite": "alpha",
      "badge": "A",
      "name": "Alpha",
      "color_family": "blue",
      "color": [10, 20, 30],
      "shades": [[10, 20, 30], [20, 35, 55]]
    },
    {
      "max": 5,
      "sprite": "beta",
      "badge": "B",
      "name": "Beta",
      "color_family": "orange",
      "color": [40, 50, 60],
      "shades": [[40, 50, 60], [65, 75, 85], [85, 95, 110]],
      "shade_sprites": ["beta", "beta-warm", "beta-hot"]
    },
    {
      "max": 999999,
      "sprite": "gamma",
      "badge": "C",
      "name": "Gamma",
      "color_family": "green",
      "color": [70, 80, 90],
      "shades": [[70, 80, 90], [90, 110, 120]]
    }
  ],
  "blocked": { "sprite": "blocked", "badge": "BLOCK", "name": "Blocked", "color": [80, 75, 95] },
  "review": { "sprite": "review", "badge": "REV", "name": "Reviewing", "stage": 2, "color": [80, 120, 200] },
  "done": {
    "sprite": "done",
    "badge": "DONE",
    "name": "Done",
    "stage": 3,
    "color": [40, 100, 255]
  },
  "idle": { "sprite": "idle", "badge": "IDLE", "name": "Idle", "stage": 3, "color": [40, 100, 255] },
  "error": { "sprite": "error", "badge": "ERROR", "name": "Error", "color": [255, 40, 40] },
  "context_alerts": {
    "warning": { "min_percent": 70, "badge": "WARN", "name": "Context High", "color": [255, 190, 40] },
    "critical": { "min_percent": 85, "badge": "CRIT", "name": "Context Critical", "color": [255, 255, 255] }
  }
}

Default Theme: Progress Bar

No images needed — just a smooth color gradient that acts as a visual progress bar: red (just started) through yellow/green (making progress) to blue (done). It's a progress bar, not a health bar — the color tracks how far along the task is, not how "healthy" anything is. Works out of the box.

Landscape — What Else Is Out There?

We researched the space. Nothing does what VisualHUD does.

Tool	Changes Terminal Appearance	Driven by Process State	Configurable Themes	Multi-Terminal
VisualHUD (this)	bg + tab color + images + title	Claude Code hooks	Yes (theme.json)	Goal
claude-code-iterm2-tab-status	Tab title emoji only	Claude Code hooks	No (3 hardcoded states)	No
aiterm	Profile switch	Directory-based (cd)	No	Yes (6 terminals)
classmethod.jp blog	Background color	Start/stop only	No (2 hardcoded states)	No
Zestful	Separate overlay	Claude Code hooks	No	N/A
C.H.U.D.	Separate Electron window	Claude Code hooks	No	N/A
ccstatusline	Statusline text	Claude Code API	Yes (text themes)	N/A
claude-hud	Statusline text	Claude Code API	No	N/A

The gap: Existing tools either change appearance but not based on process state (aiterm, sshbg), or react to process state through overlays / statuslines / tab emoji — not the terminal itself. Nobody ships a configurable state machine that drives full terminal appearance through hook lifecycle events.

Complementary tools we could integrate with:

ccstatusline / claude-hud — they handle the statusline, we handle the terminal chrome
aiterm — they set a baseline profile per project, we modulate it during runtime
agent-notify — they do audio/push notifications, we do visual

Terminal escape code references for multi-terminal support:

iTerm2: OSC 1337;SetColors, tab color via OSC 6;1;bg, Python API for background images
Kitty: kitten @ set-colors, background via kitten @ set-background-image
WezTerm: Lua set_config_overrides for colors and background
Ghostty: SIGUSR2 config reload for theme switching
tmux: status bar styling via set-option

What Works Today

VisualHUD is repo-local and functional for Codex, Claude Code, and iTerm2:

Working:

Tab color changes via iTerm2 escape sequences (OSC 6;1;bg and SetColors=tab) with per-session isolation.
Background, selection, cursor, and muted UI surface colors update through OSC 1337;SetColors.
Window/tab title, badge text, and hudProgress/hudContext user vars update from hook lifecycle state.
Background images update through the iTerm2 Python API (LocalWriteOnlyProfile) for the active terminal session.
Windows Terminal/PowerShell installs for Codex and updates the tab title plus OSC 9;4 progress status.
WezTerm installs for Codex and updates title, right status, colors, and live background sprites through OSC 1337;SetUserVar plus the bundled Lua module.
PreToolUse, UserPromptSubmit, Notification, PermissionRequest, Stop, StopFailure, TaskCompleted, and SessionStart are mapped into the engine by repo-local adapters.
Theme stages use color_family plus shades, so a character can keep the same sprite while the terminal chrome advances through multiple color steps.
Pokemon and TMNT both ship source-backed sprite packs and theme JSON.
Context/token pressure is an ambient overlay: warning and critical label the state while preserving the active stage color/sprite.

Current hooks:

.codex/hooks/visualhud-codex.sh maps Codex events into engine.sh and falls back to TMNT when no active theme file exists. Clean installs into other Codex repos write Pokemon as the active theme by default.
.claude/hooks/visualhud-claude.sh maps Claude Code events into engine.sh and defaults to Pokemon.
Both adapters set VISUALHUD_REAPPLY_DELAY=0.12 by default to reapply title/color after TUI repaint.

Known limitations:

iTerm2 and WezTerm are the complete live-background renderers today; Windows Terminal/PowerShell has title/progress support but not dynamic background images.
Background images are static only; sprite animation is parked until a terminal adapter supports it cleanly.
Badge content is text/emoji only because iTerm2 does not support image badges.
Snapshot/restore of the original terminal profile is still planned.

Tested and confirmed:

Background image per-session isolation works via ITERM_SESSION_ID UUID extraction.
GIF backgrounds do not animate in iTerm2; frame cycling works, but low-res source GIFs are not good enough for full-screen backgrounds.
iTerm2 does not support images in badges or corners: badges are text/emoji only, status bar icons are tiny, and inline images scroll with text.
Pokemon HOME sprites and source-backed TMNT panel crops work as static backgrounds.

Sprite Animation

Themes can offer both static and animated sprites. Two approaches, depending on terminal support:

Approach 1: Native GIF Background

Set an animated GIF directly as the background image. If the terminal animates it natively, this is zero-effort animation.

Terminal	Animated GIF Background	Status
WezTerm	Natively supported	Confirmed working
iTerm2	First frame only, no animation	Confirmed not supported (2026-03-22)
Kitty	Graphics protocol has frame support	Untested
Ghostty	PNG/JPEG only, no GIF	Not supported

Test script: ./test-gif-background.sh

Approach 2: Frame Cycling

Extract GIF frames to individual PNGs, cycle them as background images via the Python API. Tested on iTerm2: animation is smooth, but source sprites are too low-res (48-133px) for 4K displays. Would need high-res source art (512px+) to look good.

Charmander: 69 frames, 30ms intervals (~33 FPS) — smooth animation confirmed
Source quality is the bottleneck, not the cycling mechanism
No open-source high-res animated Pokemon sprites exist (all game sprites are pixel art < 133px)
AI upscaling produces blurry results on pixel art at this scale

Test script: ./test-frame-cycling.sh

Status: Parked. The frame cycling mechanism works. Revisit when high-res animated source art is available or AI upscaling improves.

Theme Config with Animation

Animation is parked until a terminal adapter supports it cleanly. A future theme extension should keep the current stage contract and add animation fields beside "sprite" instead of replacing the base sprite.

{
  "stages": [
    {
      "name": "Charmander",
      "max": 2,
      "sprite": "charmander",
      "color": [255, 60, 60],
      "badge": "FIRE",
      "animated_sprite": "charmander-run"
    }
  ]
}

Engine support for animated_sprite is not implemented yet. Add a failing test before making that contract real.

Color Shades

Theme stages can define multiple "shades" for the same character. The engine chooses a shade from the current tool-call position inside that stage's range, so the sprite stays stable while the terminal chrome visibly advances:

Michelangelo (max 5)
tool 3 -> [255, 125, 25]
tool 4 -> [255, 150, 48]
tool 5 -> [255, 175, 70]

This is deliberate stage-local shading rather than cross-stage interpolation. Stages can also define "shade_sprites" with one sprite per shade when the art should advance with the color. TMNT uses this for character-color variants, and future themes such as Batman and Power Rangers should use the same JSON-plus-sprites contract instead of changing engine.sh.

Token Usage Indicator (Separate from Task Progress)

Task completion (stage progression) is the main visual driver — background, tab color, images.

Token/context usage is a separate ambient indicator that doesn't interfere with the main visual:

Badge/title suffix surfaces only when it matters (CTX 70%+ warning, CTX 85%+ critical)
The task stage color, cursor, and sprite stay intact; context labels must not gray-wash or emergency-wash the pane
Themes can name those alerts: Pokemon uses Pokemon Center/Chansey and Nurse Joy/Blissey, TMNT uses Casey Jones for critical context
Codex can derive context percent from hook payload token data or a matching session JSONL token-count event

These are independent axes: you can be on stage 3 (Charizard) with low token usage, or stage 1 (Charmander) with high token usage.

TMNT Source Art Import

The TMNT skin is only visually complete once real source images exist on disk. Chat attachments are not repo files, so place a four-panel character-select reference at:

assets/source/tmnt/character-select.png

Then generate source-backed sprite assets:

python3 scripts/import-tmnt-sprites.py \
  --source assets/source/tmnt/character-select.png \
  --output-dir themes/tmnt/sprites \
  --source-label "tmnt-character-select-reference"

The importer writes tmnt-leonardo.png, tmnt-michelangelo.png, tmnt-donatello.png, tmnt-raphael.png, and manifest.json with crop provenance. Do not ship generated placeholder TMNT art; source-backed PNGs must include the manifest.

For character-focused one-off assets, the importer strips neutral corner mattes from source images and renders transparent areas over the matching theme color. The generated manifest records that color as backdrop_color, which prevents yellow April, white Casey, or other stage families from drifting back to gray.

Key Bugs We Fixed

Documenting these so we don't repeat them:

ITERM_SESSION_ID format mismatch — The env var is w0t0p0:UUID but the iTerm2 Python API's session.session_id is just UUID. Must strip the prefix: sid.split(":")[-1]. This caused background images to silently never match any session.
iTerm2 Python API connection — Requires "Enable Python API" in iTerm2 Preferences > General > Magic. Without it, all Python API calls fail silently if errors are suppressed.
Badge positioning — badge_top_margin is pixel-based, which breaks on different window sizes. Fix: dynamically calculate from window height on each stage change (rows * cell_height * 0.85).
Cross-window contamination — Original implementation used TTY device for session isolation, which doesn't work in hook sandbox context (ps is blocked, tty returns garbage). Fix: use ITERM_SESSION_ID env var which is always inherited by child processes.
Badge disappears on resize/different monitors — badge_top_margin is pixel-based (not percentage). When the window is shorter than the margin value, the badge goes off-screen. Moving windows between monitors with different sizes makes it worse. Dynamic recalculation in set_bg.py helps but only fires on stage transitions, not on resize. Needs a resize listener in v0.1.

Status

Pre-release. Repo-local Codex and Claude Code hook wiring works on iTerm2. Windows Terminal/PowerShell Codex installs work for title and progress status. WezTerm Codex installs work for title, status, colors, and live backgrounds on Windows.

Ideas Borrowed From the Ecosystem

Deep-dived every project above and pulled the best patterns:

Idea	Stolen From	Why It's Good
Snapshot/restore terminal state on exit	JasperSui	Clean teardown — save tab color, title, badge before we touch anything, restore when Claude stops
"Needs attention" state via `Notification` hook	JasperSui	We only use PreToolUse/Stop — missing the "waiting for permission" state entirely
Stale PID cleanup for orphaned state files	JasperSui	Dead sessions shouldn't leave ghost state files around
Auto-contrast color adjustment	JasperSui	If theme color is too close to tab's existing color, auto-pick a visible alternative
Terminal abstraction layer (per-terminal module)	aiterm	Each terminal (iTerm2, Kitty, Ghostty, WezTerm) gets its own adapter with same interface
Context health thresholds (green <70%, yellow 70-84%, red 85%+)	ccstatusline	Modulate visual intensity based on context window usage
DI pattern for testing (no heavy mocks)	claude-hud	Inject deps, test cleanly
Config priority: env vars > config file > defaults	JasperSui	Standard, flexible, zero-surprise
Hot-reload config on file mtime change	JasperSui	Change theme without restarting Claude
Focus-to-dismiss attention state	JasperSui	Attention clears when user looks at the tab
Multi-agent priority display (highest alert wins)	Zestful	When running multiple sessions, show the most urgent state

Roadmap

Now — Extract & Polish (v0.1)

Core engine + themeable + works reliably:

Done:

Current focus — Harden the theme engine:

The theme engine is now data-driven: engine.sh reads theme.json, advances stage counters, applies stage shades, resolves sprite paths, and drives iTerm2. Pokemon and TMNT live under themes/, and both Codex and Claude use repo-local adapters.

Next hardening work:

Replace any weak TMNT one-off cover-art states with character-focused source art.
Add the next branded theme candidates, Batman and Power Rangers, as JSON/sprite packs that prove third-theme parity without engine changes.
Add a terminal-renderer abstraction for Windows Terminal/PowerShell, Kitty, WezTerm, and Ghostty.
Add snapshot/restore so VisualHUD can return terminal chrome to its original state.
Add a CLI installer/doctor once the repo-local contract is stable.

Then — Polish:

Window border integration (JankyBorders) — colored border around iTerm2 window that changes with stage progression:
- Uses JankyBorders (brew install borders) with apply-to=<window-id> for per-window support
- Border color matches current stage (red → yellow → green → blue)
- Border thickness increases as task progresses (thin at start, thick at done)
- Done state: thick border stays in final color as persistent visual indicator
- Supports multiple iTerm2 windows simultaneously (each gets its own border color based on its session state)
- Replaces any current janky border solution entirely
- Get window ID via macOS Accessibility API or yabai, pass to borders apply-to=<wid> active_color=0xffRRGGBB width=N
- Supports gradient (gradient(top_left=...,bottom_right=...)) and glow (glow(0xAARRGGBB)) effects
- Requires macOS 14.0+ (Sonoma)
Snapshot/restore — save terminal state before first hook, restore on Stop
"Needs attention" state — hook into Notification event for permission_prompt
Stale state cleanup — auto-remove state files for dead sessions
Config priority — env vars > ~/.visualhud/config.json > defaults

Release — Easy Install & Switch (v1.0)

What makes it a real tool people can actually use:

Big Brain Ideas

Things that would be sick but aren't urgent:

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.agents/skills		.agents/skills
.claude		.claude
.codex-sdlc		.codex-sdlc
.codex		.codex
.github/workflows		.github/workflows
assets/source/tmnt		assets/source/tmnt
docs/screenshots		docs/screenshots
scripts		scripts
skills		skills
tests		tests
themes		themes
wezterm		wezterm
.gitignore		.gitignore
AGENTS.md		AGENTS.md
ARCHITECTURE.md		ARCHITECTURE.md
CLAUDE.md		CLAUDE.md
CLAUDE_CODE_SDLC_WIZARD.md		CLAUDE_CODE_SDLC_WIZARD.md
LICENSE		LICENSE
PROVE-IT.md		PROVE-IT.md
README.md		README.md
ROADMAP.md		ROADMAP.md
SDLC-LOOP.md		SDLC-LOOP.md
SDLC.md		SDLC.md
START-SDLC.md		START-SDLC.md
TESTING.md		TESTING.md
THEMES.md		THEMES.md
demo.sh		demo.sh
diagnose.py		diagnose.py
engine.sh		engine.sh
package-lock.json		package-lock.json
package.json		package.json
set_bg.py		set_bg.py
setup-iterm2.sh		setup-iterm2.sh
setup-wezterm.ps1		setup-wezterm.ps1
start-sdlc.sh		start-sdlc.sh
test-badge.sh		test-badge.sh
test-frame-cycling.sh		test-frame-cycling.sh
test-gif-background.sh		test-gif-background.sh
visualhud		visualhud

Folders and files

Latest commit

History

Repository files navigation

VisualHUD

Install

Screenshots

Common Commands

Release To npm

Create A Theme

5. Use With Claude Code

5. Verify

Windows Status

How It Works

Themes

Theme Config (theme.json)

Default Theme: Progress Bar

Landscape — What Else Is Out There?

What Works Today

Sprite Animation

Approach 1: Native GIF Background

Approach 2: Frame Cycling

Theme Config with Animation

Color Shades

Token Usage Indicator (Separate from Task Progress)

TMNT Source Art Import

Key Bugs We Fixed

Status

Ideas Borrowed From the Ecosystem

Roadmap

Now — Extract & Polish (v0.1)

Release — Easy Install & Switch (v1.0)

Big Brain Ideas

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages