Kaloko

Your AI agents build; Kaloko walks every screen, puts it on one canvas and records who approved what.

Your coding agent (Claude Code, Codex or any LLM with a shell) walks your acceptance plan with the kaloko skill. Kaloko captures every screen and e-mail of the flow, checks the criteria and lays the whole flow out on a canvas: screens, branches, locales and evidence. People review and approve it there, and the newest captures double as documentation.

• Product, pricing and the service (organizations, shared canvases, reviews): https://kaloko.app
• Guides: https://kaloko.app/guides

Pages are walked in Chromium, WebKit and Firefox, on phone, tablet and desktop presets, in light and dark mode. Native apps too: Android, iOS, Electron, macOS and Windows. Screens taken by any other tool (Maestro, Appium, XCUITest) are imported with their UI tree. See What Kaloko can walk and design.

Install

Requires Node 20 or newer.

npm install --save-dev kaloko
npx kaloko init --agent claude --org <your-org>   # or --agent codex | all
npx kaloko doctor

init creates kaloko.config.yml and copies the kaloko skill to .claude/skills/kaloko (Claude Code) or skills/kaloko (Codex). It reads the project first: the framework (Next.js, Nuxt, SvelteKit, Remix, Astro, Rails and others), the dev server's command and URL, the locales of the i18n config and the main routes, and drafts qa/flows/main-pages.yml so the first walk works without editing. Run it again after npm update kaloko to refresh the skill.

Then ask your agent

With the skill installed, the agent types the commands below, not you. It writes the acceptance plan and the scenario from the task, walks the screens, evaluates, shares the canvas and later works through what reviewers said. For example:

Read the task in docs/tasks/TASK-123, write its acceptance plan and a Kaloko scenario, walk it on local and share the result on the pull request.

Go through the open Kaloko feedback on TASK-123: fix what reviewers rejected, run the affected steps again, share, and answer each comment with what changed.

Draft a Kaloko scenario for https://example.com (home, pricing, contact) with the seo, a11y and perf packs, run it on production read-only and summarise its health.

Run a scenario by hand (or in CI)

npx kaloko validate qa/flows/checkout.yml
npx kaloko start --scenario qa/flows/checkout.yml --env local
npx kaloko browser start
npx kaloko walk                       # playwright steps
npx kaloko capture --step <id>        # agent or manual steps
npx kaloko evaluate                   # deterministic checks + semantic evaluator
npx kaloko preview                    # local canvas
npx kaloko share --pr                 # upload to kaloko.app, comment on the PR

When a run belongs to a record outside Kaloko, say a change request in your QMS, name it at the start: --ref CC-2026-001 (repeat it for more, or set KALOKO_REFS in CI) and, if you like, --purpose dry_run, formal or smoke (KALOKO_PURPOSE). The canvas shows both, and npx kaloko runs --ref CC-2026-001 or GET /api/v1/orgs/<org>/runs?ref=CC-2026-001 lists every run of that record with its verdict, environment and purpose.

After a fix, walk only what the change reaches: npx kaloko affected explains which steps the changed files touch (routes, imports, affects: globs in the scenario), and npx kaloko walk --affected walks them. Several locales walk at once with --concurrency 3. When a step's selector no longer exists, the walk proposes one from the page and prints the patch; --heal applies it once the step passes.

Automatic criteria read the page itself: text, counts and attributes, the URL after a step (url_matches), computed styles, also against a design token (style_equals with token: color.brand.primary), and read-only values such as localStorage or dataLayer (js_equals). A step script never has to compute a result and leave a marker for a criterion to find. The acceptance reference of the kaloko skill lists every check.

npx kaloko help lists every command.

What Kaloko can walk and design

Full: Kaloko drives it, captures it and runs the checks. Capture only: Kaloko takes the screens, your tool or a person moves between them. Via import: another tool takes the screens and kaloko capture --image or kaloko import lays them out.

