From ce9cbe13fb421686f3f12677cbc084198ad3ac1a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hanno=20J=2E=20G=C3=B6decke?= Date: Thu, 19 Nov 2026 14:47:49 +0100 Subject: [PATCH 1/3] docs(claude): install the Claude Code plugin from the marketplace Lead the Claude Code section with the two marketplace commands, explain which Claude surface loads the plugin versus the Desktop extension, link the published .mcpb release asset, and add a step-by-step T3 Code quickstart with a verification step and a copyable setup prompt. Refs #98 Co-Authored-By: Claude Opus 5.5 --- README.md | 11 ++- .../src/content/docs/docs/getting-started.md | 94 +++++++++++++++---- 2 files changed, 82 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 483da953..5343d70a 100644 --- a/README.md +++ b/README.md @@ -86,10 +86,13 @@ claude plugin marketplace add https://github.com/callstackincubator/mobile-dev.g claude plugin install mobile-dev@mobile-dev ``` -Or in a session, `/plugin install mobile-dev --marketplace https://github.com/callstackincubator/mobile-dev.git#release/claude`. +The plugin is installed for your user, so the CLI, the Claude desktop app's **Code** tab +and T3 Code's Claude threads all load it. Inside a session, run the same steps as +`/plugin marketplace add https://github.com/callstackincubator/mobile-dev.git#release/claude` +and `/plugin install mobile-dev@mobile-dev`. Run `claude plugin marketplace update mobile-dev` to update. -For Claude Desktop chats, download `mobile-dev--claude-desktop-darwin-arm64.mcpb` +Regular Claude Desktop chats do not load Claude Code plugins. For them, download `mobile-dev--claude-desktop-darwin-arm64.mcpb` from the [latest release](https://github.com/callstackincubator/mobile-dev/releases/latest), open **Settings > Extensions > Advanced settings**, and under **Extension Developer** click **Install Extension…** and select the file, or open it with Claude Desktop. @@ -121,8 +124,10 @@ profiles go only to the TraceSift service on your Mac. [T3 Code](https://github.com/pingdotgg/t3code) runs Claude Code and Codex, so it loads the Mobile Dev plugin that each of them has installed. On the Mac that runs T3 Code, install the [Claude Code plugin](#claude-code-and-claude-desktop) for Claude threads +(run the two `claude plugin` commands in a terminal, then start a new Claude thread) and the [Codex plugin](#codex) for Codex threads. In both, the panel opens in T3 Code's -Browser. +Browser. See the [T3 Code setup guide](https://incubator.callstack.com/codex-mobile-dev-plugin/docs/getting-started#t3-code) +for the settings each provider needs. Turn off T3 Code's own device integration while you use Mobile Dev. In **Settings → Devices**, turn off **Use devices**, which also turns off **Agents can use diff --git a/website/src/content/docs/docs/getting-started.md b/website/src/content/docs/docs/getting-started.md index 6f41ac33..643f4776 100644 --- a/website/src/content/docs/docs/getting-started.md +++ b/website/src/content/docs/docs/getting-started.md @@ -41,20 +41,56 @@ When an update is offered in the desktop app, click **Update**, then fully quit ## Claude +Claude has two places that load Mobile Dev, and each has its own installation: + +| Where you chat with Claude | What to install | +| --- | --- | +| **Claude Code**: the `claude` CLI, the **Code** tab in the Claude desktop app, IDE extensions, and hosts that run Claude Code, such as [T3 Code](#t3-code) | The [Claude Code plugin](#claude-code) | +| **Claude Desktop chats**: the regular chat in the Claude desktop app | The [Claude Desktop extension](#claude-desktop) | + +Install one of them per place. Both use the same server, so avoid installing the plugin and a local connection side by side. + +### Claude Code + +The plugin is published as a Claude Code marketplace on this repository's `release/claude` branch. On an Apple Silicon Mac with Node.js 22.19 or later, run these commands in a terminal: + +```sh +claude plugin marketplace add https://github.com/callstackincubator/mobile-dev.git#release/claude +claude plugin install mobile-dev@mobile-dev +``` + +The plugin is installed for your user, so the CLI, the desktop app's **Code** tab, and T3 Code's Claude threads all pick it up. Inside a running Claude Code session you can run the same steps as `/plugin marketplace add https://github.com/callstackincubator/mobile-dev.git#release/claude` and `/plugin install mobile-dev@mobile-dev`. + +1. Start a new Claude Code session in your app project. +2. Ask **“Open Mobile Dev.”** and approve the tool calls when prompted. +3. Claude opens the device panel in a browser beside the chat: the built-in browser pane in the desktop app's **Code** tab, or a private `127.0.0.1` link you open in your browser from the CLI. The first open downloads the panel's runtime once, which can take a minute. + +The plugin finds Node.js on `PATH` or where Homebrew, nvm, fnm, Nix, Volta, mise, or asdf install it. If none is found, Claude tells you at the start of a session. + +To update, run `claude plugin marketplace update mobile-dev`, then start a new session. + +To try a source build instead, first complete the repository's [Build and package setup](https://github.com/callstackincubator/mobile-dev/blob/main/CONTRIBUTING.md#build-and-package), then run from that checkout: + +```sh +npm run package:claude +claude plugin validate ./release/claude-plugin/mobile-dev +claude --plugin-dir ./release/claude-plugin/mobile-dev +``` + ### Claude Desktop -Claude Desktop currently uses a manual preview. Obtain a `mobile-dev--claude-desktop-darwin-arm64.mcpb` bundle from the person sharing it, or [build a bundle from source](https://github.com/callstackincubator/mobile-dev/blob/main/CONTRIBUTING.md#claude-desktop-local-development). The bundle is not yet published by this repository's release workflow. +For regular chats in the Claude desktop app, download `mobile-dev--claude-desktop-darwin-arm64.mcpb` from the [latest release](https://github.com/callstackincubator/mobile-dev/releases/latest). 1. Open **Settings → Desktop app** and choose **Manage** beside **Extensions**. 2. Open **Advanced settings**. Under **Extension Developer**, choose **Install Extension…** and select the `.mcpb` file. You can also open the bundle with Claude Desktop. 3. Fully quit and reopen Claude, start a new conversation, and ask **“Open Mobile Dev.”** 4. Approve the connector when prompted. Choose **Expand** for the larger view when available. -The bundle includes the plugin and native helpers; Claude supplies Node. Install newer bundles manually to update. Mobile Dev does not add a permanent Claude sidebar entry. +The bundle includes the server and native helpers; Claude supplies Node. Install a newer bundle to update. Mobile Dev does not add a permanent Claude sidebar entry. See [Claude's desktop extension instructions](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop) for the current custom-extension installation flow. -For a local connection or bundle build, first complete the repository's [Build and package setup](https://github.com/callstackincubator/mobile-dev/blob/main/CONTRIBUTING.md#build-and-package). Then run these commands from that checkout with Node.js 22.19 or later: +For a local connection, first complete the repository's [Build and package setup](https://github.com/callstackincubator/mobile-dev/blob/main/CONTRIBUTING.md#build-and-package). Then run these commands from that checkout with Node.js 22.19 or later: ```sh npm run build @@ -63,18 +99,6 @@ npm run claude:config Merge the generated `.local-dev/claude-desktop-config.json` entry into the existing `mcpServers` configuration through **Settings → Developer → Edit Config**, preserving other servers. Restart Claude after changing the server. -### Claude Code - -The source build can package a local Claude Code plugin: - -```sh -npm run package:claude -claude plugin validate ./release/claude-plugin/mobile-dev -claude --plugin-dir ./release/claude-plugin/mobile-dev -``` - -Run these after the source-build setup above. The plugin requires Node.js 22.19 or later on `PATH`. Rich views depend on the host's MCP Apps capabilities. Use one Mobile Dev installation or local connection at a time to avoid duplicate servers. - ## Cursor Cursor currently uses a manual preview, not a Cursor Marketplace listing. It requires Node.js 22.19 or later on `PATH`. @@ -92,17 +116,47 @@ For a local MCP connection, run `npm run build` and `npm run cursor:config` from ## T3 Code -[T3 Code](https://github.com/pingdotgg/t3code) runs Claude Code and Codex, so it loads the Mobile Dev plugin that each of them has installed. On the Mac that runs T3 Code, install the [Claude Code](#claude-code) plugin for Claude threads and the [Codex](#codex-cli) plugin for Codex threads. In both, the panel opens in T3 Code's Browser. +[T3 Code](https://github.com/pingdotgg/t3code) runs Claude Code and Codex, so it loads the Mobile Dev plugin that each of them has installed. Install the plugin for the provider you use, on the Mac that runs T3 Code. In both, the panel opens in T3 Code's Browser. + +### 1. Turn off T3 Code's device tools + +In **Settings → Devices**, turn off **Use devices**, which also turns off **Agents can use devices**. Otherwise T3 Code gives agents its own `device_*` tools, with the same names as Mobile Dev's, and tells them to prefer those tools. -Turn off T3 Code's own device integration while you use Mobile Dev. In **Settings → Devices**, turn off **Use devices**, which also turns off **Agents can use devices**. Otherwise T3 Code gives agents its own `device_*` tools, with the same names as Mobile Dev's, and tells them to prefer those tools. +### 2. Install the plugin -Codex threads need one setting, because T3 Code renders Codex's panel in the chat and asks you to confirm each action that the panel takes, such as each tap: +For **Claude threads**, run these commands in a terminal on that Mac, outside T3 Code: + +```sh +claude plugin marketplace add https://github.com/callstackincubator/mobile-dev.git#release/claude +claude plugin install mobile-dev@mobile-dev +``` + +Claude threads need no further setting. + +For **Codex threads**, install the [Codex plugin](#codex-cli), then add one setting, because T3 Code otherwise renders Codex's panel in the chat and asks you to confirm each action that the panel takes, such as each tap: 1. Open **Settings → Providers**, then the Codex instance. 2. Under **Variables**, click **Add variable**. Set `MOBILE_DEV_PANEL` to `browser`. -3. Start a new thread. -Ask **“Open Mobile Dev.”** The agent opens the panel with T3 Code's `preview_open` tool, and T3 Code shows the page as a floating preview. To dock the panel beside the chat, click the preview's **Open in right panel** button. Performance recordings still render as cards in the chat. +### 3. Open Mobile Dev + +Start a **new** thread with the Claude or Codex provider, so it loads the plugin, and ask **“Open Mobile Dev.”** The agent opens the panel with T3 Code's `preview_open` tool, and T3 Code shows the page as a floating preview. To dock the panel beside the chat, click the preview's **Open in right panel** button. The first open downloads the panel's runtime once, which can take a minute. + +Setup worked when the panel shows Mobile Dev's device list. Choose a simulator or emulator there, and it boots and streams in the panel. Performance recordings still render as cards in the chat. + +### Let an agent do the setup + +Paste this prompt into a terminal Claude Code session, outside T3 Code: + +```text +Install the Mobile Dev Claude Code plugin for me. Run +`claude plugin marketplace add https://github.com/callstackincubator/mobile-dev.git#release/claude` +and then `claude plugin install mobile-dev@mobile-dev`. Confirm with +`claude plugin list` that mobile-dev is installed and enabled. Check that +Node.js 22.19 or later and the full Xcode are installed (`node --version`, +`xcode-select -p`), and for Android that `adb` is on PATH. Then tell me to turn off +Settings → Devices → Use devices in T3 Code and start a new Claude thread there. +``` ## Other environments From bc926f101f4d452d04077abf98fdd46e906ae616 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hanno=20J=2E=20G=C3=B6decke?= Date: Thu, 19 Nov 2026 15:05:00 +0100 Subject: [PATCH 2/3] docs(claude): trim the Claude Code install section Co-Authored-By: Claude Opus 5.5 --- .../src/content/docs/docs/getting-started.md | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/website/src/content/docs/docs/getting-started.md b/website/src/content/docs/docs/getting-started.md index 643f4776..5e43264e 100644 --- a/website/src/content/docs/docs/getting-started.md +++ b/website/src/content/docs/docs/getting-started.md @@ -59,24 +59,6 @@ claude plugin marketplace add https://github.com/callstackincubator/mobile-dev.g claude plugin install mobile-dev@mobile-dev ``` -The plugin is installed for your user, so the CLI, the desktop app's **Code** tab, and T3 Code's Claude threads all pick it up. Inside a running Claude Code session you can run the same steps as `/plugin marketplace add https://github.com/callstackincubator/mobile-dev.git#release/claude` and `/plugin install mobile-dev@mobile-dev`. - -1. Start a new Claude Code session in your app project. -2. Ask **“Open Mobile Dev.”** and approve the tool calls when prompted. -3. Claude opens the device panel in a browser beside the chat: the built-in browser pane in the desktop app's **Code** tab, or a private `127.0.0.1` link you open in your browser from the CLI. The first open downloads the panel's runtime once, which can take a minute. - -The plugin finds Node.js on `PATH` or where Homebrew, nvm, fnm, Nix, Volta, mise, or asdf install it. If none is found, Claude tells you at the start of a session. - -To update, run `claude plugin marketplace update mobile-dev`, then start a new session. - -To try a source build instead, first complete the repository's [Build and package setup](https://github.com/callstackincubator/mobile-dev/blob/main/CONTRIBUTING.md#build-and-package), then run from that checkout: - -```sh -npm run package:claude -claude plugin validate ./release/claude-plugin/mobile-dev -claude --plugin-dir ./release/claude-plugin/mobile-dev -``` - ### Claude Desktop For regular chats in the Claude desktop app, download `mobile-dev--claude-desktop-darwin-arm64.mcpb` from the [latest release](https://github.com/callstackincubator/mobile-dev/releases/latest). From ed37094313ce23b8c6598dab27bc50ce8f0b1c2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hanno=20J=2E=20G=C3=B6decke?= Date: Thu, 19 Nov 2026 15:23:39 +0100 Subject: [PATCH 3/3] docs(claude): copy the agent setup prompt with a button Co-Authored-By: Claude Opus 5.5 --- website/src/components/starlight/Head.astro | 29 +++++++++++++++++++ .../src/content/docs/docs/getting-started.md | 18 +++--------- website/src/styles/docs.css | 19 ++++++++++++ 3 files changed, 52 insertions(+), 14 deletions(-) diff --git a/website/src/components/starlight/Head.astro b/website/src/components/starlight/Head.astro index ea2b2493..b529ad0e 100644 --- a/website/src/components/starlight/Head.astro +++ b/website/src/components/starlight/Head.astro @@ -10,3 +10,32 @@ const fonts = [switzerRegular, switzerMedium, geistMonoRegular, geistMonoMedium] {fonts.map(href => )} + + diff --git a/website/src/content/docs/docs/getting-started.md b/website/src/content/docs/docs/getting-started.md index 5e43264e..b5fe38f1 100644 --- a/website/src/content/docs/docs/getting-started.md +++ b/website/src/content/docs/docs/getting-started.md @@ -59,6 +59,10 @@ claude plugin marketplace add https://github.com/callstackincubator/mobile-dev.g claude plugin install mobile-dev@mobile-dev ``` +Or let your agent do the setup: + + + ### Claude Desktop For regular chats in the Claude desktop app, download `mobile-dev--claude-desktop-darwin-arm64.mcpb` from the [latest release](https://github.com/callstackincubator/mobile-dev/releases/latest). @@ -126,20 +130,6 @@ Start a **new** thread with the Claude or Codex provider, so it loads the plugin Setup worked when the panel shows Mobile Dev's device list. Choose a simulator or emulator there, and it boots and streams in the panel. Performance recordings still render as cards in the chat. -### Let an agent do the setup - -Paste this prompt into a terminal Claude Code session, outside T3 Code: - -```text -Install the Mobile Dev Claude Code plugin for me. Run -`claude plugin marketplace add https://github.com/callstackincubator/mobile-dev.git#release/claude` -and then `claude plugin install mobile-dev@mobile-dev`. Confirm with -`claude plugin list` that mobile-dev is installed and enabled. Check that -Node.js 22.19 or later and the full Xcode are installed (`node --version`, -`xcode-select -p`), and for Android that `adb` is on PATH. Then tell me to turn off -Settings → Devices → Use devices in T3 Code and start a new Claude thread there. -``` - ## Other environments The shared server supports local MCP connections over stdio. After completing the [source-build setup](https://github.com/callstackincubator/mobile-dev/blob/main/CONTRIBUTING.md#build-and-package), configure your client's local MCP server connection to launch Node.js 22.19 or later with the absolute path to the built `dist/server.mjs` as its argument. Keep the built distribution and its bundled helpers together. diff --git a/website/src/styles/docs.css b/website/src/styles/docs.css index 4bbe19bb..21c0ac28 100644 --- a/website/src/styles/docs.css +++ b/website/src/styles/docs.css @@ -226,6 +226,25 @@ mobile-starlight-toc a[aria-current='true'] { color: #0a0a0a !important; } +/* Copy buttons in docs Markdown (data-copy), styled as a primary link button. */ +.sl-markdown-content .copy-prompt { + display: inline-flex; + align-items: center; + gap: 0.5rem; + padding: 0.5rem 1rem; + border: 1px solid var(--accent); + border-radius: 999rem; + background: var(--accent); + color: #0a0a0a; + font-family: var(--cs-font-mono); + font-size: 0.8125rem; + letter-spacing: 0.055em; + text-transform: uppercase; + cursor: pointer; +} +.sl-markdown-content .copy-prompt:hover { filter: brightness(1.1); } +.sl-markdown-content .copy-prompt:focus-visible { outline: 2px solid var(--sl-color-white); outline-offset: 2px; } + .sl-badge { font-family: var(--cs-font-mono); letter-spacing: 0.04em;