Kobiton Automate

Plugin for the Kobiton mobile testing platform. Works with Claude Code, GitHub Copilot CLI, Gemini CLI, Codex CLI, and Cursor (CLI and IDE). Manage devices, upload apps, run automation sessions, and view test results directly from your AI coding assistant.

Contents

• Before You Begin
• Installation
  • Claude Code
  • GitHub Copilot CLI
  • Gemini CLI
  • Codex CLI
  • Cursor CLI
  • Cursor IDE
  • Other MCP Clients
  • Claude Surface Compatibility
• Login
  • API Key Authentication (Alternative)
• Getting Started
  • Your First Session
  • Which Skill Do I Want?
  • Concepts
  • Prerequisites
• What You Can Do
• Tools
• Skills
• Commands
• Running Automation Tests
• Interactive Device Testing
• Examples
• Troubleshooting
• Privacy & Data
• Development
• License

Before You Begin

Make sure you have:

• A Kobiton account - sign up at kobiton.com if you don't have one
• A supported AI assistant - install Claude Code, Copilot CLI, Gemini CLI, Codex CLI, or Cursor (CLI or IDE)
• A project directory - your AI assistant must launch from a workspace, not from your home folder

Installation

Claude Code

Open your project and start a Claude Code session:

cd my-project
claude

Inside the session, add the Kobiton marketplace and install the plugin:

/plugin marketplace add kobiton/automate
/plugin install automate@kobiton

GitHub Copilot CLI

Open your project and start a Copilot CLI session:

cd my-project
copilot

Inside the session, add the Kobiton marketplace and install the plugin:

/plugin marketplace add kobiton/automate
/plugin install automate@kobiton

Gemini CLI

From your project directory, install the extension directly from GitHub:

cd my-project
gemini extensions install https://github.com/kobiton/automate

Then launch Gemini CLI:

gemini

The kobiton MCP server and bundled skills are auto-discovered. Confirm the extension is active with /extensions list and the MCP server with /mcp.

Codex CLI

Add the Kobiton marketplace and install the plugin from the in-session browser. Codex opens a browser for Kobiton OAuth login on the first tool call.

codex plugin marketplace add kobiton/automate
codex

Inside Codex:

1. Type /plugins to open the plugin browser
2. Select the kobiton marketplace, then install the automate plugin
3. The system browser should open for Kobiton OAuth login. After sign-in, tokens are cached in the OS keychain (macOS Keychain / Linux Secret Service / Windows Credential Manager) with automatic refresh.
4. Run /mcp to confirm kobiton is Connected.

If you prefer not to use the marketplace, register the MCP server directly in ~/.codex/config.toml:

[mcp_servers.kobiton]
url = "https://api.kobiton.com/mcp"

Then copy AGENTS.md into your workspace so Codex picks up the tool list and skill reference:

curl -sLO https://raw.githubusercontent.com/kobiton/automate/main/AGENTS.md

Launch codex and run /mcp to confirm. The OAuth flow still applies on the first tool call.

Cursor CLI

Open your project and start a Cursor CLI session:

cd my-project
agent

Inside the session, add the Kobiton marketplace:

/plugin marketplace add github.com/kobiton/automate

Cursor parses the repository for a few seconds; when the automate entry appears, press Enter to install (pick the installation scope that suits you). The installation brings in the bundled skills, the kobiton MCP server, and the slash commands.

Then exit and relaunch agent. Cursor CLI currently loads plugin skills only at session start, so the skills won't appear until a fresh session.

Run /mcp list, select Kobiton, and choose Login to complete Kobiton OAuth in the browser.

Run /setup once to install the ~/.kobiton/bin/kobiton CLI wrapper used by the run-interactive-session skill. Cursor registers plugin commands without a namespace prefix, so the plugin's setup and doctor commands appear as /setup and /doctor — pick the one with the Kobiton description to tell them apart from Cursor's built-ins.

If you also use the Cursor IDE, install the plugin only once. Installs are shared between the CLI and the IDE (see the note in the next section).

Cursor IDE

The Cursor desktop editor installs the plugin from its built-in plugin browser:

1. Open Cursor Settings > Plugins and paste https://github.com/kobiton/automate into the search box
2. Click the automate result, then Add to Cursor, then Install

To authenticate with the Kobiton MCP server: open Tool & MCPs, search for kobiton, click Authenticate, and complete the OAuth login in the browser.

