Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.open-harness.dev/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Create an Agent

1

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-...
2

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,
});
3

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:
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
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.