Hermes LINE User Gateway via chatmux

A standalone Hermes platform plugin for a personal LINE account, backed by chatmux. Includes source, account-free tests, example configuration, and deployment documentation so another agent can review and adapt the integration.

Unofficial integration — account risk: chatmux uses @evex/linejs, not the official LINE Messaging API. LINE may restrict or suspend the connected account. Use a dedicated account. If an official bot meets your needs, prefer the official API instead.

Architecture

LINE personal account
  ↕ unofficial LINE protocol / E2EE
chatmux LINE adapter (Node.js + tsx + linejs)
  ↕ stdio JSON-RPC
chatmux daemon (Bun, JSONL + SQLite/FTS5)
  ↕ MCP Streamable HTTP — numeric loopback only
this plugin (platform key: line_user)
  ├─ exact authorization / activation rules
  ├─ durable cursor + inbox + outbox
  ├─ optional native-mention / reply projection
  └─ Hermes session and profile routing
       ↕
Hermes agent / tools / memory

chatmux owns LINE login tokens, E2EE keys, reconnects, message storage, and actual network sends. This plugin does not log into LINE. Hermes's official Messaging API platform remains the separate line platform.

Related MCP server: LINE OA MCP Ultimate

What is included

• Observe-first configuration; outbound disabled by default.

• Exact DM/group allowlists, activation prefixes, and outbound target gates.

• Atomic event cursor/inbox persistence before agent dispatch.

• Read acknowledgement after durable acceptance, not after model completion.

• Durable outbound operations with no blind retry after ambiguous sends.

• Optional native group mentions and replies-to-agent triggers through a read-only chatmux SQLite projection.

• Named-profile routing for native-mention groups, with fail-closed profile checks.

• CLI diagnostics, inbox/outbox inspection, explicit cursor reset, and macOS LaunchAgent rendering.

Important limits

• This is an experimental integration, not an official or universally compatible LINE connector.

• Native group handling depends on both chatmux's SQLite schema and Hermes internal APIs, including gateway.run._profile_runtime_scope and agent.secret_scope. Verify these on your Hermes checkout before activation; do not remove isolation checks to bypass incompatibility.

• Native-mention groups currently expose the fixed toolsets web and memory; this is not a configurable general-purpose group tool policy.

• chatmux's send API has no caller idempotency key / operation-status query. Exactly-once delivery is not promised; ambiguous sends require operator reconciliation.

• Static media/stickers are not supported as agent prompts. No native reply rendering, typing, or reaction support is promised.

• Adding chatmux as an MCP server alone does not provide automatic message-triggered agent runs. This plugin supplies that consumer loop for Hermes; other runtimes need their own consumer.

• Local message storage contains decrypted content. Loopback is a host-level trust boundary, not authentication against other local processes.

Install from source

Prerequisites: a compatible Hermes installation, Git, Python 3.11–3.14, and separately installed chatmux with its Node/Bun dependencies. Review both projects before connecting an account.

git clone https://github.com/tardis7575/hermes-chatmux-line-gateway.git
cd hermes-chatmux-line-gateway

# Directory discovery: use the intended Hermes profile's plugins directory.
mkdir -p ~/.hermes/plugins
ln -s "$PWD" ~/.hermes/plugins/line_user-platform
hermes plugins list --plain --no-bundled

Do not install into multiple profile directories or change a running gateway unintentionally. Alternatively build a wheel with uv build and install it into the same environment as Hermes; a separate venv will not make the plugin discoverable to an existing Hermes process.

1. Review account setup and live canaries.

2. Start chatmux interactively for the initial QR login; credentials stay in chatmux's protected data directory.

3. Copy the relevant settings from examples/hermes.config.yaml into the intended profile. Begin in observe mode with sending disabled.

4. Discover exact IDs locally; never infer an ID from a display name.

5. Follow install / activation / rollback. Enable only after reviewing scope; restart only the intended gateway.

6. Prove one authorized DM and one group canary, then test restart, network loss, and ambiguous-send handling before relying on it.

No live account credentials, chat history, real chat IDs, or operator deployment reports are included. Fixtures use synthetic identities.

For another agent runtime

Use chatmux's MCP tools directly: read_events, list_chats, read_messages, get_status, send_message, and mark_read. Discover live schemas with tools/list rather than assuming a fixed SDK signature.

Build a persistent consumer that:

1. Establishes the current event head on first use without replaying history.

2. Saves opaque cursors unchanged, atomically with accepted work.

3. Enforces allowlists and activation rules outside the LLM.

4. Serializes work per conversation and isolates sessions/memory.

5. Saves outbound intent before sending and holds ambiguous outcomes.

6. Coordinates sends across consumers sharing an account.

Native mention metadata is currently resolved from chatmux's local projection, not a portable MCP-only contract. See architecture and protocol.

Development

uv sync --extra test
uv run python -m pytest -ra
uv build

Standalone tests do not require a LINE login. Tests requiring Hermes or a chatmux checkout must be explicitly provisioned; skipped integrations are not evidence of live delivery. See compatibility and verification.

Documentation

• Architecture

• Protocol contract

• Delivery semantics

• Install and rollback

• Live acceptance

• macOS operations

• Troubleshooting

• Security

MIT licensed. This repository contains the consumer/plugin, not a vendored copy of chatmux or linejs; those projects retain their respective licenses.