Using both Cursor CLI and the Cursor IDE? They share plugin installs: a plugin installed from the agent CLI shows up in the IDE, and vice versa. Install the plugin once in either one, installing it in both registers the skills, commands, and MCP server twice.

For a lightweight per-project setup that registers just the kobiton MCP server, drop .cursor/mcp.json from this repo into your project's .cursor/ directory:

cd my-project
mkdir -p .cursor
curl -sLO --output-dir .cursor https://raw.githubusercontent.com/kobiton/automate/main/.cursor/mcp.json

Works for both the Cursor IDE and the agent CLI. You won't get the bundled skills, the setup and doctor commands, or the CLI wrapper.

Other MCP Clients

Kobiton's MCP server is built on the open Model Context Protocol, so any MCP-compatible client can connect to it. Same endpoint (https://api.kobiton.com/mcp), same browser-based OAuth login as the clients above.

Good to know: End-to-end tested only on Claude Code, Copilot CLI, Gemini CLI, Codex CLI, Cursor CLI, and the Cursor IDE; entries below are configs we expect to work but have not yet validated. Please open an issue if any do not work for your setup. We're happy to help.

ChatGPT (Apps SDK)

ChatGPT consumes MCP servers via an HTTPS endpoint registered in ChatGPT developer mode. Point ChatGPT at:

https://api.kobiton.com/mcp

The Apps SDK does not require a separate manifest file; tool descriptors, OAuth flow, and _meta.ui widget hints flow through the MCP protocol itself. Reference: developers.openai.com/apps-sdk/build/mcp-server.

Continue / Cline / other generic MCP clients

Register the kobiton server in your client's MCP config. Most clients read a JSON block like:

{
  "mcpServers": {
    "kobiton": {
      "url": "https://api.kobiton.com/mcp"
    }
  }
}

Adjust to your client's specific format. The server URL and OAuth handshake are the same; if your client doesn't support OAuth, fall back to the API-key auth path (see API Key Authentication below) - most clients accept custom headers blocks.

Claude Surface Compatibility

Every Claude surface that supports MCP can call the Kobiton tools. The guided skills install automatically only in Claude Code today; other surfaces need a manual skill upload.

Claude surface	Atomic MCP tools	Orchestrated skills ¹	How to connect
Claude Code (CLI / IDE)	✅ Yes	✅ Yes	Install the plugin
Claude Cowork (macOS / Windows)	✅ Yes	⚠️ Manual upload ²	Add https://api.kobiton.com/mcp as a connector under Connectors
claude.ai web · Claude Desktop · Claude mobile	✅ Yes	⚠️ Manual upload ²	Add https://api.kobiton.com/mcp as a Custom Connector at claude.ai; for mobile, configure it on the web first and it syncs to the app

¹ run-interactive-session also requires the downloaded kobiton CLI binary (macOS on Apple Silicon, Linux x64, or Windows x64 under Git Bash; Intel Macs unsupported) - see the platform support note. ² This plugin is not listed in the Claude directory yet, so these surfaces can't install it as a plugin. As a workaround, zip a skill folder from this repo (e.g. skills/run-automation-suite/) and upload it as a custom skill.

Login

The first time your AI assistant calls a Kobiton tool, a browser window opens for OAuth login. Sign in with your Kobiton credentials, tokens are then managed automatically by the assistant.

You can also trigger or inspect authentication explicitly:

• Claude Code: type /mcp and select kobiton to start the OAuth flow
• GitHub Copilot CLI: type /mcp auth kobiton to start the OAuth flow; use /mcp (or /mcp show) to inspect server status
• Gemini CLI: type /mcp auth kobiton to start the OAuth flow; use /mcp to inspect server status
• Codex CLI: browser opens automatically on the first MCP tool call (e.g. "List my Kobiton devices") after plugin install. Tokens are cached in the OS keychain with automatic refresh. Use /mcp (or /mcp verbose) to inspect server status
• Cursor CLI: run /mcp list, select Kobiton, and choose Login to start the OAuth flow; tokens are stored by Cursor in the OS keychain
• Cursor IDE: open Cursor Settings > Tool & MCPs, search for kobiton, and click Authenticate to start the OAuth flow

Behind the scenes, .mcp.json points to the Kobiton MCP server and authentication uses OAuth 2.1:

{
  "mcpServers": {
    "kobiton": {
      "type": "http",
      "url": "https://api.kobiton.com/mcp"
    }
  }
}

