{"id":45216206,"url":"https://github.com/hrygo/hotplex","last_synced_at":"2026-07-03T06:01:11.430Z","repository":{"id":348129425,"uuid":"1196122681","full_name":"hrygo/hotplex","owner":"hrygo","description":"HotPlex — Unified access layer for AI Coding Agent.","archived":false,"fork":false,"pushed_at":"2026-06-28T11:03:47.000Z","size":61718,"stargazers_count":43,"open_issues_count":13,"forks_count":11,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-28T13:05:56.302Z","etag":null,"topics":["aep","ai-agent","claude-code","codex","gateway","go","harness","openclaw","opencode","websocket"],"latest_commit_sha":null,"homepage":"https://github.com/hrygo/hotplex","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hrygo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-30T11:50:22.000Z","updated_at":"2026-06-28T11:03:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hrygo/hotplex","commit_stats":null,"previous_names":["hrygo/hotplex-worker","hrygo/hotplex"],"tags_count":60,"template":false,"template_full_name":null,"purl":"pkg:github/hrygo/hotplex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hrygo%2Fhotplex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hrygo%2Fhotplex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hrygo%2Fhotplex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hrygo%2Fhotplex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hrygo","download_url":"https://codeload.github.com/hrygo/hotplex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hrygo%2Fhotplex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35074237,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-03T02:00:05.635Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aep","ai-agent","claude-code","codex","gateway","go","harness","openclaw","opencode","websocket"],"created_at":"2026-02-20T17:08:49.925Z","updated_at":"2026-07-03T06:01:11.416Z","avatar_url":"https://github.com/hrygo.png","language":"Go","funding_links":[],"categories":["Artificial Intelligence"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eHotPlex Gateway\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eThe Unified Bridge for AI Coding Agents\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  A high-performance Go gateway providing a single WebSocket interface\u003cbr\u003e\n  to access any AI Coding Agent across Web, Slack, and Feishu.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"README_zh.md\"\u003e简体中文\u003c/a\u003e | \u003cstrong\u003eEnglish\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/hrygo/hotplex/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/hrygo/hotplex/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Version-v1.31.0-10B981?style=flat-square\" alt=\"Version\"\u003e\n  \u003ca href=\"https://github.com/hrygo/hotplex/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-Apache%202.0-3B82F6?style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Go-1.26+-00ADD8?style=flat-square\u0026logo=go\" alt=\"Go\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Protocol-AEP%20v1-7C3AED?style=flat-square\" alt=\"AEP v1\"\u003e\n  \u003ca href=\"https://github.com/hrygo/hotplex/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/hrygo/hotplex?style=flat-square\" alt=\"Stars\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## ✨ Core Capabilities\n\n### 🏗️ Core Architecture\n- 🌐 **Universal AEP Gateway** — Abstract any AI Coding Agent behind a single WebSocket protocol (AEP v1) with backpressure-aware streaming, per-session monotonic sequencing, and automatic LLM retry with exponential backoff.\n- 🔌 **Pluggable Worker Backends** — **Claude Code**, **OpenCode Server**, **ACP** (JSON-RPC 2.0 over stdio for any ACP-compatible agent), and **Codex CLI** behind a unified interface. Switch agents at any granularity with 5-level config fallback (bot → platform → env → messaging → default).\n- 🔄 **Deterministic Sessions** — UUIDv5 session IDs for seamless reconnect across network drops. 5-state machine with per-user pool quotas, dual **SQLite/PostgreSQL** persistence, and background GC.\n\n### 📱 Multi-Platform Delivery\n- 🌍 **Write Once, Deploy Anywhere** — Bridge agents to **Slack** (Socket Mode), **Feishu** (WebSocket), and **Web** with zero agent code changes. Each adapter provides platform-native streaming, slash commands, and interaction management.\n- 🎙️ **Voice Input \u0026 Summary** — Seamless integration with platform voice messages (Speech-to-Text supporting both optional cloud-based Feishu STT API and fully localized, offline custom speech recognition commands) and auto-synthesized summaries back to users (Text-to-Speech via Microsoft Edge-TTS or localized CPU-friendly MOSS-TTS sidecar).\n- ⏰ **AI-Native Cron Scheduler** — Agents autonomously create scheduled tasks from natural language (\"remind me in 30m\"). Supports cron expressions, fixed intervals, and one-shot schedules with lifecycle controls (`max_runs`, `expires_at`), attached session injection, and automatic result delivery.\n- 💬 **Embedded Web Chat \u0026 Admin UI** — A single binary serves the AEP gateway, a Next.js SPA web chat, and an admin dashboard for bot management, API keys, and session monitoring — all out of the box.\n\n### 🤖 Agent Intelligence\n- 🎭 **B/C Dual-Channel Personality** — **B-channel** directives (SOUL/AGENTS/SKILLS) unconditionally override **C-channel** context (USER/MEMORY). Three-level per-bot fallback (global → platform → bot). META-COGNITION hardened with **XML Sanitizer** to block prompt injection.\n- 🧠 **Brain LLM Orchestration** — Optional intelligence layer with intent routing (greetings bypass the coding agent), two-stage safety guard, context compression (8K token threshold), and cross-session user preference extraction.\n\n### 🛡️ Security \u0026 Operations\n- 🔒 **Enterprise-Grade Security** — Timing-safe API key authentication, SSRF protection with DNS rebinding defense, command/tool/model allowlists, environment isolation, and path traversal prevention.\n- 📊 **End-to-End Observability** — 30+ Prometheus metrics, OpenTelemetry distributed tracing with W3C TraceContext propagation, and structured JSON logging.\n- 🛠️ **Self-Contained CLI** — 13 subcommands in one binary: `gateway`, `service` (systemd/launchd/SCM), `onboard` (guided setup), `doctor` (25 diagnostic checks), `cron`, `slack`, `config`, `update` (self-update), `dev`, `status`, `security`, `install`, `version`.\n- 🔄 **Hot-Reload Configuration** — YAML + env var configuration with runtime hot-reload, field-level audit trail, and versioned rollback — no restarts for most changes.\n\n## ⚡ Quick Start\n\n\u003e **AI Agents:** Read https://github.com/hrygo/hotplex/blob/main/INSTALL.md and complete the HotPlex installation and configuration\n\n### Install\n\n**macOS / Linux (one-click binary):**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/hrygo/hotplex/main/scripts/install.sh | bash -s -- --latest\n```\n\n**Windows (PowerShell 5.1+):**\n\n```powershell\nInvoke-WebRequest -Uri https://raw.githubusercontent.com/hrygo/hotplex/main/scripts/install.ps1 -OutFile install.ps1\n.\\install.ps1 -Latest\n```\n\n**From source (requires Go 1.26+, pnpm, Node.js 22+):**\n\n```bash\ngit clone https://github.com/hrygo/hotplex.git\ncd hotplex\nmake quickstart\n```\n\n\u003e **Tip (Claude Code):** After cloning, use `/hotplex-setup` for interactive environment setup and `.env` configuration.\n\n**Docker (Experimental):**\n\n```bash\ncp configs/env.example .env  # edit with your API keys\ndocker compose up -d\n```\n\n### Configure\n\n```bash\n# Interactive setup wizard\nhotplex onboard\n\n# Or auto-generate all configs:\nhotplex onboard --non-interactive --enable-slack --enable-feishu\n```\n\n### Run\n\n```bash\n# Development mode (foreground)\nmake dev\n\n# Production mode (background daemon)\nhotplex gateway start -d\n\n# Stop / restart\nhotplex gateway stop\nhotplex gateway restart -d\n```\n\n### Install as System Service\n\n```bash\nhotplex service install              # user-level (no root)\nsudo hotplex service install --level system  # system-wide\nhotplex service start\nhotplex service status\nhotplex service logs -f\n\n# Uninstall\nhotplex service uninstall\n```\n\nSupports **systemd** (Linux), **launchd** (macOS), and **Windows SCM**.\n\n### Services\n\n| Service             | Address                  | Note                                   |\n| :------------------ | :----------------------- | :------------------------------------- |\n| Gateway (WebSocket) | `ws://localhost:8888/ws` | Main protocol endpoint                 |\n| Admin API           | `http://localhost:9999`  | Management \u0026 Statistics                |\n| Web Chat UI         | `http://localhost:8888`  | **Embedded SPA** (served from Gateway) |\n| Dev Web Chat        | `http://localhost:3000`  | Next.js Dev Server (`make dev`)        |\n\n## 🏗️ Architecture\n\nHotPlex sits between frontend clients and backend AI coding agents, featuring a built-in **Meta-Cognition Core** that abstracts protocol differences into a unified **AEP v1** WebSocket layer.\n\n![HotPlex Architecture](docs/assets/architecture.svg)\n\n\n## 🔗 SDKs \u0026 Libraries\n\n|    Language    | Path                                                         | Features                                              |\n| :------------: | :----------------------------------------------------------- | :---------------------------------------------------- |\n|     **Go**     | [`client/`](client/)                                         | Full-featured, channel-based events, production-grade |\n| **TypeScript** | [`examples/typescript-client/`](examples/typescript-client/) | Streaming, multi-turn chat, React compatible          |\n|   **Python**   | [`examples/python-client/`](examples/python-client/)         | Asyncio, session resume, CLI ready                    |\n|    **Java**    | [`examples/java-client/`](examples/java-client/)             | Enterprise AEP v1 implementation                      |\n\n### Connect with Go SDK\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    client \"github.com/hrygo/hotplex/client\"\n)\n\nfunc main() {\n    c, err := client.New(context.Background(),\n        client.URL(\"ws://localhost:8888/ws\"),\n        client.WorkerType(\"claude_code\"),\n        client.APIKey(\"\u003cyour-api-key\u003e\"),\n    )\n    if err != nil {\n        panic(err)\n    }\n    defer c.Close()\n\n    c.SendInput(context.Background(), \"Explain HotPlex architecture\")\n\n    for env := range c.Events() {\n        if data, ok := env.AsMessageDeltaData(); ok {\n            fmt.Print(data.Content)\n        }\n    }\n}\n```\n\n## 🛠️ Configuration\n\n| Key                         | Default                      | Description                                    |\n| :-------------------------- | :--------------------------- | :--------------------------------------------- |\n| `agent_config.enabled`      | `true`                       | Enable agent personality/context injection     |\n| `messaging.tts_enabled`     | `true`                       | Enable voice reply (voice-in → voice-out)      |\n| `messaging.tts_provider`    | `edge+moss`                  | TTS provider: `edge` (Edge-TTS), `moss` (MOSS CPU), `edge+moss` |\n| `messaging.stt_provider`    | `local`                      | STT provider: `local` (local command), `feishu` (Feishu API), `feishu+local` |\n| `brain.enabled`             | `false`                      | Enable Brain LLM orchestration (auto-discovers keys from worker configs)  |\n| `webchat.enabled`           | `true`                       | Serve embedded webchat SPA from gateway        |\n| `worker.auto_retry.enabled` | `true`                       | Intelligent LLM retry with exponential backoff |\n| `gateway.addr`              | `localhost:8888`             | WebSocket gateway address                      |\n| `admin.addr`                | `localhost:9999`             | Admin API address                              |\n| `db.path`                   | `~/.hotplex/data/hotplex.db` | SQLite database path                           |\n| `log.level`                 | `info`                       | Log level: debug, info, warn, error            |\n\n\u003e [!TIP]\n\u003e See [Configuration Reference](docs/reference/configuration.md) for the full list of environment variables and YAML settings.\n\n## 📖 Documentation\n\nHotPlex ships with **self-hosted documentation** — a Chinese-first docs portal built from Markdown sources, compiled into static HTML, and embedded directly into the gateway binary. Access it at `http://localhost:8888/docs` after starting the gateway.\n\n| Area                | Guide                                                                                                              |\n| :------------------ | :----------------------------------------------------------------------------------------------------------------- |\n| **Getting Started** | [5-Minute Quick Start](docs/getting-started.md) · [Docs Portal](docs/index.md)                                    |\n| **Tutorials**       | [Slack Integration](docs/tutorials/slack-integration.md) · [Feishu Integration](docs/tutorials/feishu-integration.md) · [AI Personality](docs/tutorials/agent-personality.md) · [Cron Tasks](docs/tutorials/cron-scheduled-tasks.md) |\n| **Guides**          | [Remote Coding Agent](docs/guides/developer/remote-coding-agent.md) · [Enterprise Deployment](docs/guides/enterprise/deployment.md) · [Contributing](docs/guides/contributor/development-setup.md) |\n| **Reference**       | [CLI Reference](docs/reference/cli.md) · [Configuration](docs/reference/configuration.md) · [Admin API](docs/reference/admin-api.md) · [AEP v1 Protocol](docs/reference/aep-protocol.md) |\n| **Architecture**    | [Gateway Design](docs/architecture/Worker-Gateway-Design.md) · [Agent Config Design](docs/architecture/Agent-Config-Design.md) · [Meta-Cognition](internal/agentconfig/META-COGNITION.md) |\n| **Security**        | [Security Policies](docs/reference/security-policies.md) · [Authentication](docs/security/Security-Authentication.md) · [SSRF Protection](docs/security/SSRF-Protection.md) |\n\n\u003e [!TIP]\n\u003e Build docs locally: `make docs-build`. Source files live in `docs/`, output goes to `internal/docs/out/` (embedded via `go:embed`).\n\n## 👥 Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feat/AmazingFeature`)\n3. Commit with conventional messages (`git commit -m 'feat: add AmazingFeature'`)\n4. Push to the branch (`git push origin feat/AmazingFeature`)\n5. Open a Pull Request\n\n\u003e [!NOTE]\n\u003e All build/test/lint operations must use `make` targets. See `make help` for the full list.\n\n## 🛡️ Security\n\nIf you discover a security vulnerability, please do NOT open a public issue. Report it via [SECURITY.md](SECURITY.md) or contact maintainers directly.\n\n## 📜 License\n\nDistributed under the [Apache License 2.0](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhrygo%2Fhotplex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhrygo%2Fhotplex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhrygo%2Fhotplex/lists"}