Installation

Requirements

Node ≥ 18
Android platform-tools (adb) on your PATH — for Android devices and emulators
idb — only if you want to drive iOS. See iOS setup.

Install the CLI

npm install -g verikun    # installs the `verikun` and `vk` commands globally

Re-run the same command later to upgrade.

Then check your setup:

vk doctor

vk doctor reports whether adb is present, whether exactly one device is resolvable, whether the device has been prepared for testing, and whether it has a screen lock. It is read-only — it never changes a device.

To set a test device up, prepare it once — animations off, a 1-minute display timeout, notifications silenced, battery idle disabled:

vk device prep --device <serial>   # a physical device must be named
vk device prep                     # an emulator is auto-selected

A physical device must be named so prep never lands on a personal phone that happened to be plugged in; vk device prep --revert puts it back, and vk doctor --fix is an alias for the same thing. Full detail: Device state.

The npm package also carries the agent SKILL.md, but registering that skill with a particular agent is a separate step — the two sections below do that.

Connect a device

Any of these works:

A physical Android phone over USB with developer options and USB debugging enabled, or over wireless adb.
An Android emulator (emulator -avd <name>, or start one from Android Studio).
An iOS simulator (xcrun simctl boot <name>, or Simulator.app) — see iOS setup.

Confirm verikun can see it:

vk devices

With more than one device attached, verikun picks one no other job is driving and says which on stderr; name one with --device <serial> (or the VERIKUN_DEVICE environment variable) to choose.

Register the skill with your agent

The CLI is what drives the device. The skill is what teaches an AI agent to drive it well — the act → inspect → assert loop, the selector grammar, exit-code semantics, and the gotchas. Installing one does not install the other.

Claude Code plugin

This repository doubles as a Claude Code plugin marketplace:

/plugin marketplace add ddikman/verikun   # add this repo as a marketplace
/plugin install verikun@verikun           # install the plugin

The plugin ships the skill; the vk CLI is a separate Node package, so install it with npm install -g verikun as above. Because they update independently they can fall out of step — Keeping it up to date covers how to notice.

Cursor, Copilot, Windsurf, and others

The skill is a plain SKILL.md with name/description frontmatter, so vercel-labs/skills can install it into any of the 70+ agents it supports:

npx skills add ddikman/verikun --skill verikun    # pick your agent when prompted

Add --agent cursor (or windsurf, github-copilot, opencode, …) to target one directly, and -g to install globally rather than into the current project. As with the plugin, this installs the skill only — the CLI still comes from npm install -g verikun.

Keeping it up to date

vk doctor warns when either half is stale:

verikun: 0.25.0 — npm has 0.26.3
  npm install -g verikun@latest
claude-code-plugin: 0.24.0 — behind this CLI (0.26.3); the agent is reading stale skill docs
  claude plugin update verikun@verikun   (then restart Claude Code)

A stale skill means an agent confidently using a flag your CLI no longer has, which is why the skill asks the agent to run vk doctor once at the start of a session.

Both are warnings — being out of date does not change doctor’s exit code. Set VERIKUN_NO_UPDATE_CHECK=1 to skip the check entirely.

Build from source

To run an unreleased version, or to work on verikun itself:

git clone https://github.com/ddikman/verikun && cd verikun
npm install      # dev deps + builds dist/ via the prepare hook
npm link         # optional: put `verikun` and `vk` on your PATH

Without npm link, invoke it as node dist/bin/verikun.js <command>. See Contributing for the watch/test loop.

Your first test →