How hkuds/openharness works
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: query_engine.py QueryEngine · base.py Tool execution · runtime.py UI runtime · router.py ohmo gateway
Components 21
Entry & UI
- OpenHarness CLI · Interactive and headless text, JSON, and stream-JSON modes.
src/openharness/cli.py - UI runtime · Selects and owns interactive runtime sessions.
src/openharness/ui/runtime.py - Backend host · Session protocol boundary for the terminal client.
src/openharness/ui/backend_host.py - Terminal frontend
frontend/terminal/src/App.tsx
Agent Core
- QueryEngine · Streams model turns, executes requested tools, and repeats to completion.
src/openharness/engine/query_engine.py - Query & stream events · Carries query state and streaming events to output consumers.
src/openharness/engine/query.py - Prompt construction · Combines system, project, skill, and memory context.
src/openharness/prompts/system_prompt.py - Memory & sessions · Maintains resumable history and relevance-selected knowledge.
src/openharness/memory/manager.py - Swarm coordination · Delegates to agents and coordinates teams, mailboxes, permissions, and worktrees.
src/openharness/swarm/team_lifecycle.py
Tools & Extensions
- Tool execution · Filesystem, shell, web, task, team, scheduling, and interaction tools.
src/openharness/tools/base.py - Permission checker · Trust boundary for commands, writes, network access, and extensions.
src/openharness/permissions/checker.py - Lifecycle hooks · Runs pre- and post-tool behavior.
src/openharness/hooks/executor.py - Dynamic extensions · Loads instructions, commands, hooks, agents, and MCP configuration.
src/openharness/skills/loader.py
Providers & MCP
- Provider registry · Selects named provider profiles and compatible clients.
src/openharness/api/registry.py - Provider client · Normalizes streaming requests across model providers.
src/openharness/api/client.py - Auth manager · Manages persistent credentials and provider auth flows.
src/openharness/auth/manager.py - LLM providers · Hosted, local compatible, and subscription-backed model endpoints.
- MCP client · Connects stdio and HTTP MCP servers and derives tools from schemas.
src/openharness/mcp/client.py
ohmo Gateway
- ohmo gateway · Converts channel messages into harness sessions and returns responses.
ohmo/gateway/router.py - Channel bus · Decouples channel adapters from gateway processing.
src/openharness/channels/bus/queue.py - Chat platforms · Telegram, Slack, Discord, email, WhatsApp, Matrix, and others.
Connections 23
- 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