hermes-progress-tail

Compact Hermes gateway plugin for live progress tails.

What it does

• Shows latest tool calls, sticky todo state, delegated subagent progress, reasoning/thinking, and background jobs in compact progress bubbles.
• Updates one editable progress message instead of spamming chat.
• Keeps completed turn progress bubbles visible as history.
• Starts a fresh progress bubble for a new user turn after the prior final answer, while true interrupts keep updating the active bubble.
• Keeps running background jobs visible after the parent turn finishes.
• Falls back conservatively on no-edit platforms.
• Redacts common secrets before rendering progress.
• Suppresses conflicting Hermes built-in gateway progress/reasoning display plugin-side on owned gateway sessions.

Clarify decision checkpoints

• Normal work keeps the compact live tail unchanged.
• clarify freezes a bounded, decision-complete checkpoint rather than an activity transcript.
• Editable platforms freeze the current bubble; no-edit platforms send one checkpoint snapshot.
• A response updates that checkpoint at most once, and later activity starts a fresh progress bubble.
• Checkpoint data is runtime-only and redacted; it never includes raw chain-of-thought.
• This release adds no new configuration.

Before / after

Install

Installing or updating requires Python 3.12 or newer. During the compatibility-removal window, uninstall remains available with the previously supported Python 3.10 and 3.11 (and newer); python3 is still required.

curl -fsSL https://raw.githubusercontent.com/tickernelz/hermes-progress-tail/v0.2.25/install.sh | bash

Restart Hermes manually after install/update:

/restart

Uninstall:

curl -fsSL https://raw.githubusercontent.com/tickernelz/hermes-progress-tail/v0.2.25/uninstall.sh | bash

By default, the installer is interactive and asks for target profile plus setup depth. It never restarts Hermes automatically.

Install options

Use environment variables for automation:

• HPT_INTERACTIVE=0 — non-interactive install/update.
• HPT_DRY_RUN=1 — show what would change without writing files; non-interactive by default.
• HPT_PROFILES=work,personal — install/update selected profiles.
• HPT_ALL_PROFILES=1 — install/update default plus every discovered profile.
• HPT_TELEGRAM_FLOOD_SAFE=1 — rewrite Telegram progress-tail cadence to safer values while keeping rich messages enabled.
• HERMES_HOME=/path/to/.hermes — target a custom Hermes home.
• HPT_REPO=owner/repo — download from another GitHub repo.
• HPT_REF=v0.2.25 — download a specific tag/branch/ref.
• HPT_SOURCE_DIR=/path/to/repo — install from a local checkout instead of downloading.

Examples:

curl -fsSL https://raw.githubusercontent.com/tickernelz/hermes-progress-tail/v0.2.25/install.sh | env HPT_INTERACTIVE=0 bash
curl -fsSL https://raw.githubusercontent.com/tickernelz/hermes-progress-tail/v0.2.25/install.sh | env HPT_DRY_RUN=1 bash
curl -fsSL https://raw.githubusercontent.com/tickernelz/hermes-progress-tail/v0.2.25/install.sh | env HPT_PROFILES=work,personal bash
curl -fsSL https://raw.githubusercontent.com/tickernelz/hermes-progress-tail/v0.2.25/install.sh | env HPT_ALL_PROFILES=1 bash

Local checkout install:

HPT_INTERACTIVE=0 HPT_SOURCE_DIR=/path/to/hermes-progress-tail bash install.sh

Python installer entrypoint:

python -m hermes_progress_tail.installer install --hermes-home ~/.hermes

Expected config

The installer merges missing defaults without overwriting existing user values.

plugins:
  enabled:
    - hermes-progress-tail

progress_tail:
  enabled: true

  tools:
    enabled: true
    lines: 3
    preview_length: 120
    show_completed: true
    show_duration: true
    timestamp: true
    timestamp_format: "%H:%M"

  delegates:
    enabled: true
    max_delegates: 4
    lines_per_delegate: 2
    max_goal_chars: 48
    max_line_chars: 120
    show_model: false
    show_tool_count: true
    show_completion: true
    completed_ttl_seconds: 5
    thinking: "off"

  todo:
    sticky: true
    hide_tool_line: true
    max_pending: 3
    max_completed: 3
    max_cancelled: 2
    max_item_chars: 40

  patch:
    detail: smart
    preview_chars: 48
    max_files: 3

  assistant:
    enabled: true
    max_lines: 80
    max_chars: 2500
    min_update_chars: 160

  reasoning:
    enabled: true
    max_lines: 80
    max_chars: 3000
    min_update_chars: 300
    no_edit_strategy: "off"

  background_jobs:
    enabled: true
    list_running: true
    show_completed: true
    completed_ttl_seconds: 5
    max_jobs: 4
    head_lines: 2
    tail_lines: 3
    max_line_chars: 120
    update_interval_seconds: 30
    suppress_native_notify: true
    suppress_watch_notifications: true

  native_gateway:
    suppress: true

  cleanup:
    auto_delete: false
    delay_seconds: 5
    delete_on_success: true
    delete_on_failure: false
    delete_background_active: false

  footer:
    enabled: true
    density: normal # compact|normal|debug
    max_path_chars: 56

  telegram:
    rich_messages: true # default-on; falls back to MarkdownV2 if Bot API rich edit/send is unavailable
    verification_table: true
    thinking_blocks: true
    max_table_rows: 8
    compact_success: true
    max_detail_items: 8
    collapse_narrative_chars: 1200 # collapse Progress/Reasoning past this size into a tappable <details> block; 0 disables
    collapse_peek_units: 1 # keep this many newest units (Progress lines / Reasoning thoughts) visible above the collapse; 0 collapses the whole section
    rich_budget_bytes: 7500 # hard UTF-8 byte budget for a rich card; keeps Telegram from collapsing it behind "Show more"
    min_narrative_chars: 300 # never shrink Progress/Reasoning below this when fitting the byte budget

  renderer:
    strategy: auto
    edit_interval: 15.0
    message_rollover_minutes: 20
    stale_ttl_seconds: 900
    redact_secrets: true
    mode: sectioned # focused|sectioned
    style: emoji # emoji|plain
    density: normal # compact|normal|verbose|debug
    agent_label: "" # optional label for focused HUD header, e.g. Akbar

  no_edit:
    interval_seconds: 60
    min_new_events: 3
    final_summary: true
    max_snapshots_per_turn: 5

  platforms:
    discord:
      strategy: live_tail
      tools_enabled: true
      assistant_enabled: true
      reasoning_enabled: true
      delegates_enabled: true
      background_jobs_enabled: true