| Target | How | Checks | Design | Support | |---|---|---|---|---| | Web in Chromium | Playwright, the shared browser or an own one | all | live HTML steps | full | | Web in WebKit (Safari's engine) and Firefox | Playwright, one pass per engine | all except the accessibility tree, focus rings and layout shifts (and the Tab walk on WebKit) | rendered in Chromium | full | | Phones, foldables, tablets, laptop to 2560 px, TV | device presets: size, pixel ratio, touch, user agent | all | whole screen, device frame, safe areas | full | | Light and dark, reduced motion, high contrast | emulated per capture | all; contrast per scheme | dark pages, token modes per scheme | full | | Installed web app (PWA) | display-mode: standalone rules and matchMedia | all | yes | full for CSS; scripts that read the mode at load need a real install | | Android: emulator, USB or Wi-Fi phone | adb: deep links, taps, typing, dark mode | UI tree, app pack | HTML mockups | full | | Android WebView | DevTools over adb (debuggable builds) | web checks on the page | | full | | iOS Simulator | simctl: deep links, dark mode; taps with idb | UI tree with idb, text by OCR without | HTML mockups | full with idb, capture only without | | iPhone and iPad | devicectl, idevicescreenshot or pymobiledevice3 | text by OCR | HTML mockups | capture only | | Electron | Playwright | all web checks | | full | | macOS apps | window screenshot, accessibility tree | UI tree | | capture only | | Windows apps | PowerShell and UI Automation: taps, typing | UI tree | | full on Windows, via import elsewhere | | React Native, Flutter, iOS WKWebView, Maestro, Appium, XCUITest | their own runner | UI tree from a dump, or text | | via import |

npx kaloko devices                                         # the presets
npx kaloko browser install --browsers webkit,firefox
npx kaloko start --scenario qa/flows/checkout.yml --env staging \
  --browsers chromium,webkit --color-schemes light,dark --viewports iphone-se,pixel-8,desktop-hd

The canvas switches between browsers and schemes next to the locale, draws the device frame and shows the same step in another browser beside it. npx kaloko doctor says which engines and app tools are missing on this machine and how to install them. Details: skills/kaloko/reference/devices.md and apps.md.

Pull request previews in CI

npx kaloko ci github      # or: npx kaloko ci gitlab

writes a workflow that waits for the pull request's preview deployment (Vercel, Netlify, Cloudflare Pages, any review app), walks the steps the change affects and puts one comment per scenario on the pull request. Add a KALOKO_TOKEN secret (tester role) and commit it. In short, the GitHub workflow does this:

on:
  deployment_status:
jobs:
  walk:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    env:
      KALOKO_TOKEN: ${{ secrets.KALOKO_TOKEN }}
      GH_TOKEN: ${{ github.token }}
      KALOKO_BROWSER_CHANNEL: chromium
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - run: npx kaloko browser install --with-deps
      - run: npx kaloko ci preview-url --wait 600 --github-env
      - run: |
          npx kaloko start --scenario qa/flows/checkout.yml --env preview
          npx kaloko walk --ephemeral --affected
          npx kaloko share --pr

Uploads go by content hash: captures that did not change since an earlier run are not sent again, and an interrupted share picks up where it stopped.

With the Kaloko GitHub App (Team and up), each pull request also gets one Kaloko check on its newest commit. It turns green when the runs shared for that commit pass, whether they came from this workflow, a coding agent in the cloud or a laptop. Branch protection can require it, and labels and /kaloko skip <reason> control a single pull request. Details: skills/kaloko/reference/ci.md.

When a screenshot is not enough

npx kaloko walk --record                # each step on video, from the previous screen to its capture
npx kaloko walk --record failed         # only the steps that fail (flaky ones, mostly)
npx kaloko walk --record flow           # the whole walk per language, a chapter per step
npx kaloko video export --format mp4    # the run as one video, a title card and verdict before each step

The canvas plays a step's video next to its screenshot, and the Technical tab shows its trace: clicks, typing, requests with status and timing, console messages. Click a row and the video jumps there. Web recordings need nothing but Chrome (WebM with VP9); with ffmpeg installed you also get MP4 for Safari, app recordings (Android screenrecord, iOS Simulator, macOS) and the walkthrough export. npx kaloko video tools says what this machine has. Videos play on: when one ends, the next step's video starts, and replay moves to the next step by itself; a step that needs a decision waits for you, and a step without video shows its screenshot for three seconds. Recordings stay in the local preview on Free and Team; Business and Enterprise share them with the run.

Screenshots you already have

npx kaloko import playwright-report/        # or test-results/, a trace.zip, results.json
npx kaloko import walkthrough/ --adhoc      # a Cursor or Antigravity walkthrough, a folder of screenshots

lays screenshots, Playwright reports and traces out as a run: matched to the scenario's steps (by step id in steps.json, URL or title), or as an ad-hoc flow when there is no scenario. Build and share it like any run. When something does not work (Chrome, token, environment URL, evaluator key), npx kaloko doctor says what to fix, and npx kaloko doctor --fix installs a missing browser, creates missing folders and fills in org: from your token. Every error the CLI prints says what to do next; if you are still stuck, write to [email protected].

Review only what changed

After kaloko share, steps that look exactly as they did in the last accepted run (same screenshots, same criteria, automatic checks passing) keep the approval a person gave them, with who and when. The rest waits in review mode: one step at a time on the canvas, J/K to move, A to approve, R to return with a note. The share says it in one line:

12 steps unchanged, approvals carried over; 5 need review: https://kaloko.app/acme/runs/…/#review

npx kaloko review (or --json, or MCP get_review_queue) tells an agent what still waits for a person, so it can pass the link on. Agents never approve for people: their decisions are marked and do not count as a person's.

To see what moved, compare a step with the accepted run side by side, as a pixel diff, with Swipe or with Onion skin; G shows one step in every locale and viewport at once. Comments can carry a box, an arrow or a line drawn on the screenshot. On Business and Enterprise an accepted run has a signed acceptance record (who approved what and when, criteria results, screenshot hashes) as PDF and JSON:

npx kaloko signoff <run-id> --out handover/   # download and check the record
npx kaloko signoff --verify record.pdf         # check one someone handed you; no token needed

Every AI verdict comes with one sentence saying why. Criteria marked vision: true, and answers the text evaluator is unsure about, get a second look at the screenshot from a vision model (ANTHROPIC_API_KEY, or through Kaloko); kaloko build lists what to act on with the score and the reason. As an experiment an admin switches on under Settings → Security → Experiments, Clef on Cloudflare also names the kind of problem each screen and its recording show (overlap, cut-off text, a raw translation key, an endless spinner); reviewers turn the right findings into comments with one click, and findings never change a verdict. Triage counts against the hosted-evaluation allowance, so it needs the Team plan or higher. Check packs (seo, a11y, perf, usability, console) report the app's health apart from acceptance: they never fail a step that meets its brief, kaloko health lists what is new since the previous run, and kaloko health adopt makes one check an acceptance criterion when the team wants it to decide. The a11y pack walks the page with Tab (order, visible focus, traps, skip link) and reads names from the accessibility tree. Pixel diffs skip the regions a step ignores; kaloko walk --stability 3 and kaloko stability find the clocks, ads and carousels worth ignoring, and kaloko stability --pull brings in the regions reviewers marked on kaloko.app.

A changelog with pictures

Your accepted runs already hold every screen of the release. CHANGELOG.md can show them: a picture names a step instead of a file, and Kaloko shows the accepted capture of it.

- You can pay with Apple Pay in the checkout.
  ![before](kaloko:checkout/payment?version=prev) ![after](kaloko:checkout/payment)

npx kaloko changelog draft            # the Unreleased entry: merged PRs and changed screens, before and after
npx kaloko changelog draft --apply    # the same, written into CHANGELOG.md (Keep a Changelog)
npx kaloko release 2.4.0              # record the release and its pictures; prints the changelog page

The draft groups pull requests and commits (Conventional Commits when you use them) into Added, Changed, Fixed and Removed; your agent rewrites the lines for people. The version comes from what the repository already uses (git tags, package.json, release-please, changesets, semantic-release); when a release tool owns CHANGELOG.md, Kaloko only reads it. The page on kaloko.app has a slider between before and after, switches language and screen size, and links each picture to its flow on the canvas. Share it with guests, readers from your company's domain, or publish it with a feed. Repositories with several apps list them under products: in kaloko.config.yml; npx kaloko products sync puts them on Kaloko before the first release, and Products in the app's menu lists each with its newest version, changelog and docs (npx kaloko products list in the terminal).

When release-please, changesets or semantic-release makes your releases, npx kaloko ci github --release adds a workflow that records each published release on Kaloko; your release tool keeps writing CHANGELOG.md.

Docs that keep up with the app

Guides in your docs/ folder (tutorials, how-to guides, reference, explanation) use the same step references, so their pictures never go stale. A Czech translation of pay.md is pay.cs.md next to it.

npx kaloko init --docs=full           # docs folders with a template in each
npx kaloko docs check                 # broken references, stale sections, missing translations; exit 1 in CI
npx kaloko docs publish               # the docs on kaloko.app: versions, languages, screens, search
npx kaloko export --format docusaurus # or md, vitepress, mkdocs, html, pdf, json: pictures as files

When a screen changes after its guide was written, the section on kaloko.app says "the screen changed in 2.4 — check the text", and kaloko docs check lists it. A guide plays as a walkthrough, one step at a time, and readers can ask for a "What's new" e-mail with every release.

Jira, Linear, Slack and Teams

When a reviewer returns a step, the fix usually gets planned in Jira or Linear. Create the issue from the step, on the canvas or from the terminal:

npx kaloko issue create --step checkout --to jira --criterion AC2

The issue gets the screenshot, the criterion, the reviewers' notes and a link back to the step. When it is done in the tracker, the comment on the step is resolved. A branch or pull request title that names the issue (WEB-12, or Linear's eng-42) links the run to it. Slack and Teams channels are chosen per project in Settings → Integrations, with the events each channel wants and quiet hours. Both come with the Team plan and up.

