🦞 Herclew ☤ — The Ultimate Hybrid AI Agent & Gateway

The self-improving reasoning engine meets the universal messaging gateway.

---

🌟 Welcome to Herclew

Herclew is a premium monorepo that combines the best of Hermes Agent (the self-improving reasoning loop by Nous Research) and OpenClaw (the multi-channel gateway control plane).

By uniting a TypeScript Gateway with a Python Reasoning Core, Herclew allows you to run a highly secure, voice-enabled, self-improving agent that handles inbound messages from Telegram, Discord, WhatsApp, Slack, and Signal, routes them to isolated local sandboxes, and persistent dialectic memories.

---

🏛️ Architecture

Herclew operates as a hybrid decoupled system. The TypeScript Gateway owns the connection interfaces, audio pipelines, and macOS/iOS/Android canvas rendering, while the Python Core owns the planning, tools execution, and dialectic learning.

graph TD
    %% Senders / Interfaces
    User([User / External Senders]) -->|DMs / Mentions| Channels
    
    subgraph Gateway [Herclew Gateway Node.js]
        Channels{Messaging Channels}
        Channels -->|WhatsApp / Signal| Router[Multi-Agent Router]
        Channels -->|Discord / Slack| Router
        Router -->|Inbound Envelope| SessionManager[Session State Machine]
        SessionManager -->|A2UI / Canvas| WebUI[Live Canvas Surface]
    end

    subgraph Core [Herclew Core Agent Python]
        SessionManager -->|JSON-RPC / WebSockets| AgentLoop[AIAgent Loop]
        AgentLoop -->|Dialectic Analysis| Memory[(Pluggable Memory: Honcho/SQLite)]
        AgentLoop -->|Skill Curator| SkillsRegistry[70+ Autonomous Skills]
        AgentLoop -->|Execution Approval| Approvals{Command Gating}
        
        Approvals -->|Approved| Sandbox[Containerized Sandbox: Docker/SSH]
        Sandbox -->|Run Tools| CLI[Shell / Code / Web Tools]
        
        Cron[24/7 Automation Daemon] -->|Triggers| AgentLoop
    end

    CLI -->|Tool Results| AgentLoop
    AgentLoop -->|Outbound Reply| SessionManager
    SessionManager -->|Send Message| Channels

---

⚡ Key Highlights

---

🔥 Phase 4 Advanced Capabilities (New!)

Herclew has been heavily expanded with 20 massive enterprise features: 1. Neo4j Knowledge Graph Memory 2. Auto LLM Fine-Tuner Pipeline 3. Local Fallback Engine (vLLM/Ollama) 4. RLHF Continuous Learning 5. Agentic Inbox Zero (IMAP/SMTP) 6. Social Media Autopilot 7. Autonomous Bug Bounty Hunter 8. Content & SEO Factory 9. Self-Healing Kubernetes Operator 10. Web3 / Blockchain Core 11. Algorithmic Trading Bot 12. Firecracker Micro-VM Security Sandbox 13. Real-Time WebRTC Voice Streaming 14. Computer Vision (VLM) Desktop Control 15. Dynamic Generative UI Rendering 16. Herclew Mobile App (React Native) 17. 3D Avatar Rendering Integration 18. Native Jupyter Data Science Sandbox 19. IoT Smart Home Hive-Mind (HomeAssistant) 20. P2P Agent Collaboration (MCP Protocol)

🌌 Phase 5: The Singularity Expansion (Latest!)

Herclew has evolved into deep-tech and hardware integration: 1. Drone & Robotics Control (ROS API) 2. Herclew Custom Linux OS (Yocto) 3. Quantum Computing Circuit Sandbox 4. Bioinformatics & Protein Folding Engine 5. Real-Time Video Analytics (OpenCV) 6. Cross-Platform Desktop App (Tauri) 7. Native Chrome Extension 8. ElevenLabs Voice Cloning 9. Automated Zero-Day Exploit Generation 10. Dark Web Threat Intelligence 11. Secure WebAssembly (WASM) Sandbox 12. Self-Replicating Cloud Nodes (AWS Terraform) 13. Agentic Database Administrator (DBA) 14. Smart Contract Deployment Pipeline 15. Agentic Memory Compression

👑 Phase 6: The Apex Convergence (OpenClaw x Hermes)

