{"id":50530842,"url":"https://github.com/kobiton/automate","last_synced_at":"2026-06-03T13:03:16.092Z","repository":{"id":349961656,"uuid":"1193991513","full_name":"kobiton/automate","owner":"kobiton","description":"AI coding assistant plugin for the Kobiton mobile testing platform. Works with Claude Code, Copilot CLI, Gemini CLI, and Codex CLI to manage devices, upload apps, run mobile automation, and view test results directly from your workspace.","archived":false,"fork":false,"pushed_at":"2026-05-28T04:49:35.000Z","size":22243,"stargazers_count":9,"open_issues_count":26,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-28T05:13:29.141Z","etag":null,"topics":["ai-coding-assistant","android-testing","appium","claude-code","cli-tool","codex-cli","copilot-cli","gemini-cli","ios-testing","kobiton","mobile-automation","mobile-testing","test-automation"],"latest_commit_sha":null,"homepage":"https://kobiton.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kobiton.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-27T19:54:54.000Z","updated_at":"2026-05-28T04:49:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kobiton/automate","commit_stats":null,"previous_names":["kobiton/automate"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/kobiton/automate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kobiton%2Fautomate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kobiton%2Fautomate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kobiton%2Fautomate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kobiton%2Fautomate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kobiton","download_url":"https://codeload.github.com/kobiton/automate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kobiton%2Fautomate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33865658,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-coding-assistant","android-testing","appium","claude-code","cli-tool","codex-cli","copilot-cli","gemini-cli","ios-testing","kobiton","mobile-automation","mobile-testing","test-automation"],"created_at":"2026-06-03T13:03:15.089Z","updated_at":"2026-06-03T13:03:16.084Z","avatar_url":"https://github.com/kobiton.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \u003cimg src=\"./assets/logo.svg\" width=\"35\" align=\"center\" alt=\"Kobiton Logo\" /\u003e Kobiton Automate\n\n[![Discord](https://img.shields.io/discord/1486036652685267055?color=7289DA\u0026label=Discord\u0026logo=discord\u0026logoColor=white)](https://discord.gg/uHvBFDZVP)\n[![Cloud](https://img.shields.io/badge/Cloud-☁️-blue)](https://kobiton.com)\n[![Twitter Follow](https://img.shields.io/twitter/follow/KobitonMobile?style=social)](https://x.com/KobitonMobile)\n\nPlugin for the [Kobiton](https://kobiton.com) mobile testing platform. Works with [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Codex CLI](https://github.com/openai/codex), and [Cursor](https://cursor.com) (CLI and IDE). Manage devices, upload apps, run automation sessions, and view test results directly from your AI coding assistant.\n\n## Contents\n\n- [Before You Begin](#before-you-begin)\n- [Installation](#installation)\n  - [Claude Code](#claude-code)\n  - [GitHub Copilot CLI](#github-copilot-cli)\n  - [Gemini CLI](#gemini-cli)\n  - [Codex CLI](#codex-cli)\n  - [Cursor CLI](#cursor-cli)\n  - [Cursor IDE](#cursor-ide)\n  - [Other MCP Clients](#other-mcp-clients)\n- [Login](#login)\n  - [API Key Authentication (Alternative)](#api-key-authentication-alternative)\n- [Getting Started](#getting-started)\n- [What You Can Do](#what-you-can-do)\n- [Tools](#tools)\n- [Skills](#skills)\n- [Commands](#commands)\n- [Running Automation Tests](#running-automation-tests)\n- [Interactive Device Testing](#interactive-device-testing)\n- [Examples](#examples)\n- [Troubleshooting](#troubleshooting)\n- [Privacy \u0026 Data](#privacy--data)\n- [Development](#development)\n- [License](#license)\n\n## Before You Begin\n\nMake sure you have:\n\n- **A Kobiton account** - sign up at [kobiton.com](https://kobiton.com) if you don't have one\n- **A supported AI assistant** - install [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview), [Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Codex CLI](https://github.com/openai/codex), or [Cursor](https://cursor.com) (CLI or IDE)\n- **A project directory** - your AI assistant must launch from a workspace, not from your home folder\n\n## Installation\n\n### Claude Code\n\nOpen your project and start a Claude Code session:\n\n```bash\ncd my-project\nclaude\n```\n\nInside the session, add the Kobiton marketplace and install the plugin:\n\n```\n/plugin marketplace add kobiton/automate\n/plugin install automate@kobiton\n```\n\n### GitHub Copilot CLI\n\nOpen your project and start a Copilot CLI session:\n\n```bash\ncd my-project\ncopilot\n```\n\nInside the session, add the Kobiton marketplace and install the plugin:\n\n```\n/plugin marketplace add kobiton/automate\n/plugin install automate@kobiton\n```\n\n### Gemini CLI\n\nFrom your project directory, install the extension directly from GitHub:\n\n```bash\ncd my-project\ngemini extensions install https://github.com/kobiton/automate\n```\n\nThen launch Gemini CLI:\n\n```bash\ngemini\n```\n\nThe `kobiton` MCP server and bundled skills are auto-discovered. Confirm the extension is active with `/extensions list` and the MCP server with `/mcp`.\n\n### Codex CLI\n\nAdd 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.\n\n```bash\ncodex plugin marketplace add kobiton/automate\ncodex\n```\n\nInside Codex:\n\n1. Type `/plugins` to open the plugin browser\n2. Select the **kobiton** marketplace, then install the **automate** plugin\n3. 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.\n4. Run `/mcp` to confirm `kobiton` is **Connected**.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFallback: manual \u003ccode\u003econfig.toml\u003c/code\u003e setup\u003c/strong\u003e\u003c/summary\u003e\n\nIf you prefer not to use the marketplace, register the MCP server directly in `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.kobiton]\nurl = \"https://api.kobiton.com/mcp\"\n```\n\nThen copy `AGENTS.md` into your workspace so Codex picks up the tool list and skill reference:\n\n```bash\ncurl -sLO https://raw.githubusercontent.com/kobiton/automate/main/AGENTS.md\n```\n\nLaunch `codex` and run `/mcp` to confirm. The OAuth flow still applies on the first tool call.\n\u003c/details\u003e\n\n### Cursor CLI\n\nOpen your project and start a Cursor CLI session:\n\n```bash\ncd my-project\nagent\n```\n\nInside the session, add the Kobiton marketplace:\n\n```\n/plugin marketplace add github.com/kobiton/automate\n```\n\nCursor parses the repository for a few seconds; when the **automate** entry appears, press \u003ckbd\u003eEnter\u003c/kbd\u003e to install (pick the installation scope that suits you). The installation brings in the bundled skills, the `kobiton` MCP server, and the slash commands.\n\nThen exit and relaunch `agent`. Cursor CLI currently loads plugin skills only at session start, so the skills won't appear until a fresh session.\n\nRun `/mcp list`, select **Kobiton**, and choose **Login** to complete Kobiton OAuth in the browser.\n\nRun `/setup` once to install the `~/.kobiton/bin/kobiton` CLI wrapper used by the `run-interactive-test` 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.\n\nIf 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).\n\n### Cursor IDE\n\nThe Cursor desktop editor installs the plugin from its built-in plugin browser:\n\n1. Open **Cursor Settings** \u003e **Plugins** and paste `https://github.com/kobiton/automate` into the search box\n2. Click the **automate** result, then **Add to Cursor**, then **Install**\n\nTo authenticate with the Kobiton MCP server: open **Tool \u0026 MCPs**, search for **kobiton**, click **Connect**, and complete the OAuth login in the browser.\n\n\u003e **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.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAlternative: project-only MCP config (MCP server only, no skills or commands)\u003c/strong\u003e\u003c/summary\u003e\n\nFor 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:\n\n```bash\ncd my-project\nmkdir -p .cursor\ncurl -sLO --output-dir .cursor https://raw.githubusercontent.com/kobiton/automate/main/.cursor/mcp.json\n```\n\nWorks 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.\n\u003c/details\u003e\n\n### Other MCP Clients\n\nKobiton's MCP server is built on the open [Model Context Protocol](https://modelcontextprotocol.io), 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.\n\n\u003e **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](https://github.com/kobiton/automate/issues/new?template=bug_report.md) if any do not work for your setup. We're happy to help.\n\n#### ChatGPT (Apps SDK)\n\nChatGPT consumes MCP servers via an HTTPS endpoint registered in ChatGPT developer mode. Point ChatGPT at:\n\n```\nhttps://api.kobiton.com/mcp\n```\n\nThe 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](https://developers.openai.com/apps-sdk/build/mcp-server).\n\n#### Continue / Cline / other generic MCP clients\n\nRegister the `kobiton` server in your client's MCP config. Most clients read a JSON block like:\n\n```json\n{\n  \"mcpServers\": {\n    \"kobiton\": {\n      \"url\": \"https://api.kobiton.com/mcp\"\n    }\n  }\n}\n```\n\nAdjust 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](#api-key-authentication-alternative) below) - most clients accept custom `headers` blocks.\n\n## Login\n\nThe 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.\n\nYou can also trigger or inspect authentication explicitly:\n\n- **Claude Code**: type `/mcp` and select **kobiton** to start the OAuth flow\n- **GitHub Copilot CLI**: type `/mcp auth kobiton` to start the OAuth flow; use `/mcp` (or `/mcp show`) to inspect server status\n- **Gemini CLI**: type `/mcp auth kobiton` to start the OAuth flow; use `/mcp` to inspect server status\n- **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\n- **Cursor CLI**: run `/mcp list`, select **kobiton**, and choose **Login** to start the OAuth flow; tokens are stored by Cursor in the OS keychain\n- **Cursor IDE**: open **Cursor Settings** \u003e **Tool \u0026 MCPs**, search for **kobiton**, and click **Connect** to start the OAuth flow\n\nBehind the scenes, `.mcp.json` points to the Kobiton MCP server and authentication uses OAuth 2.1:\n\n```json\n{\n  \"mcpServers\": {\n    \"kobiton\": {\n      \"type\": \"http\",\n      \"url\": \"https://api.kobiton.com/mcp\"\n    }\n  }\n}\n```\n\nAfter login, verify the plugin loaded by asking your assistant: *\"List my Kobiton devices\"*. If tools aren't recognized, see [Troubleshooting](#troubleshooting).\n\n\u003ca id=\"api-key-authentication-alternative\"\u003e\u003c/a\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAPI Key Authentication (Alternative)\u003c/strong\u003e\u003c/summary\u003e\n\nFor CI/CD pipelines or headless environments that cannot open a browser, use API key auth instead:\n\n1. Copy `.mcp.apikey-example.json` to `.mcp.json`\n2. Generate an API key at **Kobiton Portal \u003e Settings \u003e API Keys**\n3. Set the environment variable:\n\n   ```bash\n   # Add to ~/.zshrc, ~/.bashrc, or ~/.bash_profile\n   export KOBITON_AUTH=\"Basic $(echo -n 'username:apikey' | base64)\"\n   ```\n\n4. Reload your shell and restart your AI CLI.\n\n\u003e **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`.\n\u003e\n\u003e **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}\"`.\n\u003e\n\u003e **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`:\n\u003e\n\u003e ```\n\u003e \"env_http_headers\": { \"Authorization\": \"KOBITON_AUTH\" }\n\u003e ```\n\u003e\n\u003e **Recommended:** maintain a fork of `kobiton/automate` with this change committed, then install from your fork - survives plugin reinstalls and Codex upgrades. **Last resort:** edit the installed copy under `~/.codex/.tmp/marketplaces/kobiton/.codex/.mcp.json` directly (this is Codex cache; the edit is overwritten on every reinstall).\n\n\u003c/details\u003e\n\n## Getting Started\n\nAfter installation, run setup to fetch your credentials and write them to `~/.kobiton/.credentials`:\n\n```\n/automate:setup\n```\n\nThe plugin uses your already-authenticated MCP session (OAuth) to fetch your username and API key - no manual file editing required.\n\nTo verify everything is wired correctly, run the diagnostic:\n\n```\n/automate:doctor\n```\n\n`/automate:doctor` is read-only. It checks the CLI installation (symlink + target), the credentials file, the active profile, and required fields, and prints actionable remediation hints for any failures.\n\n\u003e **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.\n\n**CLI symlink install behavior across CLIs:** The `run-interactive-test` skill depends on a `~/.kobiton/bin/kobiton` symlink.\n\n- **Claude Code, Codex CLI**: recreated 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 recreates the symlink on demand.\n- **GitHub Copilot CLI, Gemini CLI, Cursor CLI**: no SessionStart hook runs, so create the symlink manually by running 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 symlink goes missing.\n\nManual fallback - if the SessionStart hook was denied on Codex, or you need to install without an active session:\n\n```bash\nbash \"$(find ~/.codex -name install-cli.sh -path '*automate*' 2\u003e/dev/null | head -1)\"\n```\n\nThe script is idempotent - safe to re-run.\n\n## What You Can Do\n\n**Ask your assistant naturally:**\n\n- \"List my available Android devices\"\n- \"Upload my-app.apk and run tests on the Pixel 6\"\n- \"Show me the results for session 502\"\n- \"Run my Appium test script on the Pixel 6\"\n\n## Tools\n\n13 MCP tools across 4 domains.\n\n### Devices\n\n| Tool | Description |\n|------|-------------|\n| `listDevices` | List available devices filtered by platform, availability, or group |\n| `getDeviceStatus` | Get real-time status of a specific device |\n| `reserveDevice` | Reserve a device for exclusive testing |\n| `terminateReservation` | Release a reserved device by terminating its reservation |\n\n### Sessions\n\n| Tool | Description |\n|------|-------------|\n| `listSessions` | List test sessions with filters for status, device, platform |\n| `getSession` | Get session details including commands, capabilities, metadata |\n| `getSessionArtifacts` | Get download URLs for video, logs, screenshots, reports |\n| `terminateSession` | Stop a running test session |\n\n### Apps\n\n| Tool | Description |\n|------|-------------|\n| `listApps` | List uploaded app builds in your organization |\n| `uploadAppToStore` | Upload an app to Kobiton Store (permanent, visible in portal) |\n| `confirmAppUpload` | Confirm uploaded app for tracking record |\n| `getApp` | Get app details and version history |\n\n### Account\n\n| Tool | Description |\n|------|-------------|\n| `getCredential` | Return the authenticated user's username, API key, and portal URL — backs `/automate:setup` |\n\n## Skills\n\n| Skill | Description |\n|-------|-------------|\n| **run-automation-suite** | Guided workflow for app upload, device selection, local Appium script execution (Node.js, Python, .NET, Java), and result collection. |\n| **run-interactive-test** | Guided workflow for interactive testing using natural language. WebDriver actions, device operations (adb shell, logs, screen), file management (push/pull), and more. |\n\n\u003e **Platform support note:** all MCP tools and the `run-automation-suite` skill work on every platform the host CLI supports. The `run-interactive-test` skill ships a CLI binary for **macOS Apple Silicon** only. On other platforms, use `run-automation-suite` or the MCP tools directly.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `/automate:setup` | Fetch credentials from the authenticated MCP server and write them to `~/.kobiton/.credentials` |\n| `/automate:doctor` | Read-only diagnostic for CLI installation, credentials file, active profile, and required fields |\n\nOn Cursor (CLI and IDE) these register without the `automate:` prefix — as `/setup` and `/doctor`, distinguishable from Cursor's built-ins by the Kobiton description.\n\n## Running Automation Tests\n\nUse 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.\n\n## Interactive Device Testing\n\nUse the **run-interactive-test** 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.\n\nBeyond WebDriver, the skill also supports device operations (adb shell, logs, screen capture), file management (push/pull files to device), and app management.\n\n## Examples\n\nSee [docs/examples.md](docs/examples.md) for prompt examples covering every tool and skill - device management, session management, app management, automation, and interactive testing.\n\n## Troubleshooting\n\n### Updating the Plugin\n\nAfter the plugin is updated upstream, pull the latest version:\n\n- **Claude Code / Copilot CLI:** run `/plugin install automate@kobiton` again\n- **Gemini CLI:** run `gemini extensions update kobiton-automate` from your shell\n- **Codex CLI:** run `codex plugin marketplace upgrade` to refresh the marketplace catalog, then reinstall the plugin from the browser to pull the latest manifest\n- **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.\n\nTo make sure the assistant picks up the changes with no stale cache, reload per CLI:\n\n- **Claude Code:** run `/reload-plugins` in-session. If tools still behave unexpectedly, `/clear` resets the session context.\n- **GitHub Copilot CLI:** exit and relaunch the session (`exit`, then `copilot`). No in-session reload command.\n- **Gemini CLI:** exit and relaunch (`exit`, then `gemini`). Confirm with `gemini extensions list`.\n- **Codex CLI:** exit and relaunch. Confirm with `codex plugin list`.\n\nIf the issue persists after relaunch, quit the terminal entirely and start a fresh session.\n\n### Common Issues\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eMCP server doesn't appear in \u003ccode\u003e/mcp\u003c/code\u003e after install\u003c/strong\u003e\u003c/summary\u003e\n\nAll 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:\n\n**Claude Code** — reload plugins in the current session:\n\n```\n/reload-plugins\n```\n\n**GitHub Copilot CLI** — exit and relaunch the session:\n\n```bash\nexit\ncopilot\n```\n\n**Gemini CLI** — exit and relaunch; if still missing, verify the extension is enabled:\n\n```bash\nexit\ngemini extensions list\ngemini\n```\n\n**Codex CLI** — exit and relaunch; if still missing, verify the marketplace was added and the plugin was installed:\n\n```bash\nexit\ncodex plugin marketplace list\ncodex plugin list\ncodex\n```\n\nIf using the manual fallback config, also check `grep -A 4 \"mcp_servers.kobiton\" ~/.codex/config.toml`.\n\nThen check the server list (`/mcp` in Claude Code, Gemini CLI, and Codex CLI, `/mcp show` in Copilot CLI). `kobiton` should now appear.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\"Device not found\"\u003c/strong\u003e\u003c/summary\u003e\n\nThe 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.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\"Upload timeout\"\u003c/strong\u003e\u003c/summary\u003e\n\nLarge 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.\n\u003c/details\u003e\n\n### Claude Code\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ePlugin features not working or behaving unexpectedly\u003c/strong\u003e\u003c/summary\u003e\n\nSome older versions of Claude Code don't support the plugin features this plugin relies on. Make sure you're on the latest version:\n\n```bash\nnpm install -g @anthropic-ai/claude-code@latest\n```\n\nThen restart Claude Code and try again.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\"It keeps asking me to open a folder\"\u003c/strong\u003e\u003c/summary\u003e\n\nClaude Code requires a working directory. Launch it from inside a project folder:\n\n```bash\ncd my-project\nclaude\n```\n\nIf you see this prompt repeatedly, make sure you are not running `claude` from your home directory or root (`/`).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\"Plugin not found in marketplace\"\u003c/strong\u003e\u003c/summary\u003e\n\nThe Kobiton marketplace must be added before installing:\n\n```bash\n/plugin marketplace add kobiton/automate\n/plugin install automate@kobiton\n```\n\nIf it still isn't found, check your internet connection and ensure you're running the latest version of Claude Code (`claude update`).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\"claude: command not found\"\u003c/strong\u003e\u003c/summary\u003e\n\nClaude Code is not installed or not in your PATH.\n\n- **Install:** follow the [official install guide](https://docs.anthropic.com/en/docs/claude-code/overview)\n- **PATH issue:** if you installed via npm, make sure your npm global bin directory is in your PATH:\n\n  ```bash\n  npm install -g @anthropic-ai/claude-code\n  ```\n\n  Then open a new terminal window and try `claude` again.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\"Nothing happens after install\"\u003c/strong\u003e\u003c/summary\u003e\n\nThe plugin installed but tools don't appear or Claude doesn't recognize Kobiton commands.\n\n1. Run `/reload-plugins` to force Claude to pick up the new plugin\n2. Try asking: *\"List my Kobiton devices\"*\n3. If still not working, quit Claude Code entirely and start a fresh session\n4. Verify `.mcp.json` exists in the plugin directory — it tells Claude where the Kobiton MCP server lives\n\u003c/details\u003e\n\n### Copilot CLI\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eMCP tools not available after plugin install\u003c/strong\u003e\u003c/summary\u003e\n\nVerify the plugin is installed and the MCP server is configured:\n\n```bash\n# Check installed plugins\ncopilot plugin list\n\n# Check MCP server status\n/mcp show\n```\n\nIf the `kobiton` MCP server doesn't appear, add it manually by running `/mcp add` and entering the following when prompted:\n\n- **Server name:** `kobiton`\n- **Type:** `http`\n- **URL:** `https://api.kobiton.com/mcp`\n\nAlternatively, edit `~/.copilot/mcp-config.json` directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"kobiton\": {\n      \"type\": \"http\",\n      \"url\": \"https://api.kobiton.com/mcp\"\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTool calls are blocked\u003c/strong\u003e\u003c/summary\u003e\n\nCopilot CLI requires explicit tool permissions. Allow Kobiton tools:\n\n```bash\n# Allow all Kobiton MCP tools\ncopilot --allow-tool='kobiton'\n\n# Or allow specific tools\ncopilot --allow-tool='kobiton(listDevices)' --allow-tool='kobiton(getSession)'\n```\n\u003c/details\u003e\n\n### Gemini CLI\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eExtension installed but tools or skills don't appear\u003c/strong\u003e\u003c/summary\u003e\n\nVerify the extension is registered and enabled:\n\n```bash\ngemini extensions list\n```\n\nIf `kobiton-automate` is missing, reinstall:\n\n```bash\ngemini extensions install https://github.com/kobiton/automate\n```\n\nIf listed but disabled, enable it:\n\n```bash\ngemini extensions enable kobiton-automate\n```\n\nThen 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.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003e/mcp\u003c/code\u003e shows \u003ccode\u003ekobiton\u003c/code\u003e as Disconnected (OAuth not authenticated)\u003c/strong\u003e\u003c/summary\u003e\n\nThe extension is installed but you haven't completed OAuth yet. Trigger the flow manually:\n\n```\n/mcp auth kobiton\n```\n\nA browser window opens for Kobiton login. After signing in, run `/mcp` again — the status should change to 🟢 Connected.\n\nNote: `kobiton` here is the **MCP server name** (declared inside the extension), not the extension name `kobiton-automate`. `/mcp` commands always take the server name.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eOAuth doesn't open a browser on first tool call\u003c/strong\u003e\u003c/summary\u003e\n\nGemini 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.\n\nIf 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).\n\u003c/details\u003e\n\n### Codex CLI\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTools not appearing or \"MCP server kobiton not initialized\"\u003c/strong\u003e\u003c/summary\u003e\n\nVerify each step:\n\n1. **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.\n2. **Codex version recent enough** — update with `npm install -g @openai/codex@latest`.\n\nAfter fixing, exit Codex and relaunch; the server should show in `/mcp` (or `/mcp verbose`).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eBrowser does not open for OAuth login\u003c/strong\u003e\u003c/summary\u003e\n\nCodex tries to launch your system browser when Kobiton requires sign-in. If nothing opens, check:\n\n1. **Default browser is set** — your OS needs a default browser. SSH sessions without X forwarding cannot open one.\n2. **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.\n3. **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.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eOAuth login completes but \u003ccode\u003e/mcp\u003c/code\u003e still shows Disconnected\u003c/strong\u003e\u003c/summary\u003e\n\nThis usually means the cached token is stale and refresh failed. Force a re-login by clearing the OS keychain entry and reconnecting:\n\n- **macOS:** open Keychain Access, search for `codex-mcp` or `kobiton`, delete the entry, then trigger a tool call to re-run OAuth.\n- **Linux:** `secret-tool clear service codex-mcp` (or use Seahorse to remove the entry).\n- **Windows:** open Credential Manager, find the Codex entry under Generic Credentials, remove it.\n\nAfter clearing, run any Kobiton tool prompt; the browser should reopen for fresh login.\n\u003c/details\u003e\n\n### Cursor CLI\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSkills or slash commands don't appear (or show stale names) after install\u003c/strong\u003e\u003c/summary\u003e\n\nCursor CLI caches plugin state per session, and older builds didn't load plugin-bundled skills at all:\n\n1. **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.\n2. **Update the CLI** — plugin skills only register in CLI builds from `2026.05.05` onward. Run `agent update`, then relaunch.\n3. **Reinstall if still missing** — `/plugin marketplace add github.com/kobiton/automate`, wait for the **automate** entry to appear, then press \u003ckbd\u003eEnter\u003c/kbd\u003e to install.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003ekobiton\u003c/code\u003e shows Disconnected or MCP tool calls silently fail\u003c/strong\u003e\u003c/summary\u003e\n\n- **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.\n- **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`.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e\u003ccode\u003e~/.kobiton/bin/kobiton\u003c/code\u003e CLI wrapper missing (interactive testing fails)\u003c/strong\u003e\u003c/summary\u003e\n\nCursor 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 symlink goes missing.\n\u003c/details\u003e\n\n### Still Stuck?\n\nFor additional help, open an issue at [github.com/kobiton/automate/issues](https://github.com/kobiton/automate/issues/new?template=bug_report.md) or ask in [#general-discussion](https://discord.com/channels/1486036652685267055/1488189710248710327) on Discord. Feel free to share [feature requests](https://github.com/kobiton/automate/issues/new?template=feature_request.md). We welcome product feedback and will consider it as we continue to improve the platform.\n\n## Privacy \u0026 Data\n\nThis plugin connects to the Kobiton cloud API (`api.kobiton.com`) over HTTPS (TLS 1.2+).\n\n**Authentication:**\n\n- **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.\n- **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.\n\n**Data handling:**\n\n- The plugin does not store any data locally beyond what your AI assistant retains in its conversation context.\n- Tool responses (device lists, session details, test results) pass through your assistant's context window and are subject to [Anthropic's Privacy Policy](https://www.anthropic.com/privacy), [GitHub Copilot's Privacy Statement](https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement), [Google's Gemini Privacy Notice](https://ai.google.dev/gemini-api/terms), or [OpenAI's Privacy Policy](https://openai.com/policies/privacy-policy), depending on which assistant you use.\n- App binaries uploaded via `uploadAppToStore` are sent directly to Kobiton's pre-signed S3 URLs, not through your AI assistant.\n\nFor details on how Kobiton handles your data, see the [Kobiton Privacy Policy](https://kobiton.com/privacy-policy) and [Trust Center](https://kobiton.com/trust-center/).\n\n## Development\n\nThe `tools/` directory contains reference YAML schemas that mirror the MCP server's tool definitions. They are published to S3 for the backend but are not consumed by the plugin at runtime.\n\n```bash\n# Install dependencies\npnpm install\n\n# Validate manifests and schemas\npnpm run validate\n\n# Run tests\npnpm test\n\n# Refresh the .codex/ mirror after editing skills/ or assets/\npnpm run build:codex\n\n# Build combined tool definitions (for S3 publishing)\npnpm run build\n```\n\n## License\n\n[MIT](https://opensource.org/license/mit)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkobiton%2Fautomate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkobiton%2Fautomate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkobiton%2Fautomate/lists"}