hermesd 2026.4.9__tar.gz

hermesd-2026.4.9/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Claude Code / Superpowers (development artifacts)
+.claude/
+.remember/
+.superpowers/
+docs/superpowers/

hermesd-2026.4.9/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to hermesd will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2026.4.9] - 2026-04-09
+
+### Added
+
+- Initial release of hermesd TUI monitoring dashboard
+- 8-panel overview with compact and detail views:
+  - [1] Gateway & Platforms — PID, version, update status, platform connection state
+  - [2] Sessions — active/total count, messages, tool calls, per-session detail table
+  - [3] Tokens / Cost — today and total token usage, estimated cost from token counts
+  - [4] Tools — available tools grid, per-session call stats
+  - [5] Config — model, provider, personality, compression, security
+  - [6] Cron — scheduler tick, job list with schedule/state/next-run
+  - [7] Skills / Providers — provider auth status, skills by category with descriptions, j/k scrolling
+  - [8] Logs — tailed agent/gateway/error logs with Tab switching
+- Adaptive layout: single-column at 80x24 (SSH/tmux), full grid at 100+ columns
+- Read-only SQLite access with `PRAGMA data_version` caching
+- Cache preservation on transient errors (never blanks out on write contention)
+- Auto-reconnect after 3 consecutive DB errors
+- Gateway PID detection with `gateway.pid` fallback for launchd restarts
+- Cost estimation from token counts when provider doesn't report costs
+- Skin/theme system inheriting from Hermes Agent config
+- Keyboard navigation: 1-8 expand, Esc back, j/k scroll, Tab cycle logs, r refresh, q quit
+- Escape sequence handling for Ghostty/SSH/tmux environments
+- 164 tests covering all panels, data collection, resilience, and edge cases

hermesd-2026.4.9/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nous Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hermesd-2026.4.9/PKG-INFO

