Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
7 changes: 2 additions & 5 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -1,5 +1,2 @@
libs/openagent/sandbox/vm/setup/*.sh text eol=lf
libs/openagent/sandbox/vm/setup/steps/*.sh text eol=lf
libs/hexagent/sandbox/vm/setup/*.sh text eol=lf
libs/hexagent/sandbox/vm/setup/steps/*.sh text eol=lf
libs/openagent/sandbox/vm/wsl/prebuilt/openagent-prebuilt.tar filter=lfs diff=lfs merge=lfs -text
libs/uniharness/sandbox/vm/setup/*.sh text eol=lf
libs/uniharness/sandbox/vm/setup/steps/*.sh text eol=lf
4 changes: 2 additions & 2 deletions .github/images/logo.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
16 changes: 8 additions & 8 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,10 @@ jobs:
matrix:
include:
# Core package
- working-directory: "libs/hexagent"
- working-directory: "libs/uniharness"
python-version: "3.11"
# Other packages in monorepo
# - working-directory: "libs/hexagent-cli"
# - working-directory: "libs/uniharness-cli"
# python-version: "3.11"
fail-fast: false
uses: ./.github/workflows/_lint.yml
Expand All @@ -38,16 +38,16 @@ jobs:
matrix:
include:
# Core package
- working-directory: "libs/hexagent"
- working-directory: "libs/uniharness"
python-version: "3.11"
- working-directory: "libs/hexagent"
- working-directory: "libs/uniharness"
python-version: "3.12"
- working-directory: "libs/hexagent"
- working-directory: "libs/uniharness"
python-version: "3.13"
# Other packages
# - working-directory: "libs/hexagent-cli"
# - working-directory: "libs/uniharness-cli"
# python-version: "3.11"
# - working-directory: "libs/hexagent-cli"
# - working-directory: "libs/uniharness-cli"
# python-version: "3.13"
fail-fast: false
uses: ./.github/workflows/_test.yml
Expand All @@ -59,7 +59,7 @@ jobs:
strategy:
matrix:
include:
- working-directory: "libs/hexagent"
- working-directory: "libs/uniharness"
python-version: "3.11"
fail-fast: false
uses: ./.github/workflows/_integration_test.yml
Expand Down
4 changes: 2 additions & 2 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -215,14 +215,14 @@ __marimo__/
/tmp/
*/tmp/

# HexAgent Sandbox
# UniHarness Sandbox
mounts/

# Git worktrees
.trees/

# Electron build artifact
libs/hexagent_demo/electron/dist.zip
libs/uniharness_demo/electron/dist.zip

# Vite dev-server cache
**/.vite/
Expand Down
8 changes: 4 additions & 4 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,9 @@ repos:

- repo: local
hooks:
- id: hexagent
name: format and lint hexagent
- id: uniharness
name: format and lint uniharness
language: system
entry: make -C libs/hexagent format lint
files: ^libs/hexagent/
entry: make -C libs/uniharness format lint
files: ^libs/uniharness/
pass_filenames: false
46 changes: 23 additions & 23 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Contributing to HexAgent
# Contributing to UniHarness

Thank you for your interest in contributing to HexAgent! We believe agent infrastructure should be open, vendor-neutral, and community-driven — and every contribution moves that forward.
Thank you for your interest in contributing to UniHarness! We believe agent infrastructure should be open, vendor-neutral, and community-driven — and every contribution moves that forward.

Whether you're fixing a typo, adding a new tool, implementing a computer backend, or improving documentation, you're helping build the agent harness the community needs.

Expand All @@ -16,11 +16,11 @@ Whether you're fixing a typo, adding a new tool, implementing a computer backend

```bash
# Clone the repository
git clone https://github.com/an7tang/hexagent.git
cd hexagent
git clone https://github.com/UnicomAI/UniHarness.git
cd uniharness

# Set up the core library
cd libs/hexagent
cd libs/uniharness
uv sync --group test

# Verify everything works
Expand All @@ -31,15 +31,15 @@ make test
### Project Structure

```
hexagent/
uniharness/
├── libs/
│ ├── hexagent/ # Core agent harness library
│ │ ├── hexagent/ # Package source
│ ├── uniharness/ # Core agent harness library
│ │ ├── uniharness/ # Package source
│ │ ├── tests/ # Unit + integration tests
│ │ ├── sandbox/ # Docker/VM sandbox configs
│ │ ├── Makefile # Build targets
│ │ └── pyproject.toml # Package config
│ └── hexagent_demo/ # Demo desktop application
│ └── uniharness_demo/ # Demo desktop application
│ ├── backend/ # FastAPI backend
│ ├── frontend/ # React frontend
│ └── electron/ # Electron shell
Expand All @@ -52,7 +52,7 @@ hexagent/
### Running Tests

