Run Interactive Session

Run Interactive Test

Overview

Drive a Kobiton device interactively from natural-language intent. Given a request like "find the Login button and tap it" or "pull the latest log file from this Pixel", this skill creates (or resumes) a session, translates the intent into the right CLI command - WebDriver action, adb shell, file transfer, app launch, test run - captures the response, saves artifacts (screenshots, page source) under the workspace, and reports back in plain language.

Use this skill whenever the user wants to interact with a mobile device on Kobiton, run exploratory tests, inspect device state, manage files on a device, or execute test sessions - even if they don't say "interactive test" explicitly.

Prerequisites

Runs on macOS (Apple Silicon), Linux (x64), and Windows (x64 under Git Bash), and needs a local filesystem — it executes a locally cached CLI binary and reads ~/.kobiton/.credentials. On Intel Macs or other unsupported architectures, or anywhere a local filesystem isn't available, don't invoke this skill: route to run-automation-suite (user already has a test script) or drive-automation-session (describe the flow instead), both cross-platform. Check this before reserving a device, so a doomed run doesn't burn device minutes. See the Skill compatibility matrix in CLAUDE.md.

Before invoking this skill, ensure:

• Kobiton CLI wrapper - ~/.kobiton/bin/kobiton (a symlink to this plugin's run.sh wrapper on macOS/Linux, a bash exec-shim on Windows) must exist and resolve to an executable. Claude Code and Codex CLI both recreate it automatically via a bundled SessionStart hook; on Codex, the user trusts the hook once via /hooks after install. /automate:setup re-installs the wrapper on demand on any host. GitHub Copilot CLI and Gemini CLI load /automate:setup (Copilot via Claude-format .md, Gemini via bundled TOML at commands/automate/setup.toml) but have no SessionStart hook - run /automate:setup once after install. The CLI binary itself is downloaded, not bundled: the install script fetches the build pinned in CLI_VERSION (sha256-verified) into ~/.kobiton/cli/ on first run. run.sh reports a missing binary or missing credentials with the right remedy, so surface its error rather than pre-flighting your own checks.
• Credentials file - ~/.kobiton/.credentials must contain a valid INI-formatted profile with KOBITON_USER, KOBITON_API_KEY, and KOBITON_PORTAL. Created by /automate:setup. The active profile is $KOBITON_PROFILE if set, otherwise default.
• Kobiton MCP connection - useful for listDevices / getDeviceStatus calls when picking a device. Default api.kobiton.com/mcp; check .mcp.json for the configured endpoint.
• Kobiton account - credentials with device access for the target platform (Android / iOS) and remaining session quota.

If a command fails with a credentials error or missing-binary error, direct the user to run /automate:doctor for diagnostics, then /automate:setup to repair.

How It Works

All CLI calls go through a single wrapper at ~/.kobiton/bin/kobiton that automatically handles:

• CLI binary resolution - resolves the pinned CLI build from the version cache at ~/.kobiton/cli/<version>/ (falling back to the newest cached build with a drift warning).
• Portal URL - from KOBITON_PORTAL in credentials, or derived from .mcp.json as fallback.
• Credentials - loaded from ~/.kobiton/.credentials using AWS-style profiles ($KOBITON_PROFILE, default default).
• Session token - loaded by the CLI from ~/.kobiton/.session once a session exists.

Every command is self-contained - no env vars to manage between calls:

~/.kobiton/bin/kobiton <cli-args>

$KOBITON_BIN is used as shorthand throughout this document. In every Bash command, substitute it with the literal path ~/.kobiton/bin/kobiton - the variable does not persist between Bash calls.

Conventions

Argument order

Global flags must come before the subcommand:

$KOBITON_BIN [global-flags] <subcommand> [subcommand-flags]

Example: $KOBITON_BIN -u <udid> session create (NOT $KOBITON_BIN session -u <udid> create).

Help-first discovery

The CLI has built-in help at every level. Always check --help before running a command you haven't used before or when unsure about arguments:

$KOBITON_BIN --help                    # list all top-level commands
$KOBITON_BIN session --help            # session create, ping, end
$KOBITON_BIN session create --help     # show create flags and usage
$KOBITON_BIN wd --help                 # webdriver post/get commands
$KOBITON_BIN device --help             # list, adb-shell, forward, ps, screen
$KOBITON_BIN device adb-shell --help   # run adb shell commands on device
$KOBITON_BIN file --help               # list, push, pull files on device
$KOBITON_BIN file push --help          # push local file to device
$KOBITON_BIN test --help               # test run with built-in framework
$KOBITON_BIN test run --help           # show test run flags and usage
$KOBITON_BIN app --help                # app management commands
$KOBITON_BIN app run --help            # show app run flags and usage

Rule: if a command fails with "unexpected argument" or "unknown flag", run --help on that command to discover the correct syntax before retrying. Do not guess - the help output is authoritative.

Artifacts storage

All session artifacts (screenshots, page source) must be saved under the current workspace at:

.kobiton/sessions/<session-id>/

This keeps artifacts organized per session, easy to review, and version-controllable. Never save artifacts to /tmp/ or other locations outside the workspace.

Workspace vs home. This .kobiton/ is workspace-relative (your CWD when running the skill) - do not confuse with ~/.kobiton/ in the user's home, which holds the CLI symlink, credentials, and session JWT (managed by /automate:setup). Workspace .kobiton/ only contains per-session artifacts the skill creates.

Before writing the first artifact in a session, ensure the directory exists with mkdir -p .kobiton/sessions/<session-id>. It's idempotent, so include it defensively whenever you're about to write - especially when resuming an existing session, where Instructions § 2 may have been skipped.

Instructions

1. Pick a device

Ask the user which device or platform to target. If they haven't specified one, call the MCP tool listDevices to surface available options, optionally filtered by platform / OS version.

If the user already has a specific device in mind, confirm its availability with getDeviceStatus before proceeding.

Capture both the UDID (used for session creation) and the device id (the separate numeric ID used to build portal launch URLs).

2. Create or resume a session

If there is no active session yet, create one:

$KOBITON_BIN -u <udid> session create

The output contains a line like kobitonSessionId: 12345. Capture it:

1. Parse the session ID from the output.
2. Create the artifacts directory: mkdir -p .kobiton/sessions/<session-id>.
3. Store the session ID for use in screenshot and page source commands.

The JWT is saved automatically to ~/.kobiton/.session. All subsequent commands use it - no flags needed.

If a session may already exist (e.g., the user is continuing earlier work), check first:

$KOBITON_BIN session ping

Exit code 0 -> session alive, reuse it. Non-zero -> expired; create a fresh one.

3. Interact with the device

Translate the user's natural-language intent into one or more CLI commands using the Command Reference below.

For each command:

1. Run it via Bash using the literal path ~/.kobiton/bin/kobiton.
2. Parse the response (JSON envelope, plain text, or exit code) to extract values - see Output § Per-command response shapes for the summary rules and references/response-shapes.md for the full per-command table.
3. Report results in plain language to the user.

Chaining. Multi-step intents require chaining the output of one command into the next. Example - "find the Name field and type Hello":

1. Find the element:

   $KOBITON_BIN wd post element '{"using":"id","value":"com.app:id/etName"}'

   The response is JSON; extract the element ID from the value field.

2. Type into it (substituting the captured element ID):

   $KOBITON_BIN wd post element/<ELEMENT_ID>/value '{"text":"Hello"}'

Always extract the element ID from the response before using it in subsequent commands. Element IDs do not survive page transitions - re-find on each new screen instead of caching.

4. Capture artifacts

Ensure the artifacts directory exists first (idempotent, safe to repeat):

mkdir -p .kobiton/sessions/<session-id>

Screenshot. The CLI emits the base64-encoded PNG directly on stdout; decode and save in one pipe:

$KOBITON_BIN wd get screenshot \
  | base64 -d \
  > .kobiton/sessions/<session-id>/screenshot-$(date +%s).png

Then use the Read tool on the saved file to display it inline, and report the file path to the user.

Page source. The CLI emits raw XML (Android UIAutomator2) or hierarchy markup (iOS XCUITest) on stdout:

$KOBITON_BIN wd get source > .kobiton/sessions/<session-id>/source-$(date +%s).xml

Read the saved file for element inspection, or use grep / xmllint to extract specific nodes (see Example 3).

5. End the session

When the user is done:

$KOBITON_BIN session end

This terminates the Kobiton-side session and frees the device. The local artifacts directory at .kobiton/sessions/<session-id>/ is preserved for later review and version control.

Command Reference

WebDriver commands

adb-shell commands (Android only)

device adb-shell forwards everything after it to adb shell <...> on the device. Three failure modes account for most AI-agent mistakes - read these before composing a command.

Restricted sessions (public cloud and trial devices). On Kobiton public cloud devices and for trial users, every invocation is checked against a deny-by-default whitelist before it reaches the device. Dedicated devices (private cloud / on-premise) are unrestricted; everything in this block applies only to restricted sessions. The interactive shell is unavailable on restricted sessions - every invocation must name a command.

Rejected on restricted sessions:

• Any command not in the whitelist below, and command lines longer than 1024 characters.
• Control characters, and these shell metacharacters anywhere in the input: & ; | $ ` ( ) > < \ " ' * ? ~ { } # ! - so no pipes, redirection, command or variable substitution, backgrounding, globbing, or quoting. Arguments may not contain whitespace.

Whitelisted commands, by category:

File-path arguments must stay inside /sdcard/Download/, /sdcard/Documents/, or /data/local/tmp/, plus the individually allowed read-only file /proc/version; paths containing .. are rejected. To list a directory outside that allowlist, use $KOBITON_BIN file list <path> instead of adb-shell ls. The same directories bound file push / file pull.

Settings: only settings get secure enabled_accessibility_services and settings put secure enabled_accessibility_services <value> are permitted. Every other settings namespace, key, and subcommand (including list and delete) is rejected.

A rejected invocation prints one of these messages on stdout and - gotcha - exits 0, so check the first line of output rather than $?:

• Input contains a forbidden character: '<c>'.
• Command is not on the whitelist: '<cmd>'.
• Argument is not permitted for '<cmd>': '<arg>'.
• Only get/put of secure enabled_accessibility_services is permitted for 'settings'. (the settings rule has its own message)

The whitelist evolves with CLI releases; $KOBITON_BIN device adb-shell --help carries the full current policy - trust it over this snapshot.

Quoting rules. The local shell parses pipes, redirects, globs, and variable expansion before the wrapper sees them. Anything you wrap in quotes survives to the device's shell; anything outside is interpreted on your laptop.

• Plain command, no shell metacharacters - pass args separately (works on restricted and unrestricted sessions alike; /sdcard/Download/ is inside the restricted path allowlist):

  $KOBITON_BIN device adb-shell ls -la /sdcard/Download/
  $KOBITON_BIN device adb-shell getprop ro.build.version.release
  

• Pipes, redirects, globs, &&, $VAR, or quotes inside the command - unrestricted (dedicated) devices only: wrap the entire remote command in one quoted string so it runs on the device's shell, not your local shell:

  $KOBITON_BIN device adb-shell "dumpsys window | grep mCurrentFocus"
  $KOBITON_BIN device adb-shell 'pm list packages -3 | wc -l'
  $KOBITON_BIN device adb-shell "logcat -d -t 200 > /sdcard/log.txt"

  On a restricted session this form is rejected outright - the quotes and the metacharacters inside them are all forbidden characters, so there is no on-device composition form at all. Compose locally instead (next bullet).

• Restricted sessions: compose locally. Run the bare whitelisted command, bound its output, redirect locally into the session artifact directory, then filter the file locally:

  $KOBITON_BIN device adb-shell dumpsys window \
    > .kobiton/sessions/<session-id>/window-$(date +%s).txt
  grep mCurrentFocus .kobiton/sessions/<session-id>/window-*.txt

  On unrestricted devices prefer the quoted on-device form - filtering locally on the full output is slower and can overflow the 25k-token MCP limit if it isn't routed through an artifact file. On restricted sessions the local route is the only one: always bound the command (-d -t N, -n 1) and go through an artifact file, never paste raw output to chat.

Platform guard. adb is Android-only. If the active session targets iOS, do not call device adb-shell. Refuse and reach for the WebDriver equivalent (wd post execute '{"script":"mobile: ..."}') or a different inspection path.

Device logs on iOS. logcat is Android-only; the cross-platform log path is $KOBITON_BIN device log, which streams until killed — always bound it and expect the bound's exit code, which means success here, not failure:

timeout 45 $KOBITON_BIN device log > .kobiton/sessions/<session-id>/device-log.txt   # exit 124 = bound fired (coreutils)
# stock macOS has no `timeout` - use the perl-alarm equivalent (exit 142 = SIGALRM, same meaning):
perl -e 'alarm shift; exec @ARGV' 45 ~/.kobiton/bin/kobiton device log > .kobiton/sessions/<session-id>/device-log.txt

The Restricted column says what changes on a restricted session; ok means the command runs as written.

Big-output commands. dumpsys, logcat, pm list -f, and full process dumps can blow past the 25k-token MCP limit. For these, redirect to an artifact file first, then read/grep only what you need (the redirect is your local shell's, so this exact pattern also works on restricted sessions - it is the same local-composition idiom from the quoting rules):

$KOBITON_BIN device adb-shell logcat -d -t 1000 \
  > .kobiton/sessions/<session-id>/logcat-$(date +%s).txt
grep -E 'FATAL|AndroidRuntime' \
  .kobiton/sessions/<session-id>/logcat-*.txt | head -20

Never paste full dumpsys/logcat output to chat - surface a summary + the file path.

Long-running commands. Streaming commands like logcat (no -d), device log, tcpdump, or top (no -n 1) run forever. Either bound them (-d -t N, -c N, -n 1, or the timeout/perl-alarm wrapper for device log) or launch with run_in_background: true and kill explicitly.

adb-shell vs WebDriver overlap. Both can press keys, type, and tap. Tie-breakers:

• If the target is a known element ID -> WebDriver (wd post element/<id>/click, .../value).
• If the target is a hardware key, a blind coordinate tap, or a system-level action -> adb shell input / am / pm.

Web content visibility differs by platform. iOS exposes web page content to the automation hierarchy — wd get source on a Safari page includes the page's text, links, and buttons, so in-page elements (cookie dialogs, page buttons) are findable and clickable with native locators. Android's UiAutomator does not see inside a WebView: the same dialog that is clickable on iOS is invisible on Android — fall back to coordinate taps or handle it outside the WebView. Locator tip for iOS web content: when an accessibility id lookup misses (or an XPath by @label does), check wd get source for the element's actual XCUIElementType — web controls often surface as Link or StaticText rather than Button, and the type in your XPath must match.

• For inspection (foreground app, processes, build props, settings) -> adb shell only; there is no WebDriver equivalent.

Default: prefer adb-shell for system-level work, WebDriver for UI element-level work.