@@ -0,0 +1,348 @@
+Metadata-Version: 2.4
+Name: hermesd
+Version: 2026.4.9
+Summary: TUI monitoring dashboard for Hermes AI agent
+Project-URL: Homepage, https://github.com/mudrii/hermesd
+Project-URL: Repository, https://github.com/mudrii/hermesd
+Project-URL: Issues, https://github.com/mudrii/hermesd/issues
+Project-URL: Changelog, https://github.com/mudrii/hermesd/blob/main/CHANGELOG.md
+Author: Nous Research
+Author-email: Ion Mudreac <mudreac@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent,dashboard,hermes,monitoring,terminal,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=14.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hermesd
+
+A real-time TUI monitoring dashboard for [Hermes Agent](https://github.com/NousResearch/hermes-agent).
+
+![hermesd overview](images/SCR-20260409-pzqv.png)
+
+## Why This Exists
+
+When you run Hermes Agent seriously — gateway handling Telegram, Discord, Slack, and WhatsApp simultaneously, cron jobs firing reminders, multiple CLI sessions with sub-agents spawning sub-agents, dozens of skills loaded, 7+ LLM providers configured — the information gets scattered fast.
+
+**The problem:** there was no single place to answer the obvious questions:
+- Is my gateway actually running? Which platforms are connected?
+- How many tokens have I burned today and what's the estimated cost?
+- Which sessions are active and how much context are they consuming?
+- What cron jobs are scheduled, and did the last one succeed or fail?
+- Which skills are installed and what do they do?
+- What's in my error log right now?
+
+The only way to answer these was running `hermes status`, `hermes sessions list`, `hermes cron list`, tailing log files, and mentally stitching together a picture from 5+ different sources. That friction adds up.
+
+**The solution:** `hermesd` — a single terminal command that reads `~/.hermes/` and presents everything in one live-updating dashboard. Gateway health, sessions, tokens, costs, tools, cron, skills, logs — all refreshed automatically, no API keys, no network access, zero writes to your agent state.
+
+It's not trying to replace the Hermes CLI or your Telegram interface. It's the at-a-glance overview layer that tells you whether everything is healthy and where your tokens are going — so you can make decisions without hunting for data.
+
+## Features
+
+### 8 Dashboard Panels
+
+| # | Panel | What It Shows |
+|---|-------|---------------|
+| 1 | **Gateway & Platforms** | Live gateway PID, Hermes version, update status, per-platform connection dots |
+| 2 | **Sessions** | Active/total count, message and tool call totals, recent session list |
+| 3 | **Tokens / Cost** | Today's and all-time token usage, estimated cost (~USD) from token counts |
+| 4 | **Tools** | Available tools count, per-session call stats, full tool name grid |
+| 5 | **Config** | Model, provider, personality, max turns, reasoning, compression, security |
+| 6 | **Cron** | Scheduler tick, job table with schedule, state, next run, error count |
+| 7 | **Skills / Providers** | Provider auth status, skills grouped by category with descriptions, j/k scrolling |
+| 8 | **Logs** | Tailed agent, gateway, and error logs with level coloring and Tab switching |
+
+### Key Features
+
+- **Read-only** — hermesd never writes to `~/.hermes/` or modifies Hermes Agent state
+- **Live-updating** — polls every 5 seconds (configurable with `--refresh-rate`)
+- **Adaptive layout** — full 8-panel grid on wide terminals, compact single-column on 80x24 (SSH/tmux)
+- **Detail views** — press `1`-`8` to expand any panel to full-screen
+- **Scrollable lists** — `j`/`k` to scroll through skills and logs in detail mode
+- **Resilient** — keeps showing last known good data on transient SQLite lock contention
+- **Theme-aware** — inherits your Hermes Agent skin (default, ares, mono, slate, poseidon, sisyphus, charizard)
+- **SSH/tmux compatible** — `tty.setcbreak` mode, escape sequence handling for remote terminals
+- **Cost estimation** — computes ~USD from token counts when the provider doesn't report costs
+- **Zero config** — no config file, no API keys, just `hermesd` and go
+
+## Screenshots
+
+### Overview — The Full Picture
+
+The main dashboard shows all 8 panels at a glance. Gateway status with PID and version at the top, sessions and token costs side by side, tools and config, cron and skills, logs at the bottom. The footer shows keyboard shortcuts and a polling indicator.
+
+![Overview](images/SCR-20260409-pzqv.png)
+
+### [1] Gateway & Platforms — Is Everything Connected?
+
+Press `1` to expand. Shows whether the gateway process is alive (with correct PID even after launchd restarts), Hermes version with update status, and a per-platform table with connection state and last-seen timestamps. Catches the "gateway says running but the PID is dead" case.
+
+![Gateway Detail](images/SCR-20260409-pzxz.png)
+
+### [3] Tokens / Cost — Where Are My Tokens Going?
+
+Press `3` for the full per-session token breakdown. Shows input, output, cache-read, cache-write, and reasoning tokens for every session, plus estimated cost. The compact view shows today's totals with `~$` prefix indicating estimated costs when the provider (e.g., OpenAI Codex) doesn't report them.
+
+![Tokens Detail](images/SCR-20260409-qaah.png)
+
+### [4] Tools — What's Available and What's Being Used?
+
+Press `4` for two tables: **Tool Calls** showing per-session call counts (which sessions are using the most tools), and **Available Tools** listing all 29 registered tools in a 3-column grid. The compact view shows the top callers.
+
+![Tools Detail](images/SCR-20260409-qacn.png)
+
+### [5] Config — Current Agent Configuration
+
+Press `5` for the full config key-value table: model, provider, personality, max turns, reasoning effort, compression threshold, secret redaction, and approval mode. All read from `~/.hermes/config.yaml`.
+
+![Config Detail](images/SCR-20260409-qael.png)
+
+### [6] Cron — Scheduled Jobs
+
+Press `6` to see all cron jobs with their schedule, current state, next run time, and last execution status. The compact view shows tick recency, job count, and error count. Reads from `~/.hermes/cron/jobs.json`.
+
+![Cron Detail](images/SCR-20260409-qbwi.png)
+
+### [7] Skills & Providers — What's Installed?
+
+Press `7` for two sections: **Providers** showing auth status for each configured LLM provider (active marked with `●`), and **Skills** grouped by category with descriptions loaded from each skill's `SKILL.md` frontmatter. Use `j`/`k` to scroll through the full skill list. The scroll position indicator shows `[11-69/69]`.
+
+![Skills Detail](images/SCR-20260409-qbym.png)
+
+### [8] Logs — What Just Happened?
+
+Press `8` for the full log viewer with three tabs: **agent**, **gateway**, and **errors**. Press `Tab` to switch between them. Log lines are color-coded by level (INFO green, WARNING orange, ERROR red). The compact view shows the last 5 agent log lines.
+
+![Logs Detail](images/SCR-20260409-qcgt.png)
+
+## Installation
+
+Requires Python 3.11+ and a working [Hermes Agent](https://github.com/NousResearch/hermes-agent) installation (`~/.hermes/` must exist).
+
+### From Source (recommended)
+
+```bash
+git clone https://github.com/mudrii/hermesd.git
+cd hermesd
+uv venv .venv --python 3.11
+source .venv/bin/activate
+uv pip install -e .
+hermesd
+```
+
+### Via pip (from source)
+
+```bash
+pip install git+https://github.com/mudrii/hermesd.git
+hermesd
+```
+
+### Via uv (from source)
+
+```bash
+uv tool install git+https://github.com/mudrii/hermesd.git
+hermesd
+```
+
+### Docker
+
+```bash
+docker build -t hermesd .
+docker run -it -v ~/.hermes:/home/hermesd/.hermes:ro hermesd
+```
+
+### Nix Flake
+
+```bash
+# Run directly
+nix run github:mudrii/hermesd
+
+# Dev shell
+nix develop github:mudrii/hermesd
+```
+
+> **Note:** PyPI publication is planned. Once published, `pip install hermesd` and `uv tool install hermesd` will work without the `git+` prefix.
+
+## Usage
+
+```bash
+# Launch the dashboard (reads ~/.hermes by default)
+hermesd
+
+# Custom hermes home directory (for profiles)
+hermesd --hermes-home ~/.hermes-work
+
+# Faster polling (every 2 seconds)
+hermesd --refresh-rate 2
+
+# Disable colors
+hermesd --no-color
+
+# Show version
+hermesd --version
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `HERMES_HOME` | `~/.hermes` | Override the Hermes home directory |
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `1`-`8` | Expand panel to full-screen detail view |
+| `Esc` | Return to overview |
+| `j` / `k` | Scroll down/up in detail mode |
+| `Tab` | Cycle log sub-view: agent / gateway / errors (panel 8) |
+| `r` | Force immediate refresh |
+| `q` | Quit |
+| `?` | Toggle help overlay |
+
+## Architecture
+
+hermesd is a **read-only companion** — it reads files from `~/.hermes/` and never writes anything.
+
+```
+~/.hermes/                        hermesd
+  state.db (SQLite WAL) ───────> db.py      Read-only (mode=ro), data_version cache
+  gateway_state.json ──────────> collector.py  JSON/YAML mtime-cached readers
+  gateway.pid ─────────────────>
+  config.yaml ─────────────────>
+  cron/jobs.json ──────────────>
+  auth.json ───────────────────>
+  skills/*/SKILL.md ───────────>
+  sessions/*.json ─────────────>
+  logs/*.log ──────────────────>
+                                     |
+                                     v
+                                 models.py   Pydantic DashboardState
+                                     |
+                                     v
+                                 app.py      Rich TUI (Live + Layout + threads)
+                                     |
+                                     v
+                                 panels/*.py  8 panel renderers (compact + detail)
+```
+
+### Design Decisions
+
+| Decision | Why |
+|----------|-----|
+| SQLite `mode=ro` + `check_same_thread=False` | Guarantees no writes; safe for cross-thread polling/render |
+| `PRAGMA data_version` caching | Skips re-reads when agent hasn't written, minimizing I/O |
+| Cache preservation on error | Transient SQLite lock contention keeps last good data visible |
+| Auto-reconnect after 3 errors | Recovers from WAL checkpoint invalidation |
+| `gateway.pid` fallback | Detects correct PID after launchd/systemd restarts |
+| `tty.setcbreak` (not `setraw`) | Preserves signal handling over SSH/tmux |
+| `os.read(fd, 64)` bulk read | Captures escape sequences as single chunks |
+| Cost estimation from tokens | Shows ~USD when provider doesn't report costs |
+| Adaptive layout threshold | 80x24 gets compact single-column; 100+ gets full grid |
+
+## Themes
+
+hermesd inherits the active skin from Hermes Agent's `config.yaml`:
+
+| Skin | Style |
+|------|-------|
+| `default` | Gold/bronze on dark — the classic Hermes look |
+| `ares` | Deep red with gold accents |
+| `mono` | Grayscale minimalist |
+| `slate` | Cool blue tones |
+| `poseidon` | Ocean blue |
+| `sisyphus` | Silver/stone gray |
+| `charizard` | Warm orange/amber |
+
+## Development
+
+```bash
+git clone https://github.com/mudrii/hermesd.git
+cd hermesd
+uv venv .venv --python 3.11
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+# Run tests (164 tests, <0.5s)
+python -m pytest tests/ -v
+
+# Run the dashboard
+hermesd
+```
+
+### Project Structure
+
+```
+hermesd/
+  __init__.py          Version string
+  __main__.py          CLI entry point (argparse)
+  app.py               Rich TUI: Live context, input thread, adaptive layout
+  collector.py         Reads all ~/.hermes data sources
+  db.py                Read-only SQLite with data_version caching
+  models.py            Pydantic models for dashboard state
+  theme.py             Skin/color system matching Hermes Agent
+  panels/
+    __init__.py        Panel dispatch and registry
+    gateway.py         [1] Gateway & Platforms
+    sessions.py        [2] Sessions
+    tokens.py          [3] Tokens / Cost
+    tools.py           [4] Tools
+    config_panel.py    [5] Config
+    cron.py            [6] Cron
+    overview.py        [7] Skills / Providers
+    logs.py            [8] Logs
+tests/                 164 tests: panels, data, resilience, edge cases
+```
+
+### Adding a Panel
+
+1. Create `hermesd/panels/your_panel.py` with `render_*(state, theme, detail)` function
+2. Add data model to `hermesd/models.py`
+3. Collect data in `hermesd/collector.py`
+4. Register in `hermesd/panels/__init__.py`
+5. Add to layout in `hermesd/app.py`
+6. Write tests in `tests/test_your_panel.py`
+
+## Requirements
+
+- **Python** >= 3.11
+- **Hermes Agent** installed with `~/.hermes/` directory present
+- **Terminal** with 256-color or truecolor support
+
+### Dependencies
+
+Only 3 runtime dependencies — all of which are already installed as part of Hermes Agent, so hermesd adds **zero new packages** to your system:
+
+| Package | Version | Purpose | In hermes-agent? |
+|---------|---------|---------|------------------|
+| `rich` | >= 14.0 | TUI rendering (Live, Layout, Panel, Table, Text) | Yes (`rich>=14.3.3`) |
+| `pyyaml` | >= 6.0 | Reading config.yaml | Yes (`pyyaml>=6.0.2`) |
+| `pydantic` | >= 2.0 | Data models and validation | Yes (`pydantic>=2.12.5`) |
+
+If you install hermesd into the same environment as Hermes Agent, no additional downloads are needed.
+
+## License
+
+[MIT License](LICENSE)
+
+## Credits
+
+Built for [Hermes Agent](https://github.com/NousResearch/hermes-agent) by [Nous Research](https://nousresearch.com).