```bash
cd libs/hexagent
cd libs/uniharness

make test # Unit tests with coverage
make integration_test # Integration tests (requires API keys)
Expand Down Expand Up @@ -94,14 +94,14 @@ pre-commit install
- Test behavior, not implementation details
- Prefer testing public APIs over internal functions
- Descriptive test names: `test_<action>_<condition>_<expected_result>`
- Unit tests in `tests/unit_tests/` — mirror the `hexagent/` directory structure
- Unit tests in `tests/unit_tests/` — mirror the `uniharness/` directory structure
- Integration tests in `tests/integration_tests/`

## Making Changes

### Before You Start

1. Check existing [issues](https://github.com/an7tang/hexagent/issues) to see if someone is already working on it
1. Check existing [issues](https://github.com/UnicomAI/UniHarness/issues) to see if someone is already working on it
2. For significant changes, open an issue first to discuss the approach
3. Fork the repository and create a feature branch

Expand All @@ -116,7 +116,7 @@ pre-commit install

3. Ensure all checks pass:
```bash
cd libs/hexagent
cd libs/uniharness
make format
make lint
make test
Expand Down Expand Up @@ -151,31 +151,31 @@ When contributing, keep these principles in mind:

### Framework-Agnostic Core

The core library (`hexagent/`) is framework-agnostic — LangChain integration lives in `hexagent/langchain/`. Don't introduce LangChain imports outside of that directory.
The core library (`uniharness/`) is framework-agnostic — LangChain integration lives in `uniharness/langchain/`. Don't introduce LangChain imports outside of that directory.

### Where to Contribute

| Area | Good for | Location |
|------|----------|----------|
| New tools | Adding capabilities to agents | `hexagent/tools/` |
| Computer implementations | New execution environments | `hexagent/computer/` |
| Web providers | New search/fetch backends | `hexagent/tools/web/providers/` |
| MCP improvements | Protocol support | `hexagent/mcp/` |
| Prompt fragments | Better agent instructions | `hexagent/prompts/fragments/` |
| Demo features | UI/UX improvements | `libs/hexagent_demo/` |
| New tools | Adding capabilities to agents | `uniharness/tools/` |
| Computer implementations | New execution environments | `uniharness/computer/` |
| Web providers | New search/fetch backends | `uniharness/tools/web/providers/` |
| MCP improvements | Protocol support | `uniharness/mcp/` |
| Prompt fragments | Better agent instructions | `uniharness/prompts/fragments/` |
| Demo features | UI/UX improvements | `libs/uniharness_demo/` |
| Tests | Improving coverage | `tests/` |
| Documentation | Clarity and examples | `README.md`, `libs/*/README.md` |

## Good First Issues

