RN Agent Observer

VI · English

RN Agent Observer 2.4.0은 React Native/Expo를 위한 로컬 런타임 관측 브리지입니다. 이 도구는 CLI와 MCP에서 동일한 TypeScript 코어를 사용하며, ADB/UIAutomator를 통해 Android를 제어하고, 개발 계측에서 텔레메트리를 수신하며, Metro의 Chrome DevTools Protocol을 통해 console/exception/heap/JS CPU 프로파일을 내보내고, 앱 계측 없이 요청별 네트워크를 수집하며, 에이전트를 위한 state/headline/actions/UI findings가 포함된 화면 이해를 생성하고, 세션 안정적 ref 스냅샷 + diff + 자동 기록 리플레이를 제공하며, 화면 비디오를 녹화하고, SQLite로 세션을 저장하며, 스크린샷/트레이스/UI 트리를 디스크의 아티팩트로 유지합니다.

현재 릴리스는 Windows에서 Android v1을 완성했습니다: 45개의 MCP 도구, 대응하는 CLI, 결정적 랩이 포함된 Expo 데모, 투명한 휴리스틱 진단, 픽셀 + UI 구조 비교.

요구 사항

• Node.js 22.12 이상

• pnpm 9.6

• Android Platform Tools (adb)

• USB 디버깅이 활성화된 Android 에뮬레이터 또는 실제 기기

• 앱별 텔레메트리가 필요한 경우 Expo development build

Related MCP server: React Native MCP Server

빠른 시작

pnpm install
pnpm check
adb devices -l
pnpm rn-observe --help
pnpm mcp:check

observer를 Expo/React Native 앱에 연결합니다:

$env:RN_OBSERVER_PROJECT_ROOT = 'C:\path\to\expo-app'
$env:RN_OBSERVER_DEVICE_ID = 'emulator-5554'
# Có thể bỏ qua nếu app.json chứa expo.android.package
$env:RN_OBSERVER_APP_ID = 'com.example.app'

pnpm rn-observe launch
pnpm rn-observe observe
pnpm rn-observe understand-screen
pnpm rn-observe ui-model
pnpm rn-observe tap --test-id buy-button
pnpm rn-observe performance
pnpm rn-observe diagnose

아티팩트와 SQLite 데이터는 <projectRoot>/.artifacts/ 아래에 생성됩니다. 대용량 바이너리는 MCP 응답에 포함되지 않습니다.

결정적 데모

pnpm --filter @rn-agent-observer/demo-expo android -- --device <device-name>

데모에는 PerformanceLab, NetworkLab, RenderLab, AnimationLab, ErrorLab, VisualLab이 포함되어 있습니다. NetworkLab은 내부 픽스처(0/500/2000ms 및 HTTP 503)를 사용하므로 인터넷 서비스에 의존하지 않습니다. PerformanceLab은 계측을 통해 의도된 100ms long JS task를 정확히 보고합니다.

MCP

pnpm mcp:check
pnpm mcp:start

서버는 stdio를 사용합니다. 클라이언트 구성과 45개 도구의 전체 목록은 docs/protocol.md에 문서화되어 있습니다.

AI 에이전트 통합

에이전트(OpenCode/Claude Code/Cursor/Codex...)가 observer를 사용하는 방법은 3가지입니다:

1. MCP 서버 (권장 — 구조화된 도구)

{
  "mcpServers": {
    "rn-agent-observer": {
      "command": "node",
      "args": [
        "C:\\abs\\rn-agent-observer\\packages\\mcp-server\\dist\\server.js"
      ],
      "env": {
        "RN_OBSERVER_PROJECT_ROOT": "C:\\path\\to\\expo-app",
        "RN_OBSERVER_DEVICE_ID": "emulator-5554"
      }
    }
  }
}

2. 스킬로 설치 (CLI를 통해 에이전트에게 디버그 워크플로우 교육)

npx skills add GinzaTech/rn-agent-observer

스킬은 skills/rn-agent-observer/SKILL.md에 있습니다 — observe -> understand-screen -> reproduce -> diagnose -> fix -> understand-screen -> compare 루프, 메트릭을 정직하게 읽는 방법, 일반적인 오류 복구를 가르칩니다. 설치 후 "앱 X가 버벅거려"라고 말하면 에이전트가 자동으로 rn-observe를 사용합니다.

3. AGENTS.md (에이전트가 이 저장소 내에서 작업하는 경우) — 루트에 이미 있으며, 에이전트가 자동으로 읽습니다.

세 가지 방법을 동시에 사용할 수 있습니다: skill/AGENTS.md는 워크플로우를 가르치고, MCP는 직접 호출 가능한 도구를 제공합니다.

문서

• 상세 사용 가이드

• 전체 프로젝트 개요 (VI/EN)

• 아키텍처

• CLI 및 MCP 프로토콜

• 메트릭 정의

• Capability matrix

• 테스트 및 런타임 검증

• 테스트 청사진

• 문제 해결

• Changelog

현재 버전

• Android/Windows는 Observer 2.4.0의 유일한 지원 대상입니다.

• ADB에는 신뢰할 수 있는 JS FPS 신호가 없습니다. 필드는 available: false로 반환되며 값을 추측하지 않습니다.

• JS blocking, route, React 렌더, 네트워크 메타데이터는 앱 내 개발 계측이 필요합니다.

• CDP를 통한 DevTools 내보내기(devtools-export, devtools-profile)와 요청별 네트워크(metro-network)는 Metro가 실행 중이고 앱이 Metro에 연결되어 있어야 합니다(adb reverse tcp:8081 tcp:8081). 다른 React Native DevTools 세션이 연결을 유지하고 있으면 사용할 수 없습니다.

• reload --fast는 CDP Page.reload(JS 전용)를 사용하며, Metro를 사용할 수 없을 때 자동으로 force-stop으로 폴백합니다.

• 계측이 없는 앱: metro-network(CDP), app-state(포그라운드 activity, PID), device-network(기기 수준 바이트 카운터, 앱 귀속 아님)를 폴백 증거로 사용합니다.

• record(screenrecord)는 Android에 따라 클립당 180초로 제한됩니다.

• Perfetto 트레이스는 Android를 지원합니다. 심층 트레이스 분석은 여전히 Perfetto UI/Android Studio에서 수행합니다.

• CDP 명령은 프로세스 간에 큐잉됩니다. 외부 React Native DevTools는 observer 잠금에 참여하지 않으므로 여전히 닫아야 합니다.

• session stop은 자동으로 리플레이를 생성합니다. 세션의 ref는 reorder/scroll에도 안정적입니다. 세션이 없으면 EVIDENCE_NOT_RECORDED를 발생시킵니다.

• understand-screen/MCP understand_screen은 사용 가능한 경우 계측된 route, 화면 상태, 헤드라인, 텍스트/액션 refs, UI findings, 스크린샷/UI 트리 증거를 반환합니다. 반복 호출은 변경되지 않은 로딩을 감지합니다. 분류는 휴리스틱이며 텍스트 필드 값은 항상 redact됩니다.

• ui-model/MCP runtime_ui_model은 TypeScript AST로 TSX를 파싱하여 component + file:line을 얻은 다음, 계측 및 네이티브 트리와 상호 연관시킵니다. 결과는 rendered, visible/offscreen/hidden/unmounted/flattened-or-unobserved, enabled, 근거가 있는 canPress를 구분합니다.

• 개발 전용 Babel 플러그인은 소스 기반 testID를 자동으로 추가하고 onPress를 래핑합니다. session stop은 start/success/error 상호작용을 수집하고 testID가 있는 탭을 리플레이에 포함합니다. 핸들러 인자, props, 입력 값은 기록하지 않습니다.

• Observer는 기본적으로 네트워크 본문을 수집하지 않습니다. 개발 전용 옵트인은 fail-closed allowlist를 사용하지만 여전히 개발 픽스처에만 사용해야 합니다.

RN Agent Observer (English)

RN Agent Observer 2.4.0 is a local runtime observability bridge for React Native/Expo. It uses one shared TypeScript core behind both a CLI and an MCP server, drives Android through ADB/UIAutomator, receives telemetry from development instrumentation, exports console/exceptions/heap/JS CPU profiles through Metro's Chrome DevTools Protocol, captures per-request network traffic without app instrumentation, produces structured screen understanding (state/headline/actions/UI findings) for agents, provides session-stable ref snapshots + diffs + automatically recorded replay scripts, records on-screen video, persists sessions in SQLite, and keeps screenshots/traces/UI trees as on-disk artifacts.

The current release completes Android v1 on Windows: 45 MCP tools, the matching CLI, an Expo demo app with deterministic labs, transparent heuristic diagnosis, and pixel + structural UI comparison.

Requirements

• Node.js 22.12 or newer

• pnpm 9.6

• Android Platform Tools (adb)

• An Android emulator or physical device with USB debugging enabled

• An Expo development build if you need app-specific telemetry

Quick Start

pnpm install
pnpm check
adb devices -l
pnpm rn-observe --help
pnpm mcp:check

Point the observer at your Expo/React Native app:

$env:RN_OBSERVER_PROJECT_ROOT = 'C:\path\to\expo-app'
$env:RN_OBSERVER_DEVICE_ID = 'emulator-5554'
# Optional when app.json contains expo.android.package
$env:RN_OBSERVER_APP_ID = 'com.example.app'

pnpm rn-observe launch
pnpm rn-observe observe
pnpm rn-observe understand-screen
pnpm rn-observe ui-model
pnpm rn-observe tap --test-id buy-button
pnpm rn-observe performance
pnpm rn-observe diagnose

Artifacts and SQLite data are created under <projectRoot>/.artifacts/; large binaries are never embedded in MCP responses.

Deterministic demo

pnpm --filter @rn-agent-observer/demo-expo android -- --device <device-name>

The demo ships PerformanceLab, NetworkLab, RenderLab, AnimationLab, ErrorLab, and VisualLab. NetworkLab uses internal fixtures (0/500/2000ms and HTTP 503) so it never depends on Internet services. PerformanceLab reports its intentional 100ms long JS task precisely through instrumentation.

MCP

pnpm mcp:check
pnpm mcp:start

The server speaks stdio. Client configuration and the full list of 45 tools are documented in docs/protocol.md.

Documentation

• Full project overview (VI/EN)

• Detailed usage guide (Vietnamese)

• Architecture

• CLI and MCP protocol

• Metrics definitions

• Capability matrix

• Testing and runtime verification

• Test blueprint

• Troubleshooting

• Changelog

AI agent integration

Three ways for agents (OpenCode/Claude Code/Cursor/Codex...) to use the observer:

1. MCP server (recommended — structured tools)

{
  "mcpServers": {
    "rn-agent-observer": {
      "command": "node",
      "args": [
        "C:\\abs\\rn-agent-observer\\packages\\mcp-server\\dist\\server.js"
      ],
      "env": {
        "RN_OBSERVER_PROJECT_ROOT": "C:\\path\\to\\expo-app",
        "RN_OBSERVER_DEVICE_ID": "emulator-5554"
      }
    }
  }
}

2. Install as a skill (teaches the agent the debugging workflow via CLI)

npx skills add GinzaTech/rn-agent-observer

The skill lives at skills/rn-agent-observer/SKILL.md — it teaches the observe -> understand-screen -> reproduce -> diagnose -> fix -> understand-screen -> compare loop, how to read metrics honestly, and common failure recovery. After installing, just say "app X feels laggy" and the agent knows to reach for rn-observe.

3. AGENTS.md (when the agent works inside this repo) — already present at the repo root; agents read it automatically.

All three can be combined: the skill/AGENTS.md teach the workflow, MCP provides directly callable tools.

Current boundary

• Android/Windows is the only supported target of Observer 2.4.0.

• ADB has no trustworthy JS FPS signal; the field is returned as available: false — values are never guessed.

• JS blocking, route, React renders, and network metadata require development instrumentation inside the app.

• CDP features (devtools-export, devtools-profile, metro-network) need Metro running for the right app and the app connected to it (adb reverse tcp:8081 tcp:8081); they cannot attach while another React Native DevTools session holds the connection.

• reload --fast uses CDP Page.reload (JS-only) and automatically falls back to force-stop when Metro is unavailable.

• Observer CDP commands queue across processes; external React Native DevTools must still be closed because it does not participate in the observer lock.

• session stop automatically writes a replay, session refs survive reorder/scroll, and missing sessions produce EVIDENCE_NOT_RECORDED.

• understand-screen/MCP understand_screen returns the instrumented route when available, screen state, headline, text/action refs, UI findings, and screenshot/UI-tree evidence; repeated calls detect unchanged loading. Classification is heuristic and text-field values are always redacted.

• ui-model/MCP runtime_ui_model parses TSX with the TypeScript AST for component + file:line, then correlates source with instrumentation and the native tree. It distinguishes rendered, visible/off-screen/hidden/unmounted/flattened-or-unobserved, enabled, and evidence-backed canPress states.

• The development-only Babel plugin injects a source-derived testID and wraps onPress; session stop collects interaction start/success/error and promotes testID taps into replay. Handler arguments, props, and input values are never recorded.

• Network body capture is off by default. Development-only opt-in uses fail-closed allowlists and should still be limited to fixtures.

• Apps without instrumentation: use metro-network (CDP), app-state (foreground activity, PID), and device-network (device-level byte counters, not app-attributed) as fallback evidence.

• record (screenrecord) is limited to 180s per clip by Android.

• Perfetto tracing is supported on Android; deep trace analysis remains in Perfetto UI/Android Studio.