--- title: Screen help: QR codes and verification codes on your phone nav: Screen help summary: When automation stops at a QR code, a verification code or a human check, Agent J puts the code or a full screenshot on your paired phone; you scan, tap Done or type the answer, and the work goes on. order: 53 --- # Screen help: QR codes and verification codes on your phone An Agent working in a browser sooner or later reaches a step only a person can pass: a sign-in QR code, a verification code, a check that you are not a robot. You do not need to be at the computer — Agent J sends that screen to the phone you paired. - A QR code on the page: Agent J cuts the code out, enlarges it and sends it to you. You scan it. - Anything else (a verification code, a human check, a code it could not find): Agent J sends a high-resolution screenshot — of the browser page or of the whole computer screen. You scan from it, tap done, or type what needs to be filled in. [Agent J browser and sign-ins](/docs/browser-automation/) · [Using the phone](/docs/phone/) · [Command reference](/docs/cli/) ## What the phone shows {#card} A help card opens on the phone. Its top line says "Scan request" or "Screen help" and whether it comes from the Agent or from one of your own automations. - The picture fills the middle, with a countdown below it. A QR code stays valid for 2 minutes by default, a screenshot for 5 minutes. - Tap a screenshot to see it full screen; tap again to go back. - A phone cannot scan its own screen: show the card on another device, or long-press the picture to save it and pick it in the scanning app. - QR card: scan, then tap "I scanned it". - Screenshot card: deal with what it shows and tap "Done". If something must be typed in (a verification code), write it in the box below and tap "Send". - Not now? Tap "Not now". The Agent learns you skipped it, stops and tells you where it is stuck. The card shows on every remote you paired; once you deal with it on one, it closes on the others too. When several cards are waiting, you see one at a time with a note of how many follow. If the Agent is watching the page, the card closes by itself as soon as the page moves on after your scan. ## How the Agent uses it {#agent} This is built into Agent J; there is nothing to install. The main Agent has the `agentj-screen-help` skill and uses it on its own whenever automation is stuck on a QR code, a verification code or a human check. You can also just ask, for example: *if you get stuck on a QR code, send it to my phone*, or *show me the screen and I will tell you the code*. After your answer the Agent looks at the page again and carries on only if the sign-in really worked. If the code expired, it reloads the page and sends it once more; after a second miss it stops and tells you. ## Commands {#commands} The Agent usually runs these; it is enough to know they exist. Cut the QR code out of the browser's current page, send it, and close the card when the page changes: ```bash agentj qr push --text "Sign-in needs a scan" --wait-until page-change ``` Only one part of one tab (`--tab` is a piece of the address, `--selector` a page element): ```bash agentj qr push --tab weixin --selector ".login-qrcode" --wait-until answered ``` Send a screenshot asking for the verification code, and wait for your answer: ```bash agentj screen ask --question "What is the verification code?" ``` The whole computer screen, asking only for a tap on done: ```bash agentj screen ask --screen --question "Please click Allow for me" --reply done ``` One call waits at most 170 seconds. If there is no outcome yet it returns `pending` with the card's id; keep waiting, or withdraw the card: ```bash agentj screen wait ``` ```bash agentj screen cancel ``` The outcome is printed as JSON: `done` (you tapped done), `answered` (you typed an answer; it is in `answer` and handed over once), `page_changed` (the page moved on), `cancelled` (you tapped "Not now"), `expired`. Only `shown` set to `true` means the card actually reached the phone. ## In your own scripts {#scripts} No Agent needed. When one of your own cron jobs or systemd timers on this computer reaches a sign-in, it can call the same commands. Add `--from` with a name and the card shows which automation sent it: ```bash agentj qr push login.png --from nightly-upload --text "Admin sign-in needs a scan" --wait-until answered ``` - Names use letters, digits and `.` `_` `-` only. - Pictures only: PNG, JPEG or WebP, up to 1.4 MB each. Only PNG pictures get the QR code cut out; other formats go as they are. - A few cards a minute per source, at most 4 open at once. - Only programs on this computer, running as the same user as Agent J, can send. ## When the code is not found locally {#vision} The QR code is found and cut out on this computer: it costs nothing and the picture stays here. The cut is read again and used only if it gives the same result as the original; otherwise the whole picture goes. To give a vision model a try when the local search finds nothing, add `--vision` to `agentj qr push` and set three variables in the environment that runs the command: `AGENTJ_VISION_URL`, `AGENTJ_VISION_MODEL` and `AGENTJ_VISION_API_KEY` (an OpenAI-compatible service on your own account). It is off by default and only called when nothing was recognised locally; when it is used, that picture goes to the model service you configured. ## Which computers {#platforms} - QR cut-out: Linux (x86_64, aarch64) and macOS. Elsewhere the whole picture is sent uncut. - Whole-screen capture (`--screen`) needs a desktop: macOS uses its own screencapture; Linux uses grim on Wayland, and import, scrot or gnome-screenshot on X11. A server without a desktop cannot capture its screen — use the browser page or a picture file instead. ## Privacy {#privacy} A screenshot may show private things. This is how Agent J handles it: - It travels only end-to-end encrypted to your own paired remotes. Never to friends, public bots, Telegram or e-mail. - It never enters chat history and is not saved on the phone; on the Agent J host it is kept in memory only. It is deleted when the card ends (dealt with, withdrawn, expired, "Stop everything" or a restart). - Logs record only the id, type, size and outcome — never the picture, the question, the answer or what the QR code contains. - Never type a password into this card. An answer that looks like a password or key is refused on the phone. To hand a key to the Agent, use the phone's [key card](/docs/phone-admin/) (`agentj secret request`).
Technical details - The commands reach the `agentj` program on the Agent J host over a local channel open only to the same user; from there the card goes end-to-end encrypted to the phone. - QR codes are found locally with zxing-cpp; the cut is the largest code plus a fresh white margin, decoded again and used only when the result matches. - `--ttl` changes how long a card stays: up to 10 minutes for a QR code, 15 minutes for a screenshot. - Exit codes: 0 sent / done / page changed, 3 cancelled, 4 still waiting, 5 not shown or expired, 2 bad arguments or picture, 1 Agent J is not running.