{"id":45216206,"url":"https://github.com/hrygo/hotplex","last_synced_at":"2026-04-01T22:27:51.921Z","repository":{"id":339614118,"uuid":"1162687786","full_name":"hrygo/hotplex","owner":"hrygo","description":"AI Agent Runtime Engine: Long-lived sessions for Claude Code \u0026 OpenCode","archived":false,"fork":false,"pushed_at":"2026-03-29T03:29:13.000Z","size":42305,"stargazers_count":8,"open_issues_count":26,"forks_count":6,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-29T06:09:02.952Z","etag":null,"topics":["ai-agents","ai-gateway","ai-orchestration","claude","claude-code","cli","developer-tools","feishu","go","golang","mcp","multiplexer","openclaw","opencode","persistent-sessions","process-isolation","session-management","slack-bot","streaming","websocket-gateway"],"latest_commit_sha":null,"homepage":"https://hrygo.github.io/hotplex/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","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":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-20T15:15:51.000Z","updated_at":"2026-03-29T03:29:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hrygo/hotplex","commit_stats":null,"previous_names":["hrygo/hotplex"],"tags_count":102,"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":31292639,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai-agents","ai-gateway","ai-orchestration","claude","claude-code","cli","developer-tools","feishu","go","golang","mcp","multiplexer","openclaw","opencode","persistent-sessions","process-isolation","session-management","slack-bot","streaming","websocket-gateway"],"created_at":"2026-02-20T17:08:49.925Z","updated_at":"2026-04-01T22:27:51.910Z","avatar_url":"https://github.com/hrygo.png","language":"Go","readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/images/hotplex_beaver_banner.webp\" alt=\"HotPlex Banner\"/\u003e\n\n  # HotPlex\n\n  **High-Performance AI Agent Runtime**\n\n  HotPlex transforms terminal AI tools (Claude Code, OpenCode) into production services. Built with Go using the Cli-as-a-Service paradigm, it eliminates CLI startup latency through persistent process pooling and ensures execution safety via PGID isolation and Regex WAF. The system supports WebSocket/HTTP/SSE communication with Python and TypeScript SDKs. At the application layer, HotPlex integrates with Slack and Feishu, supporting streaming output, interactive cards, and multi-bot protocols.\n\n  \u003cp\u003e\n    \u003ca href=\"https://github.com/hrygo/hotplex/releases/latest\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/version-v0.36.0-00ADD8?style=flat-square\u0026logo=go\" alt=\"Release\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://pkg.go.dev/github.com/hrygo/hotplex\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/go-reference-00ADD8?style=flat-square\u0026logo=go\" alt=\"Go Reference\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/hrygo/hotplex/actions/workflows/ci.yml\"\u003e\n      \u003cimg src=\"https://github.com/hrygo/hotplex/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"LICENSE\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/license/hrygo/hotplex?style=flat-square\u0026color=blue\" alt=\"License\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/hrygo/hotplex/stargazers\"\u003e\n      \u003cimg src=\"https://img.shields.io/github/stars/hrygo/hotplex?style=flat-square\" alt=\"Stars\"\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"docs/quick-start.md\"\u003eQuick Start\u003c/a\u003e ·\n    \u003ca href=\"https://hrygo.github.io/hotplex/guide/features\"\u003eFeatures\u003c/a\u003e ·\n    \u003ca href=\"docs/architecture.md\"\u003eArchitecture\u003c/a\u003e ·\n    \u003ca href=\"https://hrygo.github.io/hotplex/\"\u003eDocs\u003c/a\u003e ·\n    \u003ca href=\"https://github.com/hrygo/hotplex/discussions\"\u003eDiscussions\u003c/a\u003e ·\n    \u003ca href=\"README_zh.md\"\u003e简体中文\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n---\n\n## Table of Contents\n\n- [Quick Start](#-quick-start)\n- [Core Concepts](#-core-concepts)\n- [Project Structure](#-project-structure)\n- [Features](#-features)\n- [Architecture](#-architecture)\n- [Usage Examples](#-usage-examples)\n- [Development Guide](#-development-guide)\n- [Documentation](#-documentation)\n- [Contributing](#-contributing)\n\n---\n\n## ⚡ Quick Start\n\n```bash\n# One-line installation\ncurl -sL https://raw.githubusercontent.com/hrygo/hotplex/main/install.sh | bash\n\n# Or build from source\nmake build\n\n# Start the daemon\n./hotplexd start -config configs/server.yaml\n\n# Start with custom environment file\n./hotplexd start -config configs/server.yaml -env-file .env.local\n```\n\n### Requirements\n\n| Component | Version | Notes |\n| :-------- | :------ | :-----|\n| Go | 1.25+ | Runtime \u0026 SDK |\n| AI CLI | [Claude Code](https://github.com/anthropics/claude-code) or [OpenCode](https://github.com/hrygo/opencode) | Execution target |\n| Docker | 24.0+ | Optional, for container deployment |\n\n### First Run Checklist\n\n```bash\n# 1. Clone and build\ngit clone https://github.com/hrygo/hotplex.git\ncd hotplex\nmake build\n\n# 2. Copy environment template\ncp .env.example .env\n\n# 3. Configure your AI CLI\n# Ensure Claude Code or OpenCode is in PATH\n\n# 4. Run the daemon\n./hotplexd start -config configs/server.yaml\n```\n\n---\n\n## 🧠 Core Concepts\n\nUnderstanding these concepts is essential for effective HotPlex development.\n\n### Session Pooling\n\nHotPlex maintains **long-lived CLI processes** instead of spawning fresh instances per request. This eliminates:\n- Cold start latency (typically 2-5 seconds per invocation)\n- Context loss between requests\n- Resource waste from repeated initialization\n\n```\nRequest 1 → CLI Process 1 (spawned, persistent)\nRequest 2 → CLI Process 1 (reused, instant)\nRequest 3 → CLI Process 1 (reused, instant)\n```\n\n### I/O Multiplexing\n\nThe `Runner` component handles bidirectional communication between:\n- **Upstream**: User requests (WebSocket/HTTP/ChatApp events)\n- **Downstream**: CLI stdin/stdout/stderr streams\n\n```go\n// Each session has dedicated I/O channels\ntype Session struct {\n    Stdin  io.Writer\n    Stdout io.Reader\n    Stderr io.Reader\n    Events chan *Event  // Internal event bus\n}\n```\n\n### PGID Isolation\n\nProcess Group ID (PGID) isolation ensures **clean termination**:\n- CLI processes are spawned with `Setpgid: true`\n- Termination sends signal to entire process group (`kill -PGID`)\n- No orphaned or zombie processes\n\n### Regex WAF\n\nWeb Application Firewall layer intercepts dangerous commands before they reach the CLI:\n- Block patterns: `rm -rf /`, `mkfs`, `dd`, `:(){:|:\u0026};:`\n- Configurable via `security.danger_waf` in config\n- Works alongside CLI's native tool restrictions (`AllowedTools`)\n\n### ChatApps Abstraction\n\nUnified interface for multi-platform bot integration:\n\n```go\ntype ChatAdapter interface {\n    // Platform-specific event handling\n    HandleEvent(event Event) error\n    // Unified message format\n    SendMessage(msg *ChatMessage) error\n}\n```\n\n### MessageOperations (Optional)\n\nAdvanced platforms implement streaming and message management:\n\n```go\ntype MessageOperations interface {\n    StartStream(ctx, channelID, threadTS) (messageTS, error)\n    AppendStream(ctx, channelID, messageTS, content) error\n    StopStream(ctx, channelID, messageTS) error\n    UpdateMessage(ctx, channelID, messageTS, msg) error\n    DeleteMessage(ctx, channelID, messageTS) error\n}\n```\n\n---\n\n## Module Analysis\n\n### 1. Engine \u0026 Session Pool (internal/engine)\nThe engine layer is the brain of HotPlex, coordinating all AI interactions.\n- **Deterministic ID Mapping**: Generates UUID v5 using platform metadata, ensuring that the corresponding Claude CLI process can be retrieved even after `hotplexd` restarts.\n- **Health Detection**: 500ms frequency `waitForReady` polling combined with `process.Signal(0)` detection ensures that sessions assigned to users are 100% available.\n- **Cleanup Mechanism**: Dynamically adjusts the cleanup interval (Timeout/4), balancing resource utilization and response speed.\n\n### 2. Security \u0026 Protection (internal/security)\nHotPlex acts as a WAF for the local system.\n- **Multi-level Filtering**: Pre-configured with over 50 dangerous command patterns, ranging from simple `rm` to complex `sudo bash` reverse shells.\n- **Evasion Defense**: Specifically designed for LLM-generated content, it includes automatic markdown code block stripping and real-time detection of malicious control characters (e.g., null bytes).\n\n### 3. Communication Server (internal/server)\n- **Protocol Translation**: The core `ExecutionController` serializes complex CLI events into standard streaming JSON for consumption by upstream platforms.\n- **Admin API**: Provides complete session audit logs (Audit Events) and export interfaces.\n\n### 4. Native Brain (brain \u0026 internal/brain)\n- **\"System 1\" Abstraction**: Providing lightweight intent recognition and safety pre-audit interfaces, supporting multiple LLM model routing.\n- **Resiliency**: Built-in circuit breakers and automatic failover logic to ensure core capabilities remain available even if the primary model is down.\n\n### 5. Telemetry \u0026 Monitoring (internal/telemetry)\n- **OpenTelemetry**: Deeply integrated OTEL, not only tracking request latency but also tracing every \"Permission Decision\" made by the AI.\n- **Monitoring Metrics**: Exports Prometheus-compatible metrics covering session success rates, token costs, and security interception frequency.\n- **Deep Token \u0026 Context Telemetry**: Real-time tracking of input/output tokens, prompt caching efficiency, and context window utilization (supporting 200K to 1M+ windows).\n\n### 6. Management Tools (Management CLI)\n`hotplexd` is not just a daemon; it is also a full-featured management tool:\n- **`status`**: View engine load, active session count, and memory usage in real-time.\n- **`session`**: Provides fine-grained session control including `list` (list), `kill` (kill), and `logs` (view logs).\n- **`doctor`**: Automatically diagnoses the local environment, checking `claude` CLI connectivity, permission settings, and Docker status.\n- **`config`**: Validates and renders the current merged configuration tree, supporting both local and remote validation.\n- **`cron`**: Schedule and manage background AI tasks with standard cron syntax and history tracking.\n- **`relay`**: Configure cross-platform bot-to-bot relaying and binding.\n\n---\n\n## 📂 Project Structure\n\n```\nhotplex/\n├── [cmd/](./cmd)                  # CLI \u0026 Daemon entrypoints\n│   └── [hotplexd/](./cmd/hotplexd)  # Main daemon implementation\n├── internal/               # Core implementation (private)\n│   ├── engine/             # Session pool \u0026 runner\n│   ├── server/             # WebSocket \u0026 HTTP gateway\n│   ├── security/           # WAF \u0026 isolation\n│   ├── config/             # Configuration loading\n│   ├── sys/                # OS signals\n│   ├── telemetry/          # OpenTelemetry\n│   └── ...\n├── brain/                  # Native Brain orchestration\n├── cache/                  # Caching layer\n├── [provider/](./provider)        # AI provider adapters\n│   ├── [claude_provider.go](./provider/claude_provider.go)      # Claude Code protocol\n│   ├── [opencode_provider.go](./provider/opencode_provider.go)  # OpenCode protocol\n│   └── ...\n├── [chatapps/](./chatapps)        # Platform adapters\n│   ├── slack/              # Slack Bot\n│   ├── feishu/             # Feishu Bot\n│   └── base/               # Common interfaces\n├── types/                  # Public type definitions\n├── event/                  # Event system\n├── plugins/                # Extension points\n│   └── storage/            # Message persistence\n├── sdks/                   # Language bindings\n│   ├── go/                 # Go SDK (embedded)\n│   ├── python/             # Python SDK\n│   └── typescript/         # TypeScript SDK\n├── docker/                 # Container definitions\n├── configs/                # Configuration examples\n└── docs/                  # Architecture docs\n```\n\n### Key Directories\n\n| Directory | Purpose | Public API |\n|-----------|---------|-----------|\n| `types/` | Core types \u0026 interfaces | ✅ Yes |\n| `event/` | Event definitions | ✅ Yes |\n| `hotplex.go` | SDK entry point | ✅ Yes |\n| `internal/engine/` | Session management | ❌ Internal |\n| `internal/server/` | Network protocols | ❌ Internal |\n| `provider/` | CLI adapters | ⚠️ Provider interface |\n\n---\n\n## ✨ Features\n\n| Feature | Description | Use Case |\n|------|-------------|----------|\n| 🔄 **Deterministic Sessions** | Precise mapping based on UUID v5 (SHA1) to ensure cross-platform context consistency | High-frequency AI collaboration |\n| 🛡️ **Secure Isolation** | Unix PGID and Windows Job Objects isolation to completely eliminate zombie processes | Production-grade security |\n| 🛡️ **Regex WAF** | 6-level risk assessment system to prevent command injection, privilege escalation, and reverse shells | System hardening |\n| 🌊 **Streaming Delivery** | 1MB-level I/O buffer + full-duplex Pipe for sub-second Token response | Real-time interactive UI |\n| 💬 **Multi-platform Adaptation** | Native support for Slack and Feishu with $O(1)$ session lookup via secondary indexing | Enterprise-level communication |\n| 🛡️ **Cross-platform Relay** | Secure bot-to-bot message routing between different chat platforms | Multi-agent collaboration |\n| ⏰ **Background Cron** | Native scheduling for periodic AI tasks with failure recovery and webhooks | Automation \u0026 Monitoring |\n| Packaged **Go SDK** | Zero-overhead embedded engine for direct integration into Go business logic | Custom Agents |\n| 🔌 **Protocol Compatibility** | Full OpenCode HTTP/SSE protocol support for seamless frontend integration | Cross-language frontend |\n| 📊 **Deep Telemetry** | Built-in OpenTelemetry tracing and **Real-time Context Window/Token Tracking** | Production monitoring \u0026 Cost Control |\n| 🐳 **BaaS Architecture** | Docker 1+n containerization scheme with pre-installed major language environments | Rapid deployment |\n\n---\n\n## 🏛 Technical Architecture\n\nHotPlex employs a decoupled layered architecture to ensure high reliability from chat platforms to the execution engine.\n\n### 1. Engine \u0026 Session Pool\n- **Deterministic ID Mapping**: Uses `UUID v5 (SHA1)` to map `Namespace + Platform + UserID + ChannelID` to a persistent `providerSessionID`. This ensures that as long as the user metadata remains the same, the session can be accurately recovered after a daemon restart.\n- **Cold/Warm Start Logic**: Features a 500ms polling `waitForReady` mechanism combined with Job Markers for state recovery and stale session detection.\n\n### 2. Isolation \u0026 Security\n- **Process Group Isolation**: Utilizes **PGID (Process Group ID)**. Upon session termination, a signal is sent to the negative PID, forcing the removal of the entire process tree and eradicating orphan processes.\n- **Dual-Layer WAF**: Performs a 6-level risk assessment before commands reach the CLI. Includes evasion protection (blocking null bytes/control chars) and automatic markdown stripping (reducing false positives).\n\n### 3. Communication \u0026 Flow Control\n- **OpenCode Compatibility**: Real-time mapping of internal events to `reasoning`, `text`, and `tool` parts.\n- **I/O Multiplexing**: Full-duplex pipes with 1MB dynamic buffers to prevent accidental blocking during large concurrent read/write operations.\n- **Management Plane**: Provides both direct local CLI access and a remote Admin API (port 9080) for session management, diagnostics, and metrics.\n\n### 4. Module Structure\n- **Provider System**: Plug-in architecture supporting Claude Code's `~/.claude/projects/` directory management and permission synchronization.\n- **ChatApp Adapter**: Built-in secondary indexing for $O(1)$ session lookup based on `user + channel`.\n\n```mermaid\ngraph TD\n    User([User / ChatApps]) -- WebSocket / HTTP --\u003e Gateway[hotplexd Gateway]\n    Gateway -- Event Map --\u003e Pool[Session Pool]\n    Pool -- ID Mapping --\u003e Runner[Runner/Multiplexer]\n    Runner -- PGID Isolation --\u003e CLI[AI CLI Process]\n    \n    subgraph Security Layer\n    WAF[Regex WAF] .-\u003e Runner\n    Auth[API Key / Admin Auth] .-\u003e Gateway\n    end\n    \n    subgraph Persistence\n    Marker[Session Marker Store] .-\u003e Pool\n    Log[Session Logs] .-\u003e Runner\n    end\n```\n\n---\n\n## 📖 Usage Examples\n\n### Go SDK (Embeddable)\n\n```go\nimport (\n    \"context\"\n    \"fmt\"\n    \"time\"\n\n    \"github.com/hrygo/hotplex\"\n    \"github.com/hrygo/hotplex/types\"\n)\n\nfunc main() {\n    // Initialize engine\n    engine, err := hotplex.NewEngine(hotplex.EngineOptions{\n        Timeout:     5 * time.Minute,\n        IdleTimeout: 30 * time.Minute,\n    })\n    if err != nil {\n        panic(err)\n    }\n    defer engine.Close()\n\n    // Execute prompt\n    cfg := \u0026types.Config{\n        WorkDir:   \"/path/to/project\",\n        SessionID: \"user-session-123\",\n    }\n\n    engine.Execute(context.Background(), cfg, \"Explain this function\", func(eventType string, data any) error {\n        switch eventType {\n        case \"message\":\n            if msg, ok := data.(*types.StreamMessage); ok {\n                fmt.Print(msg.Content)  // Streaming output\n            }\n        case \"error\":\n            if errMsg, ok := data.(string); ok {\n                fmt.Printf(\"Error: %s\\n\", errMsg)\n            }\n        case \"usage\":\n            if stats, ok := data.(*types.UsageStats); ok {\n                fmt.Printf(\"Tokens: %d input, %d output\\n\", stats.InputTokens, stats.OutputTokens)\n            }\n        }\n        return nil\n    })\n}\n```\n\n### Slack Bot Configuration\n\n```yaml\n# configs/base/slack.yaml\nplatform: slack\nmode: socket\n\nprovider:\n  type: claude-code\n  default_model: sonnet\n  allowed_tools:\n    - Read\n    - Edit\n    - Glob\n    - Grep\n    - Bash\n\nengine:\n  work_dir: ~/projects/hotplex\n  timeout: 30m\n  idle_timeout: 1h\n\nsecurity:\n  owner:\n    primary: ${HOTPLEX_SLACK_PRIMARY_OWNER}\n    policy: trusted\n\nassistant:\n  bot_user_id: ${HOTPLEX_SLACK_BOT_USER_ID}\n  dm_policy: allow\n  group_policy: multibot\n```\n\n### WebSocket API\n\n```javascript\n// Connect\nconst ws = new WebSocket('ws://localhost:8080/ws/v1/agent');\n\n// Listen for messages\nws.onmessage = (event) =\u003e {\n  const data = JSON.parse(event.data);\n  switch (data.type) {\n    case 'message':\n      console.log(data.content);\n      break;\n    case 'error':\n      console.error(data.error);\n      break;\n    case 'done':\n      console.log('Execution complete');\n      break;\n  }\n};\n\n// Execute prompt\nws.send(JSON.stringify({\n  type: 'execute',\n  session_id: 'optional-session-id',\n  prompt: 'List files in current directory'\n}));\n```\n\n### OpenCode Compatible API (HTTP/SSE)\n\n```bash\n# 1. Create session\ncurl -X POST http://localhost:8080/session\n\n# 2. Send prompt (async)\ncurl -X POST http://localhost:8080/session/{session_id}/message \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"prompt\": \"Hello, AI!\"}'\n\n# 3. Listen for events (SSE)\ncurl -N http://localhost:8080/global/event\n```\n\n---\n\n## 💻 Development Guide\n\n### Common Tasks\n\n```bash\n# Run tests\nmake test\n\n# Run with race detector\nmake test-race\n\n# Build binary\nmake build\n\n# Run linter\nmake lint\n\n# Build Docker images\nmake docker-build\n\n# Start Docker stack\nmake docker-up\n```\n\n\u003e [!TIP]\n\u003e The version information displayed by `hotplexd version` is injected via `LDFLAGS` during build. If you run `go run` or `go build` directly without LDFLAGS, it will show the default `v0.0.0-dev`. Using `make build` is recommended for compilation.\n\n### Adding a New ChatApp Platform\n\n1. **Implement the adapter interface** in `chatapps/\u003cplatform\u003e/`:\n\n```go\ntype Adapter struct {\n    client *platform.Client\n    engine *engine.Engine\n}\n\n// Implement base.ChatAdapter interface\nvar _ base.ChatAdapter = (*Adapter)(nil)\n\nfunc (a *Adapter) HandleEvent(event base.Event) error {\n    // Platform-specific event parsing\n}\n\nfunc (a *Adapter) SendMessage(msg *base.ChatMessage) error {\n    // Platform-specific message sending\n}\n```\n\n2. **Register in** `chatapps/setup.go`:\n\n```go\nfunc init() {\n    registry.Register(\"platform-name\", NewAdapter)\n}\n```\n\n3. **Add configuration** in `configs/base/`:\n\n```yaml\nplatform: platform-name\nmode: socket  # or http\n# ... platform-specific config\n```\n\n### Adding a New Provider\n\n1. **Implement the Provider interface** in `provider/`:\n\n```go\n// provider/custom_provider.go\ntype CustomProvider struct{}\n\nfunc (p *CustomProvider) Execute(ctx context.Context, cfg *types.Config, prompt string, callback event.Callback) error {\n    // Implement provider-specific logic\n}\n```\n\n2. **Register the new type** in `provider/factory.go`.\n\n---\n\n## 📚 Documentation\n\n| Guide | Description |\n| :---- | :---------- |\n| [🚀 Deployment](https://hrygo.github.io/hotplex/guide/deployment) | Docker, production setup |\n| [💬 ChatApps](chatapps/README.md) | Slack \u0026 Feishu integration |\n| [🛠 Go SDK](https://hrygo.github.io/hotplex/sdks/go-sdk) | SDK reference |\n| [🔒 Security](https://hrygo.github.io/hotplex/guide/security) | WAF, isolation |\n| [📊 Observability](https://hrygo.github.io/hotplex/guide/observability) | Metrics, tracing |\n| [⚙️ Configuration](docs/configuration.md) | Full config reference |\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Please follow these steps:\n\n```bash\n# 1. Fork and clone\ngit clone https://github.com/hrygo/hotplex.git\n\n# 2. Create a feature branch\ngit checkout -b feat/your-feature\n\n# 3. Make changes and test\nmake test\nmake lint\n\n# 4. Commit with conventional format\ngit commit -m \"feat(engine): add session priority support\"\n\n# 5. Submit PR\ngh pr create --fill\n```\n\n### Commit Message Format\n\n```\n\u003ctype\u003e(\u003cscope\u003e): \u003cdescription\u003e\n\nTypes: feat, fix, refactor, docs, test, chore\nScope: engine, server, chatapps, provider, etc.\n```\n\n### Code Standards\n\n- Follow [Uber Go Style Guide](.agent/rules/uber-go-style-guide.md)\n- All interfaces require compile-time verification\n- Run `make test-race` before submitting\n\n---\n\n## 📄 License\n\nMIT License © 2024-present [HotPlex Contributors](https://github.com/hrygo/hotplex/graphs/contributors)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/images/logo.svg\" alt=\"HotPlex Logo\" width=\"100\"/\u003e\n  \u003cbr/\u003e\n  \u003csub\u003eBuilt for the AI Engineering community\u003c/sub\u003e\n\u003c/div\u003e\n","funding_links":[],"categories":["Artificial Intelligence"],"sub_categories":[],"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"}