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

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

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 for details.