Usercase

Open the site once as a virtual user and report: does it load, is the Usercase SDK running (which project), is a firewall/bot protection blocking us (and how to unblock, per vendor), is the secret key set. Always run this before starting visits. If it reports a block, stop and tell the user. If you have not read the research procedure yet, call the instructions tool with command research first.

Get the Usercase script for the connected project, with where to put it per framework. If nothing is connected yet, it opens the browser to connect and says what to tell the user. Use when check_site says the SDK is not running and you are in the site's repository: add the script once to the root layout/document, show the user the diff, then run check_site on the local site to confirm. Do not commit or deploy unless asked. If you have not read the install procedure yet, call the instructions tool with command install first.

Takes no parameters.

Save virtual users to .usercase/people.json (adds to what is there). People have no names — like real visitors; each gets a number (p1, p2…) to refer to them by. Make people who would really come to this site — varied goals, devices, arrival paths, and states of mind. Do not make everyone a perfect fit for one feature. Show the list to the user before running visits.

List the virtual users in .usercase/people.json and whether each has visited yet.

Takes no parameters.

Recent visit results (one summary per visit) and what the safety guard blocked. Call after each round of visitor sub-agents finishes — it also says whether the research run goes on to another round.

Open a visible browser on the user's screen so THEY can sign in to the site with one demo account. Only the resulting session (cookies) is saved, under an account name in .usercase/sessions/ — the password never passes through you or us. Call it once per demo account, one at a time. Returns immediately; tell the user to sign in and close the window, then run check_site — it checks whether the sign-in really worked. If an account is not signed in or has expired, call login again with that same account name. Members (member=true) are spread across the signed-in accounts. Never ask the user for their password.

Choose whether visitors' writes reach the site: signing up, posting, commenting, saving, liking. 'block' (the default) sends nothing to the site; 'send' lets those through for real. Only the user can decide this — ask them, and only call this with their answer. 'send' suits a test or staging site, or data that may be messed up; on a live site real users will see what visitors post. Payments, deleting, wallet connections and sign-out stay blocked either way. Saved in .usercase/settings.json.

Connect Usercase to a project in the browser, or switch to another project. Opens the Usercase dashboard where the user signs in and picks the project. Other tools connect by themselves when nothing is connected — use this only when the user wants another project, or check_site says the SDK sends to a different project.

Takes no parameters.

Install the visitor sub-agent definition (Claude Code: ~/.claude/agents/, Codex: ~/.codex/agents/ — user-wide, nothing is added to the repository) so visitors can be started. Run once if that agent type is not available. The user may need to restart Claude Code afterwards.

Takes no parameters.

Screens and element words from this project's recent real visits. Call first in the question procedure, before writing a condition — page globs and click targets must match what visitors actually saw. If you have not read the question procedure yet, call the instructions tool with command question first.

Takes no parameters.

Run a condition over this project's recent visits: how many it matches, grammar problems, overlap with existing questions, and what matched visitors did. Repeat until there are no problems.

Save the question as a DRAFT in the dashboard Inbox, after the user approved it. The server checks the condition again and refuses it if there are problems. Nobody sees it until someone turns it on.

What is in the user's Several steps window: whether the card is a question or a research invite, the page under Where, and the words they wrote. Call first in the steps procedure. If you have not read the steps procedure yet, call the instructions tool with command steps first.

Send the condition back to the user's Several steps window (a question or a research invite), after question_check shows no problems. The server checks it again and refuses it if there are problems. The user saves it there.

List the findings of a Usercase research's latest report (key, severity, title, who, and whether one is being fixed). Use when the fix command has no finding key. If you have not read the fix procedure yet, call the instructions tool with command fix first.

Read one finding of a Usercase research report with all its evidence: why, who, the screen checks from the recordings, the paths people took, what they wrote, and the suggested changes. Read it before looking for the code. If you have not read the fix procedure yet, call the instructions tool with command fix first.

