@nordbyte/nordrelay 0.3.1 → 0.4.0

package/.env.example

@@ -20,10 +20,16 @@ TELEGRAM_ALLOWED_CHAT_IDS=
 # Optional explicit override. Keep false for private bots.
 TELEGRAM_ALLOW_ANY_CHAT=false
 
-# Agent access. Codex is enabled by default; Pi is opt-in and requires the
-# `pi` CLI from https://pi.dev/ on the host.
+# Agent access. Codex is enabled by default; Pi, Hermes, OpenClaw, and Claude Code are opt-in.
+# Pi requires the `pi` CLI from https://pi.dev/ on the host. Hermes uses
+# the Hermes API Server (`hermes gateway` with API_SERVER_ENABLED=true).
+# OpenClaw uses the OpenClaw Gateway WebSocket RPC endpoint.
+# Claude Code uses the Claude Agent SDK and the host `claude` CLI when present.
 NORDRELAY_CODEX_ENABLED=true
 NORDRELAY_PI_ENABLED=false
+NORDRELAY_HERMES_ENABLED=false
+NORDRELAY_OPENCLAW_ENABLED=false
+NORDRELAY_CLAUDE_CODE_ENABLED=false
 NORDRELAY_DEFAULT_AGENT=codex
 
 # Codex defaults for newly created or reattached Telegram sessions.
@@ -47,6 +53,43 @@ PI_CLI_PATH=
 PI_SESSION_DIR=
 PI_DEFAULT_MODEL=
 PI_DEFAULT_THINKING=medium
+PI_DEFAULT_PROFILE=default
+
+# Hermes Agent defaults. HERMES_DEFAULT_REASONING: none, minimal, low,
+# medium, high, xhigh. HERMES_API_KEY must match API_SERVER_KEY when the
+# Hermes API Server is protected.
+HERMES_CLI_PATH=
+HERMES_HOME=
+HERMES_STATE_DB_PATH=
+HERMES_API_BASE_URL=http://127.0.0.1:8642
+HERMES_API_KEY=
+HERMES_DEFAULT_MODEL=
+HERMES_DEFAULT_REASONING=
+HERMES_DEFAULT_PROFILE=default
+
+# OpenClaw Agent defaults. OPENCLAW_DEFAULT_THINKING: off, minimal, low,
+# medium, high, xhigh. Gateway token/password are optional unless your
+# OpenClaw Gateway requires shared-secret authentication.
+OPENCLAW_CLI_PATH=
+OPENCLAW_GATEWAY_URL=ws://127.0.0.1:18789
+OPENCLAW_GATEWAY_TOKEN=
+OPENCLAW_GATEWAY_PASSWORD=
+OPENCLAW_AGENT_ID=main
+OPENCLAW_HOME=
+OPENCLAW_STATE_DIR=
+OPENCLAW_DEFAULT_MODEL=
+OPENCLAW_DEFAULT_THINKING=
+OPENCLAW_DEFAULT_PROFILE=default
+
+# Claude Code defaults. CLAUDE_CODE_DEFAULT_EFFORT: off, low, medium, high,
+# xhigh. CLAUDE_CODE_CLI_PATH is optional; NordRelay uses `claude` on PATH or
+# the Claude Agent SDK bundled runtime.
+CLAUDE_CODE_CLI_PATH=
+CLAUDE_CONFIG_DIR=
+CLAUDE_CODE_DEFAULT_MODEL=
+CLAUDE_CODE_DEFAULT_EFFORT=
+CLAUDE_CODE_DEFAULT_PROFILE=default
+CLAUDE_CODE_MAX_TURNS=100
 
 # Telegram output controls.
 CONNECTOR_LOG_FORMAT=text

package/README.md

@@ -1,15 +1,15 @@
 # NordRelay
 
-NordRelay is a remote control plane for coding agents across messaging channels. The current implementation connects Codex and Pi coding-agent sessions to Telegram, keeps independent sessions per chat or forum topic, streams replies and tool activity back to Telegram, supports files, photos, voice input, model controls, session browsing, retry/abort, and CLI handback.
+NordRelay is a remote control plane for coding agents across messaging channels. The current implementation connects Codex, Pi, Hermes, OpenClaw, and Claude Code coding-agent sessions to Telegram, keeps independent sessions per chat or forum topic, streams replies and tool activity back to Telegram, supports files, photos, voice input, model controls, session browsing, retry/abort, and CLI handback.
 
-The repo is both a local Codex marketplace and a standalone Node app. The plugin lives in `plugins/nordrelay/`; the full bot runtime lives in `src/` and uses `@openai/codex-sdk` for Codex plus Pi RPC mode for Pi.
+The repo is both a local Codex marketplace and a standalone Node app. The plugin lives in `plugins/nordrelay/`; the full bot runtime lives in `src/` and uses `@openai/codex-sdk` for Codex, Pi RPC mode for Pi, the Hermes API Server for Hermes, the OpenClaw Gateway WebSocket RPC surface for OpenClaw, and the Claude Agent SDK for Claude Code.
 
 ## Features
 
 Session control:
 
 - Independent coding-agent sessions per Telegram private chat, group chat, and forum topic.
