hermes-agent/plugins/mascot

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.