iOS Logcat Web

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

!License
!Version
!Build Status

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.

!iOS Logcat Web Screenshot

✨ 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.

$3

| 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" |

$3

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

$3

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

$3

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
`

$3

`bash


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

$3

- 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).
`bash
brew install libimobiledevice
`

$3

You can install it globally using npm or bun:

`bash


Using Bun (Recommended)

bun add -g ios-logcat-web

Using npm

npm install -g ios-logcat-web
`

Once installed, simply run:

`bash
ios-logcat
`

$3

Run directly with bunx or npx without installing:

`bash
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:

$3


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.

$3

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.