hotplex

README

hotplex

Production-Grade Control Plane for Elite AI CLI Agents

Don't reinvent the wheel. Leverage powerful tools like Claude Code with millisecond latency, secure isolation, and full-duplex integration.

English • 简体中文 • SDK Guide

⚡ What is hotplex?

hotplex is more than just a process multiplexer; it is the "Last Mile" Adapter for AI agent engineering.

Our First Principle is: Leverage existing, state-of-the-art AI CLI tools (like Claude Code, Aider, OpenCode) and upgrade them from "terminal tools for humans" to "cloud-native operators for systems."

Developers no longer need to build complex agent runtimes from scratch or reinvent file manipulation logic. By maintaining a persistent, thread-safe process pool, hotplex eliminates the interaction gap caused by cold starts and provides a unified security framework and streaming I/O abstraction. Whether building a personal AI assistant or enterprise-grade CI/CD pipelines, hotplex brings elite agent capabilities to your infrastructure with minimal overhead.

Why hotplex?

• 🧩 Leverage vs. Build: Directly integrate elite tools like Claude Code, skipping months of agent logic development.
• 🚀 200ms Instant Response: Eliminate Node.js/Python spin-up latencies for a fluid, real-time experience.
• ♻️ Stateful Session Pool: Managed lifecycle with persistent VFS state and context across requests.
• 🔒 Security Control Center: Built-in Command WAF and PGID isolation to provide a hard sandbox for AI operations.
• 🔌 Production Ready: Embed via Go SDK or deploy as a WebSocket Gateway for modern microservice architectures.

---

🏗️ 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 WebSocket connections (hotplexd).
• 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:  "bypass-permissions",
        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 WebSocket Gateway

Operate hotplexd as an infrastructure daemon to serve cross-language clients (React, Node, Python, Rust).

Build & Run:

make build
./bin/hotplexd --port 8080 --allowed-tools "Bash,Edit"

Connect & Control: Connect your websocket client to ws://localhost:8080/ws/v1/agent. Check out _examples/websocket_client/ for a fully functional web demo implementation.

---

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

---

🛡️ 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:

• Provider Abstraction: Decoupled engine from specific CLI tools; native support for Claude Code and OpenCode.
• L2/L3 Isolation: Integrating Linux Namespaces (PID/Net) and WASM-based execution sandboxes.
• Event Hooks: Plugin system for custom audit sinks, session telemetry, and real-time notifications (Slack/Webhook).
• Observability (OTel): Native OpenTelemetry tracing for the entire prompt-to-tool execution pipeline.
• Remote Execution: Secure SSH/Docker payload delivery for isolated remote sandbox execution.

---

🤝 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 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 (
	ProviderTypeClaudeCode = provider.ProviderTypeClaudeCode
	ProviderTypeOpenCode   = provider.ProviderTypeOpenCode
)

Provider constants

Variables

var (
	// ErrDangerBlocked is returned when a dangerous operation is blocked.
	ErrDangerBlocked = types.ErrDangerBlocked
	// ErrInvalidConfig is returned when the configuration is invalid.
	ErrInvalidConfig = types.ErrInvalidConfig
)

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
)

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 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 current/last session.
	GetSessionStats() *SessionStats

	// StopSession forcibly terminates a persistent session and its process group.
	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.