Introduction

The world of AI agents is evolving rapidly, but building production-ready agents remains challenging. While Large Language Models provide incredible intelligence, they need infrastructure to interact with the world—tools to execute actions, memory to persist knowledge, permissions to ensure safety, and coordination to work with other agents.

Enter OpenHarness—an open-source Python implementation that delivers core lightweight agent infrastructure. It provides the complete "harness" that wraps around an LLM to transform it into a functional agent. The model provides intelligence; the harness provides hands, eyes, memory, and safety boundaries.

OpenHarness is designed for researchers, builders, and the community to understand how production AI agents work, experiment with cutting-edge tools and coordination patterns, extend the harness with custom plugins, and build specialized agents on proven architecture.

What is an Agent Harness?

An Agent Harness is the complete infrastructure that wraps around an LLM to make it a functional agent. Think of it as the difference between having a brilliant mind and having that mind equipped with tools, knowledge, observation capabilities, and the ability to take action safely.

The harness equation is simple yet powerful:

OpenHarness implements this equation through a comprehensive set of subsystems that work together to create a robust, production-ready agent platform. Whether you're building a coding assistant, a research agent, or a multi-agent system, OpenHarness provides the foundation you need.

Key Features of OpenHarness

Architecture Overview

OpenHarness implements the core Agent Harness pattern with 10 interconnected subsystems:

These components work together through a unified flow: User Prompt → CLI or React TUI → RuntimeBundle → QueryEngine → Anthropic-compatible API Client → Tool Registry → Permissions + Hooks → Execution → Results back to QueryEngine.

Quick Start Guide

One-Click Install

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

Prerequisites

• Python 3.10+ and [uv](https://docs.astral.sh/uv/)
• Node.js 18+ (optional, for the React terminal UI)
• An LLM API key

One-Command Demo

# 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 OpenHarness
uv run oh

Configure a Workflow

Use the unified setup flow instead of manually thinking about auth → provider → model:

uv run oh setup

This walks through choosing a workflow (Anthropic-Compatible API, Claude Subscription, OpenAI-Compatible API, Codex Subscription, or GitHub Copilot), selecting a backend preset, authenticating if needed, picking a model, and saving the profile.

Provider Compatibility

OpenHarness treats providers as workflows backed by named profiles. It supports a wide range of backends:

Extending OpenHarness

Add a Custom Tool

Creating custom tools is straightforward with Pydantic-based validation:

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}")

Add a Custom Skill

Create skills as Markdown files with frontmatter metadata:

---
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
...

Add a Plugin

Plugins can include commands, hooks, and agents. Create a plugin structure:

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

OpenHarness is compatible with claude-code plugins and has been tested with 12 official plugins including commit-commands, security-guidance, hookify, feature-dev, code-review, and pr-review-toolkit.

Ecosystem & Integration

OpenHarness is designed to work seamlessly with existing AI development ecosystems: