How maxgfeller/open-harness works
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: agent.ts Agent · session.ts Session · create-local-tools.ts Tools · create-fs-tools.ts FS tools
Components 19
Core runtime
Agent execution, orchestration, tools, and streaming
- Agent · Streaming execution primitive that calls the model and tools
packages/core/src/agent.ts - Runner · Abstract execution shape that middleware composes around
packages/core/src/runner.ts - Session · Long-lived conversation state, compaction, retry, persistence, and hooks
packages/core/src/session.ts - Conversation · Lighter stateful wrapper for manually composed middleware
packages/core/src/conversation.ts - Middleware · Turn tracking, compaction, retry, persistence, and lifecycle hooks
packages/core/src/middleware/index.ts - Tools · Filesystem, shell, local composition, and skill tools
packages/core/src/tools/create-local-tools.ts - FS tools · Read, write, edit, list, grep, and delete operations
packages/core/src/tools/create-fs-tools.ts - Bash tool · Command execution tool backed by a shell provider
packages/core/src/tools/create-bash-tool.ts - Skill tool · Loads markdown-based skills on demand
packages/core/src/tools/skill.ts - MCP · External tool sources merged into the agent toolset
packages/core/src/mcp.ts - Skills · Discovered markdown guidance packages for the agent
packages/core/src/skills.ts - UI stream · 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 · Default filesystem and shell provider implementation
packages/core/src/providers/node.ts - VFS provider · 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 · Provider and hooks for consuming OpenHarness streams in React
packages/react/src/provider.tsx - Vue adapter · Provider and composables for consuming OpenHarness streams in Vue
packages/vue/src/provider.ts
Examples
Reference integrations for CLI and web runtimes
- CLI demo · Node terminal integration that streams agent runs to the console
examples/cli/cli.ts - Next.js demo · React-based chat app with API route bridging into core
examples/nextjs-demo/app/api/chat/route.ts - Nuxt demo · Vue-based chat app with server endpoint bridging into core
examples/nuxt-demo/server/api/chat.post.ts
Connections 22
- 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