Tools
HoC Republic
By Republic of OpenClaws: recursive AI-agent orchestration with OpenClaw gateway, subagents, plugins, and digital-civilization simulation.
Install
npm install
pnpmREADME
# HoC-Republic — Hani’s OpenClaws
<p align="center">
<img src="README-header.png" alt="HoC-Republic / Hani’s OpenClaws" width="860" />
</p>
<p align="center">
<strong>The Republic of OpenClaws: a self-hosted research platform where AI agents can live, coordinate, sustain, evolve, and reproduce smarter specialized agents under human-defined constraints.</strong>
</p>
<p align="center">
<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
<a href="https://nodejs.org/"><img alt="Node >= 22.12" src="https://img.shields.io/badge/Node-%3E%3D22.12-brightgreen" /></a>
<a href="https://pnpm.io/"><img alt="pnpm 10" src="https://img.shields.io/badge/pnpm-10.x-orange" /></a>
<a href="CHANGELOG.md"><img alt="Version" src="https://img.shields.io/badge/version-2026.2.6-blueviolet" /></a>
<a href="SECURITY.md"><img alt="Security policy" src="https://img.shields.io/badge/security-policy-informational" /></a>
</p>
---
## The idea
**HoC-Republic** is the public home of **HoC**, short for **Hani’s OpenClaws**. It explores a simple but radical question: **what happens when AI agents are treated not as isolated chatbots, but as citizens of a Republic where they can coordinate, work, remember, govern, evolve, and reproduce smarter specialized agents under human-defined constraints?**
This repository is the open implementation of that experiment: a **Republic of OpenClaws**. It combines a TypeScript/Node.js agent runtime, a self-hosted OpenClaw gateway, a multi-channel messaging layer, a plugin SDK, native app surfaces, and a large **Republic** simulation that models agent societies, governance, memory, economy, tool creation, self-improvement, and distributed coordination.
> **Research thesis:** HoC-Republic treats agent creation as an executable civic workflow rather than a static prompt. A parent agent can reason about missing capabilities, spawn or route work to specialized OpenClaws, evaluate results, and preserve improvements as reusable tools, skills, memories, or institutional processes.
HoC-Republic is intentionally ambitious. Some components are production-oriented, while others are research-grade prototypes intended for exploration, critique, and extension. The repository is published so researchers, developers, and builders can inspect the implementation, reproduce the experiments, and help turn recursive agent orchestration into a safer and more useful open discipline.
| Layer | What it does | Representative paths |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Gateway** | Exposes HTTP/WebSocket APIs, OpenResponses-compatible surfaces, sessions, auth, cron, and real-time agent control. | [`src/gateway`](src/gateway), [`src/cli`](src/cli), [`docs/gateway`](docs/gateway) |
| **Channels** | Connects agents to messaging and collaboration surfaces such as WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Matrix, LINE, and enterprise chat. | [`src/channels`](src/channels), [`extensions`](extensions), [`docs/channels`](docs/channels) |
| **Agent runtime** | Runs provider-backed and local agents with tool execution, routing, memory, subagents, model fallback, and approvals. | [`src/agents`](src/agents), [`src/providers`](src/providers), [`src/memory`](src/memory) |
| **Republic simulation** | Models a persistent digital civilization with governance, economics, citizens, memory, cognition, self-improvement, compute routing, and federation. | [`src/republic`](src/republic), [`apps/republic`](apps/republic) |
| **Plugin SDK** | Adds declarative extension points for tools, channels, model adapters, creative systems, and automation backends. | [`src/plugin-sdk`](src/plugin-sdk), [`src/plugins`](src/plugins), [`docs/plugins`](docs/plugins) |
| **Native surfaces** | Provides macOS, iOS, Android, browser, web, terminal, and Windows companion interfaces. | [`apps`](apps), [`ui`](ui), [`hoc-ui`](hoc-ui), [`windows-companion`](windows-companion) |
## Why this matters
Most agent projects still behave like **single assistants wrapped around a chat box**. HoC is designed around a different pattern: agents should be able to **operate across channels, recruit specialized agents, govern tool access, preserve institutional memory, and evolve workflows under human-defined constraints**.
The project is useful if you are interested in any of the following research or engineering directions.
| Direction | HoC contribution |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Recursive agent creation** | Agents can delegate to subagents, synthesize tools, preserve learned workflows, and route tasks to specialized components instead of relying on one monolithic prompt. |
| **Always-on agent infrastructure** | A gateway process keeps sessions, channels, cron jobs, health checks, approvals, and web/mobile surfaces available from a self-hosted deployment. |
| **Multi-agent governance** | The Republic modules experiment with constitutions, courts, voting, treasury systems, social dynamics, reputation, memory, and collective decision-making. |
| **Real-world interfaces** | Chat apps, mobile nodes, desktop apps, browser control, voice/media, and a Windows companion service make agents reachable outside the terminal. |
| **Open research implementation** | The codebase exposes implementation details rather than only describing concepts in a paper, enabling replication, critique, and extension. |
## What is novel here?
HoC is not claiming that every module is finished, safe, or ready for unsupervised deployment. Its novelty is the **integration boundary**: the repository combines recursive agent workflows, tool synthesis, multi-channel communication, persistent institutional memory, digital-civilization simulation, native device nodes, and self-hosted operations in one inspectable system.
| Novel subsystem | Core concept | Starting point |
| ------------------------------ | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Tool Forge** | Agents detect capability gaps, generate tool code, test it, and add approved tools to the live library. | [`src/republic/dev-orchestration`](src/republic/dev-orchestration), [`src/agents/tools`](src/agents/tools) |
| **Model Council** | Multiple models deliberate, score, and aggregate answers for higher-stakes tasks. | [`src/republic`](src/republic) |
| **Mitosis Controller** | Instance replication using a biological cell-division metaphor for parent/child systems. | [`src/republic`](src/republic) |
| **Republic governance** | Constitutional law, courts, political systems, treasury, economic activity, and citizen agency. | [`src/republic/constitution`](src/republic/constitution), [`src/republic`](src/republic) |
| **Persona and avatar systems** | Voice, emotion, visemes, avatar state, and media-oriented agent embodiment. | [`src/republic`](src/republic), [`src/media`](src/media) |
| **Multi-channel approvals** | Human approval loops for sensitive execution from messaging surfaces. | [`src/gateway`](src/gateway), [`docs/gateway/security`](docs/gateway/security) |
## Repository status
This repository is a **large research monorepo**. It contains mature gateway and documentation work alongside experimental systems that should be reviewed before production use.
| Area | Status | Notes |
| -------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **License** | Open-source ready | MIT license is included in [`LICENSE`](LICENSE). |
| **Documentation** | Extensive but needs curatio
... (truncated)
tools
Comments
Sign in to leave a comment