Skip to content
Get packs

Guide · Open source

How to use OpenHarness: install, run oh and try ohmo

Updated · written with AI from the project's own documentation and checked against our catalogue data

OpenHarness is an open-source Python project that supplies the infrastructure around a language model so it can work as an agent: tool use, skills, memory and coordination between sub-agents. This guide is for developers and researchers who want to see how an agent harness is built and try its command-line entry point, oh. By the end you will know what to check before installing, how to clone the project, how to preview a run safely, and what ohmo is and what it requires.

OpenHarnessHKUDS/OpenHarness · ★ 16.2k · MIT

Quick start

  1. 1Check Python. Confirm you have Python 3.10 or newer installed. Older versions do not meet the stated prerequisite.
  2. 2Clone the repository. Run git clone on the HKUDS/OpenHarness repository to get the source code onto your machine.
  3. 3Follow the install section. Complete the remaining installation steps in the README in the cloned folder, since the excerpt used here is truncated.
  4. 4Preview with dry-run. Run oh --dry-run to check settings, auth, tools and MCP servers and read the ready, warning or blocked verdict before running anything.
  5. 5Set permissions. Review the permission modes and path and command rules before allowing shell, file or web access.

What OpenHarness is and who it is for

An agent harness is the layer that wraps a language model so it can act: calling tools, reading skills, keeping memory and handing work to sub-agents. The model supplies the reasoning; the harness supplies the hands, memory and permission boundaries.

OpenHarness is written in readable Python and is aimed at people who want to understand, experiment with or extend that layer. It is a poor fit if you want a polished consumer app, since setup and configuration are developer-oriented.

  • Developers who want to see how an agent harness is structured
  • Researchers testing agent tools, skills and coordination patterns
  • Builders who want to add custom plugins or providers

Check the requirements before you install

The README lists Python 3.10 or newer as the prerequisite. Check your version first, because older interpreters will not meet it.

The project is MIT licensed, so you can read, modify and reuse the code under those terms. Review the LICENSE file in the repository for the full text.

  • Python 3.10 or newer
  • Git, to clone the repository
  • A terminal for running the oh command
python --version

Clone the repository and install

Start by cloning the project from GitHub. The README's install section begins with this clone step. The excerpt used for this guide is truncated, so follow the rest of the README's installation instructions in the cloned repository for the remaining setup steps.

Once installed, the command-line entry point is called oh. The README also mentions openharness and ohmo as names the install script links into ~/.local/bin.

git clone https://github.com/HKUDS/OpenHarness

Run oh and preview with --dry-run

The safest first run is a dry run. According to the README, oh --dry-run previews the resolved runtime settings, auth state, skills, commands, tools and configured MCP servers without executing the model, tools or sub-agents.

The preview gives a readiness verdict of ready, warning or blocked, with suggested next steps such as fixing auth or MCP configuration. Use it to confirm your setup before you let the agent act.

  • ready: the setup looks usable
  • warning: something may need attention
  • blocked: fix the listed problem first
oh --dry-run

Understand the permission controls

The README describes shell, file and web access as core capabilities. It also lists multi-level permission modes, path-level and command rules, PreToolUse and PostToolUse hooks, and interactive approval dialogs to manage them.

Read these controls before you give an agent access to your machine. Keep the permission mode strict until you understand what the agent will be allowed to do.

  • Multi-level permission modes
  • Path-level and command rules
  • PreToolUse and PostToolUse hooks
  • Interactive approval dialogs

What ohmo is and what it needs

ohmo is a personal agent built on OpenHarness. The README says you can chat with it through Feishu, Slack, Telegram or Discord, and that it can run on an existing Claude Code or Codex subscription without an extra API key.

ohmo only makes sense if you already have one of those supported subscriptions and want a personal agent reachable from chat apps. Otherwise, OpenHarness itself is the part to focus on.

What people use it for

  • Reading the Python source to learn how tool calls, skills and memory fit together in an agent
  • Testing new tools, skills or sub-agent coordination patterns in a contained setup
  • Adding a custom plugin or provider to an existing agent
  • Reaching a personal agent from a chat app such as Slack or Telegram, if you already have a supported subscription

Frequently asked questions

Is OpenHarness free to use?

OpenHarness is released under the MIT licence, which allows use, modification and redistribution under its terms. The README excerpt used here does not state pricing for any hosted service, so check the repository before assuming anything beyond the licence.

What are the requirements for OpenHarness?

The README lists Python 3.10 or newer as the prerequisite. You will also need git to clone the repository and a terminal to run the oh command.

How do I install OpenHarness?

Start by cloning the repository from GitHub with git clone https://github.com/HKUDS/OpenHarness. The excerpt used for this guide is truncated, so complete the remaining steps from the README in the cloned folder.

What is ohmo and do I need an API key for it?

ohmo is a personal agent built on OpenHarness that the README says can be reached through Feishu, Slack, Telegram or Discord. The README says it runs on an existing Claude Code or Codex subscription and needs no extra API key.

Is OpenHarness safe to run on my computer?

It gives the agent shell, file and web access, which the README calls core capabilities. Use the permission modes, path-level and command rules and approval dialogs to limit what it can do, and run oh --dry-run first.

How does OpenHarness compare to Claude Code or Aider?

The README lists Claude Code, OpenClaw, nanobot and Aider as comparable projects, but it does not compare features in the excerpt used here. OpenHarness is most useful when you want to read and modify an agent harness in Python.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

OpenHarness suits developers, researchers and builders who want to study or extend an agent harness in readable Python and are comfortable with a command-line setup. Pick something else if you want a polished consumer app or a production system you can rely on without configuration work.

Install options & downloads