hermes - 💡(How to fix) Fix feat: Unified Agent Status API — real-time state detection, notifications, and status bar integration

Summary

Propose a unified Agent Status API built into Hermes core that tracks agent lifecycle state in real-time, exposes it via a machine-readable status file, CLI command, and built-in status bar — consolidating and superseding several existing issues (#24632, #19302, #36698, #38024, #21442, #37416, #30389, #11757, #17837, #33836, #32299).

Motivation

Currently, monitoring Hermes agent state requires either:

1. External plugins (e.g. noctalia-hermes) that wire up hooks, write signal files, and poll for status — fragile, platform-specific, requires manual setup.
2. Scattered CLI commands (hermes gateway status, checking logs) — no real-time awareness.
3. Multiple disconnected feature PRs — tab titles (#36698), desktop notifications (#19302), system tray (#38024), status bar badges (#30389, #11757, #17837, #33836) — each solving a piece but no shared foundation.

Users running Hermes across multiple sessions, on headless servers, or via gateway have no way to know at a glance whether the agent is actively processing, blocked waiting for input, degraded, or offline.

Proposed Solution

Architecture: Extend existing infrastructure, not replace it

Hermes already has most of the building blocks — they just aren't connected to a unified status model:

The plan is to extend these into a coherent status system in three phases.

Phase 1: Status file (foundation)

New file: ~/.hermes/status.json — single source of truth for agent state.

Extend _touch_activity() in agent/conversation_loop.py to write a status file on every state transition (debounced 500ms to avoid high-frequency IO):

{
  "state": "busy",
  "state_detail": "calling tool: web_search",
  "gateway": {"running": true, "pid": 203245},
  "current_turn": {
    "model": "anthropic/claude-sonnet-4",
    "provider": "anthropic",
    "reasoning_effort": "high",
    "tokens_used": 4500,
    "tokens_limit": 200000,
    "tools_called": ["web_search", "read_file"],
    "started_at": "2026-06-05T10:05:00Z",
    "duration_seconds": 12
  },
  "attention": {"needs_attention": false, "reason": null, "since": null},
  "platforms": {
    "telegram": {"state": "connected"},
    "discord": {"state": "disconnected", "error": "..."}
  },
  "last_error": null,
  "updated_at": "2026-06-05T10:05:24Z"
}

State transitions:

New CLI command: hermes status

hermes status              # JSON to stdout
hermes status --format human   # Human-readable table
hermes status --watch      # Continuous mode (re-read on file change)

Implementation: new subcommand in hermes_cli/ that reads ~/.hermes/status.json + gateway_state.json, merges, and outputs. For --watch, use inotifywait or select.poll on the status file.

Also extend gateway_state.json via write_runtime_status() to include agent-level fields (current_agent_state, current_agent_detail) so gateway-only installs also expose agent state.

Phase 2: Built-in status bar + notifications (user-visible)

CLI status bar indicator — extend _get_status_bar_snapshot() and _build_status_bar_text() in cli.py to include a traffic-light state indicator:

● idle  │ anthropic/claude-sonnet-4 │ 4.5k/200k tokens │ telegram: connected │ 12s
◐ busy  │ calling tool: web_search │ 4.5k/200k tokens │ telegram: connected │ 12s
◆ attn  │ needs approval: terminal │ 4.5k/200k tokens │ telegram: connected │ 12s
▲ deg   │ telegram disconnected    │ 4.5k/200k tokens │ 12s

Config: display.status_indicator: true (default off for backward compat).

Desktop notifications — extend bell_on_complete into a full notification system:

display:
  notifications:
    enabled: true
    on: [attention, error, degraded]
    method: desktop  # desktop | bell | both | none
    desktop_command: "notify-send"  # auto-detect on macOS/Windows

When state transitions to a notification-triggering state, dispatch via notify-send (Linux), osascript (macOS), or PowerShell toast (Windows). Falls back to terminal bell if desktop notification unavailable.

TUI integration — the TUI already receives status.update events via tui_gateway/server.py. Add state transitions as status.update events with kind=agent_state so the Ink frontend can render a status indicator.

Phase 3: Hooks compatibility + plugin ecosystem (extensible)

Built-in status hook — register a built-in hook in _register_builtin_hooks() (gateway/hooks.py) that listens to agent:start, agent:end, session:start, session:end and updates the status file. This provides the same functionality as noctalia-hermes's hermes-status-hook but as a zero-config built-in.

New plugin hook: on_agent_state_change — add to VALID_HOOKS in hermes_cli/plugins.py. Fires on every state transition with {old_state, new_state, detail, context}. Plugins can register for this hook to build custom UI, send alerts, log to external systems, etc.

External script compatibility — the status file at ~/.hermes/status.json is the same interface that noctalia-hermes used (signal file pattern). Any external script that watched a signal file can watch this file instead. The hooks system is unchanged — third-party hooks still work alongside the built-in status tracking.

Backward compatibility:

• All existing hooks continue to work unchanged
• Status file writes are always-on (zero-config); user-visible features (status bar, notifications) are opt-in via config
• No breaking changes to gateway_state.json schema (new fields only)
• bell_on_complete still works; notifications config is additive

What this consolidates

Implementation priority

1. Phase 1 (smallest diff): Extend _touch_activity() + add hermes status command + write status.json
2. Phase 2 (user-visible): CLI status bar indicator + desktop notifications + TUI events
3. Phase 3 (ecosystem): Built-in hook in _register_builtin_hooks() + on_agent_state_change plugin hook

Alternatives considered

• Hooks-only approach: Rejected — hooks are the extension mechanism, not the implementation. The status tracking should be native in the agent loop, with hooks as a compatibility layer.
• D-Bus / socket IPC: More complex, harder cross-platform. File-based status is simpler and works everywhere.
• Only extend gateway_state.json: Insufficient — gateway doesn't have per-turn agent detail (tool names, tokens, reasoning effort). Need both gateway-level and agent-level status.

Additional context

The noctalia-hermes plugin demonstrated this pattern works: hook-driven signal file + status detection script + UI consumer. The key insight is that Hermes already has all the plumbing — _touch_activity(), gateway_state.json, status_callback, plugin hooks — it just needs to be wired into a unified status model. This proposal does exactly that, making the feature available to all users with zero external dependencies.