Use a local coding agent

You can pay for the participant with a plan you already have. A signed-in Codex or Claude Code CLI on your machine can be the participant's model on a hosted E2B desktop; you still need E2B_API_KEY and @e2b/desktop from the install. For an app running on your machine with Codex, a local browser study needs neither key; Claude Code cannot drive a local browser study.

A Codex participant's run is analyzed by the same Codex account, on a hosted desktop as on a local one, so it needs no OPENAI_API_KEY for its findings. A Claude Code participant's run is analyzed by the OpenAI API and needs OPENAI_API_KEY; without it the participant can run, automatic analysis is skipped, and the run names the next command, humanish analyze --run <id> --provider codex when Codex is also signed in. Setting review.analysis.provider: codex makes the Codex account analyst the study's. To opt out deliberately, set review.analysis: false.

Replace the actor block in your own-app study with this fragment, and delete caps. A Codex participant signed in with a ChatGPT account has no API price, so a dollar cap is refused with HUMANISH_COMPUTER_USE_UNPRICED_CAP (HUMANISH_SHARED_WORLD_UNPRICED_CAP in a shared-world study); for Claude Code the cap does not bound subscription usage. Keep a finite execution.timeoutMs, which bounds both.

actor:
  type: local-agent # instead of openai-computer-use
  localAgent: codex # use claude for Claude Code
  persona: synthetic-new-user
  mission: >-
    Try the app as a newcomer. Complete its primary task, then report what happened.

localAgent chooses the installed CLI (codex is the default); model is a separate optional model selection passed to that CLI. When it is omitted, a Codex participant on a hosted desktop keeps the operator's configured model selection. Having Codex installed does not change an openai-computer-use study.

Claude can drive a participant in two ways. actor.type: local-agent with localAgent: claude runs your signed-in Claude Code, which acts through humanish's JSON action reply and bills your plan with no dollar cap. actor.type: computer-use with model: claude-haiku-5-5 calls the Anthropic Messages API with ANTHROPIC_API_KEY: Claude acts with Anthropic's own computer toolset, each request is priced, and caps.maxUsd applies. See pick the participant model. An exported ANTHROPIC_API_KEY for API participants never reaches a Claude Code participant, as the next section says.

Check the CLI's sign-in state, then the study's setup:

codex login status                 # or: claude auth status
npx humanish doctor --study .humanish/studies/your-app.yaml

For a signed-in Codex participant on an E2B desktop, doctor --study also starts Codex as the run would, up to an ephemeral thread and without a model turn: the release check, then initialize, config/read, account/read and thread/start with your Codex configuration and the study's model and reasoning effort. The row names the release, the model and whether Codex is signed in with ChatGPT or an API key. A refused release, configuration or model shows up there instead of in the run.

If signed out, use codex login or claude auth login. Before launching a desktop, humanish asks the selected CLI for its local authentication status. An unavailable or unrecognized status fails before desktop creation and asks you to check or update the CLI; it is not reported as a confirmed sign-out. A CLI that is not on PATH is refused as HUMANISH_COMPUTER_USE_AGENT_MISSING, and a signed-out or unrecognized status as HUMANISH_COMPUTER_USE_AGENT_SIGNIN_REQUIRED. Shared-world studies use the same endings after HUMANISH_SHARED_WORLD_. This checks local status, not remote account validity, model access or quota.

Codex supports ChatGPT sign-in or API-key authentication. Those have separate usage and billing. ChatGPT sign-in does not supply an OpenAI API key to humanish's default participant or analysis. Claude Code uses its own authentication commands.

Where execution happensCopy Anchor Link

humanish's local-agent discovery uses each CLI's status command; a credential-file hint is not treated as proof of authentication. This supports Codex's CODEX_HOME and keyring-backed login without assuming an auth.json file must exist. Status output is classified in memory; humanish does not include account identifiers or raw status output in the result. The coding CLI runs on your host and uses its own sign-in state. A Codex participant on a hosted desktop keeps the operator's normal Codex home and configuration; it does not substitute the isolated file-backed ChatGPT profile used by local browser studies.

humanish starts Codex in a scratch directory with its general-purpose tools disabled and one humanish UI tool. Codex calls that tool to propose desktop inputs; humanish executes them, records them and returns acknowledgments with the next screenshot. The same participant implementation drives local Firecracker and hosted E2B desktops. One app-server thread retains the persona and conversation through the final feedback.

humanish starts Claude Code with --restricted, --tools Read, --strict-mcp-config, --permission-mode dontAsk and --no-session-persistence, in a scratch folder that holds only the screenshots it is asked to read, and Claude Code returns desktop actions as JSON in one conversation. Read is the only tool in the session, and it cannot open a file outside that folder. Your user, project and local settings files are ignored, so their hooks, permission rules and plugins do not load; your CLAUDE.md does not load; no MCP server starts; and Claude Code saves no transcript. Managed (administrator) settings still apply.

The Claude Code process gets PATH, HOME, USER, LOGNAME, LANG, LC_ALL, LC_CTYPE, CLAUDE_CONFIG_DIR and the proxy variables (HTTPS_PROXY, HTTP_PROXY, NO_PROXY, NODE_EXTRA_CA_CERTS) from your environment, and nothing else: no provider key, no GH_TOKEN and no --dotenv name. It signs in with Claude Code's stored login from claude auth login. A login that exists only as ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN in your environment is not passed, and the readiness check reports it as signed out.

humanish reads every message Claude Code streams. A tool call other than Read inside the folder stops the participant and fails the run with HUMANISH_CLAUDE_PARTICIPANT_TOOL_REFUSED. A session that starts with another tool, an MCP server or another permission mode fails with HUMANISH_CLAUDE_PARTICIPANT_UNRESTRICTED. These flags need Claude Code 2.1.248 or newer: doctor shows the installed release, and an older one is refused before a desktop starts with HUMANISH_COMPUTER_USE_ACTOR_UNSUPPORTED. Run claude update to replace it.

Claude Code participants from earlier humanish releases saved a transcript of every screenshot they read under ~/.claude/projects/. humanish doctor counts those folders and prints the command that removes them.

The hosted Codex participant keeps your Codex home, your configuration and the environment humanish runs with, which can include provider keys. Both CLIs are host processes. Desktop inputs execute in the selected sandbox, and each CLI can reach whatever its restrictions leave open on your machine.

What the participant can do on the desktopCopy Anchor Link

Both agents propose from the same desktop actions: click, double and triple click, move, scroll, drag, mouse down and mouse up, type, keypress, hold keys, wait, screenshot, read pointer and zoom. They come from one schema, participantActionSchema in the browser-control protocol. Codex receives it as its humanish_ui tool schema, and Claude Code as the reply shape in its first message. The schema leaves out held modifier keys on a pointer action, a field of the OpenAI computer tool. Hosted E2B and Modal desktops and the local VM run every action through one translator.

Two of the actions read the desktop. read_pointer returns where the pointer is, and zoom returns a region of a capture taken when it runs. The agent is shown that region enlarged to fit its screenshot, with the aspect ratio kept; the run keeps it at the screen's own pixels as screenshots/zoom-NNN. Codex gets the position in that action's acknowledgment and the enlarged crop as an image in the tool result that carries the next screenshot. Claude Code gets the position as text in its next message, and the enlarged crop as an image file in its folder, which it opens with Read. A Claude Code proposal that does not match its shape is refused before any input; the actions before it run, and the next message says which one was refused.

Usage and limitationsCopy Anchor Link

• It is not free. Subscription usage consumes your own plan. Runs driven this way can have estimatedCostUsd: null because token usage or a matching model rate is unavailable. Claude Code sessions can report token counts; those counts are not a subscription invoice. Inspect the recorded model and missing-cost reason instead of treating an unpriced run as $0. Rate limits on those plans are built for interactive coding; humanish fails closed with the CLI's own message and does not retry into them.
• It is slower. Launching and communicating with a local CLI adds latency. Give the participant enough execution.timeoutMs for the task and inspect elapsed time in its evidence.
• The evidence says which brain ran it. The trace records the provider and resolved Codex model. Qualified ChatGPT-account participants also record their execution profile with unknown-dollar billing.
• Both agents keep one conversation for the whole run. Codex through an app-server thread, Claude Code through one claude -p stream-json session. A participant that starts every turn cold cannot remember trying the menu and tries it again; measured on one study, that was 188 actions over 90 turns and no finish against 21 actions over 8 turns. HUMANISH_LOCAL_AGENT_ONE_SHOT=1 keeps the cold-start path for the Claude agent as a measurement switch, so "remembers" can be compared against "does not" on your own study; the trace's ids.model says which ran.

Use what a study costs to distinguish model estimates, plan usage, and desktop costs.