API Reference

Find the export you need, the package it comes from, and the page that shows it running. Every package needs Node.js 22.12 or later; the tool rows below say what else each one needs.

Exports

Export	Package	What it’s for	Page
`workflow`, `stage`, `person`, `briefFromFile`	`@obversa/runtime`	Declare a team	Runtime
`formatEvent`	`@obversa/runtime`	Print one run event	Runtime
`pipeline`, `dag`, `sequence`, `parallel`, `loop`	`@obversa/runtime`	The shapes a workflow takes	Runtime
`fnJob`, `agentJob`, `commandJob`, `gateJob`, `prove`	`@obversa/runtime`	The steps	Runtime
`isolated`, `writeScope`	`@obversa/runtime`	A step in its own worktree	Workspace
`passed`, `failed`, `all`, `any`, `not`, `predicate`, `quorum`	`@obversa/runtime`	Conditions on a step	A command decides the path
`agentCheck`, `confidenceCondition`, `minConfidence`	`@obversa/runtime`	Scored conditions	Evals
`reviewPanel`	`@obversa/runtime`	Several reviewers, a threshold	A review panel with a threshold
`tournament`	`@obversa/runtime`	Candidates, a judge, one winner	Three candidates, one winner
`kickback`, `revisionRequest`	`@obversa/runtime`	Fail a step with findings	Feedback loops
`approval`	`@obversa/runtime`	A person’s decision as a step	A person decides
`createCallbackGate`, `createCallbackClient`, `createStoredCallbackClient`, `replayCallbackClient`, `directRouter`	`@obversa/runtime`	A question with a typed answer	Callback gates
`createApprovalCallbackGate`, `resolveApproval`, `writeProofArtifact`, `createAcceptedResultRecord`, `resolveAcceptedResult`, `createProofCache`	`@obversa/runtime`	Bind a decision to exact bytes	Proof-bound acceptance and approval
`run`	`@obversa/runtime`	Run a job and record it	Running
`team`, `teamGraphType`, `projectTeamRooms`	`@obversa/runtime`	Named members who talk	Team conversation
`compileGraph`, `resolveGraphPlan`, `dagGraphType`, `convergence`	`@obversa/runtime`	Graph forms and plans	Outside graph types
`persistRunDefinition`, `loadRunDefinition`, `createGraphExecutor`	`@obversa/runtime`	Store and execute a graph	Graph executor
`readRunPreflight`, `interruptRunPreflight`, `preflight`	`@obversa/runtime`	Engine checks before the first step	Graph executor
`createLocalRunStorage`	`@obversa/runtime/storage/local`	The on-disk event and artifact store	Events and artifacts
`createGitWorktreeProvider`	`@obversa/runtime`	Capture, verify, lease, fork	Workspace contract
`ground`, `curate`, `consolidate`	`@obversa/runtime/memory`	Memory through your own functions	Memory mechanics
`MockEngine`, `defineGraphDefinition`, `runGraphTypeConformance`	`@obversa/runtime/testing`	Run offline, prove a form	Runtime
`outcomeFromAgentText`, `assertDistinctSeats`	`@obversa/runtime/workflow-support`	Read a reviewer’s reply, check families	Runtime
`startSupervisedRun`, `resumeSupervisedRun`, `readSupervisedRunStatus`	`@obversa/runner`	A run under a watchdog	Supervised local runs
`validateAgentResult`, `finalResultPart`, `modelIdentity`	`@obversa/api`	The engine contract	Safe node attempts
`runEngineConformance`, `runMemoryConformance`	`@obversa/api/testing`	Check an adapter	API
`runChild`	`@obversa/core`	One child process to a deadline	Core
`resolveCommandExecutable`, `runOwnedCommand`	`@obversa/core/command`	Find and run a tool	Core
`writerReviewerPair`, `thresholdPanel`, `featureDelivery`	`@obversa/builtin-workflows`	Ready-made teams	Built-in Workflows
`runSurface`, `startSurface`, `openSurfaceUrl`, `parseFramedResult`	`@obversa/surface`	One page for one decision	Surface
`reviewDiff`, `parseUnifiedDiff`, `appendToThread`	`@obversa/surface-diff`	Review a diff in a browser	Surface Diff
`claude`, `ClaudeCliEngine`	`@obversa/engine-claude-cli`	Claude Code as a seat	Claude CLI Engine
`codex`, `CodexEngine`	`@obversa/engine-codex-cli`	Codex as a seat	Codex CLI Engine
`devin`, `DevinCliEngine`	`@obversa/engine-devin-cli`	Devin as a seat	Devin CLI Engine
`GrokCliEngine`	`@obversa/engine-grok-cli`	Grok CLI as an engine	Grok CLI Engine
`opencode`, `OpenCodeCliEngine`	`@obversa/engine-opencode-cli`	OpenCode as a seat	OpenCode CLI Engine
`AgentSdkEngine`	`@obversa/engine-claude-agent-sdk`	The Claude Agent SDK as an engine	Claude Agent SDK Engine
`AnthropicApiEngine`	`@obversa/engine-anthropic-api`	The Anthropic API as an engine	Anthropic API Engine
`JevApiEngine`	`@obversa/engine-jev-api`	Typed questions about a run	Jev API Engine
`mastra`, `MastraEngine`	`@obversa/engine-mastra`	A Mastra agent as a seat	Mastra Engine
`openaiAgent`, `OpenAIAgentsEngine`	`@obversa/engine-openai-agents`	An OpenAI Agents SDK agent as a seat	OpenAI Agents Engine
`openGitMemory`, `openReasoningRecord`	`@obversa/memory-git`	Memory in Git, reasoning in commits	Git Memory
`createSimpleMemory`	`@obversa/memory-simple`	Memory in one process	Simple Memory
`openMarkdownCorpus`	`@obversa/memory-markdown`	Search your Markdown files	Markdown Memory
`webhookNotifier`	`@obversa/notify-webhook`	A message per run event	Webhook Notifications

Import from the package named in the row:

examples/teams/writer-reviewer-pair.ts (excerpt)

import { claude } from '@obversa/engine-claude-cli';
import { codex } from '@obversa/engine-codex-cli';
import { run } from '@obversa/runtime';
import { briefFromFile, stage, workflow, type TeamSeat } from '@obversa/runtime';

Tools

Each row says what the tool is, what you need installed, and where its home is.

Claude Code. @obversa/engine-claude-cli runs each request in a fresh Claude Code process. You need Claude Code installed and signed in. Home: claude.com/code.
Codex CLI. @obversa/engine-codex-cli runs each request in a fresh Codex CLI process. You need the Codex CLI installed and signed in. Home: github.com/openai/codex.
Devin CLI. @obversa/engine-devin-cli runs each request in a fresh Devin process with your own sign-in and settings. You need the Devin CLI installed and signed in. See Devin CLI Engine.
OpenCode CLI. @obversa/engine-opencode-cli runs each request in a fresh OpenCode process, with your own OpenCode login and settings. You need OpenCode 1.18.23 installed and signed in to your model’s provider. Home: opencode.ai.
Grok CLI. @obversa/engine-grok-cli runs each request in a fresh Grok CLI process, with your own Grok login and settings. You need Grok CLI 1.0.44 installed and signed in. Home: docs.x.ai/build/cli/headless-scripting.
Anthropic API. @obversa/engine-anthropic-api sends each request to the Anthropic API. You need an Anthropic API key. Home: console.anthropic.com.
Claude Agent SDK. @obversa/engine-claude-agent-sdk runs each request through the Claude Agent SDK. You need Claude Code signed in on the same machine, because the SDK uses its sign-in. Home: github.com/anthropics/claude-agent-sdk.
Jev API. @obversa/engine-jev-api answers structured questions about a run’s recorded state. It never reads or edits files. You need a Jev endpoint and an API key. See Jev API Engine.
Mastra. @obversa/engine-mastra runs an agent you built with Mastra, one call to the agent’s own generate per request. You need @mastra/core and whatever your agent needs, such as its model provider’s key. See Mastra Engine.
OpenAI Agents SDK. @obversa/engine-openai-agents runs an agent you built with the OpenAI Agents SDK, one call to the SDK’s runner per request. You need @openai/agents, zod and whatever your agent needs, such as an OpenAI API key. See OpenAI Agents Engine.
In-process memory. @obversa/memory-simple keeps memory inside one process. You need nothing else. Home: Simple Memory.
Git-backed memory. @obversa/memory-git stores memory in private Git references, so nothing lands in the working tree, and can write a stage’s reasoning into the commit that carries its change. You need Git installed. Home: Git Memory.
Markdown search. @obversa/memory-markdown selects ranked passages from a local folder of Markdown files and gives ground the selected files through a read-only memory view. You need nothing else. Home: Markdown Memory.
Webhook notifications. @obversa/notify-webhook posts one message per interesting run event to a URL you supply; the body carries a text field, so a Slack, Discord or Teams incoming webhook shows it with no code of its own. You need a URL to post to. Home: Webhook Notifications.
The review command. @obversa/surface-diff ships obversa-review, which opens a diff for inline review. You need Git. See Review a diff in a host pane.
The cmux host. The cmux glue opens surfaces as browser splits beside the terminal and one editor window with the two worktrees. You need cmux installed. Home: Obversa in cmux.
Plannotator. Plannotator opens its review page in a split through the PLANNOTATOR_BROWSER variable the workspace launcher sets. You need Plannotator installed. Home: github.com/backnotprop/plannotator.

Packages

Package	Purpose	Version
`@obversa/obversa`	Installs every package below except Jev, Devin, Mastra and OpenAI Agents	`0.1.2`
`@obversa/runtime`	Builds and runs workflows as graphs, team conversations or a review loop	`0.2.12`
`@obversa/runner`	Supervises stored graph runs in bounded workers	`0.2.12`
`@obversa/api`	Defines every contract: engine, memory, graph, events, artifacts, workspace, callbacks, proofs and run definitions, with their validators	`0.2.12`
`@obversa/core`	Runs one child process with a deadline and a readable result	`0.2.12`
`@obversa/memory-simple`	Stores memory in one process	`0.1.2`
`@obversa/memory-git`	Stores memory in private Git references, and writes a stage’s reasoning into its commit	`0.1.2`
`@obversa/memory-markdown`	Selects ranked passages from local Markdown files	`0.1.2`
`@obversa/notify-webhook`	Posts one message per interesting run event to a URL you supply	`0.1.0`
`@obversa/builtin-workflows`	Three ready-made workflows	`0.1.3`
`@obversa/surface`	Runs one local surface session	`0.1.1`
`@obversa/surface-diff`	Opens a git diff for inline review	`0.1.1`
`@obversa/engine-claude-agent-sdk`	Runs one engine attempt through the Agent SDK	`0.1.6`
`@obversa/engine-anthropic-api`	Runs one engine attempt through the Anthropic API	`0.1.4`
`@obversa/engine-claude-cli`	Runs one engine attempt through the Claude CLI	`0.1.6`
`@obversa/engine-codex-cli`	Runs one engine attempt through the Codex CLI	`0.1.5`
`@obversa/engine-devin-cli`	Runs one engine attempt through the Devin CLI	`0.1.3`
`@obversa/engine-grok-cli`	Runs one engine attempt through the Grok CLI	`0.1.8`
`@obversa/engine-opencode-cli`	Runs one engine attempt through the OpenCode CLI	`0.1.7`
`@obversa/engine-jev-api`	Answers decision questions over recorded run state through the Jev API	`0.1.5`
`@obversa/engine-mastra`	Runs one engine attempt through a Mastra agent you built	`0.1.2`
`@obversa/engine-openai-agents`	Runs one engine attempt through an OpenAI Agents SDK agent you built	`0.1.2`

The api, core, runtime and runner packages share one version. The runtime never imports an engine or a memory adapter: you pass the ones you want when you run.

Pages

Packages. Obversa, Runtime, Runner, API, Core, Built-in Workflows, Surface, Surface Diff. Engines. Claude CLI, Codex CLI, Devin CLI, Grok CLI, OpenCode CLI, Claude Agent SDK, Anthropic API, Jev API, Mastra, OpenAI Agents. Coming soon: eve, LangGraph. Memory and notifications. Git Memory, Simple Memory, Markdown Memory, Webhook Notifications.

Next steps

Installation: set a project up and run the first file.
Runtime: the package most files import from.
Examples: complete teams that use these exports.

Start

Concepts

Patterns

Examples

Evals and Gates

Recording Runs

Driving Runs

Surfaces and Hosts

Writing Workflow Shapes

Memory

Workspace

Compare

FAQ

API Reference

Exports

Tools

Packages

Pages

Next steps

​Exports

​Tools

​Packages

​Pages

​Next steps

Exports

Tools

Packages

Pages

Next steps