> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beacon.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes Agent

> Beacon support details for Hermes Agent endpoint telemetry

## 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:

```bash title="Sync Hermes Agent sessions" theme={null}
beacon endpoint hermes status
beacon endpoint hermes sync
```

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:

```bash title="Install runtime hooks" theme={null}
beacon endpoint hooks install --harness hermes
```

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

| Area                              | Support                                                                                                                      |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Prompt telemetry                  | Supported through Hermes `pre_llm_call` payloads, including `extra.user_message` where provided                              |
| Command, tool, and file telemetry | Supported for observed pre-tool calls, post-tool results, command execution, file-like tools, and raw Hermes payload context |
| Approval telemetry                | Supported for Hermes approval request and response hooks, including allow, deny, timeout, and unknown decisions              |
| Session and subagent telemetry    | Supported for session lifecycle events and subagent stop metadata where Hermes exposes role, status, summary, and duration   |
| Historical session sync           | Supported through `beacon endpoint hermes sync`; marked as poll collection                                                   |
| Local JSONL and dashboard         | Supported                                                                                                                    |
| MDM deployment                    | Supported for the endpoint agent. Hermes hooks are installed separately in the logged-in user's context                      |

## 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.

## Related

<Columns cols={2}>
  <Card title="Supported agent harnesses" icon="list-check" href="/runtimes">
    Return to the runtime support overview.
  </Card>

  <Card title="Hooks" icon="plug" href="/cli/hooks">
    Install, inspect, and uninstall runtime hook integrations.
  </Card>
</Columns>