hotplex

README

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.

Read this in other languages: English, 简体中文.

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.
• 🔌 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

Option A: Embed as a Go Library (SDK)

Drop into your Go backend for zero-overhead, memory-level orchestration of CLI agents.

Install:

go get github.com/hrygo/hotplex

Usage 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)
    }
}

Option B: Standalone HotPlex Proxy Server

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/hotplexd

Connect & Control:

• WebSocket: Connect to ws://localhost:8080/ws/v1/agent.
• OpenCode (HTTP/SSE): Configure your OpenCode client with baseURL: "http://localhost:8080".

---

📖 Detailed Documentation

• 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.

---

📂 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:

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

---

💡 Use Cases & Scenarios

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.

---

🗺️ Roadmap & Vision

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!

✅ 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.

🚀 Future (H2 2026)

• L2/L3 Isolation: Integrating Linux Namespaces (PID/Net) and WASM-based execution sandboxes.

---

🤝 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.

Built with ❤️ for the AI Engineering community.

Documentation

Overview

Package hotplex provides a production-ready execution environment for AI CLI agents.

Index

• Constants
• Variables
• type AssistantMessage
• type Callback
• type ClaudeCodeProvider
• type Config
• type ContentBlock
• type Engine
• type EngineOptions
• type EventMeta
• type EventWithMeta
• type Executor
• type HotPlexClient
• type OpenCodeConfig
• type Provider
• type ProviderConfig
• type ProviderEvent
• type ProviderFeatures
• type ProviderMeta
• type ProviderSessionOptions
• type ProviderType
• type SafetyManager
• type SessionController
• type SessionStats
• type SessionStatsData
• type StreamMessage
• type UsageStats

Constants

const (
	Version      = "0.9.3"
	VersionMajor = 0
	VersionMinor = 9
	VersionPatch = 3
)

const (
	ProviderTypeClaudeCode = provider.ProviderTypeClaudeCode
	ProviderTypeOpenCode   = provider.ProviderTypeOpenCode
)

Provider constants

Variables

var (
	// ErrDangerBlocked is returned when a dangerous operation is blocked by the WAF.
	ErrDangerBlocked = types.ErrDangerBlocked
	// ErrInvalidConfig is returned when the configuration is invalid.
	ErrInvalidConfig = types.ErrInvalidConfig
	// ErrSessionNotFound is returned when the requested session does not exist.
	ErrSessionNotFound = types.ErrSessionNotFound
	// ErrSessionDead is returned when the session is no longer alive.
	ErrSessionDead = types.ErrSessionDead
	// ErrTimeout is returned when an operation times out.
	ErrTimeout = types.ErrTimeout
	// ErrInputTooLarge is returned when input exceeds maximum size.
	ErrInputTooLarge = types.ErrInputTooLarge
	// ErrProcessStart is returned when the CLI process fails to start.
	ErrProcessStart = types.ErrProcessStart
	// ErrPipeClosed is returned when the pipe is closed.
	ErrPipeClosed = types.ErrPipeClosed
)

var (
	// NewEngine creates a new HotPlex Engine instance.
	NewEngine = engine.NewEngine
	// WrapSafe wraps a callback to make it safe for concurrent use.
	WrapSafe = event.WrapSafe
	// NewEventWithMeta creates a new EventWithMeta.
	NewEventWithMeta = event.NewEventWithMeta
	// TruncateString truncates a string to the given length.
	TruncateString = types.TruncateString
	// SummarizeInput creates a summary of input data.
	SummarizeInput = types.SummarizeInput
	// NewClaudeCodeProvider creates a new Claude Code provider instance.
	NewClaudeCodeProvider = provider.NewClaudeCodeProvider
	// NewOpenCodeProvider creates a new OpenCode provider instance.
	NewOpenCodeProvider = provider.NewOpenCodeProvider
)

Types

type AssistantMessage

type AssistantMessage = types.AssistantMessage

AssistantMessage represents a message from the assistant.

type Callback

type Callback = event.Callback

