How ish works

ish is a simulated human experience engine. You hand it the thing you are making (a link, an ad, a video, a PDF, a chatbot) and a sense of who it is for. Simulated people experience that thing and report back what they noticed, where they got stuck, and what they would do next, before it ships. What you get back is a reported journey (sentiment, friction, blockers, positive moments, completion) with the reasoning behind every reaction, not a score. This page is the map. It names what ish models and how the pieces relate, so the rest of the docs can assume you know what a study is versus an ask, what an iteration is, and where reactions come from.

The shape of it

Everything lives under a workspace. Inside it, two things produce reactions, and they are siblings, not one inside the other:

a study: the durable path, where simulated people do something on a real artifact, run by run.
an ask: the lighter path, where a fixed panel reacts to a few variants and picks, round by round.

People and sources are the shared inputs both of them draw on. The workspace is the root; a participant’s reactions are the leaf of either branch. A study and an ask never nest inside each other: they sit side by side under the workspace and share its people and sources. Solid arrows are containment; dotted arrows are the shared inputs each branch draws on. The study branch (workspace down to reactions) is the durable one most of this page follows. The ask branch swaps iterations and runs for rounds, and is covered in runs and asks.

Each entity owns a short alias derived from its UUID (w-6ec, s-b2c, i-d4e). An alias stands in for the full UUID anywhere an ID is expected, on both the CLI and the MCP server. The workspace, study, and iteration prefixes (w-, s-, i-) match across both surfaces; a few nouns carry a different prefix per surface (a participant is pt- on the CLI, t- on MCP). The MCP tool conventions page lists the full prefix table.

The study path, step by step

These are the five levels of the study branch, the durable path. The ask branch is the lighter sibling covered under study or ask below.

Workspace

The top-level container, one per product or brand. It holds the studies and asks, the saved people, the sources, and the credit pool everything else draws from. The backend calls this a “product”; the developer surfaces call it a workspace. See workspace.

Study

The persistent research artifact, and the recipe for a piece of research. A study fixes the modality (how people experience the thing: interactive, text, video, audio, image, document, or chat), the tasks people perform, and the questions they answer. A study does not carry the artifact itself. That lives on its iterations. See study.

Iteration

One configured batch of the study. The iteration is what holds the concrete thing people experience: the URL for an interactive study, the media for a text or video or document study, or the endpoint for a chat study. A study has one or more iterations, so an A/B is two iterations of the same recipe. Tools default to the latest. See iteration.

Run

Dispatching a group of simulated people against an iteration. You pick an audience (an explicit set of people, or a sample drawn by demographics) and ish starts a simulation for each one. Every person becomes a participant of that run. See runs and asks.

Reactions

What each participant reports back. Not a grade. A reported journey: what they noticed, where friction showed up, what blocked them, the positive moments, whether they completed the task, and the reasoning behind each of those. You read the reactions per participant and as a projected aggregate across the group.

Why study and iteration are separate

This is the split that trips people up first, so it is worth the sentence: a study is the question you are asking; an iteration is one answer you put in front of people. Keep the modality, the tasks, and the questions on the study, and the thing being judged on the iteration, and an A/B test is natural. Two iterations, same recipe, same audience, one comparison. Change the headline, add iteration B, run it on the same group, read both. The study stays the constant so the comparison is honest. If you only have one artifact and no A/B in mind, you still get an iteration. It is just labelled A and created in the same step as the study.

What a run actually does

A run fans out into one simulation per participant. Each simulation moves through a lifecycle you can poll:

draft → pending → running → completed | failed | cancelled

A participant that reaches completed produced a real journey: real observations, the reasoning behind them, and (for interactive studies) the screenshots of what they saw. A participant that failed or was cancelled did not. That distinction is also the cost model. Runs draw from the workspace credit pool, and a credit debits only when a participant completes. A run that never gets off the ground (a page that refuses to load, an empty audience, a chatbot that fails its smoke test) costs nothing, so you can fix the input and rerun without having burned anything. Read more in credits and limits.

Study or ask

Most of this page describes the study path, because it is the durable one. There is a lighter sibling, the ask, for when you do not need a persistent artifact: you want a group to react to a few variants of some creative and tell you which lands. An ask fixes its audience at creation and dispatches in rounds instead of runs. The decision rule is short:

Reach for a study

When a person needs to do something on a real surface: a URL, an app, a document, a chatbot. The journey is the point.

Reach for an ask

When a person needs to react to one or more variants of creative (a tagline, an image) and pick. The comparison is the point.

See runs and asks for the side-by-side.

Two ways to drive it

Everything above is the same model whether you type commands or let an agent call tools. The two developer surfaces map onto each other one to one.

# workspace → study → iteration → run → reactions
ish workspace use w-6ec
ish study create --name "Onboarding UX" --modality interactive \
  --assignment "Sign up:Complete the signup flow" \
  --question "How easy was it?"
ish iteration create --url https://example.com
ish study run --country SE --sample 5 --wait
ish study results

# workspace → study → iteration → run → reactions
workspace_get(workspace_id="w-6ec")
study_create(workspace_id="w-6ec", name="Onboarding UX", modality="interactive",
             assignments=["Sign up:Complete the signup flow"],
             questions=["How easy was it?"])
study_add_iteration(study_id="s-b2c", name="A", modality="interactive",
                    url="https://example.com", platform="browser")
study_run(study_id="s-b2c", audience={"sample": 5, "country": ["SE"]})
study_get(study_id="s-b2c", view="summary")

Pick the surface that fits where you already work:

ish CLI

A command for every step above. Scriptable, JSON on every command, aliases everywhere.

ish MCP server

The same model as 40 agent-native tools at mcp.ishlabs.io/mcp. Let Claude, Cursor, or ChatGPT drive ish.

Where to go next

Quickstart

Install, sign in, and read your first reactions in under five minutes.

Study

The recipe in full: modalities, tasks, and questions.

Runs and asks

The two run verbs, audiences, the simulation lifecycle, and when each fits.

Get started

Core concepts

How-to guides

Integrations

How ish works

The shape of it

The study path, step by step

Why study and iteration are separate

What a run actually does

Study or ask

Reach for a study

Reach for an ask

Two ways to drive it

ish CLI

ish MCP server

Where to go next

Quickstart

Study

Runs and asks

​The shape of it

​The study path, step by step

​Why study and iteration are separate

​What a run actually does

​Study or ask

Reach for a study

Reach for an ask

​Two ways to drive it

ish CLI

ish MCP server

​Where to go next

Quickstart

Study

Runs and asks

The shape of it

The study path, step by step

Why study and iteration are separate

What a run actually does

Study or ask

Two ways to drive it

Where to go next