v0.5.0 — Prompt Patterns

What's New

Prompt Patterns Tab (tab 9)

The HUD could show you what the agent did. Now it shows you how you use it.

• Task clustering — every session classified by intent: git ops, debugging, code gen, refactor, research, config/ops, docs — with bar chart and percentages
• Repeated request detection — prompts seen 3+ times flagged as skill candidates ("make this a skill?")
• Peak hours — 24-hour sparkline, peak hour callout
• Common tool chains — most frequent 3-tool sequences across all sessions (Read -> Edit -> Bash, etc.)

Also

• Health panel now auto-discovers API keys from .env not in the expected list
• Critical key warnings are now provider-aware (OpenRouter users no longer get ANTHROPIC_API_KEY alerts)
• Memory limit constants unified across all collectors
• Snapshot directory respects HERMES_HOME
• Alias detection checks both ~/.local/bin and /usr/local/bin
• Capacity bar thresholds (red/yellow) unified across all panels via shared constants
• Agent process list expanded: aider, cursor, windsurf

v0.4.0 — tmux Operator View

tmux Operator View

Agents running inside tmux were invisible to the HUD — you knew a process was alive but had no idea which pane it lived in or whether it needed your attention. The Agents tab now functions as a live operator panel for Ghostty + tmux workflows.

What's new:

• Pane discovery — detects all tmux panes across sessions with session/window/pane identity
• Process mapping — matches live agent processes to panes via TTY (one batch ps call for all PIDs)
• Jump hints — each live agent line shows → session:window.pane when matched
• Operator queue — scans matched pane output for approval prompts, questions, errors, and stuck states; surfaces them in a color-coded queue at the top of the Agents tab
• Pane preview section — unmatched panes running non-shell commands shown with coordinates
• macOS support — _get_process_info now dispatches by platform; macOS variant uses ps + lsof instead of /proc
• Graceful fallback — all tmux code degrades silently when tmux is not installed or no server is running
• Parallel capture — pane preview reads run concurrently via ThreadPoolExecutor

Files changed:

• hermes_hud/collectors/agents.py — TmuxPane, OperatorAlert dataclasses; matched_pane_count, unmatched_interesting_panes, has_tmux on AgentsState; 10 new helper functions
• hermes_hud/widgets/agents_panel.py — operator queue section, jump hints, unmatched panes section
• tests/test_tmux.py — 45 new tests (tmux parsing, TTY matching, alert detection, macOS etime)
• tests/test_collectors.py — assertions for new AgentsState fields

Test count: 142 (was 97)

v0.3.0 — Profiles Tab

What's New

The HUD now has a Profiles tab (press 8) — a side-by-side view of every Hermes agent profile on your system.

Hermes profiles are fully isolated agent instances, each with their own model, memory, skills, and gateway. Until now there was no way to compare them at a glance. Now you can.

Per-profile data

• Config — model, provider, backend URL, port, context length, skin, toolsets
• Usage — sessions, messages, tool calls, token counts (in/out/total), last active
• Memory — capacity bars for MEMORY.md and USER.md with entry counts
• Skills & Cron — skill count, cron job count
• Personality — first line of SOUL.md, compression config
• Services — gateway status (systemd check), server status (health endpoint), CLI alias
• API keys — configured key names from .env (names only, never values)
• Classification — local (llama-server) vs API (Anthropic, OpenRouter, etc.)

Example output

  default  (default)  anthropic  inactive

    Model    claude-opus-4-6  via anthropic
    Sessions 172  Messages 7985  Tools 3726
    Tokens   45.2M total (43.9M in / 1.3M out)
    Memory   [███████████░░░░] 69%  9 entries
    Gateway  ○ inactive  Server · n/a

  ─────────────────────────────────────────

  social  local  server up

    Model    gemma-4-26b-a4b-it  via custom
    Backend  http://localhost:8081/v1  ◉
    Context  32,768 tokens
    Sessions 29  Messages 122  Tools 19
    Tokens   103.2K total (96.1K in / 7.0K out)
    Memory   [██████████████░] 94%  7 entries
    Gateway  ○ inactive  Server ◉ running
    Alias    ~/.local/bin/social

Technical

• Collector uses urllib (no curl dependency) for server health checks
• Handles the Hermes security scanner token-field redaction pitfall
• 18 new tests, 97 total (was 79)
• Full changelog: CHANGELOG.md

v0.2.0 — Smooth Setup

The Problem

v0.1 worked as a personal Hermes dashboard, but getting it running required local fixes. Hardcoded python3.11 shebangs broke on 3.12/3.13. A bash launcher needed manual symlinking. ~/projects and ~/.hermes were baked in with no overrides. Blank panels gave no guidance when Hermes data was missing. No test suite meant contributors couldn't verify their changes.

What Changed

Proper pip-installable package

All code restructured from flat scripts into a hermes_hud/ Python package with relative imports. pip install -e . registers the hermes-hud command automatically. No symlinks, no sys.path hacks, no bash launcher.

Any Python 3.11+

Removed all 9 hardcoded python3.11 shebangs. Works with 3.11, 3.12, 3.13 — whatever you have installed.

Environment variable support

• HERMES_HOME — point to any agent data directory (default: ~/.hermes)
• HERMES_HUD_PROJECTS_DIR — point to any projects directory (default: ~/projects)

Both documented in hermes-hud --help.

First-run guidance

If ~/.hermes/ doesn't exist, the HUD prints a clear message explaining what's needed instead of showing empty panels.

Test suite

79 tests across 4 files:

• test_imports.py — All 35 modules import cleanly, no sys.path hacks, no hardcoded shebangs
• test_env_vars.py — HERMES_HOME and HERMES_HUD_PROJECTS_DIR priority chains
• test_collectors.py — Every collector runs against fake data, returns correct types, handles missing data gracefully
• test_integration.py — Full collect_all() pipeline, snapshot save/load/diff cycle, app instantiation, CLI flags, dataclass models

Developer experience

• Makefile with make install, make dev, make clean, make test
• pyfiglet moved to optional [neofetch] extra
• Updated CLAUDE.md for the new package structure

Installation (before → after)

Before:

git clone ...
cd hermes-hud
pip install -r requirements.txt
# then manually symlink the launcher
# and hope you have python3.11 specifically

After:

git clone https://github.com/joeynyc/hermes-hud.git
cd hermes-hud
pip install -e .
hermes-hud