# hkuds/openharness architecture

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

- Interactive diagram: https://gitdiagram.com/hkuds/openharness
- Repository: https://github.com/hkuds/openharness
- Video tour (about a minute): https://gitdiagram.com/hkuds/openharness/video

## Overview

#### Purpose and Entry Points
OpenHarness is a Python agent harness for LLM-driven coding and automation: provider access, iterative tool use, memory, permissions, extensions, and multi-agent work. Its primary CLI entry points are `src/openharness/__main__.py` and `src/openharness/cli.py`. `ohmo` is a personal-agent application layered over this harness, entered through `ohmo/__main__.py` and `ohmo/cli.py`, with chat-channel gateway support.

#### Runtime Assembly and UI Boundary
The UI/runtime layer builds and owns interactive sessions, selecting either a React terminal frontend or Textual-based interface. The Python backend exposes a protocol/session host to the TypeScript terminal client, separating model/tool execution from rendering and input handling.
- `src/openharness/ui/runtime.py`
- `src/openharness/ui/backend_host.py`
- `frontend/terminal/src/App.tsx`

Headless CLI operation supports text, JSON, and stream-JSON outputs, using the same underlying runtime rather than a separate automation engine.

#### Model Provider and Authentication Layer
Provider abstraction normalizes Anthropic-compatible, OpenAI-compatible, Codex, Copilot, and subscription-backed clients behind a registry/client boundary. Auth flows and persistent credential storage are separate from request execution, allowing named provider profiles and switching without changing agent-loop code.
- `src/openharness/api/registry.py`
- `src/openharness/api/client.py`
- `src/openharness/auth/manager.py`

External dependencies include remote LLM APIs, local Claude/Codex credential files, and GitHub Copilot OAuth. Compatible endpoints can include hosted providers or local Ollama.

#### Agent Execution Loop
`QueryEngine` is the central control loop: it assembles messages and tool schemas, streams model responses, detects tool-use turns, executes calls, appends results, and repeats until completion. It also owns message/event handling and cost tracking boundaries.
- `src/openharness/engine/query_engine.py`
- `src/openharness/engine/query.py`
- `src/openharness/engine/stream_events.py`

The critical flow is: prompt/session context → provider stream → requested tool calls → guarded execution/results → next model turn. Streaming events feed both terminal UI and machine-readable output modes.

#### Tool, Safety, and Extension Boundary
Tools implement the agent’s side effects: filesystem, shell, web, MCP, tasks, teams, scheduling, and user interaction. Permission checking gates execution, while lifecycle hooks can inspect or modify pre/post-tool behavior. This is the primary trust boundary for writes, commands, network access, and project-provided extensions.
- `src/openharness/tools/base.py`
- `src/openharness/permissions/checker.py`
- `src/openharness/hooks/executor.py`

Skills, plugins, slash commands, and output styles are loaded dynamically and contribute instructions, commands, hooks, agents, and MCP configuration without modifying the core engine.
- `src/openharness/skills/loader.py`
- `src/openharness/plugins/loader.py`
- `src/openharness/commands/registry.py`

#### Context, Persistence, and MCP
Prompt construction combines system instructions, environment/project context, discovered `CLAUDE.md` content, skills, and memory. Session storage supports resume/history; memory services maintain persistent and relevance-selected knowledge across sessions. MCP is an external-tool boundary supporting stdio and HTTP servers, resource reads, authentication, reconnect behavior, and schema-derived tools.
- `src/openharness/prompts/system_prompt.py`
- `src/openharness/memory/manager.py`
- `src/openharness/mcp/client.py`

#### Coordination and ohmo Gateway
OpenHarness can delegate work to in-process or subprocess agents, organize teams, synchronize permissions, manage mailboxes, and isolate work through git worktrees. `ohmo` converts channel messages into harness sessions through a gateway/router, then sends resulting responses and notifications back to configured chat platforms.
- `src/openharness/swarm/team_lifecycle.py`
- `src/openharness/swarm/subprocess_backend.py`
- `ohmo/gateway/router.py`

Channel adapters include Telegram, Slack, Discord, Feishu, email, WhatsApp, Matrix, and others; the channel bus decouples inbound events from gateway processing.
- `src/openharness/channels/adapter.py`
- `src/openharness/channels/bus/queue.py`
- `ohmo/gateway/service.py`

