OpenHarness - HKU's Open-Source Lightweight AI Agent Framework

What is OpenHarness

OpenHarness is a lightweight AI Agent framework open-sourced by the Hong Kong University Data Intelligence Lab (HKUDS), implemented in pure Python with 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 uses the MIT license and distills the "Agent Harness" architecture, providing tool calling, persistent memory, permission governance, and multi-agent coordination around LLMs. It is fully compatible with the Anthropic Skills and Claude Code plugin ecosystems, and supports switching to any OpenAI-compatible model (such as Kimi, DeepSeek, Ollama) via environment variables.

Main Features of OpenHarness

• Agent Core Loop: Implements streaming tool calling, exponential backoff retries, parallel execution, real-time token counting and cost tracking, and supports automatic context compression and resuming conversations from checkpoints.
• Toolset (43+): 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 System: Supports on-demand loading of skills from Markdown files, compatible with the anthropics/skills ecosystem, with built-in Pydantic type validation, and can reuse 1000+ official and community skill libraries.
• Memory and Context: Automatically injects CLAUDE.md project rules, persists MEMORY.md memory files across sessions, and supports MEMORY_PLACEHOLDER templated context management.
• Multi-Agent Coordination: Supports sub-agent generation and task delegation, team registry management, and background task lifecycle management; the future roadmap includes ClawTeam integration.
• Permission Governance: Provides multi-level permission modes (default/auto/plan/strict modes), supports path-level rules, command whitelists, interactive approval dialogs, and pre/post tool hooks.
• Plugin Extensions: Compatible with the claude-code/plugins format, supports custom commands, hooks, Agent classes, and MCP server extensions, and allows switching to any OpenAI-compatible model (such as Kimi, DeepSeek, Ollama) via environment variables.

Technical Principles of OpenHarness

• Agent Harness Architecture: Adopts the "Harness" design pattern, separating the LLM's intelligence layer (model) from the execution layer (tools, memory, security boundaries). The model is responsible for deciding what to do (What), while the Harness is responsible for executing it safely and efficiently (How), providing full observability.
• Core Agent Loop: Implements the standard ReAct tool-calling loop—the LLM outputs tool specifications in JSON format → the Harness parses and executes them in parallel → results are streamed back. The loop continues until the model stops calling tools (stop_reason != "tool_use"), during which exponential backoff retries and token counting are handled automatically.
• Modular Subsystem Architecture: Composed 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., with each layer decoupled through clearly defined interfaces.
• Context and Memory Management: Adopts a token budget mechanism (e.g., compressing within a 128k limit to 80k), automatically injects CLAUDE.md project rules, uses SQLite to persist MEMORY.md cross-session memory, and supports automatic context compression and resuming conversations from a breakpoint.
• Permission and governance hooks: Implements interception through PreToolUse/PostToolUse lifecycle hooks, supports multi-level permission modes (default/auto/plan/strict), path-level rule matching, command whitelists, and interactive approval dialogs to ensure sensitive operations remain controllable.
• Multi-Agent coordination mechanism: Swarm mode manages sub-Agent IDs through a registry, uses JSON Payload 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: Supports any OpenAI-compatible endpoint (Kimi, DeepSeek, Ollama, etc.) through environment variables (ANTHROPIC_BASE_URL/ANTHROPIC_MODEL), tool calls use standard JSON Schema, and skill and plugin formats are compatible with the anthropics/skills and claude-code/plugins ecosystems.
• Lightweight engineering implementation: Implemented purely in Python 3.10+, uses the uv package manager to achieve zero-lockfile installation, 11,733 lines of code (1/44 of Claude Code), removes enterprise-level overhead (telemetry, OAuth, hundreds of React components), retains the React TUI as an optional frontend, and communicates with the backend through a standard input/output protocol.

How to use OpenHarness

• Environment preparation: Ensure that Python 3.10+ is installed on the system, install the uv package manager via pip install uv , and prepare an LLM API key (supports Anthropic or any OpenAI-compatible endpoint).
• Install the project: In the project directory, run uv init my-project && cd my-project to initialize the project, then run uv add "hkuds/openharness[cli]" to install OpenHarness and its CLI dependencies.
• Configure the key: Set the API key via export ANTHROPIC_API_KEY=sk-... ; if using other models such as Moonshot or DeepSeek, you also need to set export ANTHROPIC_BASE_URL=... to point to the corresponding endpoint.
• Initialize the project: Run the oh init command to automatically generate the CLAUDE.md project rules file and the MEMORY.md memory file template, completing the project initialization configuration.
• Start interaction: Run oh run --model claude-3.5-sonnet to enter an interactive session, or execute oh demo to run the built-in demo task and experience the core features.
• Load skills: Place the .md skill files into the skills/ directory or ~/.openharness/skills/, and the system will automatically recognize the frontmatter metadata and load them on demand, compatible with the anthropics/skills ecosystem.
• Permission management: Use oh run --permissions strict to enable strict governance mode, or use oh -p "提示词" --output-format json to implement headless/CI mode output of structured results.
• Multi-Agent coordination: Create sub-Agents and delegate tasks through Swarm mode, use Asyncio coroutines to manage the lifecycle of background tasks, and support parallel research subtasks.

