Skip to main content

​
Runtime overview

Beacon supports Hermes Agent through shell hook payloads sent to beacon-hooks, with local session database sync for historical backfill.

​
Prerequisites

Before enabling Hermes Agent hooks, make sure:
  • Hermes Agent is installed for the user or ~/.hermes/config.yaml exists.
  • beacon endpoint install has run so shared endpoint config and runtime log paths exist.
  • Beacon hooks are installed with beacon endpoint hooks install --harness hermes.
  • Hermes hook consent is handled for the session, especially in non-interactive gateway, cron, or CI runs.
  • Hermes is restarted after hook install or removal so new sessions load the updated config.

​
Collection path

Beacon merges shell-hook entries into ~/.hermes/config.yaml. Hermes invokes Beacon’s hook adapter for supported lifecycle, prompt, tool, approval, and subagent events, and the adapter writes normalized endpoint events to the configured runtime JSONL log. Beacon can also read Hermes Agent’s committed SQLite session store:
Sync Hermes Agent sessions
The sync path reads ~/.hermes/state.db locally and offline. It writes mapped events with harness.collection_method=poll, so it can recover historical sessions or sessions that ran before hooks were installed, but it cannot hold, approve, deny, or delay tool calls.

​
Discovery and status

Beacon detects Hermes through the hermes executable or a local ~/.hermes directory, then checks ~/.hermes/config.yaml for Beacon-managed commands, identified by the endpoint settings flags (--log, --config, --cli) or a legacy BEACON_ENDPOINT_MODE=1 prefix, together with --platform hermes. Use beacon endpoint hooks status --harness hermes to inspect Hermes Agent hook status. Use beacon endpoint hermes status to inspect committed local sessions and how much Beacon has synced.

​
Install or configuration support

beacon endpoint install prepares shared endpoint config and runtime log paths. Install Hermes Agent hooks separately:
Install runtime hooks
Hermes Agent hooks support user-level config only. Project-level installs are rejected because Hermes reads shell hooks from the user’s Hermes config.

​
Telemetry coverage

​
Session database sync

beacon endpoint hermes sync reads committed rows from Hermes Agent’s state database after Hermes has written them. The cursor is stored in Beacon endpoint state and advances by session message id. Use --print to preview mapped events without writing the runtime log or advancing the cursor. For scheduled collection, run beacon endpoint hermes sync --watch, or run one-shot sync from your scheduler. Live hooks remain the real-time path.

​
Deployment notes

Hermes prompts for first-use consent for each (event, command) hook pair. For non-interactive gateway, cron, or CI runs, set HERMES_ACCEPT_HOOKS=1, start Hermes with --accept-hooks, or configure hooks_auto_accept: true in ~/.hermes/config.yaml. Beacon preserves existing Hermes settings and non-Beacon hooks when installing or uninstalling Hermes telemetry. It replaces only Beacon-managed Hermes hook commands. Restart Hermes after installing or removing hooks so new sessions pick up the updated configuration.

Supported agent harnesses

Return to the runtime support overview.

Hooks

Install, inspect, and uninstall runtime hook integrations.