CatScope

A lightweight Android Logcat debugging workbench

English · 简体中文

Installation · Getting Started · Architecture · Development · Documentation

CatScope lets you inspect live and offline Android Logcat, filter app logs, analyze crashes and ANRs, and save debugging sessions you can reopen later.

More screenshots: analysis and build workflows

Analysis	Build, install, and launch

Features

• Log viewing: Live ADB Logcat and offline .txt, .log, and .jsonl files, with a virtualized log list.
• Filtering: Package and PID tracking, levels, tags, keywords, exclusions, and regular expressions.
• Analysis: Local rules for Java crashes, ANRs, native crashes, JNI errors, and install failures.
• AI Context: Copy or export Markdown containing analysis results and related logs.
• Sessions and presets: Save and restore logs, filters, and analysis results in .catscope-session files; reuse configuration through workspaces and filter presets.
• Build, install, and launch: Run the project's Gradle Wrapper (assembleDebug by default), install the APK, and launch the configured app.

See Known Issues for scope and current limitations.

Installation

Download the file for your platform from GitHub Releases. The project is currently in Preview.

Platform	File	Installation
Windows 10 / 11 (x64)	*-windows-amd64.exe	Run directly; requires Microsoft WebView2 Runtime
macOS (Intel / Apple Silicon, preview)	*-macos-universal.dmg	Open the DMG and drag CatScope into Applications

The macOS build is not yet Apple-notarized, so Gatekeeper may block the first launch. After verifying the download source, allow it in System Settings → Privacy & Security. Official Linux builds are not available.

Windows supports verified in-app updates and restart when the EXE directory is writable; macOS requires manual updates. Releases include .sha256 files; see Release Assets for verification instructions.

Getting Started

Live logs:

1. Install Android SDK Platform Tools. CatScope can find ADB through PATH, ANDROID_HOME, or ANDROID_SDK_ROOT, or you can set its full path in the app.
2. Connect an Android device with USB debugging enabled and approve the authorization prompt, or start an emulator.
3. Refresh and select the device in CatScope, start Logcat, then choose a package or set filters to narrow the results.

Offline use: Open a .txt, .log, or .jsonl log file, or restore a .catscope-session file. No device is required.

For unauthorized devices, approve USB debugging on the phone. For offline devices, try reconnecting or restarting ADB. See the User Guide for full instructions.

Architecture

Wails v2 connects the Vue 3 + TypeScript UI to the Go backend. app.go coordinates ADB, log parsing, rule-based analysis, builds, and local storage.

The Hand-drawn Architecture Guide (Chinese) covers module responsibilities, log flow, and source entry points. See Architecture for the detailed design.

Development

Requires Go 1.22+, npm, and the Wails platform build dependencies. Node.js 22 LTS (22.12 or later) is recommended.

git clone https://github.com/HBLADEH/CatScope.git
cd CatScope
go install github.com/wailsapp/wails/v2/cmd/wails@v2.12.0
npm ci --prefix frontend
npm run build --prefix frontend
wails doctor
wails dev

Run the checks relevant to your changes from the repository root:

go test ./...
npm run build --prefix frontend
git diff --check

Use wails build to build the app for your current platform. See Release Assets for packaging and verification, and the contribution guide for submission requirements.

Documentation

Browse the documentation index for the full set.

Topic	Document
Log viewing, analysis, sessions, and workspaces	User Guide
Current limitations	Known Issues
Manual verification	QA Checklist
Releases and checksums	Release Assets
Changes and planned work	Changelog · Roadmap

Contributing and Feedback

Use Issues to report bugs or suggest improvements, and pull requests to contribute code. Read the contribution guide and Code of Conduct first.

Include the version, operating system, reproduction steps, and sanitized logs in bug reports. Report security vulnerabilities privately as described in the security policy.

Privacy

CatScope does not upload logs or call external model APIs. Update checks contact GitHub and are enabled by default; you can disable them in App Updates. Logs, sessions, and AI Context may contain sensitive information, so redact them before sharing.

License

MIT © 2026 HBLADEH.