OpenHarness project address

• GitHub repository：https://github.com/HKUDS/OpenHarness

OpenHarness's core advantages

• Extremely lightweight: 44x code compression ratio (11,733 vs 512,664 lines), 163 files, Python 3.10+ single-language stack, no enterprise-grade bloat (eliminating telemetry, OAuth, and hundreds of React components).
• Ecosystem compatibility: Replicates the Claude Code workflow, supports 12+ official plugins, and Skills are plug-and-play, reducing migration costs.
• Model neutrality: Not tied to Anthropic; by setting ANTHROPIC_BASE_URL to point to any compatible endpoint such as Moonshot, you can switch models.
• Secure out of the box: Pre/post tool hooks, path-level permission rules, interactive confirmation for sensitive operations, and strict mode can be enabled for local runs.
• Complete testing: 114 unit tests + 6 E2E suites; Claude Code has no such coverage.

Key information and usage requirements for OpenHarness

• Project background: Open-sourced by the University of Hong Kong Data Intelligence Lab (HKUDS) on April 1, 2026, MIT license, approximately 1,300 GitHub Stars, currently at v0.1.0 in an early stage.
• Technical specifications: Pure Python 3.10+ implementation, only 11,733 lines of code (1/44 the size of Claude Code), 163 files, using uv package manager for zero-lockfile installation.
• Architecture positioning: Adopts an "Agent Harness" architecture, separating the LLM intelligence layer from the execution layer, replicating 98% of Claude Code's tool capabilities (43 tools) and 61% of its command set (54 commands).
• Model neutrality: Natively supports the Anthropic API; via the ANTHROPIC_BASE_URL environment variable, it can switch to any OpenAI-compatible endpoint such as Moonshot, DeepSeek, OpenRouter, Ollama, etc.
• Ecosystem compatibility: Compatible with the anthropics/skills skills ecosystem (1000+ plugins) and the claude-code/plugins extension format, and supports MCP protocol integration.
• Test coverage: Includes 114 unit tests and 6 E2E test suites (Claude Code has no such coverage).
• Environment dependencies: Python 3.10+, must install the uv package manager (pip install uv), direct installation with pip is not supported
• API configuration: Requires an LLM API key and setting the environment variable ANTHROPIC_API_KEY; when using non-Anthropic models, additional configuration of ANTHROPIC_BASE_URL and ANTHROPIC_MODEL
• Project initialization: On first use, you must run oh init to generate the CLAUDE.md(project rules) and MEMORY.md(memory file) templates
• Network requirements: Tools such as web search, browser automation, and MCP servers require an internet connection; core functionality can run fully offline (when using local Ollama)

Analysis of similar competing products for OpenHarness

OpenHarness application scenarios

• AI Agent research and prototype development: The lightweight Python codebase (11,733 lines) makes it easy for researchers to understand the Agent loop, tool invocation, and memory mechanisms. It is suitable for quickly validating frontier ideas such as multi-Agent coordination and context compression, without having to deal with the complexity of TypeScript and enterprise-grade code.
• Local privatized intelligent assistant: By configuring a local Ollama endpoint, it can run in an intranet or offline environment, meeting the data residency requirements of sensitive industries such as finance and healthcare, while retaining Claude Code-level code editing and file operation capabilities.
• CI/CD automated pipelines: Using headless mode (oh -p "提示词" --output-format json) to perform code review, automated test generation, documentation updates, and other tasks in environments such as GitHub Actions and GitLab CI, outputting structured results for downstream steps to parse.
• Multi-Agent collaboration systems: Use Swarm mode to create sub-agents and delegate parallel tasks (such as simultaneously searching multiple code repositories and comparing different technical solutions), suitable for decomposing and coordinating complex R&D tasks and replacing some traditional workflow orchestration tools.
• Skill-driven domain-specific tools: Load anthropics/skills ecosystem Markdown skill files (such as data analysis, crawler writing, and API testing) to quickly build dedicated AI assistants for specific technology stacks (Python, React, Docker, etc.).
• Developer CLI workflow enhancement: Integrate into daily terminal workflows, replacing some manual Shell operations and enabling high-frequency development tasks such as natural language to command execution, batch file renaming, code refactoring, and Git commit message generation.