linc-nerve

Field-tested device control for AI coding agents — the self-healing tricks we learned keeping a physical Android/iOS bench alive, as an MCP server and a plain CLI.

nerve exposes 48 tools — screenshots, the UI element tree, tap/swipe/type, app install/launch, logs, recording — to any MCP client, and the same tools as nerve <tool> commands that print JSON.

Field notes

A device bench fails in ways a single emulator never shows you. Each of these is a behaviour you can read in the code:

• adb can wedge while looking alive. After a wireless device drops, the adb server can sit in a busy-spin: every adb call hangs, and adb kill-server hangs too because it talks to the same wedged socket. A watchdog treats "unresponsive and server at ≥ 80% CPU" as the wedge signature and recovers by killing the server's PID, never by adb kill-server; an unresponsive server with an idle CPU is left alone. → src/linc_nerve/core/adb_health.py
• A leaked UiAutomation session silently breaks the element tree. uiautomator dump is killed while another process (a leaked test driver) holds the device's single UiAutomation connection. Recovery is evidence-gated and escalates in tiers under one 45 s deadline, force-stopping only a known allowlist of test drivers — the Pixel Watch companion app, whose package name looks similar, is never touched. An empty element list therefore always means an empty screen, never a failed dump. → src/linc_nerve/core/android_ui.py
• Readiness checks fail toward "unknown", not "ready". Wake/lock state is parsed from dumpsys, whose format varies by OEM and Android version; an unrecognised format reads as unknown, so a caller skips rather than tapping a locked screen. → src/linc_nerve/core/device_state.py
• Screenshots handed to an agent are budgeted. Inline images for MCP agents are rescaled to about 300k pixels (≈ 400 vision tokens); the full-resolution file on disk is left untouched for everything else. → src/linc_nerve/mcp/_core.py

Quickstart

Android emulator first — no physical device, Xcode or WebDriverAgent needed.