-- `/agent` switches a Telegram context between enabled agents such as Codex and Pi.
+- `/agent` switches a Telegram context between enabled agents such as Codex, Pi, Hermes, OpenClaw, and Claude Code.
 - Persistent Telegram context metadata in the active workspace under `.nordrelay/contexts.json`.
 - `/new` starts a fresh thread, with workspace selection when known workspaces are available.
 - `/session` shows thread id, workspace, launch profile, launch behavior, model, reasoning, fast mode, context usage, token totals, and subscription limit remaining percentages.
@@ -27,8 +27,8 @@ Session control:
 - `/queue later <minutes> <prompt>` schedules a prompt for later execution, and `/queue inspect <queue-id>` shows full queue metadata.
 - `/abort`, `/stop`, and the inline Abort button cancel the active agent turn.
 - Busy prompts are queued per Telegram context instead of being dropped.
-- If the attached thread is currently active in the local Codex CLI, Telegram prompts are queued until that CLI task finishes.
-- Active Codex CLI turns are mirrored into Telegram with configurable `off`, `status`, `final`, or `full` modes.
+- If the attached thread is currently active in the local agent CLI, Telegram prompts are queued until that CLI task finishes.
+- Active Codex, Pi, Hermes, OpenClaw, and Claude Code CLI/API turns are mirrored into Telegram with configurable `off`, `status`, `final`, or `full` modes.
 - `/mirror` controls CLI mirroring per Telegram context.
 - Queues survive connector restarts and are resumed automatically when the external CLI turn becomes idle.
 - `/notify` controls completion/status notifications and quiet hours per Telegram context.
@@ -44,8 +44,8 @@ Adapter architecture:
 
 - Telegram is implemented as the first channel adapter with text, typing, streaming edits, inline buttons, files, photos, voice, topics, and webhook capability metadata.
 - `/channels` shows available and planned messaging adapters for Discord, WhatsApp, Slack, and Matrix.
-- Codex and Pi are implemented as agent adapters, with descriptors for future Claude Code, OpenClaw, and Hermes support.
-- `/agents` shows available/planned agent adapters and whether Codex/Pi are enabled.
+- Codex, Pi, Hermes, OpenClaw, and Claude Code are implemented as agent adapters.
+- `/agents` shows available/planned agent adapters and whether Codex, Pi, Hermes, OpenClaw, and Claude Code are enabled.
 
 Codex runtime:
 
@@ -59,7 +59,7 @@ Codex runtime:
 - Unsafe `danger-full-access` profiles require `ENABLE_UNSAFE_LAUNCH_PROFILES=true` and Telegram confirmation.
 - Review or unsafe launch profiles require an inline Telegram approval before each prompt is executed.
 - Fast mode can be toggled with `/fast` and mirrors Codex's `fast_default_opt_out` setting from `~/.codex/config.toml`.
-- Active Telegram sessions periodically sync model, reasoning, workspace, launch metadata, and fast-mode defaults from local Codex state.
+- Active Telegram sessions periodically sync model, reasoning, workspace, launch metadata, and fast-mode defaults from local agent state where supported.
 - Active local Codex CLI tasks are detected from rollout JSONL files so Telegram does not race the CLI on the same thread.
 - `/diagnostics` includes rollout path, activity status, stale/idle reason, line count, and last update time.
 - Optional per-turn token usage footer with `SHOW_TURN_TOKEN_USAGE=true`.
@@ -67,14 +67,62 @@ Codex runtime:
 Pi runtime:
 
 - Pi support is opt-in with `NORDRELAY_PI_ENABLED=true`.
-- The default Telegram agent is selected with `NORDRELAY_DEFAULT_AGENT=codex` or `pi`.
+- The default Telegram agent is selected with `NORDRELAY_DEFAULT_AGENT=codex`, `pi`, `hermes`, `openclaw`, or `claude-code`.
 - Pi sessions are driven through official `pi --mode rpc` JSONL commands and events.
 - Existing Pi sessions are discovered from `~/.pi/agent/sessions/` or `PI_SESSION_DIR`.
 - `/sessions`, `/switch`, `/attach`, `/new`, `/session`, `/handback`, `/model`, `/reasoning`, `/abort`, `/stop`, `/retry`, `/queue`, files, photos, and voice input work for Pi contexts.
 - Pi model selection uses `pi --list-models` and sends `set_model` through RPC for active sessions.
 - Pi thinking levels use `/reasoning` and support `off`, `minimal`, `low`, `medium`, `high`, and `xhigh`.
 - Pi token and context stats are read through `get_session_stats` when an RPC session is active.
