OpenHarness README

The project's README from github.com/HKUDS/OpenHarness. As one markdown file: README.md.

OpenHarness    ohmo
oh — OpenHarness & ohmo

English · 简体中文

OpenHarness delivers core lightweight agent infrastructure: tool-use, skills, memory, and multi-agent coordination.

ohmo is a personal AI agent built on OpenHarness — not another chatbot, but an assistant that actually works for you over long sessions. Chat with ohmo in Feishu / Slack / Telegram / Discord, and it forks branches, writes code, runs tests, and opens PRs on its own. ohmo runs on your existing Claude Code or Codex subscription — no extra API key needed.

Join the community: contribute Harness for open agent development.

Quick Start Architecture Tools Tests License

Python React Pytest E2E Output CI Feishu WeChat

One Command (oh) to Launch OpenHarness and Unlock All Agent Harnesses.

Supports CLI agent integration including OpenClaw, nanobot, Cursor, and more.

OpenHarness Terminal Demo

✨ OpenHarness's Key Harness Features

🔄 Agent Loop

Engine

• Streaming Tool-Call Cycle

• API Retry with Exponential Backoff

• Parallel Tool Execution

• Token Counting & Cost Tracking

🔧 Harness Toolkit

Toolkit

• 43 Tools (File, Shell, Search, Web, MCP)

• On-Demand Skill Loading (.md)

• Plugin Ecosystem (Skills + Hooks + Agents)

• Compatible with anthropics/skills & plugins

🧠 Context & Memory

Context

• CLAUDE.md Discovery & Injection

• Context Compression (Auto-Compact)

• MEMORY.md Persistent Memory

• Session Resume & History

🛡️ Governance

Governance

• Multi-Level Permission Modes

• Path-Level & Command Rules

• PreToolUse / PostToolUse Hooks

• Interactive Approval Dialogs

🤝 Swarm Coordination

Swarm

• Subagent Spawning & Delegation

• Team Registry & Task Management

• Background Task Lifecycle

• ClawTeam Integration (Roadmap)

🤔 What is an Agent Harness?

An Agent Harness is the complete infrastructure that wraps around an LLM to make it a functional agent. The model provides intelligence; the harness provides hands, eyes, memory, and safety boundaries.

Harness = Tools + Knowledge + Observation + Action + Permissions

OpenHarness is an open-source Python implementation designed for researchers, builders, and the community:

📰 What's New

Start here: Quick Start · Provider Compatibility · Showcase · Contributing · Changelog

🚀 Quick Start

1. Install

Linux / macOS / WSL

# One-click install
curl -fsSL https://raw.githubusercontent.com/HKUDS/OpenHarness/main/scripts/install.sh | bash

# Or via pip
pip install openharness-ai

Windows (Native)

# One-click install (PowerShell)
iex (Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/HKUDS/OpenHarness/main/scripts/install.ps1')

# Or via pip
pip install openharness-ai

Note: Windows support is now native. In PowerShell, use openh instead of oh because oh can resolve to the built-in Out-Host alias.

2. Configure

oh setup    # interactive wizard — pick a provider, authenticate, done
# On Windows PowerShell, use: openh setup

Supports Claude / OpenAI / Copilot / Codex / Moonshot(Kimi) / GLM / MiniMax / NVIDIA NIM and any compatible endpoint.

3. Run

oh
# On Windows PowerShell, use: openh

OpenHarness Landing Screen

4. Set up ohmo (Personal Agent)

Want an AI agent that works for you from Feishu / Slack / Telegram / Discord?

ohmo init             # initialize ~/.ohmo workspace
ohmo config           # configure channels and provider
ohmo gateway start    # start the gateway — ohmo is now live in your chat app

ohmo runs on your existing Claude Code subscription or Codex subscription — no extra API key needed.

Non-Interactive Mode (Pipes & Scripts)

# Single prompt → stdout
oh -p "Explain this codebase"

# JSON output for programmatic use
oh -p "List all functions in main.py" --output-format json

# Stream JSON events in real-time
oh -p "Fix the bug" --output-format stream-json

Dry Run (Safe Preview)

Use --dry-run when you want to inspect what OpenHarness would use before any live execution starts.

# Preview an interactive session setup
oh --dry-run

# Preview one prompt without executing the model or tools
oh --dry-run -p "Review this bug fix and grep for failing tests"

# Preview a slash command path
oh --dry-run -p "/plugin list"

# Get structured output for scripts or channels
oh --dry-run -p "Explain this repository" --output-format json

Dry-run is intentionally static:

Readiness levels:

next actions in the dry-run output tell you the shortest fix or follow-up step, such as:

🔌 Provider Compatibility

OpenHarness treats providers as workflows backed by named profiles. In day-to-day use, prefer:

oh setup
oh provider list
oh provider use <profile>

Built-in Workflows

Workflow What it is Typical backends
Anthropic-Compatible API Anthropic-style request format Claude official, Kimi, GLM, MiniMax, internal Anthropic-compatible gateways
Claude Subscription Claude CLI subscription bridge Local ~/.claude/.credentials.json
OpenAI-Compatible API OpenAI-style request format OpenAI official, OpenRouter, DashScope, DeepSeek, SiliconFlow, Groq, Ollama, GitHub Models
Codex Subscription Codex CLI subscription bridge Local ~/.codex/auth.json
GitHub Copilot Copilot OAuth workflow GitHub Copilot device-flow login

Compatible API Families

Anthropic-Compatible API

Typical examples:

Backend Base URL Example models
Claude official https://api.anthropic.com claude-sonnet-4-6, claude-opus-4-6
Moonshot / Kimi https://api.moonshot.cn/anthropic kimi-k2.5
Zhipu / GLM custom Anthropic-compatible endpoint glm-4.5
MiniMax custom Anthropic-compatible endpoint minimax-m1

OpenAI-Compatible API

Any provider implementing the OpenAI /v1/chat/completions style API works:

Backend Base URL Example models
OpenAI https://api.openai.com/v1 gpt-5.4, gpt-4.1
OpenRouter https://openrouter.ai/api/v1 provider-specific
Alibaba DashScope https://dashscope.aliyuncs.com/compatible-mode/v1 qwen3.5-flash, qwen3-max, deepseek-r1
DeepSeek https://api.deepseek.com deepseek-chat, deepseek-reasoner
GitHub Models https://models.inference.ai.azure.com gpt-4o, Meta-Llama-3.1-405B-Instruct
SiliconFlow https://api.siliconflow.cn/v1 deepseek-ai/DeepSeek-V3
NVIDIA NIM https://integrate.api.nvidia.com/v1 openai/gpt-oss-120b, nvidia/llama-3.3-nemotron-super-49b-v1
Google Gemini https://generativelanguage.googleapis.com/v1beta/openai gemini-2.5-flash, gemini-2.5-pro
Groq https://api.groq.com/openai/v1 llama-3.3-70b-versatile
Ollama (local) http://localhost:11434/v1 any local model

Advanced Profile Management

# List saved workflows
oh provider list

# Switch the active workflow
oh provider use codex

# Add your own compatible endpoint
oh provider add my-endpoint \
  --label "My Endpoint" \
  --provider openai \
  --api-format openai \
  --auth-source openai_api_key \
  --model my-model \
  --base-url https://example.com/v1

For custom compatible endpoints, OpenHarness can bind credentials per profile instead of forcing every Anthropic-compatible or OpenAI-compatible backend to share the same API key.

Ollama (Local Models)

Run local models through Ollama's OpenAI-compatible endpoint:

# Add an Ollama provider profile
oh provider add ollama \
  --label "Ollama" \
  --provider Ollama \
  --api-format openai \
  --auth-source openai_api_key \
  --model glm-4.7-flash:q8_0 \
  --base-url http://localhost:11434/v1

Saved provider profile: ollama

# Activate and verify
oh provider use ollama

Activated provider profile: ollama

oh provider list

  claude-api: Anthropic-Compatible API [ready]
  ...
  moonshot: Moonshot (Kimi) [missing auth]
    auth=moonshot_api_key model=kimi-k2.5 base_url=https://api.moonshot.cn/v1
* ollama: Ollama [ready]
    auth=openai_api_key model=glm-4.7-flash:q8_0 base_url=http://localhost:11434/v1

GitHub Copilot Format (--api-format copilot)

Use your existing GitHub Copilot subscription as the LLM backend. Authentication uses GitHub's OAuth device flow — no API keys needed.

# One-time login (opens browser for GitHub authorization)
oh auth copilot-login

# Then launch with Copilot as the provider
uv run oh --api-format copilot

# Or via environment variable
export OPENHARNESS_API_FORMAT=copilot
uv run oh

# Check auth status
oh auth status

# Remove stored credentials
oh auth copilot-logout
Feature Details
Auth method GitHub OAuth device flow (no API key needed)
Token management Automatic refresh of short-lived session tokens
Enterprise Supports GitHub Enterprise via --github-domain flag
Models Uses Copilot's default model selection
API OpenAI-compatible chat completions under the hood

🏗️ Harness Architecture

OpenHarness implements the core Agent Harness pattern with 10 subsystems:

openharness/
  engine/          # 🧠 Agent Loop — query → stream → tool-call → loop
  tools/           # 🔧 43 Tools — file I/O, shell, search, web, MCP
  skills/          # 📚 Knowledge — on-demand skill loading (.md files)
  plugins/         # 🔌 Extensions — commands, hooks, agents, MCP servers
  permissions/     # 🛡️ Safety — multi-level modes, path rules, command deny
  hooks/           # ⚡ Lifecycle — PreToolUse/PostToolUse event hooks
  commands/        # 💬 54 Commands — /help, /commit, /plan, /resume, ...
  mcp/             # 🌐 MCP — Model Context Protocol client
  memory/          # 🧠 Memory — persistent cross-session knowledge
  tasks/           # 📋 Tasks — background task management
  coordinator/     # 🤝 Multi-Agent — subagent spawning, team coordination
  prompts/         # 📝 Context — system prompt assembly, CLAUDE.md, skills
  config/          # ⚙️ Settings — multi-layer config, migrations
  ui/              # 🖥️ React TUI — backend protocol + frontend

The Agent Loop

The heart of the harness. One loop, endlessly composable:

while True:
    response = await api.stream(messages, tools)
    
    if response.stop_reason != "tool_use":
        break  # Model is done
    
    for tool_call in response.tool_uses:
        # Permission check → Hook → Execute → Hook → Result
        result = await harness.execute_tool(tool_call)
    
    messages.append(tool_results)
    # Loop continues — model sees results, decides next action

The model decides

OpenHarness (HKUDS/OpenHarness)

hooks
Searching Database…

16K ·GitHub
OpenHarness
What is this?OpenHarness is an open-source Python agent harness: the infrastructure that turns an LLM into a working agent with tool use, skills, memory and multi-agent coordination. It also ships ohmo, a personal agent that works for you in chat apps.
Is it a library I code against, or a finished tool I run?A finished CLI tool first: one command (oh) launches an interactive agent session, while oh -p runs single prompts from scripts. It is also an open Python codebase you can extend with your own plugins, providers and skills.
How do I get it running?Install with the README script, which links the oh, ohmo and openharness commands into ~/.local/bin. Then oh setup walks you through picking a provider, and oh starts an interactive session; oh -p '...' runs one-shot prompts.
Do I need API keys to use it?Often not: besides regular keys for Anthropic- or OpenAI-compatible providers, it can bridge your existing Claude Code or Codex subscription, log in via GitHub Copilot's OAuth device flow, or run local models through Ollama.
Any platform quirks to watch out for?Windows support is native, but in PowerShell you must type openh instead of oh, because oh resolves to PowerShell's built-in Out-Host alias. Linux, macOS and WSL use oh as normal.
Who is OpenHarness actually for?Researchers, builders and the community: people who want to see how production agents work under the hood, experiment with tools and coordination patterns, and build specialized agents on the architecture.
What can the agent actually do out of the box?43 built-in tools covering File, Shell, Search, Web and MCP, plus on-demand skill loading from .md files. There is also a plugin ecosystem of skills, hooks and agents that stays compatible with anthropics/skills and plugins.
What is ohmo, in one line?A personal agent built on OpenHarness: you chat with it in Feishu, Slack, Telegram or Discord, and it forks branches, writes code, runs tests and opens PRs on its own across long sessions.
Does it remember anything between sessions?Yes — persistent MEMORY.md plus session resume and history. Auto-compaction also preserves task state and channel logs across context compression, so agents can run multi-day sessions without manual compact or clear.
Can I check my setup without actually running anything?Yes — oh --dry-run resolves settings, auth state, skills, commands, tools and MCP config without calling the model or executing anything, then prints a ready / warning / blocked verdict with concrete next steps.
What are similar projects?Baize, PilotDeck, hive, prime-agent, harness-sdk, openrig, ruflo, maki
Which topics is it in?context-management, subagents, hooks, agent-harness, agent-framework, agent-memory, plugin-system, tui, openai-compatible, local-llm, ollama, multi-agent
Creator
HKUDS
Size
10.9 MB
Stars
16K
Updated
CommitJun 04Releasev0.1.9May 07
Age
6mo
Commits · 90 Days