OpenHarness - A lightweight AI Agent framework open-sourced by the University of Hong Kong.

What is OpenHarness?

OpenHarness is a lightweight AI agent framework open-sourced by the Data Intelligence Laboratory (HKUDS) at the University of Hong Kong. Implemented entirely in Python, it comprises only 11,733 lines of code (1/44 the size of Claude Code), replicating 98% of its core tool capabilities (43 tools) and 61% of its command set (54 commands). The project is licensed under the MIT license and distills the "Agent Harness" architecture, providing tool invocation, persistent memory, permission governance, and multi-agent coordination around LLM. It is perfectly compatible with the Anthropic Skills and Claude Code plugin ecosystems and supports switching to any OpenAI-compatible model (such as Kimi, DeepSeek, and Ollam) via environment variables.

Main functions of OpenHarness

• Agent Core LoopIt enables streaming tool calls, exponential backoff retries, parallel execution, real-time token counting and cost tracking, and supports automatic context compression and breakpoint resume.
• Toolset (43+)It covers file I/O, Shell commands, web search, browser automation, MCP protocol, Notebook editing, task management, Cron scheduled tasks, etc., replicating 98% of Claude Code's tool capabilities.
• Skill SystemSupports on-demand loading of Markdown files, and is compatible with... anthropics/skills The ecosystem features built-in Pydantic type validation and allows reuse of 1000+ official and community skill sets.
• Memory and ContextAutomatic injection CLAUDE.md Project rules, cross-session persistence MEMORY.md Memory file, supports MEMORY_PLACEHOLDER Templated context management.
• Multi-Agent CoordinationSupports sub-agent generation and task delegation, team registry management, and background task lifecycle management. The future roadmap includes ClawTeam integration.
• Access ControlIt provides multi-level permission modes (default/automatic/scheduled/strict mode), supports path-level rules, command whitelists, interactive approval dialog boxes, and pre/post tool hooks.
• Plugin extension:compatible claude-code/plugins The format supports custom commands, hooks, agent classes, and MCP server extensions, and allows switching to any OpenAI-compatible model (such as Kimi, DeepSeek, and Ollam) via environment variables.

OpenHarness's technical principles

