openharness-agent

What this skill does

```markdown
---
name: openharness-agent
description: Skill for using OpenHarness (oh) — the lightweight open-source Python agent harness with tool-use, skills, memory, and multi-agent coordination
triggers:
  - set up OpenHarness agent
  - use oh command for AI agent
  - configure openharness tools
  - build agent with openharness
  - add skills to openharness
  - create multi-agent workflow with openharness
  - troubleshoot openharness tool execution
  - extend openharness with custom plugins
---

# OpenHarness Agent Harness (`oh`)

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

OpenHarness is a lightweight Python agent harness that wraps an LLM with tools, memory, permissions, and multi-agent coordination — 44x lighter than Claude Code at ~11,700 lines of Python. It exposes a single `oh` CLI and a composable Python API.

---

## Installation

**Requirements:** Python 3.10+, [uv](https://docs.astral.sh/uv/), Node.js 18+ (optional, for React TUI)

```bash
git clone https://github.com/HKUDS/OpenHarness.git
cd OpenHarness
uv sync --extra dev
```

Activate the environment or use `uv run` prefix for all commands.

---

## Environment Configuration

```bash
# Anthropic (default)
export ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY

# Moonshot / Kimi (Anthropic-compatible)
export ANTHROPIC_BASE_URL=https://api.moonshot.cn/anthropic
export ANTHROPIC_API_KEY=$MOONSHOT_API_KEY
export ANTHROPIC_MODEL=kimi-k2.5

# Vertex-compatible gateway
export ANTHROPIC_BASE_URL=https://your-vertex-gateway/anthropic
export ANTHROPIC_API_KEY=$GCP_API_KEY

# Bedrock-compatible gateway
export ANTHROPIC_BASE_URL=https://your-bedrock-gateway
export ANTHROPIC_API_KEY=$AWS_API_KEY
```

Provider detection is automatic based on `ANTHROPIC_BASE_URL` content (`moonshot`, `vertex`, `aiplatform`, `bedrock`).

---

## CLI Reference

### Interactive Mode

```bash
oh                   # launch interactive TUI (React+Ink terminal UI)
uv run oh            # without activating venv
```

### Non-Interactive / Scripted Mode

```bash
# Single prompt, plain text output
oh -p "Explain this codebase"

# JSON output (structured, for programmatic consumption)
oh -p "List all functions in main.py" --output-format json

# Streaming JSON events (real-time, line-delimited)
oh -p "Fix the bug in src/api.py" --output-format stream-json

# Pass a file as context
oh -p "Review this file" --file src/main.py

# Resume a previous session
oh --resume <session-id>

# Non-interactive with permission bypass (CI/automation)
oh -p "Run tests and fix failures" --permission-mode auto
```

### Key Slash Commands (inside interactive session)

```
/help              — list all 54 commands
/plan              — show or set current task plan
/commit            — stage and commit changes via git
/resume            — resume a previous session
/memory            — view or edit persistent MEMORY.md
/compact           — manually trigger context compression
/tools             — list available tools
/skills            — list loaded skills
/hooks             — show registered hooks
/agents            — list spawned subagents
/mcp               — manage MCP server connections
/config            — view or edit current configuration
/clear             — clear conversation context
/exit              — quit the session
```

---

## Architecture Overview

```
openharness/
  engine/        # Agent loop: query → stream → tool-call → loop
  tools/         # 43 built-in tools (file, shell, search, web, MCP)
  skills/        # On-demand .md skill loading
  plugins/       # Commands, hooks, agents, MCP servers
  permissions/   # Multi-level safety: path rules, command deny
  hooks/         # PreToolUse / PostToolUse lifecycle events
  commands/      # 54 slash commands
  mcp/           # Model Context Protocol client
  memory/        # Persistent cross-session MEMORY.md
  tasks/         # Background task lifecycle
  coordinator/   # Subagent spawning + team coordination
  prompts/       # System prompt assembly, CLAUDE.md injection
  config/        # Multi-layer config with migrations
  ui/            # React+Ink TUI backend protocol