New to the project? Look for issues tagged [`good first issue`](https://github.com/an7tang/hexagent/labels/good%20first%20issue). These are scoped to be approachable without deep knowledge of the codebase.
New to the project? Look for issues tagged [`good first issue`](https://github.com/UnicomAI/UniHarness/labels/good%20first%20issue). These are scoped to be approachable without deep knowledge of the codebase.

## Reporting Issues

- Use [GitHub Issues](https://github.com/an7tang/hexagent/issues)
- Use [GitHub Issues](https://github.com/UnicomAI/UniHarness/issues)
- Include steps to reproduce, expected behavior, and actual behavior
- For bugs, include your Python version, OS, and relevant dependency versions

## Questions?

Open a [Discussion](https://github.com/an7tang/hexagent/discussions) for questions, ideas, or feedback that don't fit neatly into an issue.
Open a [Discussion](https://github.com/UnicomAI/UniHarness/discussions) for questions, ideas, or feedback that don't fit neatly into an issue.
64 changes: 32 additions & 32 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,41 +1,41 @@
<p align="center">
<img src=".github/images/logo.svg" alt="HexAgent" width="300"/>
<img src=".github/images/logo.svg" alt="UniHarness" width="300"/>
</p>

<p align="center">
<strong>Agent harness — give any LLM a computer. Ship any agent product.</strong>
</p>

<p align="center">
<a href="https://github.com/an7tang/hexagent/actions/workflows/ci.yml"><img src="https://github.com/an7tang/hexagent/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://github.com/UnicomAI/UniHarness/actions/workflows/ci.yml"><img src="https://github.com/UnicomAI/UniHarness/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"></a>
</p>

---

**HexAgent** is an open-source **agent harness**: the production runtime that gives any LLM a fully-equipped computer — terminal, filesystem, and shell — to complete tasks autonomously.
**UniHarness** is an open-source **agent harness**: the production runtime that gives any LLM a fully-equipped computer — terminal, filesystem, and shell — to complete tasks autonomously.

Unlike every other agent framework, HexAgent **separates the agent runtime from the computer it operates on**. Your agent gets a sandboxed machine; your runtime keeps its API keys, config, and source code private.
Unlike every other agent framework, UniHarness **separates the agent runtime from the computer it operates on**. Your agent gets a sandboxed machine; your runtime keeps its API keys, config, and source code private.

> **Why "harness" and not "framework"?** A framework gives you building blocks and says "assemble your own agent." A harness gives the agent a fully equipped runtime — tools, context management, safety, execution environments — so you focus on *what* the agent does, not *how* it executes. ([Read more](#agent-harness-vs-agent-framework))

## The Computer Layer

In Claude Code, Codex, and every LangChain agent, the agent runtime and the computer it controls are the same process. The agent can read its own source code, config files, and API keys. HexAgent's `Computer` protocol makes this separation explicit and pluggable — swap execution environments without changing a line of agent code.
In Claude Code, Codex, and every LangChain agent, the agent runtime and the computer it controls are the same process. The agent can read its own source code, config files, and API keys. UniHarness's `Computer` protocol makes this separation explicit and pluggable — swap execution environments without changing a line of agent code.

```python
from hexagent import create_agent
from hexagent.computer import LocalNativeComputer, LocalVM, RemoteE2BComputer
from uniharness import create_agent
from uniharness.computer import LocalNativeComputer, LocalVM, RemoteE2BComputer

# Development — run on your machine
agent = await create_agent(model="anthropic/claude-sonnet-4-20250514", computer=LocalNativeComputer())
agent = await create_agent(model="openai:gpt-5.5", computer=LocalNativeComputer())

# Security-sensitive — sandboxed VM (Lima on macOS, WSL on Windows)
agent = await create_agent(model="anthropic/claude-sonnet-4-20250514", computer=LocalVM())
agent = await create_agent(model="openai:gpt-5.5", computer=LocalVM())

# Production / multi-tenant — isolated cloud sandbox
agent = await create_agent(model="anthropic/claude-sonnet-4-20250514", computer=RemoteE2BComputer(api_key="..."))
agent = await create_agent(model="openai:gpt-5.5", computer=RemoteE2BComputer(api_key="..."))
```

```
Expand Down Expand Up @@ -64,19 +64,19 @@ Implement the `Computer` protocol to add your own — Docker, Kubernetes pods, o
## Quick Start

```bash
pip install hexagent
pip install uniharness
```

### Minimal example

```python
import asyncio
from hexagent import create_agent
from hexagent.computer import LocalNativeComputer
from uniharness import create_agent
from uniharness.computer import LocalNativeComputer

async def main():
async with await create_agent(
model="anthropic/claude-sonnet-4-20250514", # or any LLM
model="openai:gpt-5.5", # or any LLM
computer=LocalNativeComputer(),
) as agent:
result = await agent.ainvoke({
Expand All @@ -90,12 +90,12 @@ asyncio.run(main())
### Use any model

```python
from hexagent import create_agent, ModelProfile
from hexagent.computer import LocalNativeComputer
from uniharness import create_agent, ModelProfile
from uniharness.computer import LocalNativeComputer

# DeepSeek, Qwen, Llama, Mistral — anything OpenAI-compatible
model = ModelProfile(
model="deepseek/deepseek-chat",
model="deepseek:deepseek-v4-flash",
base_url="https://api.deepseek.com/v1",
api_key="your-key",
context_window=64000,
Expand All @@ -107,11 +107,11 @@ agent = await create_agent(model=model, computer=LocalNativeComputer())
### Add subagents, MCP servers, web tools

```python
from hexagent import create_agent, AgentDefinition
from hexagent.computer import LocalNativeComputer
from uniharness import create_agent, AgentDefinition
from uniharness.computer import LocalNativeComputer

agent = await create_agent(
model="anthropic/claude-sonnet-4-20250514",
model="openai:gpt-5.5",
computer=LocalNativeComputer(),
# Subagents for parallel specialized work
agents={
Expand All @@ -134,17 +134,17 @@ agent = await create_agent(
### Run in a cloud sandbox

```python
from hexagent import create_agent
from hexagent.computer import RemoteE2BComputer
from uniharness import create_agent
from uniharness.computer import RemoteE2BComputer

# Fully isolated cloud execution — no local risk
agent = await create_agent(
model="openai/gpt-4o",
model="openai:gpt-4o",
computer=RemoteE2BComputer(api_key="your-e2b-key"),
)
```

See [`libs/hexagent/README.md`](libs/hexagent/README.md) for the full API reference.
See [`libs/uniharness/README.md`](libs/uniharness/README.md) for the full API reference.

## What Can You Build?

Expand All @@ -157,7 +157,7 @@ One harness powers four product types — no other agent SDK does this:
| **Cowork** | Desktop agent that works on your local files, folders, and apps — completing knowledge work tasks autonomously while you steer | [Claude Cowork](https://www.anthropic.com/product/claude-cowork) |
| **Autonomous Agent** | Headless agent that runs tasks end-to-end without supervision | [OpenClaw](https://github.com/openclaw/openclaw), [Devin](https://devin.ai/) |

The [`hexagent_demo`](libs/hexagent_demo/) app ships with ready-to-use **Chat** and **Cowork** modes as concrete examples.
The [`uniharness_demo`](libs/uniharness_demo/) app ships with ready-to-use **Chat** and **Cowork** modes as concrete examples.

## Features

Expand All @@ -178,9 +178,9 @@ The [`hexagent_demo`](libs/hexagent_demo/) app ships with ready-to-use **Chat**
- **Web providers** — Pluggable search (Tavily/Brave) and fetch (Jina/Firecrawl) backends
- **Composable, not magical** — Small modules with explicit I/O. No hidden state. Every piece is testable and replaceable.

### How HexAgent Compares
### How UniHarness Compares

| | HexAgent | Claude Agent SDK | LangChain Deep Agents |
| | UniHarness | Claude Agent SDK | LangChain Deep Agents |
|---|---|---|---|
| **Open source** | MIT | MIT | MIT |
| **Model-agnostic** | Any LLM | Claude only | Any LLM |
Expand Down Expand Up @@ -243,23 +243,23 @@ The AI agent ecosystem has converged on a [clear taxonomy](https://blog.langchai
| **What it is** | Building blocks (tools, prompts, memory) | Durable execution engine | Complete agent operating system |
| **Analogy** | A toolkit | A job scheduler | An OS for the agent |
| **You build** | Everything from scratch | Orchestration logic | Your agent's purpose |
| **Examples** | LangChain, CrewAI, Semantic Kernel | LangGraph, Temporal | HexAgent, Claude Code, OpenHands |
| **Examples** | LangChain, CrewAI, Semantic Kernel | LangGraph, Temporal | UniHarness, Claude Code, OpenHands |

A framework says: *"Here are components. Assemble your agent."*

A harness says: *"Here is a fully equipped computer. Tell the agent what to do."*

HexAgent is a harness you can embed as a library — giving you the batteries-included runtime of products like Claude Code, with the flexibility to build any agent product you want.
UniHarness is a harness you can embed as a library — giving you the batteries-included runtime of products like Claude Code, with the flexibility to build any agent product you want.

## Project Structure

| Package | Description |
|---------|-------------|
| [`libs/hexagent`](libs/hexagent/) | **Core framework** — the agent harness library ([API docs](libs/hexagent/README.md)) |
| [`libs/hexagent_demo`](libs/hexagent_demo/) | **Demo app** — desktop Chat + Cowork built on the framework ([setup guide](libs/hexagent_demo/README.md)) |
| [`libs/uniharness`](libs/uniharness/) | **Core framework** — the agent harness library ([API docs](libs/uniharness/README.md)) |
| [`libs/uniharness_demo`](libs/uniharness_demo/) | **Demo app** — desktop Chat + Cowork built on the framework ([setup guide](libs/uniharness_demo/README.md)) |

```
libs/hexagent/hexagent/
libs/uniharness/uniharness/
├── computer/ # Computer protocol — local, VM, or cloud (E2B) execution
├── harness/ # Runtime augmentation: environment, permissions, skills, reminders
├── tools/ # Built-in tools: CLI, web, subagents, skills, todos
Expand Down
Loading
Loading