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.
Read this in other languages: English, 简体中文.
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.
- 🔄 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.
- 🔌 Ready for Scale: Support for native Go embedding or standalone Proxy mode with WebSocket and OpenCode-compatible protocols.
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.
- 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.
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.
Drop into your Go backend for zero-overhead, memory-level orchestration of CLI agents.
Install:
go get github.com/hrygo/hotplexUsage Snippet:
package main
import (
"context"
"fmt"
"time"
"github.com/hrygo/hotplex"
)
func main() {
// 1. Initialize engine singleton
opts := hotplex.EngineOptions{
Timeout: 5 * time.Minute,
PermissionMode: "bypassPermissions",
AllowedTools: []string{"Bash", "Edit", "Read", "FileSearch"},
}
engine, _ := hotplex.NewEngine(opts)
defer engine.Close()
// 2. Configure persistent session routing
cfg := &hotplex.Config{
WorkDir: "/tmp/ai-sandbox",
SessionID: "user-123", // Automatically routes to the correct hot process
TaskInstructions: "You are a senior Go systems engineer.",
}
// 3. Execute with streaming callback
ctx := context.Background()
err := engine.Execute(ctx, cfg, "Refactor the main.go to improve error handling",
func(eventType string, data any) error {
if eventType == "answer" {
fmt.Printf("🤖 Agent -> %v\n", data)
}
return nil
})
if err != nil {
fmt.Printf("Execution failed: %v\n", err)
}
}Operate hotplexd as an infrastructure daemon to serve cross-language clients (React, Node, Python, Rust) via WebSocket or OpenCode HTTP/SSE.
Build & Run:
make build
PORT=8080 ./dist/hotplexdConnect & Control:
- WebSocket: Connect to
ws://localhost:8080/ws/v1/agent. - OpenCode (HTTP/SSE): Configure your OpenCode client with
baseURL: "http://localhost:8080".
- 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.
- Quick Start Guide: Step-by-step tutorial for getting started.
- Observability Guide: OpenTelemetry and Prometheus integration.
- Docker Deployment: Container and Kubernetes deployment.
- Production Guide: Production deployment best practices.
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.
CLI Agents run raw shell commands generated by LLMs. Security must not be an afterthought. hotplex employs a deep defense-in-depth model:
| Layer | Implementation | Defense Capability |
|---|---|---|
| I. Tool Governance | AllowedTools configuration array |
Restricts agent's internal tool registry capabilities precisely |
| II. Danger WAF | Regex & Command string interception | Hard blocks destructive commands like rm -rf /, mkfs, dd |
| III. Process Isolation | SIGKILL routed via Process Group ID (PGID) |
Prevents orphaned background daemons or zombie process leaks |
| IV. Filesystem Jail | Context Path Lockdown (WorkDir) |
Constrains the agent's view/edit scope strictly to the project root |
| Domain | Application | Benefit |
|---|---|---|
| 🌐 Web-Based AI Clients | Running "Claude Code" straight from a browser chat window. | Maintains conversational state + session context persistently. |
| 🔧 DevOps Automation | AI-driven bash scripting and live Kubernetes manifest analysis. | Rapid remote execution without repeated Node/Python spin-up costs. |
| 🚀 CI/CD Intelligence | Smart code review, auto-formatting, and vulnerability auto-patching. | Integrates effortlessly into GitHub Actions or GitLab CI runners. |
| 🕵️ AIOps & Log Triage | Continuous pod monitoring with safe, controlled remediation commands. | The regex WAF ensures no accidental production outages by the AI. |
We are actively evolving hotplex to become the definitive execution engine for the Local AI ecosystem.
📊 Full 2026 Roadmap → — March 2026 Sprint: All core features completed!
- Provider Abstraction: Decoupled engine from specific CLI tools; native support for Claude Code and OpenCode.
- Event Hooks: Plugin system with Webhook, Slack, Feishu, DingTalk notifications.
- Observability: OpenTelemetry tracing + Prometheus metrics + Health endpoints (
/health,/metrics). - Remote Execution: Docker-based isolated sandbox execution.
- Multi-Language SDKs: Go SDK, Python SDK, TypeScript SDK.
- Hot Config Reload: Runtime configuration updates without restart.
- Stress Testing: Validated for 1000+ concurrent sessions.
- Documentation Site: VitePress-powered documentation with GitHub Pages deployment.
- L2/L3 Isolation: Integrating Linux Namespaces (PID/Net) and WASM-based execution sandboxes.
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 testPlease read our CONTRIBUTING.md for architectural guidelines and PR conventions.
hotplex is released under the MIT License.