Kaloko

All guides › By use case

By use case

Desktop apps: Electron and macOS apps on the same canvas

Kaloko opens Electron apps through Playwright with every web check, captures macOS app windows with their accessibility tree, and imports screens from any other tool, so desktop flows get the same review as web and mobile.

Desktop apps are often the product nobody walks through before a release: the web version gets the review, the Electron wrapper gets a smoke test. Kaloko treats a desktop window like any other screen.

The problem

Desktop releases are checked by opening the app and clicking around. Nothing is recorded, nothing is compared with the last release, and localized menus or dialogs are seen by customers first.

What changes with Kaloko

platform: electron opens the app through Playwright. Its window is a web page to Kaloko, so selectors, accessibility checks, console errors and semantic questions all work unchanged. platform: desktop captures a macOS app's window with its accessibility tree (or the text on it). Every screen is framed as a window on the canvas, next to the web and mobile runs of the same feature.

How it works

  1. Name the app

    app.electron.main: dist/main.js (or the packaged executable), or app.desktop.name: Notes for a macOS app.

  2. Script the steps

    Electron steps get a Playwright page, so app.tap('#new') or any Playwright code works. macOS steps are driven by your tool, by AppleScript or by a person, and Kaloko captures the window.

  3. Check

    packs a11y and console apply to Electron as on the web. The app pack checks labels, sizes and truncated texts in macOS windows.

  4. Review and compare

    the canvas shows each step in a window frame. The next release's run compares screen by screen against the accepted baseline.

Skills and prompts

Walk our Electron app in en and cs: the empty state, creating a note and the settings dialog. Use the a11y pack and share the run for review.
Capture the preferences window of our macOS app after each change in this PR, and tell me which labels got truncated in Czech.

Expected outcome: window-framed screens per locale with their checks, console errors from the renderer and a comparison with the previous release.

What you get

FAQ

Windows and Linux apps?

The built-in window capture is macOS only. On Windows or Linux, drive the app with WinAppDriver, Appium or your own tool and import the screenshot (and the UI dump if you have one) with kaloko capture --image.

Which macOS permissions does it need?

Screen Recording for window screenshots and Accessibility for the UI tree, granted to the terminal or the agent app. Without Accessibility, Kaloko falls back to text recognition.

More guides

Accepting a task with an AI agent, in the pull requestRegression before a release: compare the run with the accepted baselineSEO and landing-page checks on production, read-only, every dayE-mail flows: capture the message next to the screen that sent it

Install once, then work through your agent

Kaloko runs where your code and your agent are. The service stores and versions the results, shows the canvas and collects approvals.

  1. Add the CLI to the project
    npm install --save-dev kaloko

    Needs Node 20 or newer. Update later with npm update kaloko.

  2. Create the config and install the skill
    npx kaloko init --agent claude --org <your-org>

    The skill is copied to .claude/skills/kaloko. npx kaloko doctor checks Chrome, the config and the token.

  3. Create your organization and a token

    Create an organization; you become its admin. The start page offers a tester token in one click, later under Settings → API tokens. Put it into the project .env:

    KALOKO_TOKEN=qwk_…
TYPESAFE_API_KEY=…   # optional: semantic evaluator

Then just ask your agent

The skill teaches your agent the whole loop: it writes the acceptance plan and the scenario from the task, walks the screens, evaluates, shares the canvas, reads what reviewers said and fixes it. You do not type the commands; you review the canvas.

What the agent runs (or run it yourself, e.g. in CI)

The same loop by hand:

npx kaloko start --scenario docs/tasks/TASK-123/qa/scenario.yml --env local
npx kaloko walk        # playwright steps; agent/manual steps: kaloko capture
npx kaloko evaluate
npx kaloko share --pr
npx kaloko feedback    # what reviewers said, with ids to answer