AgentHub
metrogg/AgentHub
Orquestrador multi-agent com interface de chat para coordenação de agentes de código
Ver no GitHubPlataforma de orquestração multi-agent baseada em chat para coordenação de agentes de código reais. Integra gerenciador de tarefas, salas de trabalho, execução paralela e artefatos compartilhados, funcionando local-first com suporte a múltiplos modelos e runtimes.
Instalação
npx convez-ai metrogg/AgentHub1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Coordenação de múltiplos agentes de IA em tarefas complexas de desenvolvimento
- Automação de fluxos de trabalho com execução paralela de agentes especializados
- Geração e preview de código, páginas web e artefatos compartilhados com rastreabilidade
- Orquestração de tarefas com interrupção, clarificação e retry automático
Veredito

AgentHub é uma plataforma sólida para orquestração multi-agent com foco em execução real de código. A arquitetura local-first e o modelo de salas como source-of-truth oferecem transparência rara; ideal para equipes que precisam coordenar agentes especializados, mas requer familiaridade com conceitos avançados de agentes.
README
A tradução para o português deste README ainda está na fila.
AgentHub
An open, local-first AI workbench for coordinating real coding agents through group chat, task rooms, resident runtimes, and artifact delivery.
Chinese · Security · Docs · Agent Guide
AgentHub is an AI work platform built for real execution. It combines a Coze / Kimi inspired product shell with a HiClaw-lite open kernel: Matrix rooms are the collaboration source of truth, the Manager is a resident coordinator, Workers are real runtime entities, and generated outputs become traceable shared artifacts.
AgentHub is not one model pretending to be a team, and it is not a fixed-template task pipeline. Its core loop is observable, interruptible, and handoff-friendly: the user states a goal, the Manager organizes the team, Workers execute inside their own rooms, and the main group chat presents progress, reports, artifacts, and the final synthesis.
Product Shape
The first screen is a workbench, not a landing page. Users can continue from a space, a group chat, an agent direct chat, or a previous artifact.

In AgentHub, chat is not just an input box. It is the collaboration surface:
- Group chat carries goals, discussion, coordination, task status, member reports, and final review.
- Agent direct chat keeps long-running context with a single expert agent.
- Task rooms preserve a Worker’s full execution process: assignment, progress, clarification, failure, retry, and output.
- Artifact preview turns generated files, web pages, reports, and shared task directories into inspectable work assets.


