v0.6.1 • local first • WSL2 + Windows

A desktop companion layer for Hermes Agent operators.

A transparent Electron overlay, Python WebSocket bridge, and real sprite packs that keep Hermes visible on your screen. No cloud hops, no telemetry, no nonsense.

Get the commands Read the repository

Transparent overlay
Local websocket bridge
Custom pet packs
Guarded update system

Current Release 0.6.1 Curated custom gallery including Freddy, Jason, Leatherface, and Haskell.

Supported OS WSL2 on Windows Interoperable CLI opens the frameless Electron overlay from WSL environment.

Local State Path ~/.hermes_pet Uses HERMES_PET_HOME env variable for directory isolation.

Hermes Pets launch bubble screenshot with a fox pet reacting to a local command — Launch feedback **Local command, live bubble**
The pet reacts right on the desktop when Hermes emits a message.

Hermes Pets review tray screenshot showing job history and review-needed state — Operator tray **Job history and review state**
Attention needed, job finished, and brief summaries stay visible.

Hermes companion overlay - preview sandbox

Drag the pets around

Cat: Active. Drag me anywhere on the desktop dashboard!

Fox: Listening locally... Reconnects clean when websocket drops.

Ghost: Boo! Custom pet packs live in ~/.hermes_pet/custom-pets/

Dragon: Sleeping... Run 'hermes-pet launch' to wake me.

What it does

It turns local Hermes activity into a visible companion layer.

The overlay is transparent, always-on-top, draggable, and fed by a local WebSocket bridge. Sprite manifests define frame counts, frame rates, looping, and fallback behavior, so idle, hover, drag, run, review, jump, fail, and bubble states stay deterministic.

Transparent Electron overlay

Frameless, transparent, and always on top. It sits on the desktop without pretending to be a heavy dashboard.

Python WebSocket bridge

The overlay listens to a local bridge and reconnects cleanly when the socket blips. No cloud hop required.

Manifested sprite states

Sprite packs declare FPS, loop behavior, and fallback rules for idle, drag, hover, and message reactions.

Custom pet packs

Packages live under ${HERMES_PET_HOME:-~/.hermes_pet}/custom-pets/<pet-name>/ and are validated before use.

Guarded update flow

update --check and --dry-run let you preview files and steps before anything mutates on the disk.

Local diagnostics

doctor, overlay-status, and the localhost console keep the operator execution loop honest.

Reality check

Local-first means local-first.

No hosted galleries. No telemetry reporting. No cloud accounts. The repository states that native Linux, macOS, and native Windows overlay support are future investigation targets, while WSL2 on Windows is the supported production experience.

Local state

Pet directories live under ~/.hermes_pet by default, with support for HERMES_PET_HOME redirection.

Private dashboard

The operator dashboard binds strictly to localhost only and requires a unique token. It is not exposed to the web.

Public install path

The supported public install flow in the repository is directly GitHub-based, not a PyPI or pre-compiled installer.

Pet showcase

Real sprites, real packs, no fake merch-sheet theater.

The repository ships with built-in overlay species and curated custom packages. These previews use actual assets from the repository, including sprite frames and contact sheets.

Custom pet packs announcement featuring Freddy, Jason, and Leatherface available now for Hermes Pets

Built-in overlay species

Built-in cat idle sprite from the overlay asset pack

Cat overlay/assets/sprites/cat

Built-in fox idle sprite from the overlay asset pack

Fox overlay/assets/sprites/fox

Built-in ghost idle sprite from the overlay asset pack

Ghost overlay/assets/sprites/ghost

Built-in dragon idle sprite from the overlay asset pack

Dragon overlay/assets/sprites/dragon

Curated custom packs

Freddy custom pet sprite sheet showing multiple animation frames

Freddy docs/custom-pets/freddy

Jason custom pet sprite sheet showing multiple animation frames

Jason docs/custom-pets/jason

Leatherface custom pet contact sheet showing multiple animation states

Leatherface docs/custom-pets/leatherface

Haskell custom pet contact sheet showing multiple animation states

Haskell docs/custom-pets/haskell

Operator install and use

Verified commands only, no made-up workflow garnish.

The repository supports local editable installs, a direct GitHub install path, the launch bridge, and the custom pet validation command.

User Install Commands

python3 -m pip install 'git+https://github.com/asimons81/hermes-pets.git'
hermes-pet launch
hermes-pet doctor

Target Audience

The default github-linked install flow, overlay launching, and healthcheck utilities for local operators.

Launch Behavior

The companion overlay is stateful: if the socket connection is active, launch hooks into the current process cleanly.

Developer Workflow Commands

cd <repo-directory>
pip install -e .
hermes-pet custom-pet validate docs/custom-pets/freddy
hermes-pet update --check

Target Audience

Editable developer installations, testing sprite validation configurations, and performing guarded updates.

Guarded Updates

Allows operators to dry-run updates, verifying what changes will be applied before any directory mutations.

Release and status strip

The repository has an active release history.

No vaporware or mock screenshots. The local changelog tracks the step-by-step evolution of the overlay features.

Current Release

v0.6.1

Curated custom pet gallery, offering Freddy, Jason, Leatherface, and Haskell as sprite assets in the local directory.

v0.6.0

Export operator recap flow logs.

v0.5.0

Codex-driven pet pack import validation and activation.

v0.4.0

Guarded update logic and check parameters.

v0.3.0

Token-protected websocket localhost console dashboard.