Quickstart

This guide walks you through creating a simple agent that can read files and run shell commands.

Create an Agent

Set up your project

Create a new project and install dependencies:

mkdir my-agent && cd my-agent
npm init -y
npm install @openharness/core @ai-sdk/openai

Set your API key:

export OPENAI_API_KEY=sk-...

Define the agent

Create an agent.ts file:

agent.ts

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

const fsTools = createFsTools(new NodeFsProvider());
const { bash } = createBashTool(new NodeShellProvider());

const agent = new Agent({
  name: "dev",
  model: openai("gpt-5.4"),
  systemPrompt: "You are a helpful coding assistant.",
  tools: { ...fsTools, bash },
  maxSteps: 20,
});

Run the agent

Add a simple loop that streams the agent’s output:

agent.ts

import type { ModelMessage } from "ai";

let messages: ModelMessage[] = [];

for await (const event of agent.run(messages, "What files are in this directory?")) {
  switch (event.type) {
    case "text.delta":
      process.stdout.write(event.text);
      break;
    case "tool.start":
      console.log(`\nCalling ${event.toolName}...`);
      break;
    case "done":
      messages = event.messages;
      break;
  }
}

Add a Session for Multi-Turn Chat

For interactive conversations with automatic compaction and retry, wrap the agent in a Session:

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

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

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

// Second turn — session remembers the conversation
for await (const event of session.send("Now refactor the largest one")) {
  if (event.type === "text.delta") process.stdout.write(event.text);
}

Run the Examples

To run the examples, first clone and build the repository:

git clone https://github.com/MaxGfeller/open-harness.git
cd open-harness
pnpm install && pnpm build

Then pick an example:

CLI
Next.js
Nuxt

An interactive terminal agent with tool approval prompts and subagent display:

pnpm --filter cli-demo start

To use ChatGPT/Codex OAuth instead of OPENAI_API_KEY:

pnpm --filter cli-demo start -- --chatgpt

A chat app with streaming, tool visualization, and subagent status:

cp examples/nextjs-demo/.env.example examples/nextjs-demo/.env
# Edit .env and add your OPENAI_API_KEY
pnpm --filter nextjs-demo dev

Then open http://localhost:3000.

The same chat experience built with Vue 3 and Nuxt 4:

pnpm --filter nuxt-demo dev

Then open http://localhost:3000.

By default the examples use OPENAI_API_KEY. Create a .env file in the repo root:

echo "OPENAI_API_KEY=sk-..." > .env

The CLI example can instead use ChatGPT/Codex device login with --chatgpt.

Next Steps

Agents

Learn about the Agent API, events, and configuration options.

Sessions

Add compaction, retry, and persistence for multi-turn conversations.

Tools

Explore built-in tools and learn to create custom ones.

Getting Started

Core Concepts

Tools

Advanced

UI Integration

Resources

Create an Agent

Add a Session for Multi-Turn Chat

Run the Examples

Next Steps

Agents

Sessions

Tools

​Create an Agent

​Add a Session for Multi-Turn Chat

​Run the Examples

​Next Steps

Agents

Sessions

Tools

Create an Agent

Add a Session for Multi-Turn Chat

Run the Examples

Next Steps