oar README

The project's README from github.com/botiverse/oar. As one markdown file: README.md.

OAR - programming interface for all agent harnesses

OAR logo

OAR (Open Agent Runtime) is a provider-independent programming interface for coding-agent runtimes: a solid foundation for building agent workspaces and other applications.

Delete harness logic and focus on outcomes and UX.

Supported runtimes


Antigravity
Claude Code
Codex
Cursor
Grok Build
Kimi Code
Pi

Docs

Read To answer
docs/design/ Why oar exists and which design problems it treats as load-bearing
docs/spec/ Record-stream and query contracts
Conversation projection Build a conversation UI from requests, responses and native messages
docs/spec/inventory.md Independent native skills, MCP server and tool queries
docs/spec/subagents.md Subagents on any runtime, from a host or over oar mcp
docs/spec/update.md Update checks and upgrades through each runtime's own updater
docs/runtimes/ What each runtime says natively and how oar maps it
docs/development.md Working in this repo: validate changes, add a runtime, conventions
packages/cli/ The oar executable, published separately as @botiverse/oar-cli
docs/design/system.md How the library, evidence layer, projections, and continuation form one agent-facing system
docs/prior-arts/feature-comparison.md Surveyed projects compared by concrete features and evidence
docs/design/decisions.md Design decisions, their evidence, and conditions for reconsideration
docs/design/roadmap.md Which system improvements are next, and what evidence gates them

Library

import { promptAndWait, runtimes } from "@botiverse/oar";

const grok = runtimes.require("grok");
const installation = await grok.installation?.();

if (installation?.kind === "available") {
  const session = await grok.session(installation, { cwd: process.cwd() });
  session.events((event) => {
    switch (event.kind) {
      case "text_delta": process.stdout.write(event.text); break;
      case "tool_call_started": console.log(`[${event.tool}]`); break;
      case "turn_ended": console.log(event.outcome.kind); break;
    }
  });
  const run = await promptAndWait(session, "Inspect this repository", { timeoutMs: 120_000 });
  console.log(run.kind === "rejected" ? run.code : run.outcome);
  await session.dispose();
}

events() is the flat, attributed reading of the session: one Event per fact (native user message echoes, text, reasoning, background tasks, tool call start / progress / end, turn start and end, usage, model, effort, compaction, retry, app requests, control rejections, the process exit), with seq and agentPath on each. Pass { coalesceText: true } to get text in blocks instead of pieces. When the runtime's own frame matters, session.rawEvents() and session.records() expose the underlying record stream with every native payload verbatim.

CLI

npx @botiverse/oar-cli list
oar run claude "What does this repo do?" --record run.jsonl

ESM-only, requires Node.js 24+, Apache-2.0.

oar (botiverse/oar)

agent-runtime
Searching Database…

198 ·GitHub
Oar
What is this?OAR (Open Agent Runtime) is a provider-independent programming interface for coding-agent harnesses like Claude Code, Codex and Cursor, so you build one integration instead of writing separate harness logic for each agent.
Is this a library or a command-line tool?Both: oar is a library you import to read and query agent sessions, and it also ships a separate CLI executable published as @botiverse/oar-cli.
How do I start using oar in my project?Pull in the oar library and call session.events() to get a flat, normalized read of a coding-agent session, or install the @botiverse/oar-cli package to drive runtimes from the command line.
What do I need to run the CLI?You need Node.js 24 or newer; the CLI package is ESM-only, so older Node setups or CommonJS-only projects won't be able to load it directly.
Does oar replace my existing coding agents?No — oar doesn't install or run the agents itself, it reads and controls the harnesses you already have (Claude Code, Codex, Cursor, etc.), and even updates route through each runtime's own updater.
Which coding agents does oar support out of the box?oar currently supports Antigravity, Claude Code, Codex, Cursor, Grok Build, Kimi Code, and Pi as runtimes.
What do I get back from events()?events() returns a flat list of Event objects — one per fact such as text, tool call start/progress/end, turn start/end, usage, model, retries, or process exit — each tagged with a seq number and agentPath.
What's the difference between events() and rawEvents()?events() is oar's normalized, flat view of a session, while session.rawEvents() and session.records() expose the underlying native record stream with every runtime-specific payload verbatim for cases where the raw frame matters.
Can I run subagents across different runtimes?Yes — oar supports subagents on any supported runtime, driven either from a host application or over 'oar mcp', as described in docs/spec/subagents.md.
What are similar projects?openrig, headroom, OpenAgentCore, superpowers-zh, context7, testsprite-cli, mistral-vibe, copperhead
Which topics is it in?agent-runtime, harness-engineering, subagents, agentic-coding, agent-harness, cli-tool, cursor, sdk, agents, coding-agent, mcp-server, codex
Creator
botiverse
Size
7.6 MB
Stars
198
Updated
CommitOct 19Releasev0.68.1Oct 19
Age
2mo
Commits · 90 Days