Skip to content

MaxGfeller/open-harness

Repository files navigation

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 Agent, Session, Conversation, middleware, tools, UI stream integration
@openharness/react React hooks and provider for AI SDK 5 chat UIs
@openharness/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 — terminal agent with tool approval and subagents pnpm --filter cli-demo start
Next.js chat — streaming chat with @openharness/react pnpm --filter nextjs-demo dev
Nuxt chat — streaming chat with @openharness/vue pnpm --filter nuxt-demo dev

All examples require an OPENAI_API_KEY. 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 for details.