Record on the research report that you are fixing a finding (status fixing, once the user approved the change) or have fixed it (status fixed, with the files, a one-sentence summary for the team, and the pull request link if any). If the last fix of this finding is already live on the site, this starts the next fix (fix 2, 3 …); otherwise it adds to the current one. The report compares people after each fix goes live with the version right before it.

List the open issues of the Usercase project (problems found from visitors' answers to questions on the site): id, title, where, whether it is a clear fix, and whether one is being fixed. Use when the fix command has no issue id. If you have not read the fix procedure yet, call the instructions tool with command fix first.

Takes no parameters.

Read one issue of the Usercase project with all its evidence: the question and page, what people chose, what they wrote, the AI's reading, other issues with the same cause, and earlier fixes. Read it before looking for the code. If you have not read the fix procedure yet, call the instructions tool with command fix first.

Record on a Usercase issue that you are fixing it (status fixing, once the user approved the change) or have fixed it (status fixed, with the files, a one-sentence summary for the team, and the pull request link if any). After a finished fix, starting again records the next fix.

List the tasks of a Usercase research (from the dashboard) and whether each already has an expected path. Call first in the path procedure. If you have not read the path procedure yet, call the instructions tool with command path first.

Open a fresh browser on the page where the task's intended route begins and start recording its expected path. The page itself is step 1. Starting again discards the recording in progress.

Click a numbered element from the latest screen. By default it becomes a step of the path (the element is recorded; a new page reached is recorded too). record=false for clicks that are not part of the route (closing a cookie banner) — they are still repeated by path_check. press=false records the element as the final click without pressing it (a Pay or Submit button the safety guard will not press).

Type into a numbered field (a search box, a quantity). Not a path step, but repeated by path_check.

Scroll the recording page to see more.

Make a page step match any page of its kind: /notice/6553c3ba → /notice/:id. Use when participants would open a different item than the one you did (the route reads from the code). Applies to every step on that page.

Walk the recorded path again in a fresh browser: every clicked element must still be found at its recorded position with the same text, and every page must be reached. Lists the screenshots to show the user. Required before path_save.

Takes no parameters.

Upload the checked path to the dashboard, replacing the task's expected path. Only after the user approved it. success: keep (default) leaves the task's success condition; page = done on reaching the last page of the path; click = done on the last recorded click. With page or click the saved path ends at that point (later steps are left out: the task ends there, so nobody could reach them). Ask the user before changing it.

What this project's data says is worth researching: open findings, where real visitors and virtual users left, what virtual users said when they left without getting what they came for, and the researches and drafts that already exist. Call first in the new-research procedure. If you have not read the new-research procedure yet, call the instructions tool with command new-research first.

Takes no parameters.

Save the research as a DRAFT in the dashboard Inbox, after the user approved it. It becomes a research only when someone creates it there. Paths are page paths starting with / (no host), with :name for the parts that change. Expected paths recorded and saved beforehand as plan-<n> (n = the task's position in tasks, from 1) are uploaded with it.

Start a visit as one virtual user from people.json. Returns a visit_id and what you see first. You ARE this person from now on. If it says the site is blocking us, stop and report that.

Do one thing on the screen, as the person. Numbers refer to the latest screen you were shown — only what is in view; scroll to see more. It happens after the pause a real person would take on that screen, then you get the new screen — or a survey card, or the end of the visit.

Respond to the survey card on screen, as the person. Decide `bothered` FIRST — most people close these without reading. Only if bothered, pick an option, write your own words, or still close.

Start here for any Usercase work — whether the user typed a command or just asked in their own words. Returns the step-by-step procedure; follow it as the user's request, and call this before the other Usercase tools. Commands: research (test or get feedback on the site with virtual users; `research` id to have them take part in a research), new-research (plan or create a research / usability study), install (add or install the Usercase script on the site), question (make a question to ask visitors at a moment on the site), steps (write the steps for the question open in the dashboard; `session` = its window id), path (record the expected paths of a research's tasks; `research` id, optional `task`), fix (fix a finding from a research report: `research` id + `finding` key like F1, `audience` real for the real-people report; or an issue from Issues: `issue` id), connect (connect this repository to another Usercase project).