Design Principles
1. Rooms Are The Collaboration Source Of Truth
Humans, Managers, and Workers are Room participants. Messages, mentions, files, approvals, clarifications, and progress events enter the timeline. The frontend projects UI from Room timeline events and resource state instead of relying on opaque chat caches.
2. The Manager Coordinates, Not Just Plans
The Manager / Orchestrator behaves like a team lead. It observes rooms, understands goals, asks for missing context, proposes members, assigns work, handles interruptions, and performs final review. Planning is one Manager capability, not the system brain.
3. Workers Are Real Runtime Entities
Workers have identity, state, model binding, skills, workspace, RuntimeLease, Room membership, and heartbeat. OpenClaw resident Workers, Codex CLI, Claude Code, OpenCode, and Gemini CLI expose their capabilities through a shared AgentHub contract.
4. Artifacts Are First-Class Resources
Code, pages, documents, images, reports, and handoff files enter ArtifactStore / SharedStorage. Artifact references use S3-compatible object-key semantics. Local filesystem storage is the default implementation; MinIO/S3 uses the same adapter shape.
5. Local-First, Team-Hostable
AgentHub runs locally by default for developer workflows and project workspaces. Communication, storage, runtimes, and model gateways are adapter-based, so the same product shell can connect to a real Matrix homeserver, MinIO/S3, Docker resident runtimes, and OpenAI-compatible gateways.
Core Experience
User states a goal in group chat
-> Manager observes context and decides whether to reply, ask, propose members, or assign work
-> Controller Plane creates Run / Task / TaskRoom / RuntimeLease
-> Worker claims the task room and executes
-> Process events, clarifications, artifacts, and results are written back to Room timeline
-> Main group chat shows progress, reports, artifact cards, and final review
Users can enter any task room to inspect what the Worker did, where it got blocked, and where the artifact came from. Complex work becomes an execution trace that can be reviewed, interrupted, resumed, and handed off.
Product Modules
| Module | Purpose |
|---|---|
| Space | Organize projects, team members, agents, tasks, and assets |
| Agent Chat | Keep long-running direct conversations with expert agents |
| Agent Group | Coordinate users, Manager, and Workers in a shared room |
| Task Room | Preserve a Worker’s task context, process, and output |
| Task Center | Track runs, tasks, status, dependencies, retries, and human intervention |
| Asset Center | Manage generated artifacts, shared files, previews, and delivery records |
| Expert / Skill Center | Configure agents, role background, skills, MCP, and tool permissions |
| Eval / Trace | Inspect runtime events, model calls, resource state, and failure causes |
Runtime Model
AgentHub Web / Desktop
-> AgentHub Server
-> Controller API
-> RoomService + Matrix Adapter
-> Matrix Homeserver / Tuwunel
-> OpenClaw Manager
-> Worker Runtime
-> ArtifactStore / SharedStorage
-> UI Projection
Layers
| Layer | Responsibility |
|---|---|
| Product interaction | Group chat, agent direct chat, task rooms, task board, artifact cards |
| Orchestration | Manager, controller actions, runs, tasks, RuntimeLease, final review |
| Communication | Matrix rooms, timeline, participants, mentions, file events |
| Protocol projection | AG-UI, Room timeline projection, resource-state projection |
| Execution | OpenClaw Manager, OpenClaw Worker, Codex CLI, Claude Code, OpenCode, Gemini CLI |
| Capabilities | MCP, skills, rules, shell, filesystem, browser, model gateways |
| Storage | SQLite resource index, local SharedStorage, MinIO/S3-compatible object store |
Repository Layout
apps/
server/ Hono/Bun API, Room, Manager runtime, Worker runtime, Controller Plane
web/ React/Vite web workbench
desktop/ Tauri desktop shell
Android/ Android client
packages/
db/ Drizzle schema, migrations, SQLite access
shared/ Shared schemas, constants, and types
infra/
docker-compose.hiclaw-lite.yml
start-hiclaw-lite.sh
stop-hiclaw-lite.sh
openclaw-runtime/
docs/ Product, architecture, runtime, and engineering notes
tests/ bun:test integration, projection, and boundary tests
scripts/ Development process helpers
Local Setup
Requirements
- Bun >= 1.1.0
- Node.js available on
PATH - Docker Desktop for local Tuwunel / MinIO
- Optional coding-agent CLIs: Codex CLI, Claude Code, OpenCode, Gemini CLI
Install
bun install
cp .env.example .env
Review at least these settings:
DATABASE_URL
LLM_PROVIDER
LLM_API_KEY
LLM_BASE_URL
LLM_MODEL
AGENTHUB_ROOM_PROVIDER=matrix
AGENTHUB_MATRIX_HOMESERVER_URL
AGENTHUB_MATRIX_SERVER_NAME
AGENTHUB_MATRIX_REGISTRATION_TOKEN
Start HiClaw-lite Infrastructure
bash infra/start-hiclaw-lite.sh
On Windows PowerShell, bash may resolve to WSL. In that case, run the script from the WSL-mounted repo path:
wsl
cd /mnt/f/Learning/AgentHub
bash infra/start-hiclaw-lite.sh
The script prepares the local Matrix / MinIO / OpenClaw runtime environment and prints the relevant ports, health status, and diagnostics.
Stop the infrastructure:
bash infra/stop-hiclaw-lite.sh
Start AgentHub
bun run dev
The dev script runs database migrations, starts the server, selects an available web port, writes .agenthub-port, and starts the resident Manager when configuration allows it.
Open the web URL printed by the terminal, usually:
http://127.0.0.1:5644/
Common Commands
bun run dev # server + web
bun run dev:stop # stop AgentHub dev processes
bun run dev:server # server only
bun run dev:web # web only
bun run dev:desktop # desktop shell
bash infra/start-hiclaw-lite.sh
bash infra/stop-hiclaw-lite.sh
bun run infra:up # Docker Compose: Tuwunel + MinIO
bun run infra:down # stop local infrastructure
bun run infra:logs # follow infrastructure logs
bun run typecheck
bun --filter @agenthub/server typecheck
bun --filter @agenthub/web typecheck
bun test
Configuration
| Variable | Purpose |
|---|---|
PORT | AgentHub Server port, default 8000 |
DATABASE_URL | SQLite database path |
LLM_PROVIDER | Internal model provider |
LLM_API_KEY | Model gateway key |
LLM_BASE_URL | OpenAI-compatible gateway URL |
LLM_MODEL | Internal default model |
AGENTHUB_ROOM_PROVIDER | Room provider; product path uses matrix |
AGENTHUB_MATRIX_HOMESERVER_URL | Matrix homeserver URL |
AGENTHUB_MATRIX_SERVER_NAME | Matrix server name, default agenthub.local |
AGENTHUB_MATRIX_REGISTRATION_TOKEN | Local Matrix registration token |
AGENTHUB_OBJECT_STORE_PROVIDER | Local filesystem or S3-compatible object store |
AGENTHUB_CONTAINER_RUNTIME | Set to docker for Docker resident runtime |
AGENTHUB_MANAGER_BACKEND | Manager backend override |
AGENTHUB_WORKER_BACKEND | Worker backend override |
AGENTHUB_CODE_AGENT_TIMEOUT_MS | Code Agent execution timeout |
AGENTHUB_SANDBOX_PROVIDER | local-workdir or Docker sandbox |
See .env.example for the full template.
Runtime Contract
AgentHub generates a unified runtime contract for Manager and Worker entities:
SOUL.md
AGENTS.md
TOOLS.md
skills/
state.json
rooms.json
workers-registry.json
teams-registry.json
runtime.json
runtime-manifest.json
heartbeat
workspace
logs
This contract gives different runtime bases a consistent surface: identity, rooms, model binding, skills, workspace, shared task contract, health state, and Controller reconcile.
Documentation
- AGENTS.md: authoritative engineering guide for AI coding agents.
- docs/文档索引与权威口径.md: documentation index and source-of-truth notes.
- docs/AgentHub-HiClaw-lite开源内核重构方案.md: HiClaw-lite kernel design.
- docs/使用指南.md: product usage guide.
- SECURITY.md: security model and vulnerability reporting.
Contributing
Before changing runtime, Room, task, artifact, or Controller behavior, read AGENTS.md. Core rules:
- Identify the layer you are touching.
- Treat Room timeline and resource state as the source of truth.
- Keep Manager / Worker runtime boundaries explicit.
- Do not restore DAG-first, template-first, or local fake-transport paths.
- Add focused tests for projection, lifecycle, failure visibility, and boundary conditions.
Recommended checks:
bun run typecheck
bun test
Security
AgentHub can run local CLIs, read and write workspaces, and access Matrix tokens, model keys, and generated artifacts. Do not commit:
.env- model provider keys
- Matrix access tokens
- local CLI auth files
- database files
- generated workspaces
- runtime logs or diagnostics containing secrets
Use disposable workspaces, scoped provider keys, and stronger sandboxing when running untrusted prompts, repositories, or generated code.
License
AgentHub is released under the MIT License.