After login, verify the plugin loaded by asking your assistant: "List my Kobiton devices". If tools aren't recognized, see Troubleshooting.

For CI/CD pipelines or headless environments that cannot open a browser, use API key auth instead:

1. Copy .mcp.apikey-example.json to .mcp.json

2. Generate an API key at Kobiton Portal > Settings > API Keys

3. Set the environment variable:

   # Add to ~/.zshrc, ~/.bashrc, or ~/.bash_profile
   export KOBITON_AUTH="Basic $(echo -n 'username:apikey' | base64)"
   

4. Reload your shell and restart your AI CLI.

Note: OAuth and API key auth cannot coexist in a single .mcp.json (the API key config sets an Authorization header that OAuth must not have). To switch, replace .mcp.json with the appropriate format from .mcp.apikey-example.json.

/automate:setup works under both OAuth and API key auth. Either way it writes the dedicated kobiton-mcp-<host> key to ~/.kobiton/.credentials, not the key in your KOBITON_AUTH header. Per the skill compatibility matrix, three skills read that file directly and have no MCP fallback: run-interactive-session, drive-automation-session, and monitor-test-run. Run setup once before using them. The MCP tools, run-automation-suite (your script carries its own credentials), and create-test-run (pure MCP) don't need the file.

Gemini CLI: API key auth requires editing gemini-extension.json instead of .mcp.json. Add a headers block under mcpServers.kobiton with "Authorization": "${KOBITON_AUTH}".

Cursor (CLI and IDE): API key auth requires editing .cursor/mcp.json instead of .mcp.json - that is the file the plugin manifest points mcpServers at. Cursor expands ${env:NAME}, not the bare ${NAME} other clients use, so start from .cursor/mcp.apikey-example.json rather than another client's config:

mkdir -p .cursor
curl -sL -o .cursor/mcp.json https://raw.githubusercontent.com/kobiton/automate/main/.cursor/mcp.apikey-example.json

A project-level .cursor/mcp.json survives plugin updates; the plugin's own copy lives in the version-pinned plugin cache and is replaced on reinstall.

Codex CLI: OAuth is the default. For CI/headless environments where a browser cannot open, switch to API key auth by adding an env_http_headers block to the plugin's .mcp.json, then export KOBITON_AUTH in the shell that launches codex:

"env_http_headers": { "Authorization": "KOBITON_AUTH" }

Recommended: maintain a fork of kobiton/automate with this change committed, then install from your fork - survives plugin reinstalls and Codex upgrades. edit the installed copy under directly (this is Codex cache; the edit is overwritten on every reinstall).

Getting Started

After installation, run setup to fetch your credentials and write them to ~/.kobiton/.credentials:

/automate:setup

The plugin uses your already-authenticated MCP session to start setup, then a bundled local script fetches your API key directly from Kobiton and writes the file - no manual file editing required. The API key never passes through the AI assistant: the conversation only sees a single-use setup token that expires within minutes and the last 4 characters of the key. Setup uses a dedicated API key named kobiton-mcp-<host> (for example kobiton-mcp-claude), created the first time and reused on every later setup from the same assistant.

Set up with a plugin version before 1.14.0? Those versions passed the API key through the conversation, so the transcript of that setup session contains the full key. If you ever shared, exported, or synced such a transcript, rotate that key in the Kobiton portal (Settings > API Keys) and run /automate:setup again.

To verify everything is wired correctly, run the diagnostic:

/automate:doctor