-- Codex-specific features such as launch profiles, fast mode, Codex auth, rollout mirroring, Codex activity timelines, and subscription limit percentages are hidden or reported as unsupported for Pi contexts.
+- Pi launch profiles expose CLI safety modes such as default, read-only tools, no tools, offline, and safe offline.
+- Pi external CLI activity is detected from Pi session JSONL files so Telegram/WebUI prompts queue while the same Pi session is busy.
+- Pi CLI turns can be mirrored into Telegram/WebUI with status, tool activity, final answers, activity timelines, diagnostics, and generated artifact discovery.
+- Pi provider auth checks report the environment variables expected for the selected provider.
+- Codex-only subscription limit percentages remain Codex-specific; Pi reports token/context stats when available.
+
+Hermes runtime:
+
+- Hermes support is opt-in with `NORDRELAY_HERMES_ENABLED=true`.
+- The default Telegram agent can be set with `NORDRELAY_DEFAULT_AGENT=hermes`.
+- Hermes turns are executed through the Hermes API Server `/v1/runs` endpoint and streamed through `/v1/runs/{run_id}/events`.
+- `/abort` and `/stop` use the Hermes run stop endpoint when a NordRelay-started Hermes run is active.
+- Existing Hermes sessions are discovered from `~/.hermes/state.db`, or from `HERMES_STATE_DB_PATH` when configured.
+- `/sessions`, `/switch`, `/attach`, `/new`, `/session`, `/handback`, `/model`, `/reasoning`, `/abort`, `/stop`, `/retry`, `/queue`, files, photos, and voice input work for Hermes contexts.
+- Hermes model selection uses `/v1/models` when the API Server is reachable and falls back to the selected/default model.
+- Hermes reasoning uses `/reasoning` and supports `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`.
+- Hermes launch profiles include `default`, `safe`, `readonly`, and `yolo`; profiles map to run instructions and Hermes approval responses.
+- Hermes external activity is detected from `state.db`, so Telegram/WebUI prompts queue while the same Hermes session has an unfinished CLI turn.
+- Hermes CLI/API turns can be mirrored into Telegram/WebUI with status, tool activity, final answers, activity timelines, diagnostics, and generated artifact discovery.
+- `/auth` checks that the Hermes API Server is reachable and that `HERMES_API_KEY` is usable when configured.
+
+OpenClaw runtime:
+
+- OpenClaw support is opt-in with `NORDRELAY_OPENCLAW_ENABLED=true`.
+- The default Telegram agent can be set with `NORDRELAY_DEFAULT_AGENT=openclaw`.
+- OpenClaw turns are executed through the OpenClaw Gateway WebSocket RPC endpoint configured by `OPENCLAW_GATEWAY_URL`.
+- `/abort` and `/stop` call the OpenClaw Gateway cancel method when a NordRelay-started OpenClaw run is active.
+- Existing OpenClaw sessions are discovered from `openclaw sessions --all-agents --json`, or from the state directory configured with `OPENCLAW_HOME` or `OPENCLAW_STATE_DIR`.
+- `/sessions`, `/switch`, `/attach`, `/new`, `/session`, `/handback`, `/model`, `/reasoning`, `/abort`, `/stop`, `/retry`, `/queue`, files, photos, and voice input work for OpenClaw contexts.
+- OpenClaw model selection uses the Gateway `models.list` method when reachable and falls back to `openclaw models list --json`.
+- OpenClaw thinking uses `/reasoning` and supports `off`, `minimal`, `low`, `medium`, `high`, and `xhigh`.
+- OpenClaw launch profiles include `default`, `safe`, `readonly`, `local`, and `deliver`; profiles map to Gateway run flags and additional instructions.
+- OpenClaw external activity is detected from OpenClaw session state, so Telegram/WebUI prompts queue while the same OpenClaw session has an unfinished CLI turn.
+- OpenClaw Gateway turns can be mirrored into Telegram/WebUI with status, tool activity, final answers, activity timelines, diagnostics, and generated artifact discovery.
+- `/auth` checks that the OpenClaw Gateway is reachable and that `OPENCLAW_GATEWAY_TOKEN` or `OPENCLAW_GATEWAY_PASSWORD` is usable when configured.
+
+Claude Code runtime:
+
+- Claude Code support is opt-in with `NORDRELAY_CLAUDE_CODE_ENABLED=true`.
+- The default Telegram agent can be set with `NORDRELAY_DEFAULT_AGENT=claude-code`.
+- Claude Code turns are executed through `@anthropic-ai/claude-agent-sdk`, using the host `claude` executable when available and the SDK bundled runtime otherwise.
+- Existing Claude Code sessions are discovered from `~/.claude/projects/`, or from `CLAUDE_CONFIG_DIR/projects` when configured.
+- `/sessions`, `/switch`, `/attach`, `/new`, `/session`, `/handback`, `/model`, `/reasoning`, `/abort`, `/stop`, `/retry`, `/queue`, files, photos, and voice input work for Claude Code contexts.
+- Claude Code model selection exposes common aliases and model ids; explicit values from existing sessions are preserved.
+- Claude Code effort uses `/reasoning` and supports `off`, `low`, `medium`, `high`, and `xhigh`.
+- Claude Code launch profiles include `default`, `accept-edits`, `plan`, `readonly`, `no-tools`, and optional `bypass-permissions`.
+- Claude Code external activity is detected from transcript JSONL files, so Telegram/WebUI prompts queue while the same Claude Code session has an unfinished CLI turn.
+- Claude Code SDK turns can be mirrored into Telegram/WebUI with status, tool activity, final answers, activity timelines, diagnostics, and generated artifact discovery.
+- `/auth` checks the host Claude Code CLI auth state when `claude auth status` is available.
 
 Telegram input:
 
