Open Harness

OpenHarness

Build capable, general-purpose AI agents in code. Based on Vercel's AI SDK, inspired by Claude Code, Codex, and similar agent harnesses.

Documentation

Packages

| Package | Description | | --- | --- | | [@openharness/core](packages/core) | Agent, Session, Conversation, middleware, tools, UI stream integration | | [@openharness/provider-chatgpt](packages/provider-chatgpt) | Experimental ChatGPT/Codex OAuth model provider for ChatGPT subscription-backed local harnesses | | [@openharness/provider-vfs](packages/provider-vfs) | Virtual filesystem provider for sandboxed, in-memory, or SQLite-backed file access | | [@openharness/react](packages/react) | React hooks and provider for AI SDK 5 chat UIs | | [@openharness/vue](packages/vue) | Vue 3 composables and provider for AI SDK 5 chat UIs |

Quick Start

npm install @openharness/core @ai-sdk/openai

import { Agent, createFsTools, createBashTool, NodeFsProvider, NodeShellProvider } from "@openharness/core";
import { openai } from "@ai-sdk/openai";

const agent = new Agent({
  name: "dev",
  model: openai("gpt-5.4"),
  tools: {
    ...createFsTools(new NodeFsProvider()),
    ...createBashTool(new NodeShellProvider()),
  },
  maxSteps: 20,
});

for await (const event of agent.run([], "Refactor the auth module")) {
  if (event.type === "text.delta") process.stdout.write(event.text);
}

Multi-Turn with Sessions

import { Session } from "@openharness/core";

const session = new Session({ agent, contextWindow: 128_000 });

for await (const event of session.send("List all TypeScript files")) {
  if (event.type === "text.delta") process.stdout.write(event.text);
}

// Session remembers the conversation, handles compaction and retry
for await (const event of session.send("Now refactor the largest one")) {
  if (event.type === "text.delta") process.stdout.write(event.text);
}

Composable Middleware

import { Conversation, toRunner, apply, withTurnTracking, withCompaction, withRetry } from "@openharness/core";

const runner = apply(
  toRunner(agent),
  withTurnTracking(),
  withCompaction({ contextWindow: 200_000, model: agent.model }),
  withRetry({ maxRetries: 5 }),
);

const chat = new Conversation({ runner });
for await (const event of chat.send("Fix the bug")) { /* ... */ }

Subagents

Built-in subagents stay stateless by default, but you can now opt into:

• Dynamic subagent catalogs resolved at run time
• Resumable subagent sessions built on top of Session
• Background runs with separate run IDs and session IDs

Examples

| Example | Run | | --- | --- | | [CLI agent](examples/cli) — terminal agent with tool approval and subagents | pnpm --filter cli-demo start or pnpm --filter cli-demo start -- --chatgpt | | [Next.js chat](examples/nextjs-demo) — streaming chat with @openharness/react | pnpm --filter nextjs-demo dev | | [Nuxt chat](examples/nuxt-demo) — streaming chat with @openharness/vue | pnpm --filter nuxt-demo dev |

By default the examples use OPENAI_API_KEY. The CLI agent can instead use ChatGPT/Codex OAuth with --chatgpt.

To run them:

git clone https://github.com/MaxGfeller/open-harness.git
cd open-harness
echo "OPENAI_API_KEY=sk-..." > .env
pnpm install && pnpm build

Learn More

See the full documentation at docs.open-harness.dev for:

• Agents — stateless executors, events, configuration
• Sessions — compaction, retry, persistence, hooks
• Middleware — composable middleware and the Conversation API
• Tools — filesystem, bash, custom tools, permissions
• Subagents — nested delegation, dynamic catalogs, resumable sessions, and background execution
• MCP Servers — Model Context Protocol integration
• Skills — on-demand instruction packages
• UI Integration — React and Vue streaming

License

MIT — see [LICENSE](./LICENSE) for details.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MaxGfeller
• Source: MaxGfeller/open-harness
• License: MIT
• Homepage: https://open-harness.dev

Install and usage instructions live in the source repository linked above.