# swsgbl/hmharness architecture

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

- Interactive diagram: https://gitdiagram.com/swsgbl/hmharness
- Repository: https://github.com/swsgbl/hmharness

## Overview

hmharness is a HarmonyOS-focused, self-evolving agent framework. A user starts work through the CLI/REPL, TUI, or Web UI; the agent runs a tool-using kernel loop, records a session, and returns results. Harmony development spans project creation, build, device install/launch/logs, with emulator and Cangjie/lint capabilities. Separate evolution workflows use insights, skill candidates, benchmark gates, promotion/rollback, and memory distillation; ops scans ecosystem sources and produces briefs. Paths and links reflect the README and sampled code; unsampled subsystem wiring is omitted where it cannot be established.

Main entry points: [`packages/kernel/src/loop.ts`](https://github.com/swsgbl/hmharness/blob/main/packages/kernel/src/loop.ts) (Agent loop), [`packages/domain-harmony/src/index.ts`](https://github.com/swsgbl/hmharness/blob/main/packages/domain-harmony/src/index.ts) (Harmony toolchain), [`packages/agent/src/runner.ts`](https://github.com/swsgbl/hmharness/blob/main/packages/agent/src/runner.ts) (Agent runner), [`packages/cli/src/main.ts`](https://github.com/swsgbl/hmharness/blob/main/packages/cli/src/main.ts) (CLI and REPL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontends["User interfaces"]
  node_cli["CLI and REPL<br/>[main.ts]"]
  node_tui["Full-screen TUI<br/>[tui.ts]"]
  node_web["Web interface<br/>[server.ts]"]
  node_mcp_server["MCP server<br/>[mcp-server.ts]"]
end

subgraph group_runtime["Agent runtime"]
  node_agent_runner["Agent runner<br/>[runner.ts]"]
  node_agent_tools["Agent tools<br/>[tools.ts]"]
  node_agent_pipeline["Staged pipeline<br/>[pipeline.ts]"]
  node_kernel_loop["Agent loop<br/>[loop.ts]"]
  node_router["Model routing<br/>[router.ts]"]
  node_session[("Session history<br/>[session.ts]")]
  node_approval["Approval gate<br/>[shellgate.ts]"]
end

subgraph group_harmony["Harmony development"]
  node_harmony_tools["Harmony toolchain<br/>[index.ts]"]
  node_harmony_project["Project scaffolding<br/>[project.ts]"]
  node_harmony_device["Device lifecycle<br/>[index.ts]"]
  node_harmony_emulator["Emulator management<br/>[emulator.ts]"]
  node_harmony_checks["Cangjie and lint<br/>[cangjie.ts]"]
end

subgraph group_improvement["Evolution and evaluation"]
  node_evolution["Evolution cycle<br/>[evolve.ts]"]
  node_skills_memory[("Skills and memory<br/>[skills.ts]")]
  node_evaluation["Benchmark gates<br/>[harmonybench.ts]"]
  node_observability["Run observability<br/>[recorder.ts]"]
end

subgraph group_integrations["External integrations"]
  node_provider["Model provider<br/>[provider.ts]"]
  node_ops["Ecosystem radar<br/>[index.ts]"]
end

node_user(("User"))
node_mcp_host(("MCP host"))
node_device(("Device or emulator"))
node_ecosystem(("Release sources"))

node_user -->|"submits task"| node_cli
node_user -->|"submits task"| node_tui
node_user -->|"submits task"| node_web
node_cli -->|"runs task"| node_agent_runner
node_tui -->|"runs task"| node_agent_runner
node_web -->|"starts agent"| node_agent_runner
node_agent_runner -->|"runs loop"| node_kernel_loop
node_kernel_loop -->|"requests completion"| node_provider
node_kernel_loop -->|"dispatches tools"| node_agent_tools
node_kernel_loop -->|"routes requests"| node_router
node_kernel_loop -->|"appends audit"| node_session
node_kernel_loop -->|"checks approval"| node_approval
node_agent_runner -->|"runs staged work"| node_agent_pipeline
node_agent_tools -->|"invokes domain tools"| node_harmony_tools
node_harmony_tools -->|"creates projects"| node_harmony_project
node_harmony_tools -->|"builds and operates"| node_harmony_device
node_harmony_tools -->|"manages emulator"| node_harmony_emulator
node_harmony_tools -->|"runs checks"| node_harmony_checks
node_harmony_device -->|"installs and launches"| node_device
node_cli -->|"starts evolution"| node_evolution
node_evolution -->|"updates skills and memory"| node_skills_memory
node_evolution -->|"gates candidates"| node_evaluation
node_cli -->|"runs benchmarks"| node_evaluation
node_agent_runner -.->|"records runs"| node_observability
node_cli -->|"runs ops commands"| node_ops
node_ops -->|"fetches release data"| node_ecosystem
node_mcp_host -->|"calls tools"| node_mcp_server
node_mcp_server -->|"exposes Harmony tools"| node_harmony_tools

click node_cli "https://github.com/swsgbl/hmharness/blob/main/packages/cli/src/main.ts"
click node_tui "https://github.com/swsgbl/hmharness/blob/main/packages/cli/src/tui.ts"
click node_web "https://github.com/swsgbl/hmharness/blob/main/packages/web/src/server.ts"
click node_mcp_server "https://github.com/swsgbl/hmharness/blob/main/packages/cli/src/mcp-server.ts"
click node_agent_runner "https://github.com/swsgbl/hmharness/blob/main/packages/agent/src/runner.ts"
click node_agent_tools "https://github.com/swsgbl/hmharness/blob/main/packages/agent/src/tools.ts"
click node_agent_pipeline "https://github.com/swsgbl/hmharness/blob/main/packages/agent/src/pipeline.ts"
click node_kernel_loop "https://github.com/swsgbl/hmharness/blob/main/packages/kernel/src/loop.ts"
click node_provider "https://github.com/swsgbl/hmharness/blob/main/packages/kernel/src/provider.ts"
click node_router "https://github.com/swsgbl/hmharness/blob/main/packages/kernel/src/router.ts"
click node_session "https://github.com/swsgbl/hmharness/blob/main/packages/kernel/src/session.ts"
click node_approval "https://github.com/swsgbl/hmharness/blob/main/packages/kernel/src/shellgate.ts"
click node_harmony_tools "https://github.com/swsgbl/hmharness/blob/main/packages/domain-harmony/src/index.ts"
click node_harmony_project "https://github.com/swsgbl/hmharness/blob/main/packages/domain-harmony/src/project.ts"
click node_harmony_device "https://github.com/swsgbl/hmharness/blob/main/packages/domain-harmony/src/index.ts"
click node_harmony_emulator "https://github.com/swsgbl/hmharness/blob/main/packages/domain-harmony/src/emulator.ts"
click node_harmony_checks "https://github.com/swsgbl/hmharness/blob/main/packages/domain-harmony/src/cangjie.ts"
click node_evolution "https://github.com/swsgbl/hmharness/blob/main/packages/evolution/src/evolve.ts"
click node_skills_memory "https://github.com/swsgbl/hmharness/blob/main/packages/evolution/src/skills.ts"
click node_evaluation "https://github.com/swsgbl/hmharness/blob/main/packages/evaluation/src/harmonybench.ts"
click node_observability "https://github.com/swsgbl/hmharness/blob/main/packages/observability/src/recorder.ts"
click node_ops "https://github.com/swsgbl/hmharness/blob/main/packages/domain-ops/src/index.ts"

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_tui,node_web,node_mcp_server,node_user toneBlue
class node_agent_runner,node_agent_tools,node_agent_pipeline,node_kernel_loop,node_router,node_session,node_approval toneAmber
class node_harmony_tools,node_harmony_project,node_harmony_device,node_harmony_emulator,node_harmony_checks toneMint
class node_evolution,node_skills_memory,node_evaluation,node_observability toneRose
class node_provider,node_ops,node_mcp_host,node_device,node_ecosystem toneIndigo
```

## Components

### User interfaces

- [CLI and REPL](https://github.com/swsgbl/hmharness/blob/main/packages/cli/src/main.ts): `packages/cli/src/main.ts`
- [Full-screen TUI](https://github.com/swsgbl/hmharness/blob/main/packages/cli/src/tui.ts): `packages/cli/src/tui.ts`
- [Web interface](https://github.com/swsgbl/hmharness/blob/main/packages/web/src/server.ts): `packages/web/src/server.ts`
- [MCP server](https://github.com/swsgbl/hmharness/blob/main/packages/cli/src/mcp-server.ts): `packages/cli/src/mcp-server.ts`

### Agent runtime

- [Agent runner](https://github.com/swsgbl/hmharness/blob/main/packages/agent/src/runner.ts): `packages/agent/src/runner.ts`
- [Agent tools](https://github.com/swsgbl/hmharness/blob/main/packages/agent/src/tools.ts): `packages/agent/src/tools.ts`
- [Staged pipeline](https://github.com/swsgbl/hmharness/blob/main/packages/agent/src/pipeline.ts): `packages/agent/src/pipeline.ts`
- [Agent loop](https://github.com/swsgbl/hmharness/blob/main/packages/kernel/src/loop.ts): `packages/kernel/src/loop.ts`
- [Model routing](https://github.com/swsgbl/hmharness/blob/main/packages/kernel/src/router.ts): `packages/kernel/src/router.ts`
- [Session history](https://github.com/swsgbl/hmharness/blob/main/packages/kernel/src/session.ts): `packages/kernel/src/session.ts`
- [Approval gate](https://github.com/swsgbl/hmharness/blob/main/packages/kernel/src/shellgate.ts): `packages/kernel/src/shellgate.ts`

### Harmony development

- [Harmony toolchain](https://github.com/swsgbl/hmharness/blob/main/packages/domain-harmony/src/index.ts): `packages/domain-harmony/src/index.ts`
- [Project scaffolding](https://github.com/swsgbl/hmharness/blob/main/packages/domain-harmony/src/project.ts): `packages/domain-harmony/src/project.ts`
- [Device lifecycle](https://github.com/swsgbl/hmharness/blob/main/packages/domain-harmony/src/index.ts): `packages/domain-harmony/src/index.ts`
- [Emulator management](https://github.com/swsgbl/hmharness/blob/main/packages/domain-harmony/src/emulator.ts): `packages/domain-harmony/src/emulator.ts`
- [Cangjie and lint](https://github.com/swsgbl/hmharness/blob/main/packages/domain-harmony/src/cangjie.ts): `packages/domain-harmony/src/cangjie.ts`

### Evolution and evaluation

- [Evolution cycle](https://github.com/swsgbl/hmharness/blob/main/packages/evolution/src/evolve.ts): `packages/evolution/src/evolve.ts`
- [Skills and memory](https://github.com/swsgbl/hmharness/blob/main/packages/evolution/src/skills.ts): `packages/evolution/src/skills.ts`
- [Benchmark gates](https://github.com/swsgbl/hmharness/blob/main/packages/evaluation/src/harmonybench.ts): `packages/evaluation/src/harmonybench.ts`
- [Run observability](https://github.com/swsgbl/hmharness/blob/main/packages/observability/src/recorder.ts): `packages/observability/src/recorder.ts`

### External integrations

- [Model provider](https://github.com/swsgbl/hmharness/blob/main/packages/kernel/src/provider.ts): `packages/kernel/src/provider.ts`
- [Ecosystem radar](https://github.com/swsgbl/hmharness/blob/main/packages/domain-ops/src/index.ts): `packages/domain-ops/src/index.ts`

### Other components

- **User**
- **MCP host**
- **Device or emulator**
- **Release sources**

## Connections

- User → CLI and REPL: submits task
- User → Full-screen TUI: submits task
- User → Web interface: submits task
- CLI and REPL → Agent runner: runs task
- Full-screen TUI → Agent runner: runs task
- Web interface → Agent runner: starts agent
- Agent runner → Agent loop: runs loop
- Agent loop → Model provider: requests completion
- Agent loop → Agent tools: dispatches tools
- Agent loop → Model routing: routes requests
- Agent loop → Session history: appends audit
- Agent loop → Approval gate: checks approval
- Agent runner → Staged pipeline: runs staged work
- Agent tools → Harmony toolchain: invokes domain tools
- Harmony toolchain → Project scaffolding: creates projects
- Harmony toolchain → Device lifecycle: builds and operates
- Harmony toolchain → Emulator management: manages emulator
- Harmony toolchain → Cangjie and lint: runs checks
- Device lifecycle → Device or emulator: installs and launches
- CLI and REPL → Evolution cycle: starts evolution
- Evolution cycle → Skills and memory: updates skills and memory
- Evolution cycle → Benchmark gates: gates candidates
- CLI and REPL → Benchmark gates: runs benchmarks
- Agent runner → Run observability: records runs
- CLI and REPL → Ecosystem radar: runs ops commands
- Ecosystem radar → Release sources: fetches release data
- MCP host → MCP server: calls tools
- MCP server → Harmony toolchain: exposes Harmony tools