Callback is the function signature for event streaming.

type ClaudeCodeProvider

type ClaudeCodeProvider = provider.ClaudeCodeProvider

ClaudeCodeProvider implements the Provider interface for Claude Code CLI.

type Config

type Config = types.Config

Config represents the configuration for a single HotPlex execution session.

type ContentBlock

type ContentBlock = types.ContentBlock

ContentBlock represents a content block in a message.

type Engine

type Engine = engine.Engine

Engine is the core Control Plane for AI CLI agent integration.

type EngineOptions

type EngineOptions = engine.EngineOptions

EngineOptions defines the configuration parameters for initializing a new HotPlex Engine.

type EventMeta

type EventMeta = event.EventMeta

EventMeta contains metadata for stream events.

type EventWithMeta

type EventWithMeta = event.EventWithMeta

EventWithMeta wraps event data with metadata.

type Executor

type Executor interface {
	// Execute runs a command or prompt and streams normalized events.
	Execute(ctx context.Context, cfg *types.Config, prompt string, callback event.Callback) error

	// ValidateConfig checks if the session configuration is secure and valid.
	ValidateConfig(cfg *types.Config) error
}

Executor handles the core execution logic and configuration validation.

type HotPlexClient

type HotPlexClient interface {
	Executor
	SessionController
	SafetyManager

	// Close gracefully terminates all managed sessions and releases resources.
	Close() error
}

HotPlexClient defines the comprehensive public API for the HotPlex engine. It integrates execution, session management, and safety configuration.

type OpenCodeConfig

type OpenCodeConfig = provider.OpenCodeConfig

OpenCodeConfig contains OpenCode-specific configuration.

type Provider

type Provider = provider.Provider

Provider defines the interface for AI CLI agent providers.

type ProviderConfig

type ProviderConfig = provider.ProviderConfig

ProviderConfig defines the configuration for a specific provider instance.

type ProviderEvent

type ProviderEvent = provider.ProviderEvent

ProviderEvent represents a normalized event from any AI CLI provider.

type ProviderFeatures

type ProviderFeatures = provider.ProviderFeatures

ProviderFeatures describes the capabilities of a provider.

type ProviderMeta

type ProviderMeta = provider.ProviderMeta

ProviderMeta contains metadata about a provider.

type ProviderSessionOptions

type ProviderSessionOptions = provider.ProviderSessionOptions

ProviderSessionOptions configures a provider session.

type ProviderType

type ProviderType = provider.ProviderType

ProviderType defines the type of AI CLI provider.

type SafetyManager

type SafetyManager interface {
	// SetDangerAllowPaths configures the whitelist of safe directories for file I/O.
	SetDangerAllowPaths(paths []string)

	// SetDangerBypassEnabled toggles the regex WAF (requires valid admin token).
	SetDangerBypassEnabled(token string, enabled bool) error
}

SafetyManager controls the security boundaries and WAF settings.

type SessionController

type SessionController interface {
	// GetSessionStats returns telemetry and token usage for the given sessionID.
	// Note: Use the business-side sessionID provided during execution, not the internal
	// CLI-level session identifier. This sessionID maps to a specific background process.
	GetSessionStats(sessionID string) *SessionStats

	// StopSession forcibly terminates a persistent session and its underlying OS process group.
	// Note: Use the business-side sessionID (provided by the user) to identify which
	// specific agent instance to terminate.
	StopSession(sessionID string, reason string) error

	// GetCLIVersion returns the version string of the underlying AI CLI tool.
	GetCLIVersion() (string, error)
}

SessionController provides administrative control over persistent sessions.

type SessionStats

type SessionStats = engine.SessionStats

SessionStats collects session-level statistics.

type SessionStatsData

type SessionStatsData = event.SessionStatsData

SessionStatsData contains comprehensive session statistics.

type StreamMessage

type StreamMessage = types.StreamMessage

StreamMessage represents a message from the CLI stream.

type UsageStats

type UsageStats = types.UsageStats

UsageStats represents token usage statistics.