hotplex

Transforming AI CLI Agents into Production-Ready Interactive Services

Break the limits of one-off CLI tasks. Leverage full-duplex, stateful sessions for instant interaction, secure isolation, and effortless system integration.

English • 简体中文 • SDK Guide • Docs Site

⚡ What is hotplex?

hotplex is more than just a process multiplexer; it is the Strategic Bridge for AI agent engineering.

Our First Principle is: Upgrade existing AI CLI tools (like Claude Code, OpenCode) from "human-oriented terminal tools" into "system-ready, long-lived interactive services" (Cli-as-a-Service).

Developers no longer need to endure the multi-second latency of restarting CLI environments in headless mode. By maintaining a persistent, full-duplex session pool, hotplex eliminates the interaction gap caused by cold starts and provides a unified integration layer. Whether building professional AI products or automated pipelines, hotplex makes elite agent capabilities as easy to call as a standard API.

Why hotplex?

• 🔄 Cli-as-a-Service: Shift from "run-and-exit" to persistent sessions with continuous instruction flow and context preservation.
• 🧩 Ease of Integration: A unified Go SDK and protocol gateway that plugs top-tier Agent capabilities into your product instantly.
• 🚀 Zero Spin-up Overhead: Eliminate the long wait times for Node.js/Python runtimes to provide sub-second user feedback.
• 🛡️ Fast & Balanced Security: Command-level WAF and PGID isolation provide a "protective glove" for AI shell operations.
• 💬 ChatApps Integration: Connect HotPlex to platforms like Slack (native Block Kit, streaming, Assistant Status API) and DingTalk, enabling AI collaboration directly in your team's workspace.
• 🔌 Ready for Scale: Support for native Go embedding or standalone Proxy mode with WebSocket and OpenCode-compatible protocols.

🏗️ Architecture Design

hotplex decouples the access layer from the execution engine layer, leveraging bounded Go channels and WaitGroups to achieve deterministic, safe concurrent I/O handling at scale.

1. System Topology

• Access Layer: Supports native Go SDK calls or remote API connections (hotplexd). Includes a dedicated OpenCode HTTP/SSE compatibility handler.
• Engine Layer: Singleton resource manager managing the session pool, configuration overrides, and security WAF.
• Process Layer: Sub-process worker isolated in PGID-level workspaces, locked to specific directory boundaries.

2. Full-Duplex Async Streaming

Unlike standard RPC or REST request-response cycles, hotplex taps directly into Go's non-blocking concurrency model. stdin, stdout, and stderr streams are piped continuously between the client and child process, ensuring sub-second token delivery from local LLM commands.

🚀 Quick Start

Recommended: ChatApps Platform (Slack, Telegram, Feishu, etc.)

The primary access channel for production environments. Interact with AI agents directly through messaging platforms.

Get started in minutes:

# 1. Run with --config flag (recommended, highest priority)
hotplexd --config chatapps/configs

# 2. Or use environment variables
export CHATAPPS_ENABLED=true
export CHATAPPS_CONFIG_DIR=chatapps/configs
hotplexd

→ Full ChatApps Guide - Step-by-step tutorial for all platforms

Alternative: Go SDK or Standalone Server

For custom integrations or microservice architectures.

Quick example (Go SDK):

go get github.com/hrygo/hotplex

engine, _ := hotplex.NewEngine(hotplex.EngineOptions{Timeout: 5 * time.Minute})
engine.Execute(ctx, cfg, "Your prompt here", callback)

→ Full SDK Guide for detailed documentation

📖 Detailed Documentation

Core Technical Manuals

• ChatApps Manual: Multi-platform connector (Slack, DingTalk, Feishu) with native Block Kit support and AI-native UX patterns.
• Engine Manual: Core control plane, process hot-multiplexing, and execution logic.
• Provider Manual: AI agent abstraction (Claude Code, OpenCode) and event normalization.
• Internal Subsystems: Foundational security WAF, session pooling, and system utilities.

Guides & Manuals

• Architecture Deep Dive: Explore the inner workings, security protocols, and session management logic.
• SDK Developer Guide: A comprehensive manual for integrating HotPlex into your Go applications.
• Slack Integration Guide: Comprehensive guide for connecting HotPlex to Slack with native streaming.
• Observability Guide: OpenTelemetry and Prometheus integration.
• Docker Deployment: Container and Kubernetes deployment.
• Production Guide: Production deployment best practices.

📂 Example Repositories

Explore our ready-to-use examples to accelerated your integration:

• go_claude_basic: Quick start with minimal configuration.
• go_claude_lifecycle: Multi-turn, session recovery, and PGID management in Claude.
• go_opencode_basic: Minimal OpenCode integration.
• go_opencode_lifecycle: Multi-turn and session persistence in OpenCode.
• node_claude_websocket: Full-duplex web integration.

🛡️ Security Posture

CLI Agents run raw shell commands generated by LLMs. Security must not be an afterthought. hotplex employs a deep defense-in-depth model:

💡 Use Cases & Scenarios

🗺️ Roadmap & Vision

We are actively evolving hotplex to become the definitive execution engine for the Local AI ecosystem.

🚀 Future Enhancements

• Persistent Storage: Session state persistence across restarts for true long-lived agents.
• Native LLM Brain: Built-in memory and context management for autonomous agent behavior.
• Advanced Isolation: Exploring Linux Namespaces (PID/Net) and WASM-based execution sandboxes.
• Enhanced ChatApps: Expanding platform support (Discord, Teams) with richer UI components.

🤝 Contributing

We welcome community contributions! Please ensure your PR passes the CI pipeline.

# Verify code formatting and linting
make lint

# Run unit tests and race detector
make test

Please read our CONTRIBUTING.md for architectural guidelines and PR conventions.

📄 License

hotplex is released under the MIT License.