• Agent Harness ArchitectureIt adopts the "Harness" design pattern, which separates the intelligence layer (model) and execution layer (tools, memory, security boundary) of LLM. The model is responsible for deciding what to do (What), and Harness is responsible for executing it safely and efficiently (How), providing complete observability.
• Core Agent LoopImplement a standard ReAct tool call loop: LLM outputs the tool specification in JSON format → Harness parses and executes it in parallel → streams the results. The loop continues until the model stops calling the tool.stop_reason != "tool_use"During this period, index backoff retries and token counting are handled automatically.
• Modular subsystem architectureIt consists of 10+ independent subsystems, including Engine (loop engine), Tools (registry of 43 tools), Skills (Markdown skill loader), Plugins (extension hooks), Permissions (permission governance), Hooks (lifecycle events), Memory (persistent memory), Coordinator (multi-agent coordination), MCP (model context protocol client), etc., and each layer is decoupled through clearly defined interfaces.
• Context and memory managementEmploy a token budgeting mechanism (e.g., compressing the 128k limit to 80k) for automatic token injection. CLAUDE.md Project rules, using SQLite persistence MEMORY.md It supports cross-session memory, automatic context compression, and resume interrupted conversations.
• Permissions and governance hooksInterception is achieved through PreToolUse/PostToolUse lifecycle hooks, supporting multi-level permission modes (default/automatic/scheduled/strict), path-level rule matching, command whitelists, and interactive approval dialog boxes to ensure that sensitive operations are controllable.
• Multi-Agent Coordination MechanismSwarm mode manages sub-Agent IDs through a registry, uses JSON payloads for task delegation, manages lifecycles based on Python Asyncio coroutines, and supports background tasks and parallel research subtasks (such as deep research scenarios).
• Model neutrality and compatibility: Through environment variables (ANTHROPIC_BASE_URL/ANTHROPIC_MODELIt supports any OpenAI-compatible endpoint (Kimi, DeepSeek, Ollam, etc.), and tool calls use standard JSON Schema, with compatibility for skill and plugin formats. anthropics/skills and claude-code/plugins Ecology.
• Lightweight engineering implementationImplemented purely in Python 3.10+, using uv The package manager enables lock-free file installation in 11,733 lines of code (1/44 of Claude Code), eliminating enterprise-level overhead (telemetry, OAuth, hundreds of React components), and retaining React TUI as an optional frontend that communicates with the backend via standard input/output protocols.

How to use OpenHarness

• Environmental preparationEnsure your system has Python 3.10 or later installed. pip install uv Install the UV package manager and prepare the LLM API key (supporting Anthropic or any OpenAI compatible endpoint).
• Installation Project: Execute in the project directory uv init my-project && cd my-project Initialize the project, then run uv add "hkuds/openharness[cli]" Install OpenHarness and its CLI dependencies.
• Configuration key:pass export ANTHROPIC_API_KEY=sk-... Set the API key; if using other models such as Moonshot or DeepSeek, additional settings are required. export ANTHROPIC_BASE_URL=... Points to the corresponding endpoint.
• Initialize the project:implement oh init Commands are automatically generated CLAUDE.md Project rule documents and MEMORY.md Remember the file template and complete the initial project configuration.
• Start interaction:run oh run --model claude-3.5-sonnet Enter an interactive session, or execute oh demo Run the built-in demo task to experience the core functions.
• Loading skills:Will .md Skill files placed skills/ Table of Contents or ~/.openharness/skills/The system will automatically identify frontmatter metadata and load it on demand, ensuring compatibility. anthropics/skills Ecology.
• Access Management:use oh run --permissions strict Initiating a strict governance model, or through oh -p "提示词" --output-format json Achieve structured output results in headless/CI mode.
• Multi-Agent CoordinationIt creates sub-Agents and delegates tasks using the Swarm pattern, utilizes Asyncio coroutines to manage the lifecycle of background tasks, and supports parallel research of sub-tasks.

OpenHarness project address

• GitHub repositoryhttps://github.com/HKUDS/OpenHarness

OpenHarness's core advantages

• Ultra-lightweight44x code compression (11,733 vs 512,664 lines), 163 files, Python 3.10+ single language stack, no enterprise-level bloat (removed telemetry, OAuth, and hundreds of React components).
• Eco-compatibleIt replicates the Claude Code workflow, supports 12+ official plugins, and offers plug-and-play skills, reducing migration costs.
• Model neutral: Do not bind Anthropic, through settings ANTHROPIC_BASE_URL You can switch models by pointing to any compatible endpoint, such as the dark side of the moon.
• Unboxing safetyFeatures include: pre/post tool hooks, path-level permission rules, and sensitive operation interaction confirmation; strict mode can be set when running locally.
• Complete testing114 unit tests + 6 E2E kits, not covered by Claude Code.

Key information and usage requirements for OpenHarness

• Project BackgroundThe Data Intelligence Laboratory (HKUDS) at the University of Hong Kong was open-sourced on April 1, 2026, under the MIT license, and has approximately 1,300 stars on GitHub. The current version, v0.1.0, is in its early stages.
• Technical SpecificationsImplemented purely in Python 3.10+, with only 11,733 lines of code (1/44 the size of Claude Code), and 163 files. uv Package managers enable lock-free file installation.
• Architecture positioningIt adopts the "Agent Harness" architecture, separates the LLM intelligence layer from the execution layer, and replicates 98% of Claude Code's tool capabilities (43 tools) and 61% of its command set (54 commands).
• Model neutralityNative support for the Anthropic API, via ANTHROPIC_BASE_URL Environment variables can be switched to any OpenAI-compatible endpoint such as Moonshot, DeepSeek, OpenRouter, and Ollam.
• Eco-compatible:compatible anthropics/skills Skills ecosystem (1000+ plugins) and claude-code/plugins Extended format, supporting MCP protocol integration.
• Test coverageIncludes 114 unit tests and 6 E2E test suites (Claude Code does not have this coverage).
• Environment DependencePython 3.10+ is required. uv Package Manager (pip install uvIt does not support direct installation via pip.
• API ConfigurationYou need to prepare an LLM API key and set environment variables. ANTHROPIC_API_KEYAdditional configuration is required when using non-Anthropic models. ANTHROPIC_BASE_URL and ANTHROPIC_MODEL
• Project initialization: Must be run on first use oh init generate CLAUDE.md(Project Rules) and MEMORY.md(Memory File) Template
• Network requirementsTools such as web search, browser automation, and MCP server require an internet connection, but core functions can run completely offline (when using local Ollama).

Competitive analysis of OpenHarness

Application scenarios of OpenHarness

• AI Agent Research and Prototype DevelopmentA lightweight Python codebase (11,733 lines) that makes it easy for researchers to understand Agent loops, tool calls, and memory mechanisms. It is suitable for quickly validating cutting-edge ideas such as multi-agent coordination and context compression, without having to deal with the complexity of TypeScript and enterprise-level code.
• Local Private Smart AssistantBy configuring a local Ollama endpoint, it can run in intranet or offline environments, meeting the requirements of sensitive industries such as finance and healthcare that data does not leave the country, while retaining Claude Code-level code editing and file operation capabilities.
• CI/CD Automated Production Line: Utilizing headless mode (oh -p "提示词" --output-format jsonIt performs tasks such as code review, automated test generation, and documentation updates in environments such as GitHub Actions and GitLab CI, and outputs structured results for downstream steps to parse.
• Multi-Agent Collaboration SystemIt creates sub-agents and delegates parallel tasks (such as searching multiple code repositories simultaneously or comparing different technical solutions) through the Swarm pattern, which is suitable for the decomposition and coordination of complex R&D tasks and can replace some traditional workflow orchestration tools.
• Skill-driven domain-specific tools:load anthropics/skills The ecosystem of Markdown skill files (such as data analysis, web scraping, and API testing) allows for the rapid creation of dedicated AI assistants for specific technology stacks (Python, React, Docker, etc.).
• Developer CLI Workflow EnhancementIt can be integrated into daily terminal workflows to replace some manual shell operations and enable high-frequency development tasks such as natural language to command execution, batch file renaming, code refactoring, and Git commit message generation.