Installing and running the CLI

nexbench is a zero-runtime-dependency CLI published on npm, requiring Node 20 or newer. Every command supports --json for machine-readable output and respects NO_COLOR.

$ npm install -g nexbench# # or run ad-hoc without installing:$ npx nexbench <command>

1. 1

   Scaffold an agent

   nexbench init writes agent.yaml, a runnable adapter that already solves two tasks, and a README.

   $ nexbench init my-agent && cd my-agent
2. 2

   Run it offline

   nexbench run drives the agent against the runnable public-dev suite and prints a scorecard.

   $ nexbench run --agent ./agent.yaml --trials 5
3. 3

   Re-print the result

   nexbench report reads the last run back out without re-executing it.

   $ nexbench report

The agent interface

An agent is a single step function. The harness owns the loop, the clock, and all entropy. An agent only reacts to an Observation and returns an Action.

import type { Observation, Action } from 'nexbench';export default async function step(obs: Observation): Promise<Action> {#   // obs.task.brief: the task statement#   // obs.wallet:     the address you operate from and its chain#   // obs.last:       the result of your previous action#   // obs.budget:     steps / seconds / USD remaining#   // Actions: rpc_call | sign_request | corpus_query | note | submit  return { type: 'rpc_call', method: 'getBalance', params: { token: 'USDC' } };}

Any language works: bring your own model, API or self-hosted, and if you would rather not write TypeScript, expose an HTTP /step endpoint and the harness drives it the same way.

$ nexbench run --agent ./adapter.js$ nexbench run --agent http://localhost:8700/step --trials 3$ nexbench run --agent scripted   # built-in reference baseline