cobaltcapture.com

Cobalt Capture stores visual product-review sessions — screenshots with notes and annotations — at shareable URLs a coding agent can read or write. READ a review: call get_review with a review URL (/r/<slug> or /s/<slug>) or a bare slug. It returns the reviewer's notes as text plus each annotated screenshot as an image. READY-MADE PLAYBOOKS. Before improvising a site review, check whether one of these covers it — they are maintained server-side and are more thorough than anything worth reconstructing: - usability_pass — first-time-user usability audit. Signs up with a disposable inbox, works the real jobs cold in a browser, screenshots every point of friction, ranks findings by severity. Has one human approval stop (personas/jobs). - positioning_pass — positioning, messaging, and 'who is this for' audit of the public pages, desktop and phone. Read-only, so it needs no accounts and runs start to finish unattended. - flow_pass — the user names a flow (signup, checkout, inviting a teammate) and you walk it step by step, reporting what broke and what merely confused. Any email the flow sends is audited too. Reach for this when they point at a specific journey rather than the whole site. - investigation_pass — the general product investigator ('Ace'). Runs a likely persona's job-to-be-done cold against a product you OWN, in its own environment: it discovers how to run the app from the repo's conventions (boots the dev build, or runs prod with a throwaway account), and its guardrails scale to owned-dev / owned-prod / external. Reach for this for an owned-app investigation, or an audit the three above don't already name. Fetch either with get_playbook(name, url) and follow it verbatim; clients that surface MCP prompts also expose them as slash commands. If the user asks for a UX review, a QA pass, a first-time-user test, or a messaging/positioning critique, reach for these rather than inventing a method. WRITE a review (e.g. to compile a browser-testing or QA run into one shareable report): 1. Call create_review(title, summary?) ONCE. It returns a `review` slug and a `claim_token` — keep both; the claim_token authorizes every write. At this point you don't yet know what you'll find, so keep the initial summary to the task/scope. 2. For each screen, call add_screenshot(review, claim_token, image_url, comment?) as you capture it (see GETTING THE IMAGE IN below for where image_url comes from). Do this per-screen rather than batching at the end, so nothing is lost. Use add_note(review, claim_token, text) for standalone notes. 3. When the run is DONE, call update_review(review, claim_token, summary) with the headline findings and outcome. This puts the verdict at the TOP of the review, above the step-by-step screenshots — do this instead of leaving conclusions in a trailing note, which forces every reader to scroll past the intermediate steps first. 4. Share the returned review_url. No login is required: reviews are anonymous and auto-expire in 30 days unless the human opens the save_url to keep them. GETTING THE IMAGE IN. add_screenshot needs a real image, not a description. It takes an `image_url` on Cobalt's own storage, which you get by POSTing the image to https://cobaltcapture.com/api/upload (multipart field `file`, no auth, returns {url, key}). Three paths, in order of preference: 1. PREFERRED — upload from INSIDE the script that took the screenshot. If you are driving a browser (Playwright, Puppeteer, Selenium), you are already running a script with permission to run; do the POST in that same script, right after the capture. One process, no extra shell command, no second permission prompt, and the bytes never pass through you. In Python: page.screenshot(path='shot.png') url = requests.post('https://cobaltcapture.com/api/upload', files={'file': ('shot.png', open('shot.png','rb'), 'image/png')} ).json()['url'] The 3-tuple matters: requests sends application/octet-stream without it and the upload is rejected with 'not an image'. Then pass `url` to add_screenshot as `image_url`. Print the urls (or collect them) so you have them for the tool calls. Node/Playwright equivalent: the built-in request context, `request.post(..., { multipart: { file: ... } })`. Do NOT shell out to curl as a separate step when a script is already running — that is a second permission surface for no gain. 2. Live-browser screen share, when the shot must come from the HUMAN's own browser session, or when you can run page JavaScript but cannot execute scripts or shell commands: open a Cobalt editor page (/new) in that browser, have the human click Capture once and pick the window (a one-time gesture; browsers require it and no automation can drive that picker). Then call window.cobaltGrab() on that page via your javascript_tool for each screen — it grabs the current shared frame, uploads it, and returns {ok, url}. Pass that url as `image_url`. 3. `curl -sS -F file=@shot.png https://cobaltcapture.com/api/upload` — the last resort, for when you have a file but no script running (and a shell you are allowed to use). It works, but in a sandboxed client it costs a permission prompt per call, which is why it is third. NOT A PATH: base64 via `image`. The server accepts it (PNG/JPEG/WebP up to 8 MB decoded), but tool-call arguments are text YOU generate, so a screenshot means emitting tens of thousands of base64 tokens perfectly — slow, expensive, and unreliable. Worse, if the screenshot reached you as an image rather than a file, you cannot transcribe it at all. Reserve `image` for genuinely small images you already hold as base64 text. TEST ACCOUNTS / EMAIL. If the product needs a signup to review, and create_inbox is in your tool list, use it — do NOT ask the human for an email account, an inbox API key, or any third-party service. There is nothing for them to set up. Steps: 1. create_inbox() -> returns `address` and `inbox_token`. Use a FRESH inbox per test persona. 2. Type `address` into the product's signup form and submit. 3. check_inbox(address, inbox_token) -> reads what arrived. Mail normally lands within seconds; if it's empty, wait ~5s and call again (there is no blocking wait). Give it a few tries before concluding the product never sent anything — 'no verification email arrived' is a real finding, but only after you've actually waited. 4. Pull the code or confirmation link out of the message and continue in the browser. Note that senders often rewrite links for click tracking, so the confirm URL may point at a tracking domain rather than the product's own — follow it anyway, it redirects correctly. Inboxes expire, so don't reuse one across a long session. If create_inbox is NOT available, don't block the run: drive up to the verification wall, capture it, record 'signup requires email verification' as a finding, and continue with whatever is reachable without an account. The claim_token from create_review is the handle for the whole session — pass it to every add_screenshot / add_note / update_review call for that review. OPTIONAL — EMAIL THE HUMAN A LINK. If the run was unattended and the human might forget to come back for it, offer to email them the review with email_review(review, claim_token, email). It only sends to a VERIFIED COBALT ACCOUNT address (a spam guard), so ask for their Cobalt account email; if they don't have an account it tells them to make a free one. The email is a link only — nothing you write reaches them.