Kalokoby

All guides › By use case

By use case

Recordings and traces: when a screenshot is not enough

Record a step or a whole flow on video, read what happened meanwhile (clicks, requests, console) and export the run as one walkthrough video for a client or a release note.

The step passes on Tuesday and fails on Wednesday on the same commit. The screenshot shows a spinner. What happened before it, nobody saw. A recording shows the way to the screenshot, and the trace beside it lists every request and console message on the way.

The problem

Screenshots show where a step ended. Animations, loading states, menus that open twice and flaky steps happen between screenshots, so the bug report says "sometimes it hangs" and the developer cannot reproduce it.

What changes with Kaloko

kaloko walk --record records each step from the previous screen to its capture, with the pointer and clicks drawn in. Every web step walked in Chromium also keeps a trace: actions, network requests with status, size and timing, and console messages. On the canvas the video plays next to the screenshot, and clicking a row of the trace jumps the video there.

How it works

  1. Record what you need

    kaloko walk --record for each step, --record flow for the whole walk per language with a chapter per step, --record failed for only the steps that fail. --record-quality low|medium|high sets the size.

  2. Or ask for it in the scenario

    record: true on a step that always needs it, or capture.record in the config for a whole project.

  3. Look at it locally

    kaloko video list shows what was recorded, kaloko video trace --step checkout prints a step's trace as a timeline, and the local preview plays everything.

  4. Share it

    on Business and Enterprise recordings travel with the shared run; Business keeps them 30 days, Enterprise as long as you set in Settings → Storage. On Free and Team they stay in the local preview.

  5. Make one video

    kaloko video export --format mp4 puts the run's recordings in flow order with a title card and the verdict before each step.

Web recordings need only Chrome (WebM). With ffmpeg installed you also get MP4, app recordings (Android, the iOS Simulator, macOS) and the export; kaloko video tools says what this machine has.

Skills and prompts

The payment step of TASK-123 fails sometimes. Walk it five times with recording of failed attempts and tell me what the trace shows before it fails.

Expected outcome: recordings of the failing attempts only, and a summary from kaloko video trace naming the request or console error before the failure.

Export a walkthrough video of the accepted run of the new checkout for the client, in Czech.

Expected outcome: kaloko video export --format mp4 --lang cs writes one MP4 with a title card per step.

What you get

FAQ

Should we record every walk?

No. Recordings are much larger than screenshots and count in your storage. Record flaky steps, animations and demos; traces are small and are kept for every walked web step anyway.

Do traces contain passwords or form values?

No. Traces keep actions, requests and console messages, without field values or credentials.

Can apps be recorded?

Yes, with ffmpeg: Android emulators and phones through screenrecord, the iOS Simulator and macOS apps. Walks in WebKit and Firefox are neither recorded nor traced.

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 don’t type the commands; you look at 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