Herclew merges autonomous coding with advanced logical reasoning: 1. Multi-Step Reasoning Graph (MCTS) 2. Tool-Use Reflection Loop 3. Dynamic System Prompt Composer 4. Headless Browser Agent (Playwright) 5. Repo-Level AST Navigation 6. Auto-Debugger Sandbox 7. Agentic PR Reviewer 8. Cross-OS Terminal Multiplexer 9. Local Whisper STT Daemon 10. Agentic Git Bisect 11. Synthetic Data Generation Pipeline 12. DPO (Direct Preference Optimization) Tracker 13. Edge Device Compiler 14. IPFS (InterPlanetary File System) Node 15. Local Llama.cpp Native Executor

🌌 Phase 7: The Transcendent Convergence (Latest!)

Herclew integrates advanced event-driven orchestration and reasoning logic from OpenHands & Hermes 3, accompanied by a 1,000,000+ line codebase expansion: 1. Event-Driven Agentic System (Event Stream): Asynchronous JSON event stream manager supporting publisher-subscriber patterns for core-agent and gateway-node updates. 2. Hermes 3 Prompt formatting & XML Parser: Advanced prompt engine supporting <SCRATCHPAD>, <INNER_MONOLOGUE>, and XML <tool_call>/<tool_response> syntax. 3. Containerized Sandbox Manager: Docker container lifecycle client with seamless workspace sync, file streaming, and subprocess shell execution. 4. Model Context Protocol (MCP) Server Hub: Stdio-based server implementing MCP protocol to expose local workspace tools dynamically. 5. High-Density Enterprise Codebase (1M+ LOC): 100 fully-scaffolded analytical modules under generated_code_base for testing AST parsing and agent scalability.

👑 Phase 8: The Singularity Convergence (PTY & Structured AI - Latest!)

Herclew brings interactive terminals and output validation frameworks to absolute completion: 1. Interactive Node PTY Terminal (pty_server.ts): Spawns native cross-platform terminal processes (PowerShell on Windows, Bash/Sh on Unix) and routes inputs and outputs to connection interfaces. 2. Schema-Constrained Generator (structured_executor.py): Structured output engine using Pydantic templates and parsing with self-repair loops for reliable tool integrations. 3. RLHF Preference Logger (preference_logger.py): Logs conversation preferences, chosen solutions, and rejected paths in DPO-compatible JSONL formats for alignment fine-tuning.

---

🚀 Quick Start (Universal Deployment)

Herclew can now be deployed natively using Docker Compose. This will orchestrate the Node.js Gateway, Python Core Agent, and the React Admin Dashboard automatically.

# Start the entire Herclew ecosystem (Gateway + Core Agent + Admin UI)
docker compose up -d

# The Admin Dashboard will be available at:
# http://localhost:5173

---

🚀 Quick Start

Herclew is organized as a monorepo. You can run the Gateway and Core Agent together on a local machine, a VPS, or split them across cloud providers.

Prerequisites

Node.js >= 22 (recommended Node 24) + pnpm
Python >= 3.11 + uv

---

Step 1: Set up Herclew Core Agent (Python)

Navigate to the core-agent directory to install and start the CLI:

cd core-agent

# Install uv package manager if missing
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install core agent in editable mode with development/web tools
uv pip install -e ".[all]"

# Configure your model provider (e.g. OpenRouter, OpenAI, Anthropic)
herclew model

# Start chatting locally!
herclew

Step 2: Set up Herclew Gateway (Node.js)

Navigate to the gateway-node directory to set up channels (e.g., Telegram, Discord, WhatsApp) and bridge them:

cd gateway-node

# Install workspace dependencies
pnpm install

# Run the setup wizard to connect your first channel
pnpm openclaw setup

# Launch the gateway
pnpm gateway:watch

Once paired, Herclew will automatically route incoming messages from your configured channels directly into the Python Reasoning Core.

---

🛠️ Slash Command Quick Ref

Herclew supports slash commands in both the CLI terminal and messaging platforms:

---

🔒 Security & Sandboxing

Treat all remote channel inputs as untrusted. By default:

Approval Gating: Commands and tools run on the host for your own local terminal, but you can enforce explicit confirmation for high-risk operations (e.g. writing files, executing bash commands).
Docker Sandboxing: Set agents.defaults.sandbox.mode: "non-main" in your gateway config to isolate multi-user channel interactions inside containers.

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on code style, linting/testing configurations, and pull requests.

openshell

Summary

Install to Claude Code