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

Join the community: contribute Harness for open agent development.

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

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

🔄 Agent Loop • Streaming Tool-Call Cycle • API Retry with Exponential Backoff • Parallel Tool Execution • Token Counting & Cost Tracking

🔧 Harness 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 • CLAUDE.md Discovery & Injection • Context Compression (Auto-Compact) • MEMORY.md Persistent Memory • Session Resume & History

🛡️ Governance • Multi-Level Permission Modes • Path-Level & Command Rules • PreToolUse / PostToolUse Hooks • Interactive Approval Dialogs

🤝 Swarm Coordination • Subagent Spawning & Delegation • Team Registry & Task Management • Background Task Lifecycle • ClawTeam Integration (Roadmap)

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.

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

• Understand how production AI agents work under the hood
• Experiment with cutting-edge tools, skills, and agent coordination patterns
• Extend the harness with custom plugins, providers, and domain knowledge
• Build specialized agents on top of proven architecture

• 2026-04-01 🎨 v0.1.0 — Initial OpenHarness open-source release featuring complete Harness architecture:

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

The fastest way to get started — a single command handles OS detection, dependency checks, and installation:

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

Options:

# Install from source (for contributors / latest code)
curl -fsSL https://raw.githubusercontent.com/HKUDS/OpenHarness/main/scripts/install.sh | bash -s -- --from-source

# Install with IM channel support
curl -fsSL https://raw.githubusercontent.com/HKUDS/OpenHarness/main/scripts/install.sh | bash -s -- --with-channels

# Or run locally after cloning
bash scripts/install.sh --from-source --with-channels

The script will:

1. Detect your OS (Linux / macOS / WSL)
2. Verify Python ≥ 3.10 and Node.js ≥ 18
3. Install OpenHarness via pip
4. Set up the React TUI (npm install) if Node.js is available
5. Create ~/.openharness/ config directory
6. Confirm with oh --version

• Python 3.10+ and uv
• Node.js 18+ (optional, for the React terminal UI)
• An LLM API key

ANTHROPIC_API_KEY=your_key uv run oh -p "Inspect this repository and list the top 3 refactors"

# Clone and install
git clone https://github.com/HKUDS/OpenHarness.git
cd OpenHarness
uv sync --extra dev

# Example: use Kimi as the backend
export ANTHROPIC_BASE_URL=https://api.moonshot.cn/anthropic
export ANTHROPIC_API_KEY=your_kimi_api_key
export ANTHROPIC_MODEL=kimi-k2.5

# Launch
oh                    # if venv is activated
uv run oh             # without activating venv

# 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

OpenHarness supports three API formats: Anthropic (default), OpenAI-compatible (--api-format openai), and GitHub Copilot (--api-format copilot). The OpenAI format covers a wide range of providers.

Any provider implementing the OpenAI /v1/chat/completions API works out of the box:

# Example: use DashScope
uv run oh --api-format openai \
  --base-url "https://dashscope.aliyuncs.com/compatible-mode/v1" \
  --api-key "sk-xxx" \
  --model "qwen3.5-flash"

# Or via environment variables
export OPENHARNESS_API_FORMAT=openai
export OPENAI_API_KEY=sk-xxx
export OPENHARNESS_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
export OPENHARNESS_MODEL=qwen3.5-flash
uv run oh

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

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 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 what to do. The harness handles how — safely, efficiently, with full observability.

flowchart LR
    U[User Prompt] --> C[CLI or React TUI]
    C --> R[RuntimeBundle]
    R --> Q[QueryEngine]
    Q --> A[Anthropic-compatible API Client]
    A -->|tool_use| T[Tool Registry]
    T --> P[Permissions + Hooks]
    P --> X[Files Shell Web MCP Tasks]
    X --> Q

Every tool has:

• Pydantic input validation — structured, type-safe inputs
• Self-describing JSON Schema — models understand tools automatically
• Permission integration — checked before every execution
• Hook support — PreToolUse/PostToolUse lifecycle events

Skills are on-demand knowledge — loaded only when the model needs them:

Available Skills:
- commit: Create clean, well-structured git commits
- review: Review code for bugs, security issues, and quality
- debug: Diagnose and fix bugs systematically
- plan: Design an implementation plan before coding
- test: Write and run tests for code
- simplify: Refactor code to be simpler and more maintainable
- pdf: PDF processing with pypdf (from anthropics/skills)
- xlsx: Excel operations (from anthropics/skills)
- ... 40+ more

Compatible with anthropics/skills — just copy .md files to ~/.openharness/skills/.

Compatible with claude-code plugins. Tested with 12 official plugins:

# Manage plugins
oh plugin list
oh plugin install <source>
oh plugin enable <name>

OpenHarness is useful as a lightweight harness layer around Claude-style tooling conventions:

• OpenClaw-oriented workflows can reuse Markdown-first knowledge and command-driven collaboration patterns.
• Claude-style plugins and skills stay portable because OpenHarness keeps those formats familiar.
• ClawTeam-style multi-agent work maps well onto the built-in team, task, and background execution primitives.

For concrete usage ideas instead of generic claims, see docs/SHOWCASE.md.

Multi-level safety with fine-grained control:

Path-level rules in settings.json:

{
  "permission": {
    "mode": "default",
    "path_rules": [{"pattern": "/etc/*", "allow": false}],
    "denied_commands": ["rm -rf /", "DROP TABLE *"]
  }
}

React/Ink TUI with full interactive experience:

• Command picker: Type / → arrow keys to select → Enter
• Permission dialog: Interactive y/n with tool details
• Mode switcher: /permissions → select from list
• Session resume: /resume → pick from history
• Animated spinner: Real-time feedback during tool execution
• Keyboard shortcuts: Shown at the bottom, context-aware

oh [OPTIONS] COMMAND [ARGS]

Session:     -c/--continue, -r/--resume, -n/--name
Model:       -m/--model, --effort, --max-turns
Output:      -p/--print, --output-format text|json|stream-json
Permissions: --permission-mode, --dangerously-skip-permissions
Context:     -s/--system-prompt, --append-system-prompt, --settings
Advanced:    -d/--debug, --mcp-config, --bare

Subcommands: oh mcp | oh plugin | oh auth

# Run all tests
uv run pytest -q                           # 114 unit/integration
python scripts/test_harness_features.py     # Harness E2E
python scripts/test_real_skills_plugins.py  # Real plugins E2E

from pydantic import BaseModel, Field
from openharness.tools.base import BaseTool, ToolExecutionContext, ToolResult

class MyToolInput(BaseModel):
    query: str = Field(description="Search query")

class MyTool(BaseTool):
    name = "my_tool"
    description = "Does something useful"
    input_model = MyToolInput

    async def execute(self, arguments: MyToolInput, context: ToolExecutionContext) -> ToolResult:
        return ToolResult(output=f"Result for: {arguments.query}")

Create ~/.openharness/skills/my-skill.md:

---
name: my-skill
description: Expert guidance for my specific domain
---

# My Skill

## When to use
Use when the user asks about [your domain].

## Workflow
1. Step one
2. Step two
...

Create .openharness/plugins/my-plugin/.claude-plugin/plugin.json:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My custom plugin"
}

Add commands in commands/*.md, hooks in hooks/hooks.json, agents in agents/*.md.

OpenHarness is most useful when treated as a small, inspectable harness you can adapt to a real workflow:

• Repo coding assistant for reading code, patching files, and running checks locally.
• Headless scripting tool for json and stream-json output in automation flows.
• Plugin and skill testbed for experimenting with Claude-style extensions.
• Multi-agent prototype harness for task delegation and background execution.
• Provider comparison sandbox across Anthropic-compatible backends.

See docs/SHOWCASE.md for short, reproducible examples.

OpenHarness is a community-driven research project. We welcome contributions in:

# Development setup
git clone https://github.com/HKUDS/OpenHarness.git
cd OpenHarness
uv sync --extra dev
uv run pytest -q  # Verify everything works

Useful contributor entry points:

• CONTRIBUTING.md for setup, checks, and PR expectations
• CHANGELOG.md for user-visible changes
• docs/SHOWCASE.md for real-world usage patterns worth documenting

MIT — see LICENSE.

Oh my Harness!
The model is the agent. The code is the harness.

Thanks for visiting ✨ OpenHarness!