@@ -84,7 +132,7 @@ Telegram input:
 - `/voice` can select backend preference, language, and transcribe-only mode.
 - Photo messages are passed to the selected agent as local image input when supported.
 - Document messages are downloaded, sanitized, size-checked, and staged under `.nordrelay/inbox/<turn-id>/`.
-- Telegram media groups and albums are combined into one Codex turn with all photos and documents staged together.
+- Telegram media groups and albums are combined into one agent turn with all photos and documents staged together.
 - Uploaded documents include prompt instructions telling the selected agent where files were staged.
 - Staged document and photo prompts are persisted so `/retry` and queued execution can replay them after a restart.
 - Telegram forum topics are treated as separate work contexts.
@@ -99,7 +147,7 @@ Telegram output:
 - Command execution, web search, file changes, MCP tool calls, error items, and todo-list updates are surfaced.
 - Todo-list updates are rendered as a live plan/status message.
 - Generated artifacts from `.nordrelay/turns/<turn-id>/out/` are retained for manual retrieval with `/artifacts`.
-- Workspace files detected after mirrored Codex CLI turns are indexed as `/artifacts` entries, even when automatic artifact delivery is disabled.
+- Workspace files detected after mirrored Codex, Pi, Hermes, OpenClaw, or Claude Code CLI/API turns are indexed as `/artifacts` entries, even when automatic artifact delivery is disabled.
 - Automatic artifact summaries and file uploads are disabled by default; set `TELEGRAM_AUTO_SEND_ARTIFACTS=true` to send them after turns.
 - Workspace artifact detection sorts by modification time and supports configurable ignored directories and globs.
 - Image artifacts are sent with Telegram previews; large multi-file outputs are bundled into one ZIP when possible.
@@ -118,9 +166,9 @@ Authentication and safety:
 - `TELEGRAM_ADMIN_USER_IDS` restricts admin-only commands such as `/logs`, `/restart`, and `/update`.
 - `TELEGRAM_READONLY_USER_IDS` can inspect status and sessions but cannot send prompts or run mutating commands by default.
 - `TELEGRAM_ROLE_POLICIES_JSON` can override role permissions for `admin`, `operator`, and `readonly`.
-- `/auth` reports Codex authentication status.
-- `/login` starts Codex CLI device auth from Telegram when enabled.
-- `/logout` signs out of CLI auth when not using `CODEX_API_KEY`.
+- `/auth` reports Codex authentication, Pi provider environment health, Hermes API Server reachability, OpenClaw Gateway reachability, or Claude Code CLI auth for the selected agent.
+- `/login` starts Telegram-managed CLI auth for Codex, Hermes, or Claude Code when enabled.
+- `/logout` signs out of CLI auth for Codex, Hermes, or Claude Code; Codex logout is disabled while `CODEX_API_KEY` is in use.
 - `CODEX_API_KEY` can be used for host-side Codex authentication.
 - Friendly error messages are returned for auth, network, model, rate-limit, timeout, and context-length failures.
 - Outgoing Telegram messages and logs redact common token/API-key patterns, with optional custom redaction patterns.
@@ -197,6 +245,9 @@ TELEGRAM_BOT_TOKEN=123456789:replace-me
 TELEGRAM_ADMIN_USER_IDS=123456789
 NORDRELAY_CODEX_ENABLED=true
 NORDRELAY_PI_ENABLED=false
+NORDRELAY_HERMES_ENABLED=false
+NORDRELAY_OPENCLAW_ENABLED=false
+NORDRELAY_CLAUDE_CODE_ENABLED=false
 NORDRELAY_DEFAULT_AGENT=codex
 CODEX_SANDBOX_MODE=workspace-write
 CODEX_APPROVAL_POLICY=never
@@ -224,6 +275,40 @@ Pi setup:
 - Optional: set `PI_SESSION_DIR` if your Pi sessions are not stored in `~/.pi/agent/sessions/`.
 - Optional: set `PI_DEFAULT_MODEL=openai-codex/gpt-5.5` and `PI_DEFAULT_THINKING=medium`.
 
+Hermes setup:
+
+- Install Hermes Agent and confirm `hermes --help` works on the host.
+- Start the Hermes API Server locally and confirm `GET http://127.0.0.1:8642/health` returns OK.
+- Set `NORDRELAY_HERMES_ENABLED=true` in `~/.nordrelay/nordrelay.env`.
+- Keep `NORDRELAY_DEFAULT_AGENT=codex` to start chats in Codex, or set `NORDRELAY_DEFAULT_AGENT=hermes` to start chats in Hermes.
+- Set `HERMES_API_BASE_URL` if the API Server is not listening on `http://127.0.0.1:8642`.
+- Set `HERMES_API_KEY` when the Hermes API Server is protected with `API_SERVER_KEY`.
+- Optional: use `/login` or run `hermes login --no-browser` on the host to refresh Hermes provider credentials.
+- Optional: set `HERMES_STATE_DB_PATH` if your Hermes session database is not stored at `~/.hermes/state.db`.
+- Optional: set `HERMES_DEFAULT_MODEL`, `HERMES_DEFAULT_REASONING`, and `HERMES_DEFAULT_PROFILE`.
+
+OpenClaw setup:
+
+- Install OpenClaw and confirm `openclaw --help` works on the host.
+- Start the OpenClaw Gateway and confirm the WebSocket endpoint is reachable.
+- Set `NORDRELAY_OPENCLAW_ENABLED=true` in `~/.nordrelay/nordrelay.env`.
+- Keep `NORDRELAY_DEFAULT_AGENT=codex` to start chats in Codex, or set `NORDRELAY_DEFAULT_AGENT=openclaw` to start chats in OpenClaw.
+- Set `OPENCLAW_GATEWAY_URL` if the Gateway is not listening on `ws://127.0.0.1:18789`.
+- Set `OPENCLAW_GATEWAY_TOKEN` or `OPENCLAW_GATEWAY_PASSWORD` when the Gateway requires shared-secret auth.
+- Optional: set `OPENCLAW_AGENT_ID` if you want a specific OpenClaw agent instead of `main`.
+- Optional: set `OPENCLAW_HOME` or `OPENCLAW_STATE_DIR` if your OpenClaw session state is stored outside `~/.openclaw`.
+- Optional: set `OPENCLAW_DEFAULT_MODEL`, `OPENCLAW_DEFAULT_THINKING`, and `OPENCLAW_DEFAULT_PROFILE`.
+
+Claude Code setup:
+
+- Install Claude Code and confirm `claude --help` works on the host, or use the SDK bundled runtime.
+- Use `/login` or run `claude auth login` on the host when your Claude Code installation requires local auth.
+- Set `NORDRELAY_CLAUDE_CODE_ENABLED=true` in `~/.nordrelay/nordrelay.env`.
+- Keep `NORDRELAY_DEFAULT_AGENT=codex` to start chats in Codex, or set `NORDRELAY_DEFAULT_AGENT=claude-code` to start chats in Claude Code.
+- Optional: set `CLAUDE_CODE_CLI_PATH` if `claude` is not on `PATH`.
+- Optional: set `CLAUDE_CONFIG_DIR` if your Claude Code sessions are not stored under `~/.claude`.
+- Optional: set `CLAUDE_CODE_DEFAULT_MODEL`, `CLAUDE_CODE_DEFAULT_EFFORT`, `CLAUDE_CODE_DEFAULT_PROFILE`, and `CLAUDE_CODE_MAX_TURNS`.
+
 Register the local Codex marketplace:
 
 ```bash
@@ -306,7 +391,7 @@ http://127.0.0.1:31878/
 
 The dashboard is a second NordRelay client next to Telegram. It can:
 
-- Start a new Codex or Pi session.
+- Start a new Codex, Pi, Hermes, OpenClaw, or Claude Code session.
 - Start a new session from a modal with agent, workspace, model, reasoning/thinking, fast mode, and launch-profile choices.
 - Switch or attach existing sessions, and copy thread IDs from the session list.
 - Send prompts and receive streamed text/tool/plan updates through Server-Sent Events.
@@ -389,22 +474,22 @@ Run NordRelay behind your reverse proxy so the public URL forwards to `http://12
 - `/launch_profiles` or `/launch` opens the launch profile picker.
 - `/fast [on|off]` toggles Codex fast mode. Without an argument it flips the current state.
 - `/model` opens the model picker.
-- `/reasoning` opens the Codex reasoning or Pi thinking picker.
+- `/reasoning` opens the selected agent's reasoning or thinking picker.
 - `/effort` is a backward-compatible alias for `/reasoning`.
 - `/mirror [off|status|final|full]` controls local CLI mirroring for this Telegram context.
 - `/notify [off|minimal|all]` controls Telegram notifications.
 - `/notify quiet HH-HH` sets quiet hours; `/notify quiet off` disables them.
-- `/auth` reports Codex authentication status, or explains that the selected agent uses host-side CLI auth.
-- `/login` starts Telegram-initiated Codex CLI login when Codex is selected.
-- `/logout` signs out from Codex CLI auth unless `CODEX_API_KEY` is active.
+- `/auth` reports Codex authentication status, Pi provider environment health, Hermes API Server reachability, OpenClaw Gateway reachability, or Claude Code CLI auth for the selected agent.
+- `/login` starts Telegram-initiated CLI login for Codex, Hermes, or Claude Code when one of those agents is selected.
+- `/logout` signs out from CLI auth for Codex, Hermes, or Claude Code when one of those agents is selected; Codex logout is disabled while `CODEX_API_KEY` is active.
 - `/voice` reports voice transcription backends and current voice preferences.
 - `/voice backend auto|parakeet|faster-whisper|openai` selects backend preference.
 - `/voice language auto|<code>` selects transcription language.
-- `/voice transcribe_only on|off` controls whether voice is only transcribed or also sent to Codex.
+- `/voice transcribe_only on|off` controls whether voice is only transcribed or also sent to the selected agent.
 - `/tasks` or `/progress` reports the current turn and queue progress.
 - `/status` reports connector runtime status.
-- `/health` reports runtime health, auth, PIDs, Codex CLI, Pi CLI, and state DB.
-- `/version` reports connector, Codex CLI, and Pi CLI paths plus installed/latest NordRelay, Codex, and Pi versions with status icons.
+- `/health` reports runtime health, auth, PIDs, Codex CLI, Pi CLI, Hermes CLI, OpenClaw CLI, Claude Code CLI, and state DB.
+- `/version` reports connector, Codex CLI, Pi CLI, Hermes CLI, OpenClaw CLI, and Claude Code CLI paths plus installed/latest NordRelay, Codex, Pi, Hermes, OpenClaw, and Claude Code versions with status icons.
 - `/logs [lines]` shows a redacted, timestamped connector log tail. Admin only.
 - `/logs update [lines]` shows the self-update log. Admin only.
 - `/logs all [lines]` shows connector and self-update logs together. Admin only.
@@ -452,6 +537,24 @@ For Pi sessions the command looks like:
 cd ~/projects/my-workspace && pi --session ~/.pi/agent/sessions/.../session.jsonl
 ```
 
+For Hermes sessions the command looks like:
+
+```bash
+cd ~/projects/my-workspace && hermes --resume 20260512_181422_ab12cd34
+```
+
+For OpenClaw sessions the command looks like:
+
+```bash
+cd ~/projects/my-workspace && openclaw agent --agent main --session-id nordrelay-openclaw-a1b2c3d4e5f6 --message '<your next message>'
+```
+
+For Claude Code sessions the command looks like:
+
+```bash
+cd ~/projects/my-workspace && claude --resume 019e178a-f275-7d01-95d6-c244ff3e30ed
+```
+
 Change model:
 
 ```text
@@ -466,7 +569,7 @@ Change reasoning effort:
 /reasoning
 ```
 
-For Codex choose one of `minimal`, `low`, `medium`, `high`, or `xhigh`. For Pi choose one of `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`.
+For Codex choose one of `minimal`, `low`, `medium`, `high`, or `xhigh`. For Pi choose one of `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`. For Hermes choose one of `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. For OpenClaw choose one of `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`. For Claude Code choose one of `off`, `low`, `medium`, `high`, or `xhigh`.
 
 Toggle fast mode:
 
@@ -536,7 +639,7 @@ Artifacts:
 Voice and audio:
 
 - Send a Telegram voice note or audio file.
-- The connector transcribes it, then sends the transcript to Codex.
+- The connector transcribes it, then sends the transcript to the selected agent.
 - Local transcription is tried first with `parakeet-coreml` or `faster-whisper` when installed.
 - OpenAI Whisper is used when `OPENAI_API_KEY` is set.
 
@@ -605,7 +708,10 @@ Agent selection:
 
 - `NORDRELAY_CODEX_ENABLED`: enables Codex contexts. Defaults to `true`.
 - `NORDRELAY_PI_ENABLED`: enables Pi contexts. Defaults to `false`.
-- `NORDRELAY_DEFAULT_AGENT`: `codex` or `pi`, used for new Telegram contexts. Defaults to the first enabled agent.
+- `NORDRELAY_HERMES_ENABLED`: enables Hermes contexts through the Hermes API Server. Defaults to `false`.
+- `NORDRELAY_OPENCLAW_ENABLED`: enables OpenClaw contexts through the OpenClaw Gateway. Defaults to `false`.
+- `NORDRELAY_CLAUDE_CODE_ENABLED`: enables Claude Code contexts through the Claude Agent SDK. Defaults to `false`.
+- `NORDRELAY_DEFAULT_AGENT`: `codex`, `pi`, `hermes`, `openclaw`, or `claude-code`, used for new Telegram contexts. Defaults to the first enabled agent.
 - `NORDRELAY_STATE_BACKEND`: `json` or `sqlite`. JSON is the default; SQLite requires `better-sqlite3`.
 - `NORDRELAY_AUDIT_MAX_EVENTS`: maximum audit events retained. Defaults to `1000`.
 - `NORDRELAY_SESSION_LOCK_TTL_MS`: session write-lock TTL. Defaults to `1800000`.
@@ -641,6 +747,40 @@ Pi:
 - `PI_SESSION_DIR`: optional Pi session directory. Defaults to `~/.pi/agent/sessions/` or `PI_CODING_AGENT_SESSION_DIR`.
 - `PI_DEFAULT_MODEL`: optional default model pattern for new Pi sessions, for example `openai-codex/gpt-5.5`.
 - `PI_DEFAULT_THINKING`: default Pi thinking level: `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`. Defaults to `medium`.
+- `PI_DEFAULT_PROFILE`: default Pi launch profile: `default`, `readonly`, `no-tools`, `offline`, or `safe-offline`. Defaults to `default`.
+
+Hermes:
+
+- `HERMES_CLI_PATH`: optional explicit path to the Hermes CLI executable. Defaults to `hermes` on `PATH`.
+- `HERMES_HOME`: optional Hermes home directory. Defaults to `~/.hermes`.
+- `HERMES_STATE_DB_PATH`: optional explicit Hermes `state.db` path. Overrides `HERMES_HOME`.
+- `HERMES_API_BASE_URL`: Hermes API Server base URL. Defaults to `http://127.0.0.1:8642`.
+- `HERMES_API_KEY`: optional bearer token for the Hermes API Server.
+- `HERMES_DEFAULT_MODEL`: optional model label sent with new Hermes API runs.
+- `HERMES_DEFAULT_REASONING`: default Hermes reasoning effort: `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`.
+- `HERMES_DEFAULT_PROFILE`: default Hermes launch profile: `default`, `safe`, `readonly`, or `yolo`. Defaults to `default`.
+
+OpenClaw:
+
+- `OPENCLAW_CLI_PATH`: optional explicit path to the OpenClaw CLI executable. Defaults to `openclaw` on `PATH`.
+- `OPENCLAW_GATEWAY_URL`: OpenClaw Gateway WebSocket URL. Defaults to `ws://127.0.0.1:18789`.
+- `OPENCLAW_GATEWAY_TOKEN`: optional shared-secret token for the OpenClaw Gateway.
+- `OPENCLAW_GATEWAY_PASSWORD`: optional shared-secret password for the OpenClaw Gateway.
+- `OPENCLAW_AGENT_ID`: OpenClaw agent id used for runs and session discovery. Defaults to `main`.
+- `OPENCLAW_HOME`: optional OpenClaw home directory. Defaults to `~/.openclaw`.
+- `OPENCLAW_STATE_DIR`: optional explicit OpenClaw state directory. Overrides `OPENCLAW_HOME`.
+- `OPENCLAW_DEFAULT_MODEL`: optional model label sent with new OpenClaw Gateway runs.
+- `OPENCLAW_DEFAULT_THINKING`: default OpenClaw thinking level: `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`.
+- `OPENCLAW_DEFAULT_PROFILE`: default OpenClaw launch profile: `default`, `safe`, `readonly`, `local`, or `deliver`. Defaults to `default`.
+
+Claude Code:
+
+- `CLAUDE_CODE_CLI_PATH`: optional explicit path to the Claude Code CLI executable. Defaults to `claude` on `PATH`, then the SDK bundled runtime.
+- `CLAUDE_CONFIG_DIR`: optional Claude config directory. Defaults to `~/.claude`.
+- `CLAUDE_CODE_DEFAULT_MODEL`: optional default Claude Code model alias or model id.
+- `CLAUDE_CODE_DEFAULT_EFFORT`: default Claude Code effort: `off`, `low`, `medium`, `high`, or `xhigh`.
+- `CLAUDE_CODE_DEFAULT_PROFILE`: default Claude Code launch profile: `default`, `accept-edits`, `plan`, `readonly`, `no-tools`, or `bypass-permissions`. Defaults to `default`.
+- `CLAUDE_CODE_MAX_TURNS`: maximum agentic turns per Claude Code prompt. Defaults to `100`.
 
 Telegram output:
 
@@ -673,7 +813,7 @@ Auth and voice:
 - `OPENAI_API_KEY`: enables Whisper transcription fallback for voice/audio.
 - `VOICE_PREFERRED_BACKEND`: `auto`, `parakeet`, `faster-whisper`, or `openai`. Defaults to `auto`.
 - `VOICE_DEFAULT_LANGUAGE`: optional default language code, for example `de` or `en`.
-- `VOICE_TRANSCRIBE_ONLY`: when `true`, voice/audio messages are transcribed but not sent to Codex.
+- `VOICE_TRANSCRIBE_ONLY`: when `true`, voice/audio messages are transcribed but not sent to the selected agent.
 
 NordRelay wrapper:
 
@@ -725,8 +865,8 @@ Unsafe profiles are intentionally gated. Telegram asks for confirmation before a
 - Do not leave `TELEGRAM_ALLOW_ANY_CHAT=true` enabled after setup.
 - Treat `danger-full-access` as equivalent to shell access on the host.
 - Treat uploaded files as untrusted input. They are staged inside the active workspace so the selected sandbox policy still matters.
-- Keep `CODEX_API_KEY` and `OPENAI_API_KEY` in `~/.nordrelay/nordrelay.env` or host secret management.
-- In group chats, remember that any allowed user can prompt Codex in that chat context.
+- Keep `CODEX_API_KEY`, `HERMES_API_KEY`, `OPENCLAW_GATEWAY_TOKEN`, `OPENCLAW_GATEWAY_PASSWORD`, and `OPENAI_API_KEY` in `~/.nordrelay/nordrelay.env` or host secret management.
+- In group chats, remember that any allowed user can prompt the selected agent in that chat context.
 - Use `TOOL_VERBOSITY=summary` or `errors-only` when command output may include sensitive data.
 - Review and unsafe launch profiles add a Telegram approve/deny gate before each turn starts.
 
@@ -765,12 +905,18 @@ No sessions listed:
 - Symptom: `/sessions` says no recent threads found.
 - Cause for Codex: `~/.codex/state_*.sqlite` is missing, unreadable, or has no active threads.
 - Cause for Pi: `~/.pi/agent/sessions/` or `PI_SESSION_DIR` is missing, unreadable, or has no session JSONL files.
+- Cause for Hermes: `~/.hermes/state.db` or `HERMES_STATE_DB_PATH` is missing, unreadable, or has no session rows.
+- Cause for OpenClaw: `openclaw sessions --all-agents --json` returns no sessions, or `OPENCLAW_HOME`/`OPENCLAW_STATE_DIR` points at the wrong state location.
+- Cause for Claude Code: `~/.claude/projects/` or `CLAUDE_CONFIG_DIR/projects` is missing, unreadable, or has no session JSONL files.
 - Fix: run the selected agent locally once, resume or create a session, then try `/sessions` again.
 
 Wrong model, reasoning, or fast mode after switching:
 
-- The connector reads model, reasoning, sandbox, and approval policy from Codex state on `/sessions`, `/switch`, `/attach`, and `/session`; fast mode is read from `~/.codex/config.toml`.
+- The connector reads model, reasoning, workspace, sandbox, and approval metadata from supported local agent state on `/sessions`, `/switch`, `/attach`, and `/session`; Codex fast mode is read from `~/.codex/config.toml`.
 - For Pi, the connector reads model/thinking from Pi JSONL sessions and refreshes active RPC state when a session is running.
+- For Hermes, the connector reads model, reasoning, token usage, and message activity from Hermes `state.db`; `/model` and `/reasoning` values are sent with future API runs.
+- For OpenClaw, the connector reads model, thinking, token usage, and activity from OpenClaw session state; `/model` and `/reasoning` values are sent with future Gateway runs.
+- For Claude Code, the connector reads model, effort, token usage, and activity from Claude Code transcript JSONL files; `/model` and `/reasoning` values are sent with future SDK runs.
 - If values look stale, make sure the selected local CLI has finished writing session state.
 
 Pi not available:
@@ -779,6 +925,24 @@ Pi not available:
 - Fix: install Pi from https://pi.dev/, ensure `pi` is on `PATH`, or set `PI_CLI_PATH`.
 - Enable Pi with `NORDRELAY_PI_ENABLED=true`.
 
+Hermes not available:
+
+- Symptom: `/agent` cannot switch to Hermes, `/auth` fails, or prompt execution says the Hermes API request failed.
+- Fix: start the Hermes API Server, ensure `HERMES_API_BASE_URL` points to it, and set `HERMES_API_KEY` if the server requires a key.
+- Enable Hermes with `NORDRELAY_HERMES_ENABLED=true`.
+
+OpenClaw not available:
+
+- Symptom: `/agent` cannot switch to OpenClaw, `/auth` fails, or prompt execution says the OpenClaw Gateway request failed.
+- Fix: start the OpenClaw Gateway, ensure `OPENCLAW_GATEWAY_URL` points to it, and set `OPENCLAW_GATEWAY_TOKEN` or `OPENCLAW_GATEWAY_PASSWORD` if the Gateway requires shared-secret auth.
+- Enable OpenClaw with `NORDRELAY_OPENCLAW_ENABLED=true`.
+
+Claude Code not available:
+
+- Symptom: `/agent` cannot switch to Claude Code, `/auth` fails, or prompt execution says Claude Code auth is missing.
+- Fix: run `claude auth login` on the host, ensure `claude` is on `PATH`, or set `CLAUDE_CODE_CLI_PATH`.
+- Enable Claude Code with `NORDRELAY_CLAUDE_CODE_ENABLED=true`.
+
 Voice not working:
 
 - Run `/voice` to list available backends.
@@ -867,9 +1031,19 @@ npm run build
 - `src/workspace-policy.ts`: workspace allow/warn root evaluation.
 - `src/access-control.ts`: Telegram role permissions and command/callback permission mapping.
 - `src/codex-session.ts`: Codex SDK service for new/resumed threads, streaming events, abort, model, reasoning, launch profiles, and handback.
+- `src/pi-session.ts`: Pi RPC service for JSONL RPC sessions, streaming events, abort, model, thinking, launch profiles, and handback.
+- `src/hermes-session.ts`: Hermes API Server service for streamed runs, stop, model, reasoning, launch profiles, attachments, and handback.
+- `src/openclaw-session.ts`: OpenClaw Gateway service for streamed runs, cancel, model, thinking, launch profiles, attachments, and handback.
+- `src/claude-code-session.ts`: Claude Agent SDK service for streamed runs, abort, model, effort, launch profiles, attachments, and handback.
 - `src/session-registry.ts`: per-chat/topic session registry and persisted context metadata.
 - `src/session-format.ts`: compact Telegram rendering for session details, token usage, and limits.
 - `src/codex-state.ts`: reader for Codex `~/.codex/state_*.sqlite` thread, workspace, model, reasoning, sandbox, and approval metadata.
+- `src/pi-state.ts`: reader for Pi session JSONL files, activity timelines, diagnostics, and external busy detection.
+- `src/hermes-state.ts`: reader for Hermes `state.db` sessions, messages, token usage, activity timelines, diagnostics, and external busy detection.
+- `src/hermes-api.ts`: Hermes API Server client for health, capabilities, models, runs, events, approvals, and stop.
+- `src/openclaw-state.ts`: reader for OpenClaw session metadata, token usage, activity timelines, diagnostics, and external busy detection.
+- `src/openclaw-gateway.ts`: OpenClaw Gateway WebSocket RPC client for health, models, runs, stream events, and cancel.
+- `src/claude-code-state.ts`: reader for Claude Code transcript JSONL files, token usage, activity timelines, diagnostics, and external busy detection.
 - `src/attachments.ts`: inbound file staging and artifact output path construction.
 - `src/artifacts.ts`: generated artifact discovery, ZIP bundling, retention, and Telegram delivery filtering.
 - `src/voice.ts`: audio decoding and transcription backend selection.