Prerequisites: Python 3.13+ (uv fetches it for you; with plain pip you need it installed), uv, the Android SDK command-line tools, and platform-tools and emulator on your PATH (adb and emulator; with Homebrew's android-commandlinetools add $(brew --prefix)/share/android-commandlinetools/emulator to PATH). Then create an emulator.

On Apple silicon, replace x86_64 with arm64-v8a in the first two lines below. avdmanager asks whether to create a custom hardware profile; answer no.

sdkmanager "platform-tools" "emulator" "system-images;android-35;google_apis;x86_64"
avdmanager create avd -n nerve -k "system-images;android-35;google_apis;x86_64"
emulator -avd nerve -no-window &
adb wait-for-device

adb wait-for-device returns before Android has finished booting. Wait until adb shell getprop sys.boot_completed prints 1 (usually a minute or so on first boot) before step 1, or the first state call can hit a half-booted device.

Install: pipx install --python python3.13 linc-nerve (or python3.13 -m pip install linc-nerve inside a venv), after which the same commands run as nerve doctor, nerve discover and nerve state --device <serial>; and for Claude Code claude mcp add nerve -- nerve bellows.

1. Check the environment. The daemon, WebDriverAgent and $LINC_HOME (default ~/.linc) are optional, so on a fresh Android-only machine nothing fails (exit code 0); missing optional pieces show as ! warnings with an indented hint: line. The exact set of lines depends on your machine (macOS runs the xcode-clt check, a running daemon shows ✓). Sample from a fresh Linux machine, trimmed:

uvx linc-nerve doctor

  ✓ adb: adb responsive (/usr/local/bin/adb)
  ✓ device-auth: no unauthorized devices
  ✓ scrcpy-server: …/linc_nerve/vendor/scrcpy-server-v3.3.4
  ! wda-project: WDA_PROJECT_DIR not set — iOS tap/swipe/elements unavailable (Android works without it)
      hint: git clone https://github.com/appium/WebDriverAgent.git ~/.linc/wda/src && export WDA_PROJECT_DIR=~/.linc/wda/src
  ! wda-team-id: WDA_TEAM_ID not set — physical-iOS WDA signing will fail
      hint: …
  - xcode-clt: skipped — not macOS
  ! daemon: no nerve daemon on 127.0.0.1:8111 — CLI calls run in-process (the daemon is optional)
      hint: …
  ! linc-layout: missing directories: /home/you/.linc, /home/you/.linc/nerve/recordings — nerve creates them on first use
      hint: …

8 checks: 0 failed, 4 warned

2. Find the emulator.

uvx linc-nerve discover

{"devices": [{"serial": "emulator-5554", "platform": "android", "device_type": "emulator", …, "state": "online"}], "count": 1, "android": 1, "ios": 0}

With several devices attached, devices lists all of them; pass the emulator's serial to the later commands.

3. Read the screen — foreground app, element tree and a screenshot path in one call. Your launcher package and element count depend on the system image, and the screenshot lands in your temp directory ($TMPDIR on macOS, not /tmp):

uvx linc-nerve state --device emulator-5554

{"device": "emulator-5554", "platform": "android", "foreground": {"package": "com.google.android.apps.nexuslauncher", …}, "element_count": 31, "elements": [ … ], "screenshot": "<temp dir>/nerve-output/…png", …}

4. Give it to your agent. For Claude Code:

claude mcp add nerve -- uvx linc-nerve bellows

Run claude mcp list and check that nerve shows as connected, then paste a first prompt:

Take a screenshot of the emulator and tell me what app is in the foreground.

Every MCP tool is also a CLI command: the tool name minus nerve_, with _ → - (nerve_clear_app_data → nerve clear-app-data). Output is JSON on stdout; for text, put --human before the command (nerve --human discover, not nerve discover --human). Exit 0 success, 1 tool error, 2 usage error. nerve schema --json prints the full command tree.

iOS (experimental)

iOS simulators and physical devices work through WebDriverAgent (WDA), which you build once. nerve doctor prints the same steps as hints:

git clone https://github.com/appium/WebDriverAgent.git ~/.linc/wda/src
export WDA_PROJECT_DIR=~/.linc/wda/src
export WDA_TEAM_ID=<Apple Developer Team ID>   # physical devices only; simulators don't need it

Needs macOS with Xcode. Expect rough edges: WDA always binds port 8100, first start takes ~4 s on a simulator and 15–30 s on a physical device, physical devices need code signing, and watchOS is not supported.

Reference

Configuration

HTTP daemon (optional)

nerve daemon (or nerve bellows, which also serves MCP over stdio) runs an HTTP server on 127.0.0.1:8111: GET /health, GET /devices, POST /tools/<tool_name> with a JSON body, and GET /stream?device=<serial> for a server-sent-events log stream. CLI commands use the daemon when one is running and otherwise run the tool in-process. A few stateful tools (recording, streaming, reservations, diff, session-stats) need the daemon, and say so instead of answering wrongly.

MCP Tools (48)

Tools are registered via @device_tool (requires a device serial) or @global_tool (no device needed) in src/linc_nerve/mcp/*_tools.py. This section — including the count — is generated from those registrations by python -m linc_nerve.docs_gen; tests/test_docs_sync.py fails CI when it is stale. Call nerve_capabilities for the per-platform support matrix.

Discovery & Capabilities

Screenshots & Streaming

UI Inspection

Navigation

Input

App Management

Emulator / Simulator

Recording

Action Log

Device Readiness

Diagnostics & Observability

Reservation

Other

Trust

• No telemetry, no phone-home. nerve talks to your devices, your local adb server, and — for iOS — the WebDriverAgent it starts. Nothing else.
• A local usage log, under your control. Each MCP tool call is appended to $LINC_HOME/mcp-calls.jsonl (default ~/.linc/mcp-calls.jsonl, rotated at 10 MB) with the tool name, timing, success and parameters. Set NERVE_USAGE_LOG=off|redacted|full:
  • redacted (default) — values of sensitive parameters (text, password, passcode, pin, secret, token, otp) and every value under extras and uri are replaced by their length only (no hash), including inside nested dicts and lists; binary values become their size, and long strings are truncated. The log file is created owner-only (0600).
  • off — nothing is written.
  • full — raw parameter values, including typed text (except nerve_type text sent with secret=true, which is length-only in every mode). Opt in only on a machine you trust.
• The daemon is loopback-only. It binds 127.0.0.1, rejects non-loopback Hosts (DNS rebinding) and any browser Origin, and accepts tool calls only as application/json. Every value that reaches a device shell is validated or shell-quoted where it is used. Details and how to report a vulnerability: SECURITY.md.

How this repo works

This is a release mirror of LINC's private repository. The code is built by LINC's AI software factory under human review; each release lands as one commit. Issues are welcome; pull requests by arrangement — see CONTRIBUTING.md.

Built by LINC Innovations — we diagnose flaky device test suites.

Licensed under the Apache License 2.0. Bundles scrcpy-server (Apache-2.0) — see NOTICE.