```

---

## The Agent Loop (Python API)

```python
from openharness.engine import AgentLoop
from openharness.config import HarnessConfig

config = HarnessConfig.load()  # reads .openharness.json + env vars

loop = AgentLoop(config=config)

# Run a task programmatically
result = await loop.run(
    prompt="Refactor src/utils.py to use dataclasses",
    permission_mode="auto",        # bypass interactive approvals
    output_format="stream-json",   # text | json | stream-json
)

print(result.output)
print(f"Tokens used: {result.token_count}, Cost: ${result.cost:.4f}")
```

### Streaming Output

```python
import asyncio
from openharness.engine import AgentLoop
from openharness.config import HarnessConfig

async def stream_agent():
    loop = AgentLoop(config=HarnessConfig.load())

    async for event in loop.stream(prompt="Analyse main.py"):
        if event["type"] == "text":
            print(event["content"], end="", flush=True)
        elif event["type"] == "tool_use":
            print(f"\n[Tool] {event['name']}({event['input']})")
        elif event["type"] == "tool_result":
            print(f"[Result] {event['content'][:120]}")
        elif event["type"] == "done":
            print(f"\nDone. Cost: ${event['cost']:.4f}")

asyncio.run(stream_agent())
```

---

## Tools (43 Built-in)

Categories and representative tools:

| Category | Tools |
|----------|-------|
| **File I/O** | `read_file`, `write_file`, `edit_file`, `list_directory`, `find_files` |
| **Shell** | `bash`, `run_command`, `run_script` |
| **Search** | `grep`, `semantic_search`, `glob` |
| **Web** | `web_fetch`, `web_search` |
| **MCP** | Any MCP server tool via `mcp_call` |
| **Agent** | `spawn_agent`, `delegate_task` |

### Calling a Tool Directly (Python)

```python
from openharness.tools import ToolRegistry

registry = ToolRegistry()

# Read a file
result = await registry.execute("read_file", {"path": "src/main.py"})
print(result.content)

# Run a shell command
result = await registry.execute("bash", {"command": "pytest tests/ -q"})
print(result.content)

# Fetch a URL
result = await registry.execute("web_fetch", {"url": "https://example.com"})
print(result.content[:500])
```

---

## Skills (On-Demand Knowledge Loading)

Skills are `.md` files injected into the system prompt on demand. Compatible with `anthropics/skills` and `claude-code/plugins` formats.

### Installing a Skill

```bash
# Place skill file in the skills directory
cp my-skill.md ~/.openharness/skills/my-skill.md

# Or project-local
cp my-skill.md .openharness/skills/my-skill.md
```

### Writing a Custom Skill

```markdown
---
name: my-project-patterns
description: Coding patterns for MyProject
triggers:
  - use myproject conventions
  - myproject coding style
---

# MyProject Patterns

Always use `MyProject.create()` factory, never direct constructors.
Prefer async context managers for resource handling.
...
```

### Loading Skills Programmatically

```python
from openharness.skills import SkillLoader

loader = SkillLoader(skill_dirs=["~/.openharness/skills", ".openharness/skills"])

# List available skills
skills = loader.list_skills()
for skill in skills:
    print(f"{skill.name}: {skill.description}")

# Load specific skill into context
content = loader.load("my-project-patterns")
print(content)
```

---

## Memory (Persistent Cross-Session)

OpenHarness reads and writes `MEMORY.md` (and `CLAUDE.md`) for persistent context.

```bash
# View current memory
/memory

# The agent auto-updates MEMORY.md with important facts
# You can also edit it directly
vim ~/.openharness/MEMORY.md
```

```python
from openharness.memory import MemoryStore

memory = MemoryStore()

# Read persisted memory
content = memory.read()
print(content)

# Write a fact to persist across sessions
memory.append("## Project Notes\n- Always run `make lint` before committing.")
```

**CLAUDE.md**