Main entry points: [`src/openharness/engine/query_engine.py`](https://github.com/hkuds/openharness/blob/main/src/openharness/engine/query_engine.py) (QueryEngine), [`src/openharness/tools/base.py`](https://github.com/hkuds/openharness/blob/main/src/openharness/tools/base.py) (Tool execution), [`src/openharness/ui/runtime.py`](https://github.com/hkuds/openharness/blob/main/src/openharness/ui/runtime.py) (UI runtime), [`ohmo/gateway/router.py`](https://github.com/hkuds/openharness/blob/main/ohmo/gateway/router.py) (ohmo gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry &amp; UI"]
  node_openharness_cli["OpenHarness CLI<br/>Python entrypoints<br/>[cli.py]"]
  node_ui_runtime["UI runtime<br/>session assembly<br/>[runtime.py]"]
  node_backend_host["Backend host<br/>protocol host<br/>[backend_host.py]"]
  node_terminal_frontend["Terminal frontend<br/>React client<br/>[App.tsx]"]
end

subgraph group_core["Agent Core"]
  node_query_engine{{"QueryEngine<br/>agent control loop<br/>[query_engine.py]"}}
  node_query_context["Query &amp; stream events<br/>message pipeline<br/>[query.py]"]
  node_prompt_builder["Prompt construction<br/>context assembly<br/>[system_prompt.py]"]
  node_memory[("Memory &amp; sessions<br/>persistent context<br/>[manager.py]")]
  node_swarm["Swarm coordination<br/>multi-agent runtime<br/>[team_lifecycle.py]"]
end

subgraph group_trust["Tools &amp; Extensions"]
  node_tool_base{{"Tool execution<br/>side-effect tools<br/>[base.py]"}}
  node_permission_checker["Permission checker<br/>execution guard<br/>[checker.py]"]
  node_hook_executor["Lifecycle hooks<br/>tool interception<br/>[executor.py]"]
  node_extensions["Dynamic extensions<br/>skills, plugins &amp; commands<br/>[loader.py]"]
end

subgraph group_integration["Providers &amp; MCP"]
  node_provider_registry["Provider registry<br/>provider selection<br/>[registry.py]"]
  node_provider_client["Provider client<br/>LLM transport<br/>[client.py]"]
  node_auth_manager[("Auth manager<br/>credentials<br/>[manager.py]")]
  node_remote_llms(("LLM providers<br/>external APIs"))
  node_mcp_client["MCP client<br/>external tool bridge<br/>[client.py]"]
end

subgraph group_ohmo["ohmo Gateway"]
  node_ohmo_gateway["ohmo gateway<br/>channel session router<br/>[router.py]"]
  node_channel_bus["Channel bus<br/>event queue<br/>[queue.py]"]
  node_chat_channels(("Chat platforms<br/>external channels"))
end

node_openharness_cli -->|"starts interactive session"| node_ui_runtime
node_openharness_cli -->|"runs headless queries"| node_query_engine
node_ui_runtime -->|"hosts protocol session"| node_backend_host
node_backend_host -->|"protocol events and input"| node_terminal_frontend
node_ui_runtime -->|"drives session"| node_query_engine
node_query_engine -->|"emits stream events"| node_query_context
node_query_engine -->|"assembles turn context"| node_prompt_builder
node_prompt_builder -->|"retrieves context"| node_memory
node_query_engine -->|"selects provider"| node_provider_registry
node_provider_registry -->|"creates client"| node_provider_client
node_auth_manager -->|"supplies credentials"| node_provider_client
node_provider_client -->|"streams requests"| node_remote_llms
node_query_engine -->|"executes model tool calls"| node_tool_base
node_tool_base -->|"checks before execution"| node_permission_checker
node_hook_executor -.->|"intercepts lifecycle"| node_tool_base
node_extensions -.->|"contributes instructions"| node_prompt_builder
node_extensions -.->|"registers hooks"| node_hook_executor
node_mcp_client -->|"exposes external tools"| node_tool_base
node_query_engine -->|"delegates work"| node_swarm
node_chat_channels -->|"inbound events"| node_channel_bus
node_channel_bus -->|"routes messages"| node_ohmo_gateway
node_ohmo_gateway -->|"creates harness sessions"| node_query_engine
node_ohmo_gateway -->|"responses and notifications"| node_chat_channels

click node_openharness_cli "https://github.com/hkuds/openharness/blob/main/src/openharness/cli.py"
click node_ui_runtime "https://github.com/hkuds/openharness/blob/main/src/openharness/ui/runtime.py"
click node_backend_host "https://github.com/hkuds/openharness/blob/main/src/openharness/ui/backend_host.py"
click node_terminal_frontend "https://github.com/hkuds/openharness/blob/main/frontend/terminal/src/App.tsx"
click node_query_engine "https://github.com/hkuds/openharness/blob/main/src/openharness/engine/query_engine.py"
click node_query_context "https://github.com/hkuds/openharness/blob/main/src/openharness/engine/query.py"
click node_prompt_builder "https://github.com/hkuds/openharness/blob/main/src/openharness/prompts/system_prompt.py"
click node_memory "https://github.com/hkuds/openharness/blob/main/src/openharness/memory/manager.py"
click node_provider_registry "https://github.com/hkuds/openharness/blob/main/src/openharness/api/registry.py"
click node_provider_client "https://github.com/hkuds/openharness/blob/main/src/openharness/api/client.py"
click node_auth_manager "https://github.com/hkuds/openharness/blob/main/src/openharness/auth/manager.py"
click node_tool_base "https://github.com/hkuds/openharness/blob/main/src/openharness/tools/base.py"
click node_permission_checker "https://github.com/hkuds/openharness/blob/main/src/openharness/permissions/checker.py"
click node_hook_executor "https://github.com/hkuds/openharness/blob/main/src/openharness/hooks/executor.py"
click node_extensions "https://github.com/hkuds/openharness/blob/main/src/openharness/skills/loader.py"
click node_mcp_client "https://github.com/hkuds/openharness/blob/main/src/openharness/mcp/client.py"
click node_swarm "https://github.com/hkuds/openharness/blob/main/src/openharness/swarm/team_lifecycle.py"
click node_ohmo_gateway "https://github.com/hkuds/openharness/blob/main/ohmo/gateway/router.py"
click node_channel_bus "https://github.com/hkuds/openharness/blob/main/src/openharness/channels/bus/queue.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_openharness_cli,node_ui_runtime,node_backend_host,node_terminal_frontend toneBlue
class node_query_engine,node_query_context,node_prompt_builder,node_memory,node_swarm toneAmber
class node_tool_base,node_permission_checker,node_hook_executor,node_extensions toneMint
class node_provider_registry,node_provider_client,node_auth_manager,node_remote_llms,node_mcp_client toneRose
class node_ohmo_gateway,node_channel_bus,node_chat_channels toneIndigo
```

## Components

### Entry & UI

- [OpenHarness CLI](https://github.com/hkuds/openharness/blob/main/src/openharness/cli.py): Python entrypoints · Interactive and headless text, JSON, and stream-JSON modes. · `src/openharness/cli.py`
- [UI runtime](https://github.com/hkuds/openharness/blob/main/src/openharness/ui/runtime.py): session assembly · Selects and owns interactive runtime sessions. · `src/openharness/ui/runtime.py`
- [Backend host](https://github.com/hkuds/openharness/blob/main/src/openharness/ui/backend_host.py): protocol host · Session protocol boundary for the terminal client. · `src/openharness/ui/backend_host.py`
- [Terminal frontend](https://github.com/hkuds/openharness/blob/main/frontend/terminal/src/App.tsx): React client · `frontend/terminal/src/App.tsx`

### Agent Core

- [QueryEngine](https://github.com/hkuds/openharness/blob/main/src/openharness/engine/query_engine.py): agent control loop · Streams model turns, executes requested tools, and repeats to completion. · `src/openharness/engine/query_engine.py`
- [Query & stream events](https://github.com/hkuds/openharness/blob/main/src/openharness/engine/query.py): message pipeline · Carries query state and streaming events to output consumers. · `src/openharness/engine/query.py`
- [Prompt construction](https://github.com/hkuds/openharness/blob/main/src/openharness/prompts/system_prompt.py): context assembly · Combines system, project, skill, and memory context. · `src/openharness/prompts/system_prompt.py`
- [Memory & sessions](https://github.com/hkuds/openharness/blob/main/src/openharness/memory/manager.py): persistent context · Maintains resumable history and relevance-selected knowledge. · `src/openharness/memory/manager.py`
- [Swarm coordination](https://github.com/hkuds/openharness/blob/main/src/openharness/swarm/team_lifecycle.py): multi-agent runtime · Delegates to agents and coordinates teams, mailboxes, permissions, and worktrees. · `src/openharness/swarm/team_lifecycle.py`

### Tools & Extensions

- [Tool execution](https://github.com/hkuds/openharness/blob/main/src/openharness/tools/base.py): side-effect tools · Filesystem, shell, web, task, team, scheduling, and interaction tools. · `src/openharness/tools/base.py`
- [Permission checker](https://github.com/hkuds/openharness/blob/main/src/openharness/permissions/checker.py): execution guard · Trust boundary for commands, writes, network access, and extensions. · `src/openharness/permissions/checker.py`
- [Lifecycle hooks](https://github.com/hkuds/openharness/blob/main/src/openharness/hooks/executor.py): tool interception · Runs pre- and post-tool behavior. · `src/openharness/hooks/executor.py`
- [Dynamic extensions](https://github.com/hkuds/openharness/blob/main/src/openharness/skills/loader.py): skills, plugins & commands · Loads instructions, commands, hooks, agents, and MCP configuration. · `src/openharness/skills/loader.py`

### Providers & MCP

- [Provider registry](https://github.com/hkuds/openharness/blob/main/src/openharness/api/registry.py): provider selection · Selects named provider profiles and compatible clients. · `src/openharness/api/registry.py`
- [Provider client](https://github.com/hkuds/openharness/blob/main/src/openharness/api/client.py): LLM transport · Normalizes streaming requests across model providers. · `src/openharness/api/client.py`
- [Auth manager](https://github.com/hkuds/openharness/blob/main/src/openharness/auth/manager.py): credentials · Manages persistent credentials and provider auth flows. · `src/openharness/auth/manager.py`
- **LLM providers**: external APIs · Hosted, local compatible, and subscription-backed model endpoints.
- [MCP client](https://github.com/hkuds/openharness/blob/main/src/openharness/mcp/client.py): external tool bridge · Connects stdio and HTTP MCP servers and derives tools from schemas. · `src/openharness/mcp/client.py`

### ohmo Gateway

- [ohmo gateway](https://github.com/hkuds/openharness/blob/main/ohmo/gateway/router.py): channel session router · Converts channel messages into harness sessions and returns responses. · `ohmo/gateway/router.py`
- [Channel bus](https://github.com/hkuds/openharness/blob/main/src/openharness/channels/bus/queue.py): event queue · Decouples channel adapters from gateway processing. · `src/openharness/channels/bus/queue.py`
- **Chat platforms**: external channels · Telegram, Slack, Discord, email, WhatsApp, Matrix, and others.

## Connections

- OpenHarness CLI → UI runtime: starts interactive session
- OpenHarness CLI → QueryEngine: runs headless queries
- UI runtime → Backend host: hosts protocol session
- Backend host → Terminal frontend: protocol events and input
- UI runtime → QueryEngine: drives session
- QueryEngine → Query & stream events: emits stream events
- QueryEngine → Prompt construction: assembles turn context
- Prompt construction → Memory & sessions: retrieves context
- QueryEngine → Provider registry: selects provider
- Provider registry → Provider client: creates client
- Auth manager → Provider client: supplies credentials
- Provider client → LLM providers: streams requests
- QueryEngine → Tool execution: executes model tool calls
- Tool execution → Permission checker: checks before execution
- Lifecycle hooks → Tool execution: intercepts lifecycle
- Dynamic extensions → Prompt construction: contributes instructions
- Dynamic extensions → Lifecycle hooks: registers hooks
- MCP client → Tool execution: exposes external tools
- QueryEngine → Swarm coordination: delegates work
- Chat platforms → Channel bus: inbound events
- Channel bus → ohmo gateway: routes messages
- ohmo gateway → QueryEngine: creates harness sessions
- ohmo gateway → Chat platforms: responses and notifications
