iOS Logcat Web

A modern, web-based log visualization tool for iOS/macOS development, inspired by Android Studio Logcat.

iOS Logcat Web brings the powerful filtering and visualization capabilities of Android Studio's Logcat to the iOS ecosystem. Built with Bun and React, it provides a high-performance, real-time log streaming experience in your browser.

✨ Features

• Real-time Streaming: Low-latency log streaming via WebSocket.
• Advanced Filtering: Support for complex queries (e.g., level:ERROR tag:Network -message:ping).
• Process Selection: Easily switch between running processes/devices.
• Modern UI: Dark mode interface inspired by VS Code and Android Studio.
• High Performance: Backend powered by Bun for maximum throughput.

Filter Syntax

The filter engine implements a query language inspired by Android Studio Logcat, supporting key-value pairs, boolean operators, regex, and negation.

Basic Syntax

| Syntax | Description | Example | |--------|-------------|---------| | text | Global search (message, tag, process) | timeout | | key:value | Field-specific match | message:error | | -key:value | Negation (exclude) | -message:heartbeat | | key~:pattern | Regex match | message~:^Error.*timeout$ | | "quoted string" | Multi-word value | message:"connection failed" |

Supported Fields

• message — Log message content
• tag — Log tag / subsystem
• level — Log level (V, D, I, W, E, F)
• process / package — Process name
• pid — Process ID

Boolean Operators

Explicit operators follow standard precedence: & (AND) binds tighter than | (OR).

# Explicit AND — both conditions must match
message:timeout & message:network

# Explicit OR — either condition matches
message:error | message:exception

# Parentheses override precedence
(message:auth | message:login) & level:E

Implicit Logic (when no explicit operators):

• Same field → OR: message:foo message:bar ≡ message:foo | message:bar
• Different fields → AND: message:foo level:E ≡ message:foo & level:E
• Negations → AND: -message:ping -message:pong excludes both

Level Filtering

The level field uses >= comparison. level:W matches WARN, ERROR, and FATAL.

level:E              # ERROR and above
level:W & tag:Network  # WARN+ from Network subsystem

Examples

# Find errors containing "timeout", exclude heartbeat noise
message:timeout & level:E & -message:heartbeat

# Auth or login failures at warning level or above
(message:auth | message:login) & level:W

# Regex: match stack traces
message~:at\s+\w+\.\w+\(

Note: The same syntax applies to tag, process, and other fields.

🚀 Quick Start

Prerequisites

• Bun (v1.0 or later) or Node.js (v18+) must be installed on your system.
• macOS (required for log stream access).
• libimobiledevice (Required for iOS device communication).

  brew install libimobiledevice

Installation

You can install it globally using npm or bun:

# Using Bun (Recommended)
bun add -g ios-logcat-web

# Using npm
npm install -g ios-logcat-web

Once installed, simply run:

ios-logcat

Usage (No Installation)

Run directly with bunx or npx without installing:

bunx ios-logcat-web

This will:

1. Start the local server.
2. Automatically open the web interface in your default browser.
3. Begin streaming logs immediately.

⚠️ Known Limitations

Due to the architecture of Apple's unified logging system and the current implementation of third-party tools (like idevicesyslog and libimobiledevice), there are some inherent limitations regarding log visibility:

Xcode Debugging Sessions

When an app is attached to the Xcode debugger (LLDB), the system redirects stdout/stderr and certain debug-level logs exclusively to the Xcode Console and debugserver pipeline. Consequently, these logs may not appear in iOS Logcat Web during an active debugging session.

• Why: The system prioritization of the debugger channel bypasses the standard syslog relay that idevicesyslog listens to.
• Workaround: Use iOS Logcat Web for release builds, ad-hoc testing, or when running the app without an attached debugger.

Unified Logging (os_log) Coverage

While standard syslog messages are captured reliably, some low-level system logs or os_log messages with debug/info levels might be filtered out by the device's syslog relay service before reaching this tool. This is a platform limitation on iOS 10+ devices where unified logging is the default.

🛠 Tech Stack

• Runtime: Bun
• Frontend: React, Tailwind CSS
• Protocol: WebSocket
• Linting: ESLint (@antfu/eslint-config)

📅 Changelog

Please see CHANGELOG.md for more information on what has changed recently.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct, and the process for submitting pull requests.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feat/AmazingFeature)
3. Commit your Changes (git commit -m 'feat: Add some AmazingFeature')
4. Push to the Branch (git push origin feat/AmazingFeature)
5. Open a Pull Request

📝 License

Distributed under the MIT License. See LICENSE for more information.