Skip to content
Docs menu

The harness library

What @venom/harness is, which package to use for your app, how to install it and where each part of the library is documented.

View .md

@venom/harness is the agent harness the venom CLI runs on, published as a library so other programs can run the same coding-agent sessions. It gives you sessions with tools, a permission engine you control, Claude Code compatibility, subagents, context management and a model provider for any OpenAI-compatible server. It has no UI: your program decides what the agent may do and what to show.

Typical apps built on it:

  • a CI bot that reviews a diff and fails the build on findings;
  • a support or collections back office where an agent reads accounts through your own tools, drafts messages, and every action that touches a customer waits for a human approval in your UI;
  • an internal "fix this ticket" service that runs sessions in throwaway workspaces with a fixed policy;
  • another agent framework that only wants the policy engine, to vet shell commands an LLM proposes.

Which package

You want Use Runs in
Sessions inside a Node process, your own tools, direct access to pi's session object @venom/harness your process
Sessions behind HTTP and Server-Sent Events, clients in any language, approvals answered remotely @venom/harness-server (embedded with createHarnessServer, or the CLI's venom serve) your process, or the CLI
A Python program driving those sessions venom-client your process, talking to a server

The HTTP side is documented in the server API section and the generated reference at /docs/api/harness-server.

Install

The packages are not on a registry. Build them from a venom checkout, then install the tarballs:

make libs                       # dist/libs/venom-harness-0.1.0.tgz, venom-harness-server-0.1.0.tgz, the venom_client wheel
make libs VERSION=0.2.0-rc.1    # stamp a version
npm install /path/to/venom-harness-0.1.0.tgz
# with the server, install both tarballs in one command (the server depends on the harness at the same version)
npm install /path/to/venom-harness-0.1.0.tgz /path/to/venom-harness-server-0.1.0.tgz

Release builds (make release VERSION=…) put the same tarballs next to the CLI. Do not npm install the packages/harness directory of a checkout: npm links it, and the app then runs on the checkout's node_modules.

Requirement Value
Node 22.19 or newer (engines). ES modules; require() also works through Node's require(esm)
TypeScript "skipLibCheck": true. pi's declaration files do not type-check under module: NodeNext
Runtime dependencies pi 1.1.0 (@earendil-works/pi-*, exact pins), typebox, yaml
Network Only the model server you configure, MCP servers the user configured, and the web and browser tools when the model calls them (each through the permission gate)
{ "compilerOptions": { "module": "NodeNext", "moduleResolution": "NodeNext", "strict": true, "skipLibCheck": true } }

Every type you need is exported from @venom/harness and its subpaths, including pi's tool and extension types and typebox's Type, so your app does not depend on pi or typebox directly.

What the library guarantees

  • No global mutable state and no process.env writes: several harnesses and sessions in one process are fine.
  • No TTY needed. A tool call the policy would "ask" about, with no approver configured, is denied with a reason the model reads; it never hangs.
  • Nothing is written under .claude/ or ~/.claude.
  • A short hard-deny set (secret files, shell rc files, system paths, rm -rf ~, piping a download into a shell) applies whatever your rules and approver say.
  • What is a breaking change is defined by the "Public API" contract that ships with the package; anything not exported from an entry point is internal.

Where to start

Page Read it when
Embed the harness You want a first session running in Node, a Next.js route handler or a worker
Sessions, events and cost You need every HarnessOptions and CreateSessionOptions field, the event stream and saved sessions
Your own tools and approvals Your agent needs app-specific tools and your own approval policy
The permission engine You want rules, modes, the sandbox and audit records, with or without a session
Model provider You point sessions at a model server, map aliases or handle provider errors
Subagents and model tiers The agent should delegate to cheaper models, in parallel or in worktrees
Build a SaaS on the harness A worked design: a multi-tenant collections back office
@venom/harness/ws You need a WebSocket server with no dependency, as the browser relay and the voice tests do

Every entry point of the package, with what it is for, is in Entry points.

In this section

  • Embed the harness: Run a first venom session from Node, from a Next.js route handler and from a background worker, with state kept where your app wants it.
  • Sessions, events and cost: Every HarnessOptions and CreateSessionOptions field, the event stream a session emits, saved sessions and how to read a session's cost.
  • Your own tools and approvals: Give the agent app-specific tools with defineTool, decide every permission ask in your own code, and see how the permission engine treats your tools.
  • @venom/harness/ws: a WebSocket server with no dependencies: The server side of RFC 6455 for a node:http server's upgrade event, as used by the browser relay and the voice tests.
  • The permission engine: Use @venom/harness/permissions to judge tool calls with venom's rules and modes, run commands in the OS sandbox and keep audit records, with or without a session.
  • Model provider: Point harness sessions at any OpenAI-compatible server, map venom's model aliases to real models, and understand the provider's errors and model discovery.
  • Subagents and model tiers: How the agent delegates work to subagents through the task tool, which built-in agents ship, how model tiers pick cheaper models, and how writers get their own git worktrees.
  • Claude Code compatibility, config and plugins: What a harness session reads from a project (CLAUDE.md, .claude/, .mcp.json, venom.yaml, plugins, templates), how trust gates it, and the library APIs behind each.
  • Context, memory and the agent runtime: How a session keeps its context small (masking, compaction, recall), carries memory between sessions, undoes file changes, and runs its agents as processes you can signal and suspend.
  • Entry points: Every import path of @venom/harness, what it is for and whether it loads pi, with the API of the modules that have no page of their own.
  • Build a SaaS on the harness: A worked design for a multi-tenant app on @venom/harness, using a collections back office as the example: tenancy, tools, human approvals, audit, cost caps and deployment.