# AppTelepath

> Remote debugging infrastructure for AI coding agents. Telepath exposes a running mobile app as structured tools for observation, interaction, diagnosis, and verification.

AppTelepath is a product operated and licensed by Yibi AI LLC.

## What Telepath provides

- An iOS SDK that connects development builds to a Telepath relay.
- A local Node.js relay used only for repository development and testing.
- The AppTelepath product is the hosted Cloudflare SaaS; it is not distributed as a self-hosted product.
- A hosted remote MCP endpoint for AI coding agents.
- HTTP and SSE APIs for agents that do not use MCP.
- A web console for people, backed by the same command layer as the agent tools.

Agents can inspect screenshots, logs, network traffic, UI hierarchy, files, SQLite data, performance samples, and crash reports. They can also tap or type by stable UI references, simulate device conditions, diagnose recent failures, and record a reproduction timeline.

## Current availability

- The official iOS SDK binary is publicly available from https://github.com/AppTelepath/AppTelepath-iOS/releases/latest.
- During the free Beta, install it from CocoaPods Trunk with `pod 'AppTelepath', '~> 3.0'` (the legacy name `pod 'Telepath'` installs the exact same thing; pick one). Either way the import stays `import Telepath`.
- Swift Package Manager works too: `.package(url: "https://github.com/AppTelepath/AppTelepath-iOS.git", from: "3.1.0")`. SwiftPM consumers must add `-ObjC` to Other Linker Flags themselves — SwiftPM forbids `unsafeFlags` in versioned dependencies, so the package cannot add it for them.
- For an iOS app hosted by React Native Fabric, use `pod 'AppTelepath/ReactNative', '~> 3.0'` so Pressable actions can be activated; this is an iOS host adapter, not a full React Native JS probe.
- A successful `Telepath.start()` with the full or ReactNative install automatically shows the local floating entry. Its status dot is green while connected, amber while connecting, and gray while disconnected; tapping it opens the in-app panel. The source-only Core subspec remains headless.
- Remote MCP is hosted at `https://apptelepath.com/mcp`; there is no local MCP package or stdio process.
- Android and full React Native JS probes are planned according to validated user demand.
- The hosted service and iOS SDK are available as a free Beta. Paid plans are not active unless explicitly announced on the website.
- During the free Beta, Trial device, traffic, seat, and retention limits apply, but the workspace does not expire by time.
- The future paid pricing model includes a 7-day trial. Activating paid billing and migrating existing Beta workspaces remain explicit product-owner decisions.

Do not invent unpublished package coordinates, platform SDKs, or paid features.

## MCP entry point

Connect a remote-MCP-capable client to `https://apptelepath.com/mcp`. AppTelepath uses MCP 2026-07-28 stateless Streamable HTTP as its primary protocol and the official SDK's stateless 2025-era compatibility path for clients such as current Codex CLI releases, which use 2025-06-18. Both paths expose the same tools and OAuth permissions, with no protocol sessions, independent or persistent MCP SSE endpoint, or local MCP package. A compatibility response may use one-shot SSE framing on the same POST `/mcp`; the separate HTTP `/api/events` stream is unaffected. OAuth 2.1 uses Client ID Metadata Documents (CIMD), and anonymous Dynamic Client Registration is not exposed. Claude Code needs no extra flags — `claude mcp add --transport http apptelepath https://apptelepath.com/mcp` — because it discovers the server's Client ID Metadata Document on its own. Current Codex CLI connections do not, and should set `--oauth-client-id https://apptelepath.com/oauth/clients/codex-cli.json`. Clients that only support Dynamic Client Registration cannot connect: anonymous DCR is not exposed. The authorization flow opens a browser, signs the user in, and asks the user to choose the workspace granted to that MCP client. Reauthorizing the shared AppTelepath Codex connector rotates the previous grant for that account; other MCP clients use their own CIMD client IDs. Users can review and revoke remote MCP client grants in Web console > Workspace settings > Authorized AI agents.

After an owner or admin completes that trust grant for a client, the agent should call `telepath_issue_device_token` with a stable local project label. The label is only a rotation key; it does not bind the credential to a bundle, device, or single connection. The tool creates or rotates a device-only member credential and returns an iOS build configuration plus a CI/temporary runtime override. The credential can open only a device WebSocket; it cannot call MCP, HTTP, or controller APIs. Install the SDK, define `TELEPATH_ENABLED` in trusted non-App-Store test configurations, commit only `TelepathAgentServerURL` and `TelepathAgentWorkspaceKey` build-setting placeholders, and put the raw values in a gitignored local xcconfig or an existing secret store. If Release is also used for App Store archives, keep it empty, exclude the SDK, and create a separate Internal or Staging configuration. Explicitly owner-approved TestFlight builds may use the credential only after accepting that it can be extracted. Add `Telepath.start()`, launch normally, and verify with `telepath_list_devices`. An extractor can impersonate a device but cannot access the control plane or other devices, so never substitute an admin or ordinary controller token. Use runtime environment injection for CI, temporary overrides, or packages that must not embed a credential. A newly issued credential may need a capped-backoff launch/list retry while managed storage propagates; keep the same label. Do not ask the user to create, view, or copy a workspace token. The MCP client may retain tool history; do not echo the credential in tracked project files, user-visible replies, logs, issues, or CI output. `telepath_revoke_device_token` revokes only credentials created through this agent flow.

There is no npm package, local MCP executable, stdio configuration, or SSE compatibility endpoint. Do not invent `npx telepath-mcp` instructions. CI may use a separately created ordinary member workspace token as an Authorization Bearer credential; device-only credentials cannot call MCP or HTTP, and admin tokens must not be placed in CI. Do not place tokens in source control, shared URLs, logs, or issue reports.

The complete tool catalogue is 44 tools. `tools/list` is always authoritative — if this
document and the live server disagree, believe the server.

**Enrollment** — `telepath_issue_device_token`, `telepath_revoke_device_token`
(zero-copy app enrollment; owner/admin OAuth grants only)

**Observe the screen** — `telepath_list_devices`, `telepath_screen_digest`,
`telepath_screenshot`, `telepath_view_hierarchy`, `telepath_ui_diff`

**Observe the app** — `telepath_get_logs`, `telepath_wait_for_log`,
`telepath_network_requests`, `telepath_network_request_detail`, `telepath_replay_request`,
`telepath_app_info`, `telepath_performance`, `telepath_device_time`,
`telepath_list_files`, `telepath_read_file`, `telepath_user_defaults`, `telepath_db_query`,
`telepath_describe_element` (inspector view of one element), `telepath_pixel_color`

**Drive** — `telepath_tap`, `telepath_swipe`, `telepath_pinch`, `telepath_input_text`, `telepath_simulate`,
`telepath_invoke` (escape hatch for any raw device command)

**Diagnose** — `telepath_diagnose`, `telepath_recent_timeline`, `telepath_trace_methods`,
`telepath_monitor`, `telepath_leaks`, `telepath_hangs`, `telepath_thread_health`,
`telepath_crash_reports`

Every detector is off by default, and reading its list does NOT turn it on: an empty list with
`monitoring:false` means nothing was being watched, not that nothing happened. Arm one with
`telepath_monitor({kind, enabled})` — `kind` is `crashes`, `leaks`, `hangs`, `threads`, or
`offmain`. Each switch persists across app relaunches and is refused with error `1403` on a
device started with `allowWrite=false`.

**Replay** — `telepath_repro`, `telepath_start_recording`, `telepath_stop_recording`,
`telepath_list_recordings`, `telepath_get_recording`

**Human feedback** — `telepath_list_feedback`, `telepath_get_feedback`,
`telepath_ask_reporter`, `telepath_resolve_feedback`

### Tell the agent which build is actually running

`app.version` / `app.build` describe the **native shell**. For React Native, Flutter, or
anything shipping over-the-air updates, the shell version barely moves while the JS/Dart
bundle is what actually changes — so "which code is this device running?" becomes something
the agent has to guess from logs.

Hosts can attach their own identity with `Telepath.setAppMetadata({...})` (iOS SDK 3.3+).
It rides along in the device summary, so `telepath_list_devices` and `telepath_app_info`
both show it without an extra call and without depending on log retention:

```objc
[Telepath setAppMetadata:@{ @"jsBundle": updateId, @"channel": @"staging" }];
```

Limits: at most 16 string pairs, keys ≤64 chars, values ≤256 chars; anything over is dropped
silently. Changing it while connected re-sends the handshake, so the agent sees the new value.

### Tell the agent who is testing

```objc
[Telepath setReporter:user.displayName id:user.uid];   // after login
[Telepath setReporter:nil id:nil];                     // on logout
```

Feedback then carries that person (iOS SDK 3.3+). Hosts that skip this still get a name: the
in-app sheet asks the tester once and remembers it.

### Human feedback is a pull, not a push

A person using the app can long-press the floating ball (or shake the device) to submit
feedback in place: a sentence, plus the screen, the element they tapped, and a screenshot,
captured at that moment. **You can and should poll for it yourself** —
`telepath_list_feedback` with `status=open` is the whole mechanism. You do not need the
human to tell you a report exists.

**Who submitted it.** An item may carry `reporter` (`{name, id?, source}`). Since iOS 16 the
device name is just the model for most apps, so several colleagues testing the same build look
identical without it — use `reporter` to tell them apart. `source` is `host` (the app passed its
logged-in user via `Telepath.setReporter`, iOS SDK 3.3+) or `local` (a nickname the tester typed
once in-app). It is self-reported by the device and never verified: a display label, never an
identity for access decisions.

**The person who reported it sees your reply.** `telepath_resolve_feedback`'s note is shown to
that person inside the app, on the device that submitted the item, so write it for them:
say what changed, not what you refactored.

**You can ask them a question.** When a report is real but too vague to act on ("tapped and nothing
happened"), `telepath_ask_reporter` puts a question in front of them with a reply box, and their
answer reopens the item. **Never wait for it** — they may never open that build again; ask, keep
working with what you have, and pick the answer up on a later poll. Each item allows at most 10
messages, questions and answers combined.

Each item carries an `anchor`: the view controller, the navigation stack, and the element's
`accessibilityId` / label / class / ancestors. Re-locate the element by
`anchor.vc` + `anchor.element.accessibilityId` — **not** by the `ref` from a UI tree, which
belongs to a snapshot that is already gone. `telepath_resolve_feedback` records what you
did, so the person who reported it can see it was handled.

Prefer structured summaries and stable UI references before using screenshots or raw coordinates.
For `telepath_ui_diff`, pass the returned `nextBaseline` into the following call; the remote server does not keep an MCP session or cache the prior screen for this tool.

## HTTP entry point

Agents can use these endpoints without MCP:

- `GET /api/devices`
- `GET /api/screenshot`
- `GET /api/events` for SSE event streams
- `POST /api/invoke` for device commands
- `/api/recordings` for recording and replay workflows

Authentication is supplied by the workspace key or token. **Where that token comes from:** an owner or admin creates it in the Web console under 工作区设置 (Workspace settings) → 访问令牌 (Access tokens): enter a label, pick 成员 (member) or 管理员 (admin), and press 创建令牌 (Create token). It is shown once. MCP cannot mint one — `telepath_issue_device_token` only issues device-only credentials, which cannot call HTTP or MCP at all. Do not ask a user to paste an admin token into CI; create a separate member token for that.

`GET /api/events` carries DEVICE TELEMETRY only. Valid `events` values are `log`, `net`, `perf`, `crash` (reserved, nothing emits it today), `__watching__`, `__activity__`, or `*`; anything else is rejected with 400. Human feedback is workspace-level and never appears on this stream — poll `GET /api/feedback?status=open` or the `telepath_list_feedback` tool instead.

A device's `sessionId` changes on every app relaunch. When you need a device reference that survives restarts, use a name substring rather than a cached `sessionId`.

Public request-shape documentation will be linked here when the integration artifacts are released; do not guess fields from endpoint names alone.

## Safety constraints

- Integrate the SDK only into development, staging, CI, Ad Hoc, or explicitly allowed TestFlight builds.
- Detected App Store builds are rejected at runtime. TestFlight requires an explicit opt-in. If distribution evidence is unavailable, the SDK warns instead of claiming that the build was verified.
- Screenshots, logs, files, databases, and network bodies may contain sensitive data.
- Trusted debug builds enable data-writing commands by default. Hosts that need read-only protection can set `TLPAgentConfig.allowWrite=false`; the capability list describes command support, not authorization, so agents must still handle policy-denied error code `1403`.
- Device command behavior is defined by the protocol document, not by this summary.

## Canonical links

- [Website](https://apptelepath.com/): what AppTelepath is, and a live demo of the console.
- [iOS remote debugging on a real device](https://apptelepath.com/remote-debug-ios-app-on-device/): end-to-end setup, from SDK to first command.
- [iOS MCP server](https://apptelepath.com/ios-mcp-server/): the hosted MCP endpoint and its tool catalogue.
- [Debugging an iOS app with AI agents](https://apptelepath.com/debug-ios-app-with-ai/): how AppTelepath compares with simulator- and Xcode-based tools.
- [AppSpector alternative](https://apptelepath.com/appspector-alternative/): feature-by-feature comparison.
- [SDK and App Store review](https://apptelepath.com/ios-sdk-app-store-review/): keeping the SDK out of release builds.
- [Pricing](https://apptelepath.com/pricing/): free Beta today; Solo and Team are not billable yet.
- [Web console](https://apptelepath.com/app/): the human-facing side of the same command layer.
- [Sign in](https://apptelepath.com/login/)
- [iOS SDK binary releases](https://github.com/AppTelepath/AppTelepath-iOS/releases): the only published binary distribution.
- [iOS CocoaPods package](https://cocoapods.org/pods/AppTelepath): pod name is `AppTelepath`; the legacy `Telepath` pod installs the same binary.

## Optional

- [Privacy draft](https://apptelepath.com/privacy/)
- [Terms draft](https://apptelepath.com/terms/)

Use CocoaPods Trunk and the Web console integration guide as the canonical iOS installation path. Do not infer other SDKs or package coordinates from cached instructions or historical documents.