# agentscope-ai/hiclaw architecture

> Architecture diagram of the GitHub repository agentscope-ai/hiclaw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agentscope-ai/hiclaw
- Repository: https://github.com/agentscope-ai/hiclaw

## Overview

AgentTeams is a Kubernetes-native multi-agent control plane: people and automation declare Teams and Workers, the controller reconciles their infrastructure and runtime configuration, and agents collaborate through Matrix, shared storage, and task/project workflows. The graph includes the documented QwenPaw, CoPaw, and Hermes worker runtimes plus TeamHarness integrations. Evidence is limited to the README, source index references, and the supplied excerpts; unsampled subsystem links are omitted or marked unverified.

Main entry points: [`agentteams-controller/internal/backend`](https://github.com/agentscope-ai/hiclaw/tree/main/agentteams-controller/internal/backend) (Container backends), [`agentteams-controller/internal/matrix`](https://github.com/agentscope-ai/hiclaw/tree/main/agentteams-controller/internal/matrix) (Matrix services), [`qwenpaw/src/qwenpaw_worker/worker.py`](https://github.com/agentscope-ai/hiclaw/blob/main/qwenpaw/src/qwenpaw_worker/worker.py) (QwenPaw worker), [`copaw/src/copaw_worker/worker.py`](https://github.com/agentscope-ai/hiclaw/blob/main/copaw/src/copaw_worker/worker.py) (CoPaw worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_cli["agt CLI<br/>[main.go]"]
  node_crds["Team and Worker APIs<br/>[types.go]"]
  node_controller["Controller application<br/>[app.go]"]
  node_teamrec["Team reconciliation<br/>[team_controller.go]"]
  node_workerrec["Worker reconciliation"]
  node_backend["Container backends"]
  node_http["Controller HTTP API<br/>[http.go]"]
  node_projects["Project workflows<br/>[project_handler.go]"]
end

subgraph group_services["Runtime services"]
  node_storage[("Shared object storage")]
  node_gateway["AI gateway"]
  node_matrix["Matrix services"]
  node_agentloop["AgentLoop observability"]
end

subgraph group_workers["Worker runtimes"]
  node_qwen["QwenPaw worker<br/>[worker.py]"]
  node_copaw["CoPaw worker<br/>[worker.py]"]
  node_hermes["Hermes worker<br/>[worker.py]"]
end

subgraph group_extensions["Collaboration extensions"]
  node_teamharness["TeamHarness MCP<br/>[server.py]"]
  node_workerflow["WorkerFlow MCP<br/>[server.py]"]
  node_plugincli["Plugin manager CLI<br/>[main.py]"]
  node_pluginmanager["Plugin installation<br/>[plugin_manager.py]"]
end

node_users(("Users and operators"))

node_users -->|"manage resources"| node_cli
node_cli -.->|"declare resources"| node_crds
node_users -->|"call APIs"| node_http
node_http -.->|"routes workflow requests"| node_projects
node_controller -->|"registers reconciliation"| node_teamrec
node_controller -->|"registers reconciliation"| node_workerrec
node_teamrec -->|"uses runtime backend"| node_backend
node_workerrec -->|"reconciles deployment"| node_backend
node_teamrec -->|"reads Team resources"| node_crds
node_workerrec -->|"reads Worker resources"| node_crds
node_backend -.->|"runs worker runtime"| node_qwen
node_backend -.->|"runs worker runtime"| node_copaw
node_backend -.->|"runs worker runtime"| node_hermes
node_qwen -->|"syncs shared files"| node_storage
node_copaw -->|"syncs shared files"| node_storage
node_hermes -->|"syncs shared files"| node_storage
node_qwen -->|"collaborates through Matrix"| node_matrix
node_copaw -->|"collaborates through Matrix"| node_matrix
node_hermes -->|"collaborates through Matrix"| node_matrix
node_gateway -.->|"routes model traffic"| node_qwen
node_gateway -.->|"routes model traffic"| node_copaw
node_gateway -.->|"routes model traffic"| node_hermes
node_teamharness -.->|"uses room workflows"| node_matrix
node_workerflow -.->|"supports worker workflows"| node_matrix
node_users -->|"manage plugins"| node_plugincli
node_plugincli -->|"dispatches plugin actions"| node_pluginmanager
node_controller -.->|"integrates observability"| node_agentloop
node_http -.->|"serves storage-backed APIs"| node_storage

click node_cli "https://github.com/agentscope-ai/hiclaw/blob/main/agentteams-controller/cmd/agt/main.go"
click node_crds "https://github.com/agentscope-ai/hiclaw/blob/main/agentteams-controller/api/v1beta1/types.go"
click node_controller "https://github.com/agentscope-ai/hiclaw/blob/main/agentteams-controller/internal/app/app.go"
click node_teamrec "https://github.com/agentscope-ai/hiclaw/blob/main/agentteams-controller/internal/controller/team_controller.go"
click node_workerrec "https://github.com/agentscope-ai/hiclaw/blob/main/agentteams-controller/internal/controller/worker_controller.go"
click node_backend "https://github.com/agentscope-ai/hiclaw/tree/main/agentteams-controller/internal/backend"
click node_http "https://github.com/agentscope-ai/hiclaw/blob/main/agentteams-controller/internal/server/http.go"
click node_projects "https://github.com/agentscope-ai/hiclaw/blob/main/agentteams-controller/internal/server/project_handler.go"
click node_storage "https://github.com/agentscope-ai/hiclaw/tree/main/agentteams-controller/internal/oss"
click node_gateway "https://github.com/agentscope-ai/hiclaw/tree/main/agentteams-controller/internal/gateway"
click node_matrix "https://github.com/agentscope-ai/hiclaw/tree/main/agentteams-controller/internal/matrix"
click node_qwen "https://github.com/agentscope-ai/hiclaw/blob/main/qwenpaw/src/qwenpaw_worker/worker.py"
click node_copaw "https://github.com/agentscope-ai/hiclaw/blob/main/copaw/src/copaw_worker/worker.py"
click node_hermes "https://github.com/agentscope-ai/hiclaw/blob/main/hermes/src/hermes_worker/worker.py"
click node_teamharness "https://github.com/agentscope-ai/hiclaw/blob/main/plugins/teamharness/mcp/server.py"
click node_workerflow "https://github.com/agentscope-ai/hiclaw/blob/main/plugins/workerflow/mcp/server.py"
click node_plugincli "https://github.com/agentscope-ai/hiclaw/blob/main/plugins/cli/src/agentteams_cli/main.py"
click node_pluginmanager "https://github.com/agentscope-ai/hiclaw/blob/main/plugins/cli/src/agentteams_cli/plugin_manager.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_crds,node_controller,node_teamrec,node_workerrec,node_backend,node_http,node_projects,node_users toneBlue
class node_storage,node_gateway,node_matrix,node_agentloop toneAmber
class node_qwen,node_copaw,node_hermes toneMint
class node_teamharness,node_workerflow,node_plugincli,node_pluginmanager toneRose
```

## Components

### Control plane

- [agt CLI](https://github.com/agentscope-ai/hiclaw/blob/main/agentteams-controller/cmd/agt/main.go): `agentteams-controller/cmd/agt/main.go`
- [Team and Worker APIs](https://github.com/agentscope-ai/hiclaw/blob/main/agentteams-controller/api/v1beta1/types.go): `agentteams-controller/api/v1beta1/types.go`
- [Controller application](https://github.com/agentscope-ai/hiclaw/blob/main/agentteams-controller/internal/app/app.go): `agentteams-controller/internal/app/app.go`
- [Team reconciliation](https://github.com/agentscope-ai/hiclaw/blob/main/agentteams-controller/internal/controller/team_controller.go): `agentteams-controller/internal/controller/team_controller.go`
- [Worker reconciliation](https://github.com/agentscope-ai/hiclaw/blob/main/agentteams-controller/internal/controller/worker_controller.go): `agentteams-controller/internal/controller/worker_controller.go`
- [Container backends](https://github.com/agentscope-ai/hiclaw/tree/main/agentteams-controller/internal/backend): `agentteams-controller/internal/backend`
- [Controller HTTP API](https://github.com/agentscope-ai/hiclaw/blob/main/agentteams-controller/internal/server/http.go): `agentteams-controller/internal/server/http.go`
- [Project workflows](https://github.com/agentscope-ai/hiclaw/blob/main/agentteams-controller/internal/server/project_handler.go): `agentteams-controller/internal/server/project_handler.go`

### Runtime services

- [Shared object storage](https://github.com/agentscope-ai/hiclaw/tree/main/agentteams-controller/internal/oss): `agentteams-controller/internal/oss`
- [AI gateway](https://github.com/agentscope-ai/hiclaw/tree/main/agentteams-controller/internal/gateway): `agentteams-controller/internal/gateway`
- [Matrix services](https://github.com/agentscope-ai/hiclaw/tree/main/agentteams-controller/internal/matrix): `agentteams-controller/internal/matrix`
- **AgentLoop observability**

### Worker runtimes

- [QwenPaw worker](https://github.com/agentscope-ai/hiclaw/blob/main/qwenpaw/src/qwenpaw_worker/worker.py): `qwenpaw/src/qwenpaw_worker/worker.py`
- [CoPaw worker](https://github.com/agentscope-ai/hiclaw/blob/main/copaw/src/copaw_worker/worker.py): `copaw/src/copaw_worker/worker.py`
- [Hermes worker](https://github.com/agentscope-ai/hiclaw/blob/main/hermes/src/hermes_worker/worker.py): `hermes/src/hermes_worker/worker.py`

### Collaboration extensions

- [TeamHarness MCP](https://github.com/agentscope-ai/hiclaw/blob/main/plugins/teamharness/mcp/server.py): `plugins/teamharness/mcp/server.py`
- [WorkerFlow MCP](https://github.com/agentscope-ai/hiclaw/blob/main/plugins/workerflow/mcp/server.py): `plugins/workerflow/mcp/server.py`
- [Plugin manager CLI](https://github.com/agentscope-ai/hiclaw/blob/main/plugins/cli/src/agentteams_cli/main.py): `plugins/cli/src/agentteams_cli/main.py`
- [Plugin installation](https://github.com/agentscope-ai/hiclaw/blob/main/plugins/cli/src/agentteams_cli/plugin_manager.py): `plugins/cli/src/agentteams_cli/plugin_manager.py`

### Other components

- **Users and operators**

## Connections

- Users and operators → agt CLI: manage resources (evidence: `README.md`)
- agt CLI → Team and Worker APIs: declare resources
- Users and operators → Controller HTTP API: call APIs (evidence: `README.md`)
- Controller HTTP API → Project workflows: routes workflow requests
- Controller application → Team reconciliation: registers reconciliation (evidence: `agentteams-controller/internal/app/app.go`)
- Controller application → Worker reconciliation: registers reconciliation (evidence: `agentteams-controller/internal/app/app.go`)
- Team reconciliation → Container backends: uses runtime backend (evidence: `agentteams-controller/internal/controller/team_controller.go`)
- Worker reconciliation → Container backends: reconciles deployment (evidence: `agentteams-controller/internal/controller/worker_controller.go`)
- Team reconciliation → Team and Worker APIs: reads Team resources (evidence: `agentteams-controller/internal/controller/team_controller.go`)
- Worker reconciliation → Team and Worker APIs: reads Worker resources (evidence: `agentteams-controller/internal/controller/worker_controller.go`)
- Container backends → QwenPaw worker: runs worker runtime
- Container backends → CoPaw worker: runs worker runtime
- Container backends → Hermes worker: runs worker runtime
- QwenPaw worker → Shared object storage: syncs shared files (evidence: `README.md`)
- CoPaw worker → Shared object storage: syncs shared files (evidence: `README.md`)
- Hermes worker → Shared object storage: syncs shared files (evidence: `README.md`)
- QwenPaw worker → Matrix services: collaborates through Matrix (evidence: `README.md`)
- CoPaw worker → Matrix services: collaborates through Matrix (evidence: `README.md`)
- Hermes worker → Matrix services: collaborates through Matrix (evidence: `README.md`)
- AI gateway → QwenPaw worker: routes model traffic
- AI gateway → CoPaw worker: routes model traffic
- AI gateway → Hermes worker: routes model traffic
- TeamHarness MCP → Matrix services: uses room workflows
- WorkerFlow MCP → Matrix services: supports worker workflows
- Users and operators → Plugin manager CLI: manage plugins (evidence: `README.md`)
- Plugin manager CLI → Plugin installation: dispatches plugin actions (evidence: `plugins/cli/src/agentteams_cli/main.py`)
- Controller application → AgentLoop observability: integrates observability (evidence: `README.md`)
- Controller HTTP API → Shared object storage: serves storage-backed APIs