# maxgfeller/open-harness architecture

> Architecture diagram of the GitHub repository maxgfeller/open-harness, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maxgfeller/open-harness
- Repository: https://github.com/maxgfeller/open-harness

## Overview

OpenHarness is a pnpm monorepo organized as a layered agent framework plus UI adapters and demos.

At a high level, there are four architectural tiers:

1. Core agent runtime and orchestration
2. Environment/provider abstractions for tools
3. UI integration packages for React and Vue
4. Example applications that wire the core into real chat/CLI surfaces

#### 1) Core runtime: `packages/core`

This is the central subsystem. It contains the actual agent execution engine and all orchestration logic.

##### Main primitives

- `Agent`
  - Stateless execution primitive.
  - Wraps a language model, a toolset, prompts, subagents, approvals, skills, and MCP integrations.
  - Exposes `run()` as an async generator that emits typed events while the model reasons and calls tools.
  - Does not hold conversation state internally.

- `Session`
  - Stateful wrapper around an `Agent`.
  - Owns the message history across turns.
  - Adds automatic compaction, retry, persistence, and hooks.
  - Intended for long-running interactive conversations.

- `Conversation`
  - Lighter stateful wrapper around a composed runner.
  - Primarily used when callers want to assemble middleware manually instead of using `Session`.

- `Runner`
  - Abstract async-generator execution shape underlying `Agent`.
  - Middleware transforms one runner into another.

##### Core flow

The core execution flow is:

- Input conversation history + new user input
- Agent sends request to the model
- Model may emit text/reasoning chunks or tool calls
- Tool calls are executed through registered tools
- Events stream out incrementally
- Final `done` event returns updated messages and token usage

The important architectural boundary is that the agent runtime is event-driven and streaming-first. Consumers can observe the full execution process rather than only the final answer.

##### Middleware pipeline

`packages/core/src/middleware` is a separate orchestration layer that composes behavior around the runner:

- turn tracking
- compaction
- retry
- persistence
- lifecycle hooks

The architecture here is deliberately functional: middleware wraps a runner, and `apply()` composes wrappers. This makes the execution pipeline configurable without hardcoding session behavior into the agent itself.

##### Compaction and resilience

`Session` and the compaction middleware implement two-phase context management:

- pruning older tool output
- summarizing when pruning is not enough

Retry is also separate from the model call itself:

- transient failures are retried
- retries stop once streaming output has started

This separation matters for diagramming because compaction, retry, persistence, and hooks are not part of the model/tool loop itself; they are orthogonal layers wrapped around it.

##### Tools subsystem

`packages/core/src/tools` defines built-in tools and tool factories:

- filesystem tools: read, write, edit, list, grep, delete
- bash execution tool
- local tool composition
- skill tool wrapper

A key architectural point is that tools are provider-backed:

- the tool definitions are generic
- the actual environment access comes from a provider implementation

That lets the same agent runtime run against Node filesystem/shell, virtual file systems, sandboxes, or other backends.

##### Provider abstractions

`packages/core/src/providers` contains environment abstractions used by tools:

- filesystem provider interfaces and Node implementation
- shell provider interfaces and Node implementation

This is a boundary between agent logic and execution environment. The agent does not directly depend on `fs` or shell APIs; tools depend on provider interfaces.

##### Subagents and background execution

The agent can delegate to subagents through an auto-generated `task` tool.

Architecturally, subagents are separate agent instances with:

- their own toolsets
- their own conversation state
- optional nested delegation depth control

There is also background subagent support, which adds lifecycle tools:

- `agent_status`
- `agent_cancel`
- `agent_await`

This creates a second execution plane alongside the main agent loop: the parent agent can spawn independent child runs, then observe or join them later.

##### MCP and skills

Two important extensibility surfaces are built into core:

- MCP servers
  - external tool sources connected over stdio, HTTP, or SSE
  - tools are merged into the agent’s toolset
  - lazy connection on first run

- Skills
  - markdown-based instruction packages loaded on demand
  - discovered from directories and exposed via a generated `skill` tool

These are both “tool injection” mechanisms, but they differ:
- MCP injects executable remote tools
- Skills inject contextual knowledge/instructions

##### UI stream integration

`packages/core/src/ui-stream.ts` and related stream types bridge the agent/session events into AI SDK 5’s data stream protocol.

This is how a backend agent run becomes a client-consumable chat stream.

The core emits:
- standard agent events
- custom OpenHarness data parts for subagents, compaction, retry, and turn lifecycle

That means the core is not just a backend engine; it is also the source of the structured UI event stream.

#### 2) Environment/provider boundary: `packages/provider-vfs`

This package is a separate provider implementation for virtual file systems.

It exists because core tools are environment-agnostic. `provider-vfs` supplies a non-Node filesystem backend that can be plugged into the same filesystem tool factories.

Architecturally, it demonstrates that tool execution is abstracted away from the host runtime. In diagrams, this is the “tool provider” boundary between agent logic and storage/execution environment.

#### 3) Client UI integration packages

These packages adapt the core stream semantics to frontend frameworks.

##### `packages/react`

This package provides:
- `OpenHarnessProvider`
- `useOpenHarness`
- `useSubagentStatus`
- `useSessionStatus`
- `useSandboxStatus`

It is built for AI SDK 5 chat UIs and wraps the stream produced by the server. The hook layer consumes OpenHarness-specific data parts and derives reactive UI state such as:
- active subagents
- session turn number
- compaction status
- retry state

This package is a presentation adapter, not an agent engine.

##### `packages/vue`

This is the Vue 3 / Nuxt counterpart to the React package.

It exposes the same conceptual features:
- provider
- open harness chat composable
- subagent/session status composables

The architecture mirrors the React package, but uses Vue’s provide/inject and reactivity model rather than React context/hooks.

#### 4) Example applications

The examples show how the core and UI adapters are deployed in different runtimes.

##### `examples/cli`

A Node/TypeScript terminal app.

Its architecture is:
- create an agent
- use terminal I/O for prompts and approvals
- stream agent events to the console
- show subagent activity and compaction/retry lifecycle

This example is important because it proves the core is not tied to web UI. It is a general-purpose streaming agent runtime.

##### `examples/nextjs-demo`

A Next.js app with:
- an API route at `app/api/chat/route.ts`
- React UI components for chat display
- environment configuration via `.env`

The data flow is:

- browser UI sends chat input to the Next.js API route
- route converts client messages to agent input
- route constructs or retrieves a `Conversation`
- `Conversation`/`Session` streams back a response as an HTTP response
- React client consumes the AI SDK stream and renders message parts plus OpenHarness status events

Important components:
- `chat-view.tsx`: chat container
- `message-bubble.tsx`: message rendering
- `status-bar.tsx`: session/subagent state
- `route.ts`: backend bridge into core

This app demonstrates the canonical server-client split used by the library.

##### `examples/nuxt-demo`

A Nuxt 4 version of the same architecture:

- client UI components under `app/components`
- server chat endpoint at `server/api/chat.post.ts`
- Vue composables from `@openharness/vue`

The flow is the same as Next.js, but the server and client boundaries are implemented using Nuxt conventions.

#### Cross-cutting data flow

The overall runtime flow across the repository is:

1. User interacts with a CLI, React app, or Vue app
2. UI sends user input to an API route or directly to a session/runner
3. Core `Conversation` or `Session` receives the input
4. Middleware may:
   - compact history
   - retry transient failures
   - save to persistence
   - emit lifecycle hooks
5. `Agent` calls the model through the Vercel AI SDK
6. Model may call tools:
   - filesystem tools
   - bash
   - custom tools
   - MCP tools
   - skill loader
   - task/subagent tools
7. Tool results and model output stream back as typed events
8. UI adapters convert those events into AI SDK 5 message chunks and custom data parts
9. Client components/composables derive state such as messages, subagent activity, and session status

#### Important architectural boundaries

##### Stateless vs stateful
- `Agent` is stateless and reusable
- `Session` and `Conversation` own state

##### Core runtime vs environment
- core defines behavior
- providers define access to filesystem/shell/etc.

##### Execution vs presentation
- core emits events and streams
- React/Vue packages render and track status

##### Local tools vs remote tools
- built-in tools run locally through providers
- MCP tools come from external servers

##### Instructions vs execution
- skills add contextual markdown instructions
- tools and agents execute code or actions

##### Primary technologies that affect architecture

- TypeScript across the monorepo
- pnpm workspaces for package boundaries
- Vercel AI SDK as the model/tool and streaming abstraction
- React and Vue 3 as UI integration targets
- Next.js and Nuxt as example server/client runtimes
- Node APIs for the default filesystem and shell providers

#### How to think about the diagram

If you are drawing this repository, the most accurate structure is:

- center: `@openharness/core`
- above/beside it: model providers, MCP servers, filesystem/shell providers, skill sources
- below it: session/conversation wrappers and middleware pipeline
- to one side: React and Vue adapters consuming the UI stream
- on the edges: CLI, Next.js, and Nuxt examples as integration surfaces

The most important arrows are:
- UI input → session/conversation → agent → tools/model → streamed events → UI
- session/conversation ↔ persistence store
- agent → provider-backed tools
- agent → subagents / background agents
- agent → MCP servers / skill loader

Main entry points: [`packages/core/src/agent.ts`](https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/agent.ts) (Agent), [`packages/core/src/session.ts`](https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/session.ts) (Session), [`packages/core/src/tools/create-local-tools.ts`](https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/tools/create-local-tools.ts) (Tools), [`packages/core/src/tools/create-fs-tools.ts`](https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/tools/create-fs-tools.ts) (FS tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_agent["Agent<br/>stateless runtime<br/>[agent.ts]"]
  node_runner["Runner<br/>async-generator core<br/>[runner.ts]"]
  node_session["Session<br/>stateful wrapper<br/>[session.ts]"]
  node_conversation["Conversation<br/>stateful runner<br/>[conversation.ts]"]
  node_middleware["Middleware<br/>pipeline layer<br/>[index.ts]"]
  node_tools["Tools<br/>tool factories"]
  node_fs_tools["FS tools<br/>filesystem tools<br/>[create-fs-tools.ts]"]
  node_bash_tool["Bash tool<br/>shell tool"]
  node_skill_tool["Skill tool<br/>instruction tool<br/>[skill.ts]"]
  node_mcp["MCP<br/>remote tools<br/>[mcp.ts]"]
  node_skills["Skills<br/>instruction packs<br/>[skills.ts]"]
  node_ui_stream["UI stream<br/>event bridge<br/>[ui-stream.ts]"]
end

subgraph group_providers["Environment providers"]
  node_node_provider["Node provider<br/>host backend<br/>[node.ts]"]
  node_vfs_provider["VFS provider<br/>virtual backend<br/>[vfs-provider.ts]"]
end

subgraph group_ui["UI adapters"]
  node_react_adapter["React adapter<br/>UI hooks<br/>[provider.tsx]"]
  node_vue_adapter["Vue adapter<br/>UI composables<br/>[provider.ts]"]
end

subgraph group_examples["Examples"]
  node_cli_demo["CLI demo<br/>terminal app<br/>[cli.ts]"]
  node_nextjs_demo["Next.js demo<br/>web app<br/>[route.ts]"]
  node_nuxt_demo["Nuxt demo<br/>web app<br/>[chat.post.ts]"]
end

node_session -->|"wraps"| node_agent
node_conversation -->|"wraps"| node_runner
node_middleware -->|"composes"| node_runner
node_agent -->|"uses"| node_tools
node_tools -->|"includes"| node_fs_tools
node_tools -->|"includes"| node_bash_tool
node_tools -->|"includes"| node_skill_tool
node_fs_tools -->|"backed by"| node_node_provider
node_bash_tool -->|"backed by"| node_node_provider
node_fs_tools -->|"backed by"| node_vfs_provider
node_agent -->|"merges tools"| node_mcp
node_agent -->|"loads"| node_skills
node_agent -->|"emits"| node_ui_stream
node_session -->|"uses"| node_middleware
node_react_adapter -->|"consumes"| node_ui_stream
node_vue_adapter -->|"consumes"| node_ui_stream
node_cli_demo -->|"runs"| node_agent
node_cli_demo -->|"streams"| node_session
node_nextjs_demo -->|"uses"| node_react_adapter
node_nextjs_demo -->|"calls"| node_session
node_nuxt_demo -->|"uses"| node_vue_adapter
node_nuxt_demo -->|"calls"| node_session

click node_agent "https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/agent.ts"
click node_runner "https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/runner.ts"
click node_session "https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/session.ts"
click node_conversation "https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/conversation.ts"
click node_middleware "https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/middleware/index.ts"
click node_tools "https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/tools/create-local-tools.ts"
click node_fs_tools "https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/tools/create-fs-tools.ts"
click node_bash_tool "https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/tools/create-bash-tool.ts"
click node_skill_tool "https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/tools/skill.ts"
click node_mcp "https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/mcp.ts"
click node_skills "https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/skills.ts"
click node_ui_stream "https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/ui-stream.ts"
click node_node_provider "https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/providers/node.ts"
click node_vfs_provider "https://github.com/maxgfeller/open-harness/blob/main/packages/provider-vfs/src/vfs-provider.ts"
click node_react_adapter "https://github.com/maxgfeller/open-harness/blob/main/packages/react/src/provider.tsx"
click node_vue_adapter "https://github.com/maxgfeller/open-harness/blob/main/packages/vue/src/provider.ts"
click node_cli_demo "https://github.com/maxgfeller/open-harness/blob/main/examples/cli/cli.ts"
click node_nextjs_demo "https://github.com/maxgfeller/open-harness/blob/main/examples/nextjs-demo/app/api/chat/route.ts"
click node_nuxt_demo "https://github.com/maxgfeller/open-harness/blob/main/examples/nuxt-demo/server/api/chat.post.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent,node_runner,node_session,node_conversation,node_middleware,node_tools,node_fs_tools,node_bash_tool,node_skill_tool,node_mcp,node_skills,node_ui_stream toneBlue
class node_node_provider,node_vfs_provider toneAmber
class node_react_adapter,node_vue_adapter toneMint
class node_cli_demo,node_nextjs_demo,node_nuxt_demo toneRose
```

## Components

### Core runtime

Agent execution, orchestration, tools, and streaming

- [Agent](https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/agent.ts): stateless runtime · Streaming execution primitive that calls the model and tools · `packages/core/src/agent.ts`
- [Runner](https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/runner.ts): async-generator core · Abstract execution shape that middleware composes around · `packages/core/src/runner.ts`
- [Session](https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/session.ts): stateful wrapper · Long-lived conversation state, compaction, retry, persistence, and hooks · `packages/core/src/session.ts`
- [Conversation](https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/conversation.ts): stateful runner · Lighter stateful wrapper for manually composed middleware · `packages/core/src/conversation.ts`
- [Middleware](https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/middleware/index.ts): pipeline layer · Turn tracking, compaction, retry, persistence, and lifecycle hooks · `packages/core/src/middleware/index.ts`
- [Tools](https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/tools/create-local-tools.ts): tool factories · Filesystem, shell, local composition, and skill tools · `packages/core/src/tools/create-local-tools.ts`
- [FS tools](https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/tools/create-fs-tools.ts): filesystem tools · Read, write, edit, list, grep, and delete operations · `packages/core/src/tools/create-fs-tools.ts`
- [Bash tool](https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/tools/create-bash-tool.ts): shell tool · Command execution tool backed by a shell provider · `packages/core/src/tools/create-bash-tool.ts`
- [Skill tool](https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/tools/skill.ts): instruction tool · Loads markdown-based skills on demand · `packages/core/src/tools/skill.ts`
- [MCP](https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/mcp.ts): remote tools · External tool sources merged into the agent toolset · `packages/core/src/mcp.ts`
- [Skills](https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/skills.ts): instruction packs · Discovered markdown guidance packages for the agent · `packages/core/src/skills.ts`
- [UI stream](https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/ui-stream.ts): event bridge · Converts agent and session events into AI SDK data stream parts · `packages/core/src/ui-stream.ts`

### Environment providers

Host and virtual execution backends for tools

- [Node provider](https://github.com/maxgfeller/open-harness/blob/main/packages/core/src/providers/node.ts): host backend · Default filesystem and shell provider implementation · `packages/core/src/providers/node.ts`
- [VFS provider](https://github.com/maxgfeller/open-harness/blob/main/packages/provider-vfs/src/vfs-provider.ts): virtual backend · Virtual filesystem backend for non-Node environments · `packages/provider-vfs/src/vfs-provider.ts`

### UI adapters

Framework bindings for the core event stream

- [React adapter](https://github.com/maxgfeller/open-harness/blob/main/packages/react/src/provider.tsx): UI hooks · Provider and hooks for consuming OpenHarness streams in React · `packages/react/src/provider.tsx`
- [Vue adapter](https://github.com/maxgfeller/open-harness/blob/main/packages/vue/src/provider.ts): UI composables · Provider and composables for consuming OpenHarness streams in Vue · `packages/vue/src/provider.ts`

### Examples

Reference integrations for CLI and web runtimes

- [CLI demo](https://github.com/maxgfeller/open-harness/blob/main/examples/cli/cli.ts): terminal app · Node terminal integration that streams agent runs to the console · `examples/cli/cli.ts`
- [Next.js demo](https://github.com/maxgfeller/open-harness/blob/main/examples/nextjs-demo/app/api/chat/route.ts): web app · React-based chat app with API route bridging into core · `examples/nextjs-demo/app/api/chat/route.ts`
- [Nuxt demo](https://github.com/maxgfeller/open-harness/blob/main/examples/nuxt-demo/server/api/chat.post.ts): web app · Vue-based chat app with server endpoint bridging into core · `examples/nuxt-demo/server/api/chat.post.ts`

## Connections

- Session → Agent: wraps · Session owns conversation state around a reusable agent
- Conversation → Runner: wraps · Conversation is a stateful wrapper around a composed runner
- Middleware → Runner: composes · Middleware transforms one runner into another
- Agent → Tools: uses · Agent invokes tools during model reasoning
- Tools → FS tools: includes · Local filesystem tool set
- Tools → Bash tool: includes · Shell execution tool
- Tools → Skill tool: includes · Generated tool for skill loading
- FS tools → Node provider: backed by · Filesystem tools depend on provider interfaces and implementations
- Bash tool → Node provider: backed by · Shell tool uses the shell provider
- FS tools → VFS provider: backed by · Virtual filesystem backend can replace the Node provider
- Agent → MCP: merges tools · Remote MCP tools are injected into the agent toolset
- Agent → Skills: loads · Skills provide contextual instructions for runs
- Agent → UI stream: emits · Core execution events are bridged into data stream parts
- Session → Middleware: uses · Session behavior is built from middleware layers
- React adapter → UI stream: consumes · React hooks derive state from the streamed events
- Vue adapter → UI stream: consumes · Vue composables derive state from the streamed events
- CLI demo → Agent: runs · CLI wires user input directly into core execution
- CLI demo → Session: streams · Terminal app observes session lifecycle and subagent status
- Next.js demo → React adapter: uses · Next.js UI is built on the React integration package
- Next.js demo → Session: calls · API route creates or reuses a session/conversation for chat
- Nuxt demo → Vue adapter: uses · Nuxt UI is built on the Vue integration package
- Nuxt demo → Session: calls · Server endpoint streams core output into the chat app
