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.
@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 versionnpm 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.tgzRelease 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.envwrites: 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.