verikun

Agent-driven, natural-language mobile tests — during agent development or in CI. Self-healing and self-improving, with cost caps and test reports.

📚 Documentation — installation, guides, full command reference, and internals.

• Agent CLI — vk <command>: one-shot commands to inspect the screen as a semantic tree (or screenshot) and act on it.
• Puppeteer for native mobile — a thin wrapper over native Android and iOS automation runners with zero runtime dependencies.
• Natural-language tests — vk ai <file>: runs plain-English tests, compiled once and replayed model-free (~$0), calling a model only to self-heal a drifted step. Tests share a preamble with @include, written once instead of pasted into each. A compile that does not cover its test is rejected rather than cached as a pass. What that costs, and how the --max-cost-usd ceiling bounds it.
• Self-improving — the agent runner will provide prescriptive improvements to existing scripts to help stabilise flakiness for future runs.
• CI-ready — vk suite runs a folder of tests as one gated pass/fail run, across one device or a whole pool of them; vk server exposes real devices over an authenticated tunnel so a disposable CI runner (no phone attached) can still drive them, and routes around any that goes bad — including restarting a host adb server that has started dropping them.

$ vk ui
[0] TextView "Welcome back" (540,360)
[1] EditText @email_input (540,720) focused
[2] EditText @password_input (540,860) pwd
[3] Button "Sign in" @sign_in_btn (540,1020) tap
[4] TextView "Forgot password?" @forgot (540,1140) tap

$ vk tap @sign_in_btn
tapped [3] Button "Sign in" @sign_in_btn (540,1020) tap

Install

Requires Node ≥ 18 and the Android platform-tools (adb) on your PATH.

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

Then run vk doctor to check your setup. Re-run the install later to upgrade — vk doctor warns you when there is a newer release, or when the Claude Code plugin's skill docs have fallen behind the CLI, without failing on either.

The package also carries the agent SKILL.md, the CHANGELOG and the example/ tests, so they ship with your install. Registering that skill with a particular agent is a separate step — see Installation for Claude Code, Cursor, Copilot, Windsurf and others.

Quick start

vk doctor                       # check adb/device (read-only — never changes anything)
vk device prep --device <id>    # set a TEST device up once: animations off, sane display timeout
vk devices                      # list attached devices
vk ui                           # semantic snapshot of the current screen
vk tap @login_button            # tap by resource-id
vk text @email "[email protected]" # focus a field and type
vk assert text:"Welcome"        # auto-waits ~5s, then asserts — exit 0 pass / 1 fail
vk run archive smoke            # -> JUnit + HTML report, non-zero exit if anything failed

Selector lookups auto-wait for the element to appear and scroll it into view, so a flow needs far fewer explicit waits and swipes than you would expect.

Walk through the whole thing, including reading the report: Your first test.

Skill/plugin instead of MCP

verikun ships as a skill and plugin, not an MCP server, and that is deliberate. A skill lets us guide the agent on how to use verikun — when to inspect the hierarchy, what to assert, which command fits the step, and how to read the result back. That domain knowledge travels with the tool, so the agent drives the device well, not just correctly.

There is also no need for an MCP here: verikun runs locally with all its dependencies, and the agent calls it through the plain vk CLI — no shared session, data, or authentication to broker.

Documentation

| | | |---|---| | Getting started | Installation · Your first test · Using it from an AI agent | | Guides | Writing test cases · Natural-language tests · Suites · Remote devices & CI · iOS setup · Platform support · Troubleshooting | | Reference | Commands · Selectors · Auto-wait · Global flags · Exit codes · Environment variables · Reports & test runs · Device state · Device claims · Screenshots · AI plans & models | | Internals | Architecture · Core principles · Plan IR & the replay engine · Contracts · Contributing |

Exit codes, since they are the machine contract everything else rests on: 0 success · 1 not found / assertion failed / timeout · 2 usage error, ambiguous selector, or a device another job is driving · 3 environment error. Data goes to stdout; diagnostics to stderr. Full contract. Parallel agents share a host-level device claim so two jobs do not silently land on the same phone.

Feedback — help improve verikun

verikun improves from the rough edges people hit while driving it. When verikun itself is the friction — a step that heals on every cached replay (an unstable compiled selector, often a label-only control with no resource-id), a repair "give-up", or a gotcha in its own operation — that's worth an issue at github.com/ddikman/verikun/issues.

Driving verikun with an AI agent + the skill? It hands off to the suggest-verikun-improvement skill, which writes a short, TL;DR-first suggestion to a local file for you to read and edit, files nothing until you say so, and redacts every app-under-test specific (package, on-screen text, selector values, test prose, logs) so no client code or logic can leak.

Contributing

git clone https://github.com/ddikman/verikun && cd verikun
npm install      # dev deps (typescript, @types/node); also builds dist/ via the prepare hook
npm test         # type-check + the unit suite (no device needed)
npm link         # optional: put `verikun` and `vk` on your PATH

Zero runtime dependencies; the only dev dependencies are typescript and @types/node. The full contributor guide — the test loop, the Flutter device fixture, versioning and releasing, and running the documentation site locally — is Contributing.

License

MIT