/automate:doctor is read-only. It checks the CLI installation (wrapper + target), the credentials file, the active profile, required fields, and CLI version drift (the plugin's pinned version vs the installed binary vs the newest published build), and prints actionable remediation hints for any failures.

On Cursor (CLI and IDE) the plugin's commands carry no automate: prefix. Run /setup and /doctor instead, picking the entry with the Kobiton description next to it to tell it apart from Cursor's built-in command of the same name.

CLI install behavior across CLIs: The run-interactive-session skill depends on a ~/.kobiton/bin/kobiton wrapper (a symlink on macOS/Linux, an exec shim on Windows). The same install script also downloads the plugin's pinned CLI build into ~/.kobiton/cli/ the first time it runs (sha256-verified; cache hits skip the network entirely).

• Claude Code, Codex CLI: run automatically by a bundled SessionStart hook on every session start. On Codex CLI, the first session prompts you to trust the hook once via /hooks; subsequent sessions run it silently. Running /automate:setup also re-runs the installer on demand.
• GitHub Copilot CLI, Gemini CLI, Cursor CLI: no SessionStart hook runs, so run the setup command once after install: /automate:setup on Copilot and Gemini, /setup (the one with the Kobiton description) on Cursor (Copilot reads Claude-format Markdown commands; Gemini reads bundled TOML at commands/automate/setup.toml). Re-run it if the wrapper goes missing.

Manual fallback - if the SessionStart hook was denied on Codex, or you need to install without an active session:

bash "$(find ~/.codex -name install-cli.sh -path '*automate*' 2>/dev/null | head -1)"

The script is idempotent - safe to re-run.

Your First Session

New to Kobiton? This is the whole journey, start to finish. Each step is one thing you say to your assistant:

1. Set up credentials — run /automate:setup once (see above).
2. Find a device — "List my available Android devices." Kobiton's cloud devices are real phones and tablets; pick one and note its name or UDID.
3. Reserve it — "Reserve the Pixel 8." A reservation holds the device exclusively for you.
4. Do one thing on it — "Open the browser and search for kobiton" (the drive-automation-session skill auto-pilots it), or drive it step by step yourself with run-interactive-session.
5. Save it as a test case — "Save that session as a test case named smoke-search." Now the flow is repeatable.
6. (Optional) Run it at scale — "Create a test run for smoke-search on 3 devices and watch it." The create-test-run and monitor-test-run skills take it from here.

That's the full loop: device → session → test case → test run. Every skill in this plugin is a step on that path.

Which Skill Do I Want?

Reach for this when…	Skill
You have local Appium test scripts (Node.js, Python, .NET, Java) to run on Kobiton devices	run-automation-suite
You want a clean, hands-off run of a described flow that you'll SAVE as a test case and rerun	drive-automation-session
You want quick inspection or troubleshooting when something breaks — poke at the device, pull logs, push files	run-interactive-session
You have a test case or suite and want to kick off a test run from it	create-test-run
A test run is already going and you want to watch it and catch blockers	monitor-test-run
You want to debug your app on a real device attached to your machine — see it in adb / Xcode, install a local build, read logcat	debug-device-over-vusb

Say it your way — your assistant routes by meaning, not keyword: "rerun / revisit / replay a test case on other devices" goes to create-test-run; "rerun a session" means saving it as a test case first (sessions aren't rerun directly); "replay the recording" just opens the session's artifacts, no new run. And if your prompt names a goal but not a method ("test the login screen of app ABC"), the assistant asks one short question — run your scripts, let it drive the flow, or explore hands-on — defaulting to drive-automation-session so the result stays saveable as a test case.

Concepts

Term	Meaning
Session	One connection to a device — everything you did (commands, video, logs) is recorded under a session id.
Session type	How the session was driven, as the type field of getSession / listSessions: AUTO (script or agent via Appium), UIAUTOMATOR / XCUITEST (native instrumentation — startNativeSession or the CLI's test run), CLI (the bundled CLI wrapper), MANUAL (you, in the portal live view), MIXED (you interacted in the live view while an automation session ran); rarer: SCRIPTLESS, GAMEDRIVER.
Test case	A saved, replayable sequence of steps, created by saving a completed session (saveTestCase). Automation sessions are saveable; CLI sessions are not.
Revisit	What a test run does: re-executes a test case's saved steps on each selected device — one "revisit execution" per device.
Test run	An execution of a test case or test suite across one or more devices, with per-device results.
Test suite	An ordered collection of test cases run together.
Reservation	An exclusive hold on a device so nothing else can use it while you work.
Device UDID	The unique identifier of a specific device — the unambiguous way to target one.
Live remediation	When a test run execution hits a blocker, Kobiton lets you take over the device in the browser, fix the step live, and let the run continue.

Prerequisites

Before your first session, you need:

• A Kobiton account — sign up or use your organization's account.
• A supported host CLI — Claude Code, GitHub Copilot CLI, Gemini CLI, Codex CLI, or Cursor (see Installation).
• Credentials configured — run /automate:setup once after install.
• Your app build (.apk / .ipa), if you're testing your own app rather than a system app or website.
• Platform note: the run-interactive-session skill's CLI runs on macOS (Apple Silicon), Linux (x64), and Windows (x64 under Git Bash). The binary is downloaded on install — a version pinned by the plugin release, sha256-verified, cached under ~/.kobiton/cli/ — so the first install needs network access once. Intel Macs are not supported (no macos-x64 build is published); there, use run-automation-suite or drive-automation-session instead — no dead end.

One worked example, end to end — paste these to your assistant one at a time:

Upload ./builds/my-app.apk to Kobiton
List my available Android devices and reserve a Pixel
Open my app on the reserved device, log in, and add the first item to the cart
Save that session as a test case named smoke-add-to-cart
Create a test run for smoke-add-to-cart on 3 Android devices and watch it

Every step above uses only what this plugin ships: the app tools (uploadAppToStore, confirmAppUpload), device tools (listDevices, reserveDevice), the drive-automation-session skill, the saveTestCase tool, and the create-test-run / monitor-test-run skills.

What You Can Do

Ask your assistant naturally:

• "List my available Android devices"
• "Upload my-app.apk and run tests on the Pixel 6"
• "Show me the results for session 502"
• "Run my Appium test script on the Pixel 6"

Tools

41 MCP tools across 5 domains.

Devices

Tool	Description
listDevices	List available devices filtered by platform, availability, or group; virtualUsb: true narrows to private devices ready for virtualUSB (adds virtual_usb_ready / virtual_usb_reason); an org admin can pass the same udid to listHostingMachines to see why a device is not ready
listHostingMachines	Org admins only: list host machines with their virtualUSB configuration and a virtual_usb_status (state, message, next step); udid narrows to one device's host, machineId to one machine; cursor paging via afterId / next_after_id; never returns IP addresses
configureHostingMachine	Org admins only: change one host machine's virtualUSB settings (on/off, Kobiton-managed or self-managed routing) and/or its max parallel tests in one save; turning virtualUSB off or leaving Kobiton-managed routing ends active virtualUSB sessions, as in Portal; returns changed and the machine; never returns IP addresses
getDeviceStatus	Get real-time status of a specific device
reserveDevice	Reserve a device for exclusive testing
terminateReservation	Release a reserved device by terminating its reservation

Sessions

Tool	Description
listSessions	List test sessions with filters for status, device, platform
getSession	Get session details including commands, capabilities, metadata
getSessionArtifacts	Get download URLs for video, logs, screenshots, reports
getUserInputEvents	Get the touch/swipe gestures a human made on the device-only live view during a session
listAccessibilityValidations	List a session's accessibility findings, paged; filter by type and opt into heavy fields
getAccessibilityValidationsSummary	Counts and breakdown of a session's accessibility findings, without the rows
listCrashValidations	List the app crashes detected in a session, with crash logs, paged
listResponseTimeValidations	List a session's steps that exceeded the response-time threshold, paged
listBlockerValidations	List the blockers hit while replaying a test case in a session, paged
listElementSelectionValidations	List a session's steps whose target element resolved differently than recorded, paged
listFlexCorrects	List the steps Flex Correct self-healed in a session, paged
terminateSession	Stop a running test session
startNativeSession	Start an XCUITest / UIAutomator / GameDriver native automation session on a device

Apps

Tool	Description
listApps	List uploaded app builds in your organization
uploadAppToStore	Upload an app to Kobiton Store (permanent, visible in portal)
confirmAppUpload	Confirm an uploaded file so Kobiton creates the app record (parsing runs asynchronously)
getAppParsingStatus	Check the async parse status of an uploaded app version until it reaches a terminal state
getApp	Get app details and version history

Test Management

Tool	Description
saveTestCase	Convert a finished manual session into a reusable test case
listTestCases	List one team's test cases (teamId required for org members; admins omit = org-level only)
getTestCase	Get test case details including its steps
updateTestCase	Update a test case's metadata and steps
deleteTestCase	Delete a test case
createTestRun	Create a test run from a test suite or selected test cases (re-executes recorded steps — not the CLI's kobiton test run, which runs your own UIAutomator/XCUITest bundle; see run-interactive-session)
listTestRuns	List one team's test runs (teamId required for org members; admins omit = org-level only)
getTestRun	Get test run details including its sessions
terminateTestRun	Stop a running test run
listTestSuites	List one team's test suites (teamId required for org members; admins omit = org-level only)
getTestSuite	Get test suite details including member test cases
createTestSuite	Create a test suite from existing test cases
updateTestSuite	Update a test suite's metadata and membership
deleteTestSuite	Delete a test suite (member test cases are kept)

Account

Tool	Description
getCredential	Return a single-use setup token (never the API key) that the local setup script redeems to write ~/.kobiton/.credentials — backs /automate:setup
listTeams	List the teams the calling user belongs to (for team-scoped test-management calls)
getOrgSettings	Return your organization's feature flags and preferences (e.g. live remediation) — read up front by create-test-run and monitor-test-run

Skills

Skill	Description
run-automation-suite	Guided workflow for app upload, device selection, local Appium script execution (Node.js, Python, .NET, Java), and result collection.
run-interactive-session	Guided workflow for interactive testing using natural language. WebDriver actions, device operations (adb shell, logs, screen), file management (push/pull), and more. Renamed from run-interactive-cli-session in 1.8.0.
drive-automation-session	Drives an already-reserved device from a natural-language intent via a direct Appium HTTP session (observe-decide-act loop). Returns a session id consumable by saveTestCase. Complements run-interactive-session — it uses the automation session type rather than the CLI.
create-test-run	Creates a test run from a test case or suite — fills sensible defaults from the createTestRun schema when details are omitted, confirms a summary, then offers to monitor it and hands off to monitor-test-run.
monitor-test-run	Watches a running test run and narrates it: reads the live-remediation flag up front, surfaces the live-remediation URL the moment an execution is blocked (optionally auto-opening the window), and post-mortems so a BLOCKER_ENCOUNTERED execution is never reported as passed. Quiet between real state changes.
debug-device-over-vusb	Debugs your app on a real Kobiton device attached to your own machine over virtualUSB: finds vUSB-ready private devices (listDevices with virtualUsb: true), connects the device so it appears in adb / Xcode locally, runs the install-reproduce-capture-logs loop from plain language, and always disconnects. Installs the pinned virtualUSB client on first use (macOS: cached; Windows: verified installer handed to you).

Platform support note: all MCP tools and the run-automation-suite skill work on every platform the host CLI supports. The run-interactive-session skill downloads its CLI binary on install (a version pinned by the plugin release, sha256-verified, cached under ~/.kobiton/cli/) and runs on macOS (Apple Silicon), Linux (x64), and Windows (x64 under Git Bash). Intel Macs are not supported — no macos-x64 build is published; there, use run-automation-suite or the MCP tools directly. The debug-device-over-vusb skill downloads the virtualUSB client on its first use only (macOS: any architecture, cached under ~/.kobiton/vusb/; Windows: a verified .msi you install once with administrator rights), and is not supported on Linux hosts. For the full per-skill picture — which skills need a persistent local filesystem, which need the ~/.kobiton/.credentials file that /automate:setup writes, and which run on an MCP connection alone — see the Skill compatibility matrix in CLAUDE.md.

Commands

Command	Description
/automate:setup	Write your Kobiton credentials to ~/.kobiton/.credentials without passing the API key through the assistant
/automate:doctor	Read-only diagnostic for CLI installation, credentials file, active profile, required fields, CLI version drift, and the virtualUSB client pin

On Cursor (CLI and IDE) these register without the automate: prefix — as /setup and /doctor, distinguishable from Cursor's built-ins by the Kobiton description.

Running Automation Tests

Use the run-automation-suite skill to run local Appium test scripts. Your AI assistant reads your script, extracts capabilities, confirms the target device, and executes the script locally. Supports Node.js (.js), Python (.py), .NET (.cs), and Java (.java) scripts.

Interactive Device Testing

Use the run-interactive-session skill to interact with devices using natural language. Describe what you want — "tap the login button", "type hello in the search field", "swipe down" — and your assistant translates your intent into CLI commands.

Beyond WebDriver, the skill also supports device operations (adb shell, logs, screen capture), file management (push/pull files to device), and app management.

Examples

See docs/examples.md for prompt examples covering every tool and skill - device management, session management, app management, automation, and interactive testing.

Troubleshooting

Updating the Plugin

After the plugin is updated upstream, pull the latest version:

• Claude Code / Copilot CLI: run /plugin install automate@kobiton again
• Gemini CLI: run gemini extensions update kobiton-automate from your shell
• Codex CLI: run codex plugin marketplace upgrade to refresh the marketplace catalog, then reinstall the plugin from the browser to pull the latest manifest
• Cursor CLI: re-run /plugin marketplace add github.com/kobiton/automate and reinstall the automate plugin - Cursor CLI has no dedicated update command yet (/plugin marketplace list only lists what's installed). Restart agent so the new manifest is picked up.

To make sure the assistant picks up the changes with no stale cache, reload per CLI:

• Claude Code: run /reload-plugins in-session. If tools still behave unexpectedly, /clear resets the session context.
• GitHub Copilot CLI: exit and relaunch the session (exit, then copilot). No in-session reload command.
• Gemini CLI: exit and relaunch (exit, then gemini). Confirm with gemini extensions list.
• Codex CLI: exit and relaunch. Confirm with codex plugin list.

If the issue persists after relaunch, quit the terminal entirely and start a fresh session.

Common Issues

All four CLIs cache plugin state when the session starts. After installing or updating the plugin, the kobiton MCP server may not show up in the server list immediately. Force a reload:

Claude Code — reload plugins in the current session:

/reload-plugins

GitHub Copilot CLI — exit and relaunch the session:

exit
copilot

Gemini CLI — exit and relaunch; if still missing, verify the extension is enabled:

exit
gemini extensions list
gemini

Codex CLI — exit and relaunch; if still missing, verify the marketplace was added and the plugin was installed:

exit
codex plugin marketplace list
codex plugin list
codex

If using the manual fallback config, also check grep -A 4 "mcp_servers.kobiton" ~/.codex/config.toml.

Then check the server list (/mcp in Claude Code, Gemini CLI, and Codex CLI, /mcp show in Copilot CLI). kobiton should now appear.

The device may be offline, reserved by another user, or no longer in your device list. Use listDevices with available: true to find currently online devices.

Large app files or slow connections can cause uploads to time out. Retry the upload — pre-signed URLs expire after 30 minutes, so a new URL will be generated automatically.

Claude Code

Some older versions of Claude Code don't support the plugin features this plugin relies on. Make sure you're on the latest version:

npm install -g @anthropic-ai/claude-code@latest

Then restart Claude Code and try again.

Claude Code requires a working directory. Launch it from inside a project folder:

cd my-project
claude

If you see this prompt repeatedly, make sure you are not running claude from your home directory or root (/).

The Kobiton marketplace must be added before installing:

/plugin marketplace add kobiton/automate
/plugin install automate@kobiton

If it still isn't found, check your internet connection and ensure you're running the latest version of Claude Code (claude update).

Claude Code is not installed or not in your PATH.

• Install: follow the official install guide

• PATH issue: if you installed via npm, make sure your npm global bin directory is in your PATH:

  npm install -g @anthropic-ai/claude-code
  

  Then open a new terminal window and try claude again.

The plugin installed but tools don't appear or Claude doesn't recognize Kobiton commands.

1. Run /reload-plugins to force Claude to pick up the new plugin
2. Try asking: "List my Kobiton devices"
3. If still not working, quit Claude Code entirely and start a fresh session
4. Verify .mcp.json exists in the plugin directory — it tells Claude where the Kobiton MCP server lives

Copilot CLI

Verify the plugin is installed and the MCP server is configured:

# Check installed plugins
copilot plugin list

# Check MCP server status
/mcp show

If the kobiton MCP server doesn't appear, add it manually by running /mcp add and entering the following when prompted:

• Server name: kobiton
• Type: http
• URL: https://api.kobiton.com/mcp

Alternatively, edit ~/.copilot/mcp-config.json directly:

{
  "mcpServers": {
    "kobiton": {
      "type": "http",
      "url": "https://api.kobiton.com/mcp"
    }
  }
}

Copilot CLI requires explicit tool permissions. Allow Kobiton tools:

# Allow all Kobiton MCP tools
copilot --allow-tool='kobiton'

# Or allow specific tools
copilot --allow-tool='kobiton(listDevices)' --allow-tool='kobiton(getSession)'

Gemini CLI

Verify the extension is registered and enabled:

gemini extensions list

If kobiton-automate is missing, reinstall:

gemini extensions install https://github.com/kobiton/automate

If listed but disabled, enable it:

gemini extensions enable kobiton-automate

Then relaunch gemini and check /mcp for the kobiton server. The run-automation-suite skill is auto-discovered from skills/ at the extension root, no separate registration needed.

The extension is installed but you haven't completed OAuth yet. Trigger the flow manually:

/mcp auth kobiton

A browser window opens for Kobiton login. After signing in, run /mcp again — the status should change to 🟢 Connected.

Note: kobiton here is the MCP server name (declared inside the extension), not the extension name kobiton-automate. /mcp commands always take the server name.

Gemini CLI's extension uses dynamic OAuth discovery by default. The Kobiton MCP server advertises OAuth metadata at a standard well-known endpoint, so the browser flow should kick in automatically the first time a tool needs auth.

If nothing happens, try /mcp auth kobiton to trigger it explicitly. Check that your terminal can launch a browser. For headless environments, switch to API key auth by editing gemini-extension.json directly (see the API Key Authentication section above).

Codex CLI

Verify each step:

1. Plugin installed — open /plugins inside Codex and confirm automate is listed under the kobiton marketplace as Installed. If missing, run codex plugin marketplace add kobiton/automate and reinstall from the plugin browser.
2. Codex version recent enough — update with npm install -g @openai/codex@latest.

After fixing, exit Codex and relaunch; the server should show in /mcp (or /mcp verbose).

Codex tries to launch your system browser when Kobiton requires sign-in. If nothing opens, check:

1. Default browser is set — your OS needs a default browser. SSH sessions without X forwarding cannot open one.
2. Localhost ports not blocked — Codex listens on a local port to receive the login callback. Firewall rules that block all localhost ports will break the flow.
3. Headless environment — switch to API key auth (see the API Key Authentication section above). Easiest: fork this repo, commit the env_http_headers change to .codex/.mcp.json, install from your fork.

This usually means the cached token is stale and refresh failed. Force a re-login by clearing the OS keychain entry and reconnecting:

• macOS: open Keychain Access, search for codex-mcp or kobiton, delete the entry, then trigger a tool call to re-run OAuth.
• Linux: secret-tool clear service codex-mcp (or use Seahorse to remove the entry).
• Windows: open Credential Manager, find the Codex entry under Generic Credentials, remove it.

After clearing, run any Kobiton tool prompt; the browser should reopen for fresh login.

Cursor CLI

Cursor CLI caches plugin state per session, and older builds didn't load plugin-bundled skills at all:

1. Fully restart the session — exit and re-run agent. Right after an install or update, the command list can render stale entries from the previous install; a fresh launch fixes it.
2. Update the CLI — plugin skills only register in CLI builds from 2026.05.05 onward. Run agent update, then relaunch.
3. Reinstall if still missing — /plugin marketplace add github.com/kobiton/automate, wait for the automate entry to appear, then press Enter to install.

• Not logged in yet — run /mcp list, select kobiton, and choose Login to start the browser OAuth flow. Tokens are stored in the OS keychain.
• Known CLI regressions — a few CLI builds listed MCP tools but never executed the calls. Run agent update to get the latest build, then relaunch agent.

Cursor CLI does not run the plugin's SessionStart hook, so the CLI wrapper isn't created automatically like on Claude Code or Codex. Run /setup (the plugin's command with the Kobiton description, not Cursor's built-in) once after install; re-run it if the wrapper goes missing.

Still Stuck?

For additional help, open an issue at github.com/kobiton/automate/issues or ask in #general-discussion on Discord. Feel free to share feature requests. We welcome product feedback and will consider it as we continue to improve the platform.

Privacy & Data

This plugin connects to the Kobiton cloud API (api.kobiton.com) over HTTPS (TLS 1.2+).

Authentication:

• OAuth 2.1 (default): Your AI assistant opens a browser for Kobiton login. Short-lived access tokens are stored securely in the system keychain. No credentials are stored in the project.
• API Key (alternative): The KOBITON_AUTH environment variable is sent via the Authorization header on each request. The value is stored only in your shell profile, never committed to the repo.

Data handling:

• The plugin does not store any data locally beyond what your AI assistant retains in its conversation context.
• Tool responses (device lists, session details, test results) pass through your assistant's context window and are subject to Anthropic's Privacy Policy, GitHub Copilot's Privacy Statement, Google's Gemini Privacy Notice, or OpenAI's Privacy Policy, depending on which assistant you use.
• App binaries uploaded via uploadAppToStore are sent directly to Kobiton's pre-signed S3 URLs, not through your AI assistant.

For details on how Kobiton handles your data, see the Kobiton Privacy Policy and Trust Center.

Development

The tools/ directory contains the YAML schemas of the MCP server's tools. They are published as the @kobiton/mcp-tools package, the catalog the hosted MCP server serves, and are not consumed by the plugin at runtime.

# Install dependencies
pnpm install

# Validate manifests and schemas
pnpm run validate

# Run tests
pnpm test

# Refresh the .codex/ mirror after editing skills/ or assets/
pnpm run build:codex

# Build combined tool definitions into dist/, refresh the .codex/ mirror and sync manifest versions
pnpm run build

License

MIT