platforms.<name> overrides support enabled, strategy, line/preview/edit timing fields, show_completed, feature toggles (tools_enabled, assistant_enabled, reasoning_enabled, delegates_enabled, background_jobs_enabled), and timestamps.

native_gateway.suppress: true is plugin-local suppression for Hermes gateway-native progress, reasoning, interim assistant chatter, streaming, and long-running notices on platforms where progress-tail owns the live progress bubble. The installer no longer writes global display.*, streaming.enabled, or agent.gateway_notify_interval suppression keys; keep those Hermes settings normal unless you explicitly want to change Hermes outside progress-tail.

Telegram rich progress is default-on. When Bot API 10.1 rich messages are available, progress bubbles are prepared as Rich Markdown so Telegram can render headings, status tables, verification tables, visible tool details, and reasoning text natively without noisy nested Thinking / Recent tool details subheaders. Failed terminal gates are promoted above generic details; success-only cards stay compact unless compact_success is disabled. The sticky footer Status section shows runtime metadata and, when GitHub's latest release is newer than the running plugin version, a compact update notice. /progresstail status also uses readable Markdown styling and shows an update notice only when a newer GitHub release exists. If rich edit/send is unsupported or Telegram rejects a rich payload, the plugin falls back to the existing MarkdownV2 live-edit path and latches rich edits off for that adapter on capability failures.

Turn lifecycle is internal: completed progress bubbles stay visible, but new user turns get new progress bubbles after the prior final answer. If a background job is still visible, its progress bubble can keep updating.

Commands

/progresstail status
/progresstail doctor
/progresstail jobs
/progresstail update --dry-run
/progresstail update --apply
/progresstail update --apply --ref v0.2.25
/progresstail config cleanup --dry-run
/progresstail config cleanup --apply
/progresstail demo
/progresstail demo plain
/progresstail demo failed

# Platform command-menu aliases where subcommands/args are awkward:
/progresstail-update   # applies update by default
/progresstail-doctor
/progresstail-jobs
/progresstail-cleanup  # applies cleanup by default
/progresstail-demo

/progresstail update --dry-run checks the latest GitHub Release and shows the install plan without writing files. /progresstail update --apply downloads the release archive, runs the same plugin installer used by install.sh, and updates plugin files/config for the current profile. /progresstail-update is a command-menu-friendly alias that defaults to --apply; pass --dry-run explicitly if you only want a plan. Use --all-profiles or --profile work,personal for broader installs. The command never restarts Hermes; run /restart manually after an applied update.

/progresstail doctor also reports config drift. Unknown keys are likely typos or stale docs, for example warning: unknown config key progress_tail.tools.typo_lines. Retired keys are old public knobs that should be removed from config, for example warning: retired config key progress_tail.finalization.

Progress-tail owns background job visual status by default, so suppress_native_notify and suppress_watch_notifications default to true to avoid duplicate native Hermes process/watch notifications. If those are disabled while background_jobs.enabled is still true, /progresstail doctor warns because background job output may appear twice.

redact_secrets redacts sensitive values, not ordinary file paths. File paths are simplified for readability: project paths become relative, home paths become ~/..., and WSL Windows user paths like /mnt/c/Users/name/Downloads/file.pdf become ~/Downloads/file.pdf.

Development

python -m pip install -e '.[dev]'
pre-commit install
pre-commit run --all-files
python -m pytest

Useful direct checks:

ruff format .
ruff check .
python -m compileall -q .
git diff --check

Notes

Reasoning and delegate progress use guarded plugin-local monkeypatches around Hermes AIAgent / delegate_task internals. Hermes source files are not modified. If upstream internals change, the plugin should fail closed and /progresstail status should show the issue.