HexAgent — Summary

HexAgent is an open-source Python agent harness library from UnicomAI that explicitly separates the agent's runtime from the "computer" it operates on, preventing the agent from reading its own API keys, source code, or harness configuration. Rather than assembling an agent from building blocks, HexAgent provides a batteries-included operating environment: 12+ built-in tools, 3-phase automatic context compaction, a pluggable Computer protocol (local shell, local VM via Lima/WSL, or cloud sandbox via E2B), native MCP support across stdio/SSE/HTTP, and subagent orchestration supporting both foreground (blocking) and background (parallel) child agents. A single create_agent() call produces an agent that can run as a CLI coding agent, chatbot, Cowork-style desktop assistant, or fully autonomous headless agent. HexAgent explicitly positions itself against LangChain Deep Agents and the Claude Agent SDK, claiming the key differentiator is the runtime-computer isolation boundary. Compared to seeds, HexAgent most resembles claude-flow's MCP-anchored approach (own runtime, subagents as code-classes) but abandons the slash-command/skill-md surface entirely — the API is pure Python and there are no CLAUDE.md-injected behavioral rules; the whole framework is a composable library.

differs_from_seeds: Closest to claude-flow in that it ships a full runtime with subagents defined as code-level constructs (AgentDefinition Python objects), not persona-md files. Unlike claude-flow's 305-tool MCP server, HexAgent's MCP support is a client (consume any MCP server); there is no bundled MCP server to install. Unlike superpowers or spec-driver (skills-only, Claude Code context injection), HexAgent has no CLAUDE.md primitives whatsoever — the harness is a Python library consumed programmatically, not a Claude Code plugin.

HexAgent — Overview

Origin

HexAgent is developed under UnicomAI (GitHub: UnicomAI/hexagent). The README cites inspiration from Adam Wolff's QCon 2025 talk on Claude Code's architecture and a growing consensus around the "harness" vs "framework" distinction articulated in an Inngest blog post ("your agent needs a harness, not a framework"). The project targets Python 3.11+, is at pre-experimental status (0.0.x), and uses uv for dependency management.

Philosophy

The manifesto centers on three words: "Give the agent a computer."

Key philosophical positions (verbatim from README):

"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."

"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."

"Composable, not magical — Small modules with explicit I/O. No hidden state. Every piece is testable and replaceable."

The AGENTS.md (developer instructions) adds:

"Testability: Every module must be testable in isolation without complex mocks." "Idempotency: Operations should be safely repeatable. Retries must not cause unintended side effects."

Product Types Supported

From one harness:

1. CLI Coding Agent — terminal-native, analogous to Claude Code / Gemini CLI
2. Chatbot — conversational assistant with tool use
3. Cowork — desktop agent working on local files (analogous to Claude Cowork)
4. Autonomous Agent — headless, long-running

Taxonomy Position

HexAgent explicitly uses the LangChain taxonomy (Framework / Runtime / Harness) and places itself in the Harness tier alongside Claude Code and OpenHands — not the Framework tier (LangChain, CrewAI) or Runtime tier (LangGraph, Temporal).

HexAgent — Architecture

Distribution

• Type: Python library (pip install hexagent)
• License: MIT
• Runtime: Python 3.11+, uv recommended
• Repository structure: monorepo with libs/hexagent (core) and libs/hexagent_demo (demo app)

Directory Tree (core library)

libs/hexagent/hexagent/
├── computer/       # Computer protocol — LocalNativeComputer, LocalVM, RemoteE2BComputer
├── harness/        # Runtime augmentation: environment, permissions, skills, reminders
├── tools/          # Built-in tools: CLI (Bash, Read, Write, Edit, Glob, Grep), web, subagents, skills, todos
├── prompts/        # Composable system prompt from 35+ Markdown fragments with variable substitution
├── mcp/            # MCP client (stdio, SSE, HTTP)
├── langchain/      # LangChain/LangGraph integration (isolated — zero leakage into core)
└── types.py        # Framework-agnostic types: ToolResult, AgentContext, CLIResult

Computer Protocol (key differentiator)

Three implementations:

The Computer protocol is pluggable — implement your own for Docker, Kubernetes pods, or any remote target.

Middleware Pipeline

Pre-model hooks in order:

1. Context compaction (3-phase automatic)
2. Permission gating (multi-layer safety validation before tool execution)
3. Skill injection (filesystem-based SKILL.md extensions, lazy loading)
4. Image adaptation
5. Dynamic <system-reminder> injection

Target AI Tools

• Any LLM via OpenAI-compatible endpoint (Anthropic, OpenAI, DeepSeek, Qwen, Llama, Mistral)
• LangChain/LangGraph integration isolated in hexagent.langchain module
• Observability: LangSmith, Braintrust

Config Files

• AGENTS.md — developer/agent instructions (read by Claude Code, Codex, etc.)
• CLAUDE.md — project instructions
• pyproject.toml — Python package config
• libs/hexagent/hexagent/ — library source (no YAML/TOML config file for the harness itself; configured programmatically)

HexAgent — Components

Built-in Tools (12+)

From hexagent/tools/__init__.py:

Skills System

• Discovery: Filesystem-based — looks for directories containing SKILL.md with YAML frontmatter
• Loading: Lazy (on-demand, not all at once)
• Format: SKILL.md with name, description, whenToUse frontmatter + markdown instructions
• Scripts: Optional scripts/ directory for pre-built scripts referenced by SKILL.md

Subagent Definition

Subagents are defined as AgentDefinition Python objects at call site:

agents={
    "researcher": AgentDefinition(
        description="Deep-dives into codebases",
        tools=["Read", "Glob", "Grep", "WebSearch"],
        model="fast",
    ),
}

Not persona-md files — purely code-level definitions.

MCP Client

• Protocols supported: stdio, SSE, HTTP
• MCP servers added at create_agent() time via mcp_servers dict
• HexAgent is an MCP consumer, not a bundled MCP server

Computer Abstraction

• LocalNativeComputer — runs tools on the host machine
• LocalVM — Lima (macOS) or WSL (Windows) sandboxed VM
• RemoteE2BComputer — E2B cloud sandbox for multi-tenant production use

Middleware / Hooks

• Permission gating: multi-layer safety rules before every tool call
• System reminders: rule-based <system-reminder> injections before model calls
• 3-phase context compaction: automatic, built into the harness
• Image adaptation: preprocesses image inputs for model compatibility

Commands

None. HexAgent has no slash-commands, no CLAUDE.md behavioral hooks. The surface is purely Python API.

Hooks (Claude Code lifecycle)

None. No settings.json hooks, no hooks/hooks.json. HexAgent is not a Claude Code plugin.

Templates

None in the traditional sense. The prompts/ directory contains 35+ Markdown fragments that compose the system prompt programmatically.

HexAgent — Uniqueness

differs_from_seeds

HexAgent is closest to claude-flow in that both ship a full agent runtime with subagents defined as code constructs rather than YAML or persona-md files. However, claude-flow bundles a 305-tool MCP server as its primary interface and stores state in SQLite + HNSW vector; HexAgent has no bundled MCP server and stores no persistent state — it is a client library. HexAgent's decisive architectural differentiator versus every seed is the Computer protocol: the abstraction that separates the agent's runtime from the machine it controls, which no seed implements. Compared to superpowers/spec-driver/BMAD (skills-only frameworks injected via CLAUDE.md), HexAgent has zero CLAUDE.md primitives — it is a Python library, not a Claude Code plugin. Compared to agent-os/claude-conductor (markdown scaffold frameworks), HexAgent provides actual execution infrastructure rather than template documents. The isolation story (LocalVM / RemoteE2BComputer) goes further than any seed.

Positioning

HexAgent positions itself as the developer SDK for building agent products (Claude Code clones, Cowork apps, autonomous agents, chatbots) rather than a workflow guide for using Claude Code. It targets Python developers building their own agent applications, not knowledge workers using Claude Code.

Observable Failure Modes

• No behavioral defaults: No workflow enforcement, no TDD requirement, no spec-first gate. Entirely up to the developer.
• 0.0.x pre-experimental: Backward compatibility explicitly disclaimed. APIs can break at any commit.
• No cross-session memory: Each invocation is stateless unless the developer explicitly persists and re-injects conversation history.
• LangChain dependency under the hood: Despite the "vendor-agnostic core" claim, LangGraph is the execution engine (isolated in hexagent.langchain/ but present).
• No audit log: No framework-maintained record of what the agent did or decided.
• Demo app unclear: The hexagent_demo exists but there is no clear documentation of its UI surface or how to run it beyond the README mention.