logpeek

Pipe mobile device logs to AI coding agents.

logpeek gives coding agents like Claude Code, Cursor, and Gemini CLI direct access to Android and iOS device logs.

What you can do

Ask your agent things like:

• "Why is my app crashing on launch?" — agent pulls crash logs, finds the stack trace, and fixes the issue
• "Show me the last 30 seconds of error logs" — narrow time window, error-level filtering
• "What's happening in the React Native JS layer?" — isolate framework-specific logs from native noise
• "Check the network logs for failures" — grep through logs for specific patterns
• "My app is slow, what's going on?" — pull verbose logs and spot the bottleneck

Quick Start

1. Install

npm install -g logpeek

2. Connect your agent

npx logpeek init

Registers logpeek as a Claude Code plugin. Restart Claude Code after.

Any agent that runs shell commands can use logpeek. Add this to your agent's system prompt:

You have access to `logpeek` for collecting mobile device logs:
- logpeek --app com.example.app                       # collect logs (last 5m)
- logpeek --app com.example.app --level error          # errors only
- logpeek --app com.example.app -f react-native        # React Native logs only
- logpeek --app com.example.app --grep "network"       # search logs
- logpeek --app com.example.app --last 30s             # narrow time window
- logpeek devices                                      # list connected devices

3. Verify

npx logpeek doctor

Checks that adb (Android) and xcrun (iOS) are available and ready.

Commands

# Collect logs (default command)
logpeek --app com.example.app
logpeek                                          # interactive device & app picker

# List connected devices
logpeek devices

# Check prerequisites
logpeek doctor

# Register Claude Code plugin
logpeek init

Flags

| Flag | Short | Default | Description | |------|-------|---------|-------------| | --app <id> | -a | interactive | Bundle ID (iOS) or package name (Android) | | --device <id> | -d | auto | Device ID or name | | --platform <type> | -p | auto | android or ios | | --level <level> | -l | verbose | Minimum log level: verbose, debug, info, warn, error | | --source <type> | -s | all | Log source: all, native, framework | | --framework <type> | -f | — | react-native or flutter. Automatically sets --source framework. | | --last <duration> | -t | 5m | Time window (e.g., 30s, 1m, 5m, 1h) | | --lines <n> | -n | 200 | Max lines to output | | --grep <pattern> | -g | — | Case-insensitive text filter | | --verbose | | — | Debug logging | | --quiet | | — | Suppress output except errors |

Examples

# All logs from last 5 minutes
logpeek --app com.example.app

# Errors only, last 30 seconds
logpeek --app com.example.app --level error --last 30s

# React Native JS logs only (-f implies --source framework)
logpeek --app com.example.app -f react-native

# Search for network-related errors
logpeek --app com.example.app --grep "network" --level error

# Target a specific device
logpeek --app com.example.app -d "iPhone 16"

# Combine framework filter with grep
logpeek --app com.example.app -f react-native --grep "inventory" --level error

# Widen the window for intermittent issues
logpeek --app com.example.app --last 30m -n 500

Log Output

Logs are automatically formatted for readability:

15:47:37 INF [Network] GET /api/cart → 200 OK (142ms)
15:47:37 INF [Network] GET /api/user/profile → 401 Unauthorized
15:47:37 WRN [Auth] Session token expired, refreshing...
15:47:37 INF [Network] POST /api/auth/refresh → 200 OK (203ms)
15:47:39 ERR [Inventory] Failed to verify stock: Connection timeout after 5000ms
15:47:39 INF [Performance] JS thread: 58.2fps | UI thread: 60.0fps

Raw platform timestamps and process metadata are stripped. Level indicators (INF, WRN, ERR, DBG) and categories are preserved.

How It Works

Android: Uses adb logcat with PID filtering. If the app has crashed (no PID), automatically includes AndroidRuntime and FATAL EXCEPTION logs.

iOS: Uses xcrun simctl spawn <udid> log show with process/subsystem predicates. Falls back to ReportCrash and SpringBoard logs for crash debugging.

Filtering: Logs pass through a pipeline — format → level filter → source filter → grep filter → line limit. Filters combine with AND logic.

Device discovery: Automatically detects booted Android emulators (adb devices) and iOS simulators (xcrun simctl list). If multiple devices are found, an interactive picker is shown.

Framework Support

| Framework | Android | iOS | |-----------|---------|-----| | React Native | ReactNativeJS tag | com.facebook.react.runtime.JavaScript | | Flutter | flutter tag | flutter subsystem | | Native | Full logcat | Full unified log |

Platform Support

| Platform | Emulator/Simulator | Physical Device | |----------|-------------------|-----------------| | Android | Supported | Not yet | | iOS | Supported (macOS only) | Not yet |

Requirements

• Node.js >= 18
• Android: adb available, emulator booted
• iOS: macOS with xcrun simctl, simulator booted

Development

npm install
npm run dev          # watch mode
npm test             # run tests
npm run build        # production build

License

MIT