hermes-dash-pools

Unified Hermes Desktop Plugin: Dashboard + Model Pools

Combines project dashboard (Plans, Kanban, Agents) with intelligent model pool management (free fallback, paid rotation, fixed models per function).

Features

📊 Dashboard (4 Tabs)

Tab	Description
Planos	Read-only view of .hermes/plans/*.md files
Kanban	Read-only view of native Hermes Kanban boards
Agentes	Safe test mode for Technical Orchestrator agent
Model Pools	NEW — Manage model pools with fallback/rotation

🤖 Model Pools (Core Feature)

Three pool types with distinct behaviors:

Pool	Type	Behavior	Use Case
Gratis	Free	Cascata fallback — auto switches on rate limit/failure, persists until manual change	Cost-free resilience
Coding Barato	Paid	Rotação com confirmação — rotates on failure, asks before switching paid models	Budget coding tasks
Planejamento	Custom	Modelo fixo — single trusted model for planning/orchestration	Reliable planning

Pool Configuration Options:

• fallbackEnabled — Auto cascade to next model on failure
• rotationEnabled — Rotate through models on failure
• confirmPaidRotation — Require user confirmation before switching paid models
• persistFallback — Keep fallback model until manually changed

🎮 User Interactions

• Sidebar: "Dashboard" navigation item → /dashboard route
• Palette (Ctrl+K):
  • Abrir Dashboard — Open dashboard
  • Model Pools: Trocar Pool/Modelo — Quick switch
  • Model Pools: Atualizar Lista Grátis — Fetch fresh free models from OpenRouter
• Keybind: Ctrl+Shift+D — Open Dashboard

Installation

Option 1: Git Clone (Recommended for Updates)

# Navigate to Hermes desktop-plugins directory
cd %APPDATA%\Local\hermes\desktop-plugins\  # Windows
# or
cd ~/.hermes/desktop-plugins/  # Linux/Mac

# Clone the repo
git clone https://github.com/IsmaelThrash/hermes-dash-pools.git

# In Hermes: Ctrl+K → "Reload desktop plugins"

Option 2: Manual Copy

1. Download/clone this repo
2. Copy the dashboard/ folder to your Hermes desktop-plugins directory:
   • Windows: %APPDATA%\Local\hermes\desktop-plugins\hermes-dash-pools\
   • Linux/Mac: ~/.hermes/desktop-plugins/hermes-dash-pools/
3. In Hermes: Ctrl+K → Reload desktop plugins

Configuration

Model Pools Persistence

State is saved automatically to Hermes plugin storage:

• Namespace: hermes.plugin.hermes-dash-pools
• Keys: state, manual-override, pending-rotation

OpenRouter Integration

• Free model list cached for 24h (configurable in model-pools/openrouter.ts)
• Auto-refresh every 6 hours
• Manual refresh via Palette command
• CORS-safe via backend proxy endpoint /model-pools/openrouter-models

Adding Custom Models to Pools

1. Open Dashboard → Model Pools tab
2. In any pool card, use the input field at bottom: "ID do modelo (ex: anthropic/claude-3.5-sonnet)"
3. Press Enter to add
4. Models are validated against OpenRouter catalog on next refresh

Creating Custom Pools

1. Click "+ Novo Pool" in Model Pools tab
2. Enter name (e.g., "Escrita Criativa")
3. Select type: Gratis / Pago / Personalizado
4. Click "Criar Pool"
5. Add models to your new pool

Architecture

hermes-dash-pools/
├── dashboard/
│   ├── manifest.json          # { "api": "plugin_api.py" }
│   ├── plugin.js              # Main plugin (React + nanostores)
│   ├── plugin_api.py          # FastAPI backend (plans, kanban, agents, model-pools)
│   └── model-pools/           # Core logic modules
│       ├── pools.ts           # State, actions, default pools
│       ├── storage.ts         # Plugin storage wrapper
│       ├── hooks.ts           # Model request hooks (native + fallback)
│       └── openrouter.ts      # OpenRouter API integration
├── .github/workflows/         # CI (lint, typecheck)
└── README.md

State Management

• nanostores atoms for reactive state ($poolsState, $activePool, $activeModel)
• Plugin-scoped storage via ctx.storage (persists across reloads)
• Periodic auto-save every 30 seconds

Model Hook Integration

The plugin attempts to register native SDK hooks (host.registerModelHooks) for precise request/response interception. Falls back to event-based detection (host.onEvent('*')) on current SDK versions.

When native hooks are available (future Hermes release):

• Pre-request: Can override model based on active pool/agent function
• Post-response: Exact detection of 429 rate limit, timeouts, empty responses

Development

Prerequisites

• Hermes Desktop (latest)
• Python 3.11+ (for plugin_api.py backend)
• Node.js 22+ (for TypeScript modules, optional)

Local Development

# Edit files in ~/.hermes/desktop-plugins/hermes-dash-pools/
# In Hermes: Ctrl+K → "Reload desktop plugins"
# Changes hot-reload automatically

Backend Dependencies

pip install fastapi uvicorn pydantic

Migration from Old Plugins

This plugin replaces two previous plugins:

• dashboard/ → Merged into dashboard/ (tabs: Planos, Kanban, Agentes, Model Pools)
• force-default-model/ → Logic migrated to Model Pools (default pool = "Gratis" with qwen/qwen3.7-flash)

No action needed — just install this plugin and disable/remove the old ones.

Contributing

1. Fork the repo
2. Create feature branch
3. Make changes
4. Test in local Hermes
5. Submit PR

License

MIT — Free to use, modify, distribute.

Support

• Issues: GitHub Issues
• Hermes Discord: #plugins channel