Pages checked on a schedule

A read-only scenario of public or gated pages can run on Kaloko's own browsers every morning, with nobody starting the CLI (Business: 2,000 pages a month, Enterprise: 10,000):

npx kaloko schedule add --scenario qa/flows/public.yml --env production --every day --at 5
npx kaloko schedule export github --scenario qa/flows/checkout.yml --env staging   # the full walk in GitHub Actions

Hosted runs open pages (HTTP Basic and saved sessions work), take full-page screenshots in every locale and viewport and check selectors and text. Steps that click or type, apps and local environments need the full walk, which the exported workflow runs on the same schedule.

Design (Kaloko Design)

Design the screens of a flow as live HTML with your own agent and skills, in the same scenario that development and QA use. A design environment (kind: design, a folder of steps) is walked and synced into a shared draft the team sees live; kaloko share there publishes a version of the flow (unchanged steps are stored once). An accepted version becomes the design reference, and packs: [design] checks every implementation run against it (pixels, structure, tokens, contrast). Details: skills/kaloko/reference/design.md in the package and the design guides.

npx kaloko start --scenario qa/flows/checkout.yml --env design
npx kaloko design lint                    # portable HTML: works on the canvas, from disk and in other tools
npx kaloko walk && npx kaloko sync        # only changed steps render and travel
npx kaloko share --name "Checkout v2"     # a version of the whole flow
npx kaloko reference --design --version 2 # after the team accepted it

Developers and their agents build from what was approved. Dev mode (D in the step detail) shows each element's box, sizes and distances, its colors, type and spacing with the token every value comes from (or a warning when it is not a token), contrast against WCAG AA, the :hover, :focus, :active and disabled states, and its images. The same data is the step spec an agent reads, and kaloko drift checks the implementation against it:

npx kaloko spec payment                   # elements, styles → tokens, states (also MCP get_step_spec)
npx kaloko walk && npx kaloko drift       # expected token vs actual value per element; exit 1 while it differs

Each published version says what changed since the previous one, step by step: the text that moved, the viewports that look different, the tokens that changed. Read it before publishing and write your own where the reason matters:

npx kaloko share --notes-preview          # what the version notes would say
npx kaloko share --notes notes.md         # a summary, then "step-id: what changed" lines

Design in Figma? Import the frames as design steps and make them the design reference without redrawing them. Frames match steps by name (Payment / mobile); each step gets the frame image, its text layers with their type and colors, and the file's variables as tokens.json. It goes one way: prototype links and components stay in Figma. Without an API token, import a folder of frames exported from Figma.

FIGMA_TOKEN=figd_… npx kaloko design import figma "https://www.figma.com/design/<key>/Shop" --scenario qa/flows/checkout.yml
npx kaloko design import figma ./figma-export --scenario qa/flows/checkout.yml

Looking for where a pattern is already used? npx kaloko screens "empty cart" searches the newest screenshot of every step across your flows (also at /<org>/screens on kaloko.app and MCP search_screens).

On the canvas, Prototype (or P) presents the steps full screen as live pages: click through links between steps, switch the device, walk with the arrow keys, and share a link that opens straight into a step. The rules for pages that work everywhere are in skills/kaloko/reference/portable-html.md.

Your data is yours: formats

Nothing in Kaloko is stored in a format only Kaloko can read. Every export opens from disk without it:

| Export | Command | Formats | |---|---|---| | Design version | npx kaloko export --design [--version n] --out v2.zip | HTML, CSS, JS, fonts and images in the design folder layout; tokens.json (W3C DTCG); scenario.yml (qawalk.scenario.v1); screenshots (WebP); index.html start page | | Live files (handoff) | npx kaloko export --live [--version n] --out design/ | the design folder as written | | Shared run | npx kaloko export --run <id> | zip with run.json (qawalk.run.v1), screenshots and HTML snapshots, live HTML of design steps, comments and verdicts, and index.html: the canvas, offline | | Documentation captures | npx kaloko export --scenario <id> | newest image and HTML of every step, index.json | | Walkthrough video | npx kaloko video export [--format mp4\|webm\|gif] | one video of the run's recordings with title cards; step recordings are WebM (VP9) and MP4 (H.264), traces JSON (qawalk.trace.v1) |

The schemas of these formats ship with the package (schemas/).

Configuration and secrets

Project configuration is kaloko.config.yml in the repository root: environments, readonly rules for production, browser, mailbox and evaluator. npx kaloko init writes a commented template.

Secrets are never written in the config. Wherever a secret is needed, the config names an environment variable of your choice (password_env: STAGING_PASSWORD, { env: CF_ACCESS_CLIENT_SECRET }). Values are read from the environment, then the project .env next to kaloko.config.yml, then ~/.config/kaloko/.env (existing variables win), and are redacted from captured HTML, page text and console output.

• Protected environments (staging, review apps): access sends HTTP Basic credentials, service-token headers (Cloudflare Access, Vercel protection bypass, your own) or a client certificate, to the environment's own origins only. base_url may use ${VAR} for review-app URLs from CI.
• Signed-in users: accounts maps the scenario sessions' account keys to credentials per environment (user, password, TOTP). For SSO or MFA a person signs in once with npx kaloko auth save --env <env> --account <key>.
• E-mails: built-in Mailpit client; any other mailbox through a small adapter module (provider: script, example in templates/mail/), or hand a message over with npx kaloko mail --step <id> --file message.eml.
• Service and evaluator: KALOKO_TOKEN for share, feedback, review, inbox and clean-up (runs, trash, prune, keep, archive) (npx kaloko login approves one in the browser and saves it to ~/.config/kaloko/.env, or create it in your organization's settings); TYPESAFE_API_KEY for the semantic evaluator and ANTHROPIC_API_KEY for the vision evaluator (both optional; without them Kaloko evaluates on your plan's allowance). The names can be changed in the config.

npx kaloko doctor checks that every variable the config names is set and that each environment lets you in.

Personal data. capture.mask (CSS selectors) hides personal data in everything a step stores: a striped box on the screenshot, [hidden] of the same length in the HTML and the page outline, and the same places in traces, recordings and captured e-mails. pii: redact on a scenario finds e-mails, phone numbers, birth numbers, IBANs and addresses by itself; pii: pseudonymize puts consistent fake values in their place instead. An environment with pii: required gets no run without it. When such a run still holds an unmasked e-mail or phone number, npx kaloko share refuses it and names the step and element (--allow-pii overrides); other runs are shared with a warning. The site's own contacts (its domain, the footer, Organization JSON-LD) do not count. Checks always read the real page.

Set browser.channel: chrome to use an installed Chrome, or run npx kaloko browser install for the Chromium of kaloko's Playwright (KALOKO_BROWSER_CHANNEL=chromium then uses it, which is how CI runs). In CI, KALOKO_PREVIEW_URL, KALOKO_PR and KALOKO_BASE come from npx kaloko ci preview-url; KALOKO_GITLAB_TOKEN lets share --pr comment on GitLab merge requests.

License

Proprietary. Use of Kaloko is subject to the terms at https://kaloko.app/terms.