Skip to Content
Native IntegrationClaude Code Patching

Claude Code Patching — Native Mobile Integration Guide

Audience: future Swift / iOS and Kotlin / Android developers + DevOps engineers asking “what happens when Claude Code updates and breaks the VSRelay integration?”

TL;DR

VSRelay depends on patched files inside the Claude Code VS Code extension (extension.js, webview/index.js). Claude Code updates roughly every 1-2 weeks; the minifier reshuffles variable names and the patches break. The native mobile binary has zero knowledge of patches, so the recovery flow lives entirely on the desktop side via two channels:

  1. In-extension applier (primary, Phase D-α): extension contains bundled patches/ + applies them via a vscode.window.showInformationMessage({ modal: true }) consent prompt. Phone taps a button → desktop modal pops → user clicks Allow → patches apply.
  2. npx @vsrelay/doctor repair CLI (fallback, Phase D-β): npm-published package with bundled manifests. Works from any terminal without the repo.

What the native app does

Nothing. The native binary renders recoveryActions (including the invoke_extension_command primitive) generically. It forwards the command string verbatim in the wire message. The native app fetches data, sends data, renders data — it never patches, never executes, never invokes anything on the device.

What the desktop extension does

  1. Probes claude-integration-health every 30 s. Detects unpatched files.
  2. Emits ClaudeIntegrationStatus { status: 'recovery_required', recoveryActions: [...] }.
  3. On invoke_extension_command_request from phone: validates the command string against a vsrelay.* allowlist (deny by default; transitional agentic-ides.* alias also accepted during rebrand). Invokes via vscode.commands.executeCommand.
  4. The invoked command (vsrelay.applyPatches) reads the bundled manifest at <extensionPath>/patches/v<version>/manifest.json, shows the consent modal (once per Claude Code version, persisted in context.globalState), and applies via the shared @vsrelay/patch-applier.applyManifest() function.

Why this is App-Store-safe

App Store concernTruthful answer
Does the native app execute remote code?No. Forwards command strings via wire; never invokes.
Does the native app modify the device filesystem?No. The desktop modifies its own Claude Code install on the user’s laptop — entirely off-device from the App-Store perspective.
Does the native app download executable manifests?No. Manifests live in the VS Code extension and in the npm-published @vsrelay/doctor package — both desktop-side, both updated through their respective Marketplace/npm registry channels.

Why we keep the npx CLI fallback

Some users:

  • Click Block on the consent modal (intentional or accidental).
  • Have policies forbidding extensions from mutating other extensions’ files.
  • Want to verify exactly what’s being patched before authorizing.

npx @vsrelay/doctor repair lets them recover from a terminal without engaging the extension’s auto-apply path.

The patch lifecycle

  1. Anthropic ships Claude Code 2.1.X.
  2. VSRelay developer detects the break (locally and via diagnostic log monitoring).
  3. Developer decodes the minifier renames and creates the new anchor + replacement files manually.
  4. New patches/v2.1.X/manifest.json committed to the monorepo.
  5. New VSRelay extension version published to Marketplace with the bundled manifest.
  6. New @vsrelay/doctor version published to npm with the bundled manifest.
  7. End users get either path via their respective auto-update channels.

No App Store / Play Store update needed for the native client at any point.

Cross-references

  • RecoveryActions — the v1 + v2 RecoveryAction primitives + the invoke_extension_command shape.
  • ProductionDeploymentArchitecture — four trust tiers; patching is orthogonal.
  • patches/README (source repo) — manifest schema + how-to-add-a-version.
  • Spec: docs/superpowers/specs/2026-05-21-end-user-production-installer-design (source repo).
Supabase AuthProduction Deployment