@nordbyte/nordrelay 0.3.0 → 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.
@@ -137,7 +185,7 @@ Operations:
 - Telegram sends/edits/documents are routed through a rate-limit queue that honors Telegram retry-after responses.
 - Context metadata, queues, and preferences are written atomically with backup recovery.
 - Context metadata, queues, preferences, audit events, and locks can use JSON files or the optional SQLite state backend with `NORDRELAY_STATE_BACKEND=sqlite`.
-- Runtime state and logs are written under `~/.codex/nordrelay/`.
+- Runtime config, state, and logs are written under `~/.nordrelay/`.
 - `nordrelay init` creates a private runtime config, `nordrelay doctor` validates host prerequisites, and `nordrelay web` starts a full local WebUI dashboard.
 - The WebUI has responsive header/sidebar/footer navigation, live chat streaming, session controls, queue/artifact/log/diagnostic views, and settings management.
 - The WebUI supports light and dark themes, tabbed settings groups, paginated session browsing, and chat uploads for images, documents, and audio transcription.
@@ -161,7 +209,7 @@ nordrelay doctor
 nordrelay start
 ```
 
-npm is the fastest install path and is the recommended default for normal use. For package installs, put runtime configuration in a directory-local `.env` before running `nordrelay`, or in `~/.codex/nordrelay/nordrelay.env`.
+npm is the fastest install path and is the recommended default for normal use. `nordrelay init` writes the private runtime config to `~/.nordrelay/nordrelay.env`.
 
 Non-interactive setup is also supported:
 
@@ -176,7 +224,9 @@ Install dependencies and build the runtime:
 ```bash
 npm install
 npm run build
-cp .env.example .env
+mkdir -p ~/.nordrelay
+cp .env.example ~/.nordrelay/nordrelay.env
+chmod 600 ~/.nordrelay/nordrelay.env
 ```
 
 Create the Telegram bot:
@@ -184,17 +234,20 @@ Create the Telegram bot:
 1. Open Telegram and talk to `@BotFather`.
 2. Run `/newbot`.
 3. Choose a display name and bot username.
-4. Copy the bot token into `TELEGRAM_BOT_TOKEN` in `.env`.
+4. Copy the bot token into `TELEGRAM_BOT_TOKEN` in `~/.nordrelay/nordrelay.env`.
 5. Find your Telegram user id with a trusted id helper bot, for example `@userinfobot`, or from Telegram API tooling.
 6. Put your user id into `TELEGRAM_ADMIN_USER_IDS`.
 
-Minimal private-bot `.env`:
+Minimal private-bot `~/.nordrelay/nordrelay.env`:
 
 ```dotenv
 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
@@ -217,11 +270,45 @@ Codex authentication:
 Pi setup:
 
 - Install Pi from https://pi.dev/ and confirm `pi --help` works on the host.
-- Set `NORDRELAY_PI_ENABLED=true` in `.env`.
+- Set `NORDRELAY_PI_ENABLED=true` in `~/.nordrelay/nordrelay.env`.
 - Keep `NORDRELAY_DEFAULT_AGENT=codex` to start chats in Codex, or set `NORDRELAY_DEFAULT_AGENT=pi` to start chats in Pi.
 - 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
@@ -282,9 +369,9 @@ npm run foreground
 
 Runtime files:
 
-- PID file: `~/.codex/nordrelay/nordrelay.pid`
-- State file: `~/.codex/nordrelay/state.json`
-- Log file: `~/.codex/nordrelay/nordrelay.log`
+- PID file: `~/.nordrelay/nordrelay.pid`
+- State file: `~/.nordrelay/state.json`
+- Log file: `~/.nordrelay/nordrelay.log`
 - Home override: `NORDRELAY_HOME=/custom/path`
 - Local dashboard: `nordrelay web --host 127.0.0.1 --port 31878`
 
@@ -304,15 +391,19 @@ 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.
-- Switch or attach existing sessions.
+- 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.
 - Upload images, documents, and audio files from the chat composer. Images are passed as image inputs, documents are staged for the agent, and audio is transcribed through the configured voice backend.
+- Keep a persistent per-thread WebUI chat history across page reloads.
+- Control the active session model, reasoning/thinking, fast mode, and launch profile directly from the chat view.
 - Abort turns, hand sessions back to the native CLI, and inspect the active session.
-- Manage queued prompts.
-- Browse, download, ZIP, and delete artifacts.
-- Edit all supported runtime settings from tabbed Settings groups.
-- View logs, diagnostics, enabled channels, and agent adapters.
+- Manage queued prompts with pause/resume, run, cancel, reorder buttons, and drag-and-drop prioritization.
+- Browse, preview, download, ZIP, and delete artifacts.
+- Inspect the activity timeline for WebUI and mirrored CLI turns.
+- Edit all supported runtime settings from tabbed Settings groups with option selects, validation feedback, and restart actions.
+- View filtered logs, structured diagnostics, enabled channels, and agent adapters.
 
 Dashboard API endpoints are served under `/api/*`. Streaming uses `GET /api/events`.
 
@@ -383,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.
@@ -446,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
@@ -460,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:
 
@@ -530,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.
 
@@ -599,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`.
@@ -612,7 +724,7 @@ Dashboard:
 - `NORDRELAY_DASHBOARD_TOKEN`: optional dashboard bearer/login token. Required when binding to `0.0.0.0` unless basic auth is configured.
 - `NORDRELAY_DASHBOARD_USER`: optional dashboard basic-auth user.
 - `NORDRELAY_DASHBOARD_PASSWORD`: optional dashboard basic-auth password. Required with `NORDRELAY_DASHBOARD_USER`.
-- `NORDRELAY_ENV_FILE`: optional env file edited by the dashboard settings page. Defaults to `~/.codex/nordrelay/nordrelay.env` when present, otherwise `.env` in the runtime root.
+- `NORDRELAY_ENV_FILE`: optional explicit env-file path used by the wrapper and edited by the dashboard settings page. Defaults to `~/.nordrelay/nordrelay.env`.
 
 Codex:
 
@@ -635,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:
 
@@ -667,11 +813,11 @@ 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:
 
-- `NORDRELAY_HOME`: state/log directory override. Defaults to `~/.codex/nordrelay`.
+- `NORDRELAY_HOME`: config/state/log directory override. Defaults to `~/.nordrelay`.
 - `NORDRELAY_SOURCE_ROOT`: runtime source root override. Useful when the plugin is launched from Codex cache.
 - `NORDRELAY_UPDATE_METHOD`: optional `auto`, `npm`, or `git` self-update method override. Auto uses git when the runtime root has a `.git` directory and npm otherwise.
 - `NORDRELAY_KEEP_PENDING_UPDATES`: set true to avoid dropping pending Telegram updates on start.
@@ -719,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 `.env` or host secret management; `.env` is gitignored.
-- 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.
 
@@ -759,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:
@@ -773,11 +925,29 @@ 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.
 - Install `ffmpeg` and `faster-whisper` on Linux, install `parakeet-coreml` on macOS Apple Silicon, or set `OPENAI_API_KEY`.
-- Check `~/.codex/nordrelay/nordrelay.log` for transcription errors.
+- Check `~/.nordrelay/nordrelay.log` for transcription errors.
 
 Files not returned:
 
@@ -861,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.