Mascot Plugin

Animated agent mascot with real-time state tracking for the Hermes dashboard.

Features

Real-time state updates: WebSocket connection streams state changes instantly
Automatic fallback: Polls REST API if WebSocket fails
5 animation states: idle, thinking, working, waiting_input, error
Tab + sidebar widget: Full view and compact sidebar slot
SVG fallback: Placeholder works without sprite files

Installation

The plugin is bundled with Hermes Agent. Enable it in your dashboard config.

Usage

The mascot automatically displays the agent's current state:

idle: Agent is waiting for input
thinking: Agent is processing a message
working: Agent is executing a task
waiting_input: Agent needs user confirmation
error: Agent encountered an error

Manual State Control

Visit the Mascot tab in the dashboard to manually set states for testing.

Sprite Files

Place PNG/GIF sprites in plugins/mascot/static/sprites/:

hermes_idle.png
hermes_thinking.png
hermes_working.png
hermes_waiting_input.png
hermes_error.png

If sprite files are missing, an SVG placeholder is displayed automatically.

API Endpoints

Endpoint	Method	Description
`/api/plugins/mascot/state`	GET	Current mascot state
`/api/plugins/mascot/state`	POST	Update state (status, task, mood)
`/api/plugins/mascot/reset`	POST	Reset to idle state
`/api/plugins/mascot/events`	WS	WebSocket stream of state changes

WebSocket Protocol

Server sends:

{"type": "state", "state": {"status": "thinking", "task": "...", "mood": null, "last_update": 1234567890.123}}

Client connects with session token:

ws://localhost:9119/api/plugins/mascot/events?token=<session_token>

Agent Loop Integration

To emit mascot state changes from your code:

from plugins.mascot.mascot_state import get_manager

manager = get_manager()

# Set status
manager.set_state(status="thinking", task="Processing message")

# Working on something
manager.set_state(status="working", task="Running tests")

# Done
manager.reset()  # Returns to idle

Subscribers (like the WebSocket broadcaster) receive notifications automatically.

2.2 KiB Raw Blame History