OpenHarness

"OpenHarness: Open Agent Harness -- Ultra-Lightweight Claude Code"

Python

public

Forked

`oh` — OpenHarness & `ohmo`

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

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

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

OpenHarness Terminal Demo

✨ OpenHarness’s Key Harness Features

🔄 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)

🤔 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:

undefinedUnderstand how production AI agents work under the hood
undefinedExperiment with cutting-edge tools, skills, and agent coordination patterns
undefinedExtend the harness with custom plugins, providers, and domain knowledge
undefinedBuild specialized agents on top of proven architecture

📰 What’s New

undefined2026-04-18 ⚙️ v0.1.7 — Packaging & TUI polish:
- Install script now links oh, ohmo, and openharness into ~/.local/bin instead of prepending the virtualenv bin directory to PATH, which avoids clobbering Conda-managed shells.
- React TUI now supports Shift+Enter to insert a newline while keeping plain Enter as submit.
- Busy-state animation in the React TUI is quieter and less error-prone on Windows terminals, with conservative spinner frames and reduced flashing.
undefined2026-04-10 🧠 v0.1.6 — Auto-Compaction & Markdown TUI:
- Auto-Compaction preserves task state and channel logs across context compression — agents can run multi-day sessions without manual compact/clear
- Subprocess teammates run in headless worker mode; agent team creation stabilized
- Assistant messages now render full Markdown in the React TUI
- ohmo gains channel slash commands and multimodal attachment support
undefined2026-04-08 🔌 v0.1.5 — MCP HTTP transport & Swarm polling:
- MCP protocol adds HTTP transport, auto-reconnect on disconnect, and tool-only server compatibility
- JSON Schema types inferred for MCP tool inputs — no manual type mapping needed
- ohmo channels support file attachments and multimodal gateway messages
- Subprocess agents are now pollable in real runs; permission modals serialized to prevent input swallowing
undefined2026-04-08 🌙 v0.1.4 — Multi-provider auth & Moonshot/Kimi:
- Native Moonshot/Kimi provider with reasoning_content support for thinking models
- Auth overhaul: fixed provider-switching key mismatch, OPENAI_BASE_URL env override, profile-scoped credential priority
- MCP gracefully handles disconnected servers in call_tool / read_resource
- Security: built-in sensitive-path protection in PermissionChecker, hardened web_fetch URL validation
- Stability: EIO crash recovery in Ink TUI, --debug logging, Windows cmd flash fix
undefined2026-04-06 🚀 v0.1.2 — Unified setup flows and ohmo personal-agent app:
- oh setup now guides provider selection as workflows instead of exposing raw auth/provider internals
- Compatible API setup is now profile-scoped, so Anthropic/OpenAI-compatible endpoints can keep separate keys
- ohmo ships as a packaged app with ~/.ohmo workspace, gateway, bootstrap prompts, and channel config flow
undefined2026-04-01 🎨 v0.1.0 — Initial OpenHarness open-source release featuring complete Harness architecture:

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

undefinedNote: 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 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

🔌 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
undefinedAnthropic-Compatible APIundefined	Anthropic-style request format	Claude official, Kimi, GLM, MiniMax, internal Anthropic-compatible gateways
undefinedClaude Subscriptionundefined	Claude CLI subscription bridge	Local `~/.claude/.credentials.json`
undefinedOpenAI-Compatible APIundefined	OpenAI-style request format	OpenAI official, OpenRouter, DashScope, DeepSeek, SiliconFlow, Groq, Ollama, GitHub Models
undefinedCodex Subscriptionundefined	Codex CLI subscription bridge	Local `~/.codex/auth.json`
undefinedGitHub Copilotundefined	Copilot OAuth workflow	GitHub Copilot device-flow login

Compatible API Families

Anthropic-Compatible API

Typical examples:

Backend	Base URL	Example models
undefinedClaude officialundefined	`https://api.anthropic.com`	`claude-sonnet-4-6`, `claude-opus-4-6`
undefinedMoonshot / Kimiundefined	`https://api.moonshot.cn/anthropic`	`kimi-k2.5`
undefinedZhipu / GLMundefined	custom Anthropic-compatible endpoint	`glm-4.5`
undefinedMiniMaxundefined	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
undefinedOpenAIundefined	`https://api.openai.com/v1`	`gpt-5.4`, `gpt-4.1`
undefinedOpenRouterundefined	`https://openrouter.ai/api/v1`	provider-specific
undefinedAlibaba DashScopeundefined	`https://dashscope.aliyuncs.com/compatible-mode/v1`	`qwen3.5-flash`, `qwen3-max`, `deepseek-r1`
undefinedDeepSeekundefined	`https://api.deepseek.com`	`deepseek-chat`, `deepseek-reasoner`
undefinedGitHub Modelsundefined	`https://models.inference.ai.azure.com`	`gpt-4o`, `Meta-Llama-3.1-405B-Instruct`
undefinedSiliconFlowundefined	`https://api.siliconflow.cn/v1`	`deepseek-ai/DeepSeek-V3`
undefinedGoogle Geminiundefined	`https://generativelanguage.googleapis.com/v1beta/openai`	`gemini-2.5-flash`, `gemini-2.5-pro`
undefinedGroqundefined	`https://api.groq.com/openai/v1`	`llama-3.3-70b-versatile`
undefinedOllama (local)undefined	`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
undefinedAuth methodundefined	GitHub OAuth device flow (no API key needed)
undefinedToken managementundefined	Automatic refresh of short-lived session tokens
undefinedEnterpriseundefined	Supports GitHub Enterprise via `--github-domain` flag
undefinedModelsundefined	Uses Copilot’s default model selection
undefinedAPIundefined	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 what to do. The harness handles how — safely, efficiently, with full observability.

Harness Flow

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

✨ Features

🔧 Tools (43+)

Category	Tools	Description
undefinedFile I/Oundefined	Bash, Read, Write, Edit, Glob, Grep	Core file operations with permission checks
undefinedSearchundefined	WebFetch, WebSearch, ToolSearch, LSP	Web and code search capabilities
undefinedNotebookundefined	NotebookEdit	Jupyter notebook cell editing
undefinedAgentundefined	Agent, SendMessage, TeamCreate/Delete	Subagent spawning and coordination
undefinedTaskundefined	TaskCreate/Get/List/Update/Stop/Output	Background task management
undefinedMCPundefined	MCPTool, ListMcpResources, ReadMcpResource	Model Context Protocol integration
undefinedModeundefined	EnterPlanMode, ExitPlanMode, Worktree	Workflow mode switching
undefinedScheduleundefined	CronCreate/List/Delete, RemoteTrigger	Scheduled and remote execution
undefinedMetaundefined	Skill, Config, Brief, Sleep, AskUser	Knowledge loading, configuration, interaction

Every tool has:

undefinedPydantic input validation — structured, type-safe inputs
undefinedSelf-describing JSON Schema — models understand tools automatically
undefinedPermission integration — checked before every execution
undefinedHook support — PreToolUse/PostToolUse lifecycle events

📚 Skills System

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

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

🔌 Plugin System

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

Plugin	Type	What it does
`commit-commands`	Commands	Git commit, push, PR workflows
`security-guidance`	Hooks	Security warnings on file edits
`hookify`	Commands + Agents	Create custom behavior hooks
`feature-dev`	Commands	Feature development workflow
`code-review`	Agents	Multi-agent PR review
`pr-review-toolkit`	Agents	Specialized PR review agents

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

🤝 Ecosystem Workflows

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

undefinedOpenClaw-oriented workflows can reuse Markdown-first knowledge and command-driven collaboration patterns.
undefinedClaude-style plugins and skills stay portable because OpenHarness keeps those formats familiar.
undefinedClawTeam-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.

🛡️ Permissions

Multi-level safety with fine-grained control:

Mode	Behavior	Use Case
undefinedDefaultundefined	Ask before write/execute	Daily development
undefinedAutoundefined	Allow everything	Sandboxed environments
undefinedPlan Modeundefined	Block all writes	Large refactors, review first

undefinedPath-level rules in settings.json:

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

🖥️ Terminal UI

React/Ink TUI with full interactive experience:

undefinedCommand picker: Type / → arrow keys to select → Enter
undefinedPermission dialog: Interactive y/n with tool details
undefinedMode switcher: /permissions → select from list
undefinedSession resume: /resume → pick from history
undefinedAnimated spinner: Real-time feedback during tool execution
undefinedKeyboard shortcuts: Shown at the bottom, context-aware

📡 CLI

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 setup | oh provider | oh auth | oh mcp | oh plugin

🧑‍💼 ohmo Personal Agent

ohmo is a personal-agent app built on top of OpenHarness. It is packaged alongside oh, with its own workspace and gateway:

# Initialize personal workspace
ohmo init

# Configure gateway channels and pick a provider profile
ohmo config

# Run the personal agent
ohmo

# Run the gateway in foreground
ohmo gateway run

# Check or restart the gateway
ohmo gateway status
ohmo gateway restart

Key concepts:

~/.ohmo/
- personal workspace root
soul.md
- long-term agent personality and behavior
identity.md
- who ohmo is
user.md
- user profile and preferences
BOOTSTRAP.md
- first-run landing ritual
memory/
- personal memory
gateway.json
- selected provider profile and channel configuration

ohmo config uses the same workflow language as oh setup, so you can point the personal-agent gateway at:

Anthropic-Compatible API
Claude Subscription
OpenAI-Compatible API
Codex Subscription
GitHub Copilot

ohmo init creates the home workspace once. After that, use ohmo config to update provider and channel settings; if the gateway is already running, the config flow can restart it for you.

Currently ohmo init / ohmo config can guide channel setup for:

Telegram
Slack
Discord
Feishu

📊 Test Results

Suite	Tests	Status
Unit + Integration	114	✅ All passing
CLI Flags E2E	6	✅ Real model calls
Harness Features E2E	9	✅ Retry, skills, parallel, permissions
React TUI E2E	3	✅ Welcome, conversation, status
TUI Interactions E2E	4	✅ Commands, permissions, shortcuts
Real Skills + Plugins	12	✅ anthropics/skills + claude-code/plugins

# 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

🔧 Extending OpenHarness

Add a Custom Tool

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

Add a Plugin

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.

🌍 Showcase

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

undefinedRepo coding assistant for reading code, patching files, and running checks locally.
undefinedHeadless scripting tool for json and stream-json output in automation flows.
undefinedPlugin and skill testbed for experimenting with Claude-style extensions.
undefinedMulti-agent prototype harness for task delegation and background execution.
undefinedProvider comparison sandbox across Anthropic-compatible backends.

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

🤝 Contributing

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

Area	Examples
undefinedToolsundefined	New tool implementations for specific domains
undefinedSkillsundefined	Domain knowledge `.md` files (finance, science, DevOps…)
undefinedPluginsundefined	Workflow plugins with commands, hooks, agents
undefinedProvidersundefined	Support for more LLM backends (OpenAI, Ollama, etc.)
undefinedMulti-Agentundefined	Coordination protocols, team patterns
undefinedTestingundefined	E2E scenarios, edge cases, benchmarks
undefinedDocumentationundefined	Architecture guides, tutorials, translations

# 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

📄 License

MIT — see LICENSE.

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

Thanks for visiting ✨ OpenHarness!

Find me

[beta]v0.3.0