(CLI)
Hesperan CLI
Install
curl -fsSL https://hesperan.com/cli/install.sh | bash
irm https://hesperan.com/cli/install.ps1 | iex
The installer checks the checksum of the binary and puts hesperan on your PATH. Updates install themselves in the background, at most every 12 hours; hesperan update updates right away and hesperan doctor checks the installation.
Use
hesperan # type tasks, watch it work hesperan "find a used washing machine in Berlin on kleinanzeigen.de" hesperan -p "tidy up my Downloads folder" --json # once, for scripts hesperan --help # all commands
Hesperan first decides which connector can do the task. A request for a text, an opinion or a conversation is declined; a connector that is not set up yet answers with a setup hint. Then it acts step by step: it looks at what is actually possible — the links, buttons and fields on a page, the entries of a menu — and its decision engine picks the next action, with a probability for every option.
Connectors
| Connector | What it does |
|---|---|
browser | Websites: search, compare, fill forms from your profile, uploads, consent banners; stops at bot walls. |
desktop | Programs through the operating system's accessibility interface: menus, settings, dialogs, installers, print. |
files, system | A catalogue of commands: tidy folders, find duplicates, free disk space, backups with a restore test, updates. |
mail, calendar, documents | Inbox triage, unsubscribing, invoices, PDF forms, invitations, spreadsheets, deadlines. |
devices, screen | Android phones and TVs over adb, Home Assistant, printers; any screen read through text recognition. |
guard | Is this page a scam? Checkout traps, transfer checks. |
dev | CI triage, dependency PRs, issue labels, a deploy gate, end-to-end tests written as sentences. |
Coverage differs by connector and system. The browser and Linux connectors have run against real pages and programs; several others have so far only been tested against local stand-ins, and the desktop connector has not been tried on Windows.
Decision engines
| Engine | What | Set up | Costs |
|---|---|---|---|
hesperan | Hesperan 1, our own decision engine (the default) | hesperan login | Sign in with your Hesperan account or an hsp_ key; billed to your Hesperan plan. |
jev | Jev by TypeSafe, with your own key | hesperan engine key jev | Calls go straight to TypeSafe on your key; Hesperan never sees or resells them. |
your own | Any server with the System One API (POST <url>/v1/systemone) | hesperan engine add mine --url http://localhost:8000 | Your server, your key, your costs. |
hesperan engine lists them and hesperan engine use <name> switches; in a session, /engine does the same. Keys are kept in ~/.hesperan/credentials.json, readable only by you. Hesperan 1 runs on GPUs that scale to zero: the first decision after a pause can take a few minutes while the model starts, and the CLI waits for it.
Safety rules
Hesperan always takes the action its engine rates most likely. What keeps it safe are rules in the core that apply to every connector:
Stops when unsure
A model that stays very unsure several steps in a row is treated as lost: the task stops and comes back to you.
Stops for a person
Logins, captchas, payments and errors that need a person stop the task.
Nothing irreversible by accident
Buy, send, delete, submit, reset, uninstall: such a step runs only when the goal explicitly asks for exactly that. Otherwise the task stops before it.
Done means checked
“Done” counts only after a fresh look at the result confirms it; two unconfirmed claims stop the task.
No circles
An action that changed nothing is not offered again; repeated steps and going in circles stop the task.
Undo
File, mail, calendar, settings and smart-home changes are journaled: hesperan undo.
No invented text
Anything typed comes from your goal, the page or document, your profile, or a list — never made up.
How it earns autonomy
Every step is written to ~/.hesperan/tasks.jsonl with the options the engine weighed, and every run ends with an outcome: from the result check, from a benchmark, or from you with hesperan outcome <run> ok|fail, which always wins. hesperan replay last shows a run step by step.
Thresholds from outcomes. hesperan calibrate refits, per engine and per question — is the goal reached, does a person have to help, does the goal really ask for this irreversible step — the probability above which Hesperan acts. With little data the fit stays close to a cautious default, and it never leaves a fixed safe band.
Routines. A task that worked can be repeated as a routine. Each saved step is checked against the current state before it runs, and passes the same safety rules; when a step no longer fits, Hesperan goes back to deciding freely.
Shadow mode. hesperan shadow lets you work in Hesperan's browser while it silently predicts your next step. It offers to take over only after at least 20 observed steps, and only when the 95 % lower bound of its hit rate is above 90 % — in practice no earlier than 35 correct predictions in a row.
Where this stands: routines, calibration from outcomes and shadow mode are built and tested with test pages and a simulated user. They have not yet been validated with real people over real, repeated work; we will publish that evidence when we have it.
Are its probabilities honest? Measured live on 25 Sep 2026 through the production API: when Hesperan 1 was at least 90 % sure, 86 % of 915 decisions, it was right 99.8 % of the time. The middle bands are still small; see the reliability diagram. Jev and your own servers bring their own calibration; the thresholds the CLI fits from your outcomes are kept per engine.
What stays on your machine
Each decision sends the current state — the goal, the text and options on the screen — to the engine you chose. Logs, outcomes, routines and fitted thresholds stay in ~/.hesperan on your computer; sending outcomes to Hesperan is off unless you turn it on, and only ever covers runs decided by Hesperan 1.
Where to go next
- → Create a free account — to decide with Hesperan 1
- → Judgment types — the choice, yes/no and score questions every step is made of
- → Decision profiles — the same calibration idea for your own software, over the API