Run your first study

You can't run a user study on an app that has no users yet. humanish runs one anyway: one command puts a synthetic participant with a persona and a task in front of your app in a real browser, and what comes back is what they did, where they got stuck, and what it cost.

This page goes from install to a finished study on an example app. It takes about ten minutes. The participant and desktop cost about twenty cents, and the default post-run analysis about fifty cents more, described below. Your own app is the next page.

InstallCopy Anchor Link

Use Node 22.19 or newer, in a project directory:

npm install --save-dev humanish @e2b/desktop

@e2b/desktop is the hosted desktop; install it in the same project, because a one-shot npx humanish@latest cannot see a copy installed elsewhere. The keyless preview and a local browser study work without it.

Add two keysCopy Anchor Link

A live study needs a desktop and a model. By default E2B supplies the desktop and the OpenAI API drives the participant:

npx humanish keys set e2b
npx humanish keys set openai
npx humanish init --yes
npx humanish doctor --study try-live

The prompts hide what you type and write to a user-level store with mode 0600. npx humanish keys shows which keys are set and where each comes from, and npx humanish keys set with no vendor asks for each missing key in turn. E2B_API_KEY and OPENAI_API_KEY in the environment work too, and --dotenv <path> loads an ignored file for one command; pass it to both doctor and run. doctor --study checks that the study's keys or logins are present without creating a desktop or calling a model. It cannot check quota or whether a key is still valid.

init writes example studies and personas under humanish/, ignores .humanish/ (where runs land), and prints the next command for your machine. Run it after keys set: it writes the try-live study for the participant it finds credentials for, and it never overwrites an existing study file.

Two alternatives, each on its own page:

• Your signed-in Codex or Claude Code can drive the participant instead of the OpenAI key. You still need E2B. See a signed-in coding agent.
• If the app runs on your machine and you use Codex, a local browser study needs neither key.

Run the exampleCopy Anchor Link

npx humanish run try-live

try-live is the starter study init wrote. It clones drawDB, an open-source database diagram editor, builds it inside the hosted desktop, and asks one synthetic newcomer to add two tables and name them. It studies drawDB, not your project; drawDB is the application studied, not a humanish adopter or endorser.

Allow a few minutes for the build and the participant. With an OpenAI key, the study caps estimated model spend at $2: the run stops before its next model request once the estimate passes $2, and hosted desktop time is billed separately. If init found no OpenAI key and a signed-in Codex or Claude Code, it wrote a local-agent participant instead, on Codex when it is signed in and otherwise on Claude Code, bounded by a ten-minute session limit with no dollar cap. Fresh installs with an OpenAI key have finished in 108 to 183 seconds at $0.16 to $0.35 of model spend; what a study costs has the measured runs. Your run will differ.

With an OpenAI key, a post-run analysis also runs by default when the participant finishes. It sends selected text and captures from the run to OpenAI. On five try-live runs on 2026-09-30, humanish stats recorded about $0.15 for the participant and $0.49 to $0.59 for the analysis, about $0.50 typical; yours will differ. Before sending, humanish estimates the analysis with its full output allowance, so the estimate runs well above the bill, and it refuses the analysis when that estimate exceeds $10. A study run on a signed-in Codex has the same Codex account analyze it instead, with no OpenAI key. To skip it, add review.analysis: false to the study.

To watch the desktop while it runs, use npx humanish watch try-live instead.

Read what came backCopy Anchor Link

npx humanish observe --run latest --open

The Observer opens the finished run in your browser: the participant's closing report, a replay of every action, and the screenshot at each moment. Read the report, then find the screenshot behind each claim. At your terminal the server stays attached until Ctrl-C. From a coding agent's shell or a pipe, observe prints the Observer path and exits; --serve keeps it serving there.

In another terminal:

npx humanish verify --run latest --json
npx humanish stats --study try-live

verify grades the bundle for sharing (share_ready, local_only or blocked), and stats totals duration and estimated cost. Read results explains how to tell a finding from a broken run, and what you can share.

A participant who gets stuck is often the useful result: it gives you a concrete place in the app to look.

Preview without keysCopy Anchor Link

npx humanish init --yes
npx humanish run first-run
npx humanish observe --run latest --open

This writes a synthetic sample bundle and opens it. Nothing is spent and no participant visits any app; it exists so you can see the evidence format before adding keys. humanish run --dry-run and humanish watch with no study do the same.

NextCopy Anchor Link

• How a study works: the study, participant, persona, actor, subject and route on one annotated file.
• Your own app: a preview URL, a repository built inside the desktop, or the app running on your machine.
• What a study costs: measured numbers, budgets and what the caps do.
• For a coding agent setting this up for you: npx skills add danielgwilson/humanish --skill humanish. Agents should use the CLI with --json. npx humanish tui is for a person at a terminal; it refuses agent sessions. See Observer and terminal.