CatScope

Logcat without Android Studio.

A lightweight Android debugging workbench for logs, crashes, installs, launches, and daily troubleshooting.

English · 简体中文

Why CatScope · Features · Quick Start · Roadmap · Documentation

CatScope is a lightweight desktop workbench for Android Logcat. It is built for developers who need Android logs, crash clues, package filtering, device state, and routine debugging actions without opening the full Android Studio IDE.

Better than raw adb logcat, lighter than Android Studio, and more Android-aware than a generic log viewer.

CatScope is not trying to replace Android Studio. The core idea is Logcat without Android Studio, then carefully add the nearby workflows that make daily Android troubleshooting smoother: build, install, launch, crash analysis, export, and AI-friendly context generation.

Why CatScope

Android Studio is powerful, but it can be too heavy when the task is simply:

• watch Logcat for one device or app,
• filter logs by package, PID, level, tag, or keyword,
• inspect crash / ANR / native crash clues,
• export a focused log session,
• install and launch a debug build,
• collect context for a teammate or an AI agent.

CatScope keeps that workflow small and direct. The product boundary is intentionally narrow: it should become a great Android troubleshooting companion, not another full IDE.

Status

Current version: v0.6.0-preview.

CatScope is currently in Preview / Dev status. The core Logcat Viewer, Offline Log File Viewer, rule-based Crash / ANR / Native / JNI / Install Error Analyzer, local AI Context Generator, a minimal Build / Install / Launch workflow, lightweight Workspace / Filter Presets, and Session save / restore are available.

CatScope is a lightweight Android Logcat debugging workbench. It is not an Android Studio replacement, does not provide Gradle Project Sync, and does not include a code editor. The AI Context feature only generates local Markdown; CatScope does not upload logs and does not call external AI APIs.

Features

Feature Checklist

• Desktop app foundation
  • Wails v2 desktop app with a Go backend.
  • Vue 3 + TypeScript frontend.
• ADB and device management
  • ADB discovery from user configuration, ANDROID_HOME, ANDROID_SDK_ROOT, and PATH.
  • Device list parsing with clear device, offline, unauthorized, and unknown states.
  • Device information display: model, brand, Android version, SDK, and ABI.
• Live Logcat Viewer
  • Live adb logcat -v threadtime -b main,system,crash streaming.
  • Start, stop, restart, and device switching for Logcat streams.
  • Continuous stdout / stderr reading with clear error reporting.
  • 100000-line ring buffer with batch reads and dropped-line counts.
  • Virtualized frontend log table.
• Package and PID filtering
  • Installed package listing for all packages and third-party packages.
  • Package search, selection, clearing, and all-log mode.
  • PID tracking for the selected package, including app restarts.
  • Package / Level combined filtering and case-insensitive search.
• Log parsing and interaction
  • threadtime parsing, raw line preservation, and multiline log merging.
  • Java stacktrace and AndroidRuntime FATAL EXCEPTION grouping.
  • Pause, clear, detail / analysis panel, txt export, and jsonl export.
• Offline Log File Viewer
  • Open .txt, .log, and .jsonl log files.
  • Parse ordinary threadtime Logcat text files with the existing parser.
  • Preserve unparsed raw lines and multiline stacktraces.
  • Reuse search, level, tag, exclude, regex, package filtering, virtual scrolling, details, Analyzer, and AI Context generation.
  • Show live/offline source mode, file path, file name, entry count, and raw-line parse count.
  • Reopen CatScope JSONL exports as offline logs.
• Rule-based Analyzer without external AI API calls
  • Java Crash: AndroidRuntime, FATAL EXCEPTION, Process:, Caused by:, and common exception types.
  • Native Crash: SIGSEGV, SIGABRT, backtrace:, tombstone, Abort message, fault addr, and libxxx.so.
  • ANR: ANR in, Application Not Responding, Input dispatching timed out, and service / broadcast timeouts.
  • JNI Error: JNI DETECTED ERROR IN APPLICATION, CheckJNI, stale / deleted references, and pending exceptions.
  • Install Error: INSTALL_FAILED_*, INSTALL_PARSE_FAILED_*, DELETE_FAILED_*, Failure [INSTALL_FAILED...], and adb: failed to install.
• Install Error Analyzer
  • Analyze install failure text or log output.
  • Provide bilingual reasons and next-step suggestions.
  • Prepare analyzer output for future Build / Install / Launch workflows.
• Local AI Context Generator
  • Generate Markdown context for the selected analysis result.
  • Include device/package/PID metadata, analysis summary, related logs, context logs, key frames, and suggestions.
  • Copy the Markdown to the clipboard or export it as a .md file.
  • Avoid OpenAI, Claude, Gemini, or any cloud model calls.
• Build / Install / Launch MVP
  • Select an Android project directory and detect gradlew / gradlew.bat.
  • Validate settings.gradle / settings.gradle.kts.
  • Run assembleDebug by default.
  • Find the newest debug APK under build/outputs/apk.
  • Install APKs with adb install -r and optional -d, -g, -t.
  • Launch the configured package with adb shell monkey -p <package> 1.
  • Send install failures to the Install Error Analyzer and Analysis panel.
• Workspace / Filter Presets
  • Store multiple lightweight workspaces in the user's local CatScope config.
  • Restore project path, package name, selected device, log levels, search keyword, install options, and AI context options.
  • Save, select, update, and delete workspaces.
  • Built-in presets: All Logs, Errors Only, AndroidRuntime, Native Crash, Install Errors, and Current Package.
  • Save, apply, rename, and delete custom filter presets with level, package, keyword, regex, tags, and exclude keyword.
• Session Save / Restore
  • Save live or offline debugging state as a .catscope-session file.
  • Preserve logs, raw text, multiline stacktraces, package names, levels, tags, PID/TID, timestamps, filters, workspace metadata, AI Context options, notes, and Analysis results.
  • Open a session in Session mode, restore logs into the buffer, and continue search, filtering, details inspection, Analyzer, and AI Context generation.
  • Show session name, file path, log count, analysis count, and created time.
• More export formats: csv, zip.
• Module and variant selection for Build / Install / Launch.
• macOS and Linux support.

Quick Start

Requirements

• Go 1.22 or later.
• Node.js 20 or later and npm 10 or later.
• Wails v2 CLI.
• Windows with Microsoft WebView2 Runtime.
• Android SDK Platform Tools, with adb available through one of:
  • ANDROID_HOME or ANDROID_SDK_ROOT.
  • platform-tools added to PATH.
  • CatScope adb path configuration, with a more complete UI planned.

Install the Wails CLI:

go install github.com/wailsapp/wails/v2/cmd/wails@latest

Run Locally

git clone <repository-url>
cd CatScope

go test ./...

cd frontend
npm install
npm run build

cd ..
wails doctor
wails dev

Live Logcat requires an Android device or emulator with USB debugging authorized. Offline Log File Viewer works without an Android device and can open .txt, .log, or .jsonl files for search, filtering, analysis, and AI Context generation. Session mode opens .catscope-session files, which are CatScope debugging-state files for saving live or offline analysis work and returning to it later.

If the device is unauthorized, approve the authorization prompt on the device and refresh. If it is offline, reconnect the device or restart adb server and refresh.

Windows Usage

For a local development build:

scripts\check.ps1
scripts\build-windows.ps1
.\build\bin\CatScope.exe

For a GitHub Release build, download the Windows artifact, extract it if it is a portable archive, and run CatScope.exe. Live Logcat needs a device or emulator with USB debugging enabled. On the first USB connection, Android shows an authorization dialog on the device; accept it, then refresh the CatScope device list.

FAQ

Is CatScope an Android Studio replacement? No. CatScope focuses on Logcat, crash clues, installs, launches, sessions, and local context generation. It is intentionally not a full IDE.

Does CatScope upload my logs? No. Logs, sessions, workspace settings, and AI Context Markdown are local unless you manually share exported files.

Does AI Context call OpenAI, Claude, Gemini, or another cloud model? No. It only creates local Markdown that you can copy or export.

Why is my device unauthorized? The phone has not approved USB debugging for this computer. Unlock the device, accept the prompt, and refresh.

Why is my device offline? Reconnect USB, confirm debugging is enabled, or restart adb with adb kill-server and refresh.

Can CatScope sync Gradle projects or edit code? No. Build / Install / Launch is a basic helper workflow and does not include Gradle Project Sync or a code editor.

Is the Vite chunk size warning a release blocker? No. It is currently a known build warning and does not block normal use.

Tech Stack

Desktop framework: Wails v2
Backend: Go
Frontend: Vue 3 + TypeScript
Build tool: Vite
State management: Pinia
UI library: Naive UI
Virtual scrolling: Vue virtual scrolling utilities
ADB integration: Go exec.Command
Local storage: JSON configuration, SQLite planned
Primary platform: Windows
Planned platforms: macOS, Linux

Vue 3 keeps the desktop-tool UI easy to evolve. Naive UI fits dark themes, forms, drawers, tabs, notifications, and workbench-style layouts. Pinia owns device, log stream, filter, and session state. Virtual scrolling keeps large Logcat sessions responsive.

Project Scope

CatScope focuses on Android troubleshooting workflows around Logcat. The first goal is an excellent live and offline Logcat Viewer; build, install, launch, crash analysis, AI-ready context, and saved workspace presets are adjacent workflows that support the same debugging loop. The current build runner is intentionally small: it runs Gradle wrapper tasks such as the default assembleDebug, but it is not Gradle Project Sync and it is not a full IDE. The multi-workspace support is also lightweight configuration, not a full IDE project system.

CatScope is not intended to provide:

• code editing,
• layout preview,
• Gradle Project Sync,
• breakpoint debugging,
• profiler,
• complete signing management,
• AAB publishing,
• complex Flavor visual management,
• full NDK / CMake configuration UI,
• a full Android Studio replacement.

Target Users

• Android app developers.
• Android plugin developers.
• Native so / JNI debugging engineers.
• QA and automation engineers.
• Developers who often debug with AI agents.
• Anyone who needs Logcat and basic app troubleshooting without opening Android Studio.

Roadmap

1. Make the Logcat Viewer fast, filterable, searchable, and comfortable for long sessions.
2. Keep improving the rule-based Analyzer and AI context generation.
3. Expand Build / Install / Launch with module and variant selection.
4. Improve cross-platform behavior and historical log analysis.

See docs/ROADMAP.md for the full roadmap.

Repository Layout

CatScope/
├─ frontend/          # Vue 3 + TypeScript frontend
├─ internal/          # Go backend packages
├─ docs/              # Architecture, roadmap and development notes
├─ app.go             # Wails app bindings
├─ main.go            # Application entry point
├─ wails.json         # Wails project config
├─ go.mod
├─ go.sum
├─ Logo.png
├─ README.md
└─ README.zh-CN.md

Documentation

• Roadmap
• Architecture
• User Guide
• Known Issues
• Release Notes Template
• Screenshots Placeholder
• MVP Tasks
• Codex Start Prompt

Contributing

Issues, suggestions, and pull requests are welcome. The project is still early, so high-impact contributions include:

• Logcat Viewer stability, performance, and interaction improvements.
• adb compatibility across devices, ROMs, and emulators.
• Crash / ANR / native crash recognition rules.
• Build / Install / Launch workflows.
• Documentation, screenshots, setup notes, and cross-platform validation.

Before submitting changes, please run:

scripts\check.ps1

Privacy

CatScope reads device information and live Logcat through local adb. Offline log files are read from local disk only. Workspace and preset settings are saved as JSON in the user's local CatScope configuration directory, such as %APPDATA%/CatScope/config.json on Windows, and are not written into Android project directories. .catscope-session files are local JSON files that store a CatScope debugging state, including logs, filters, Analysis results, and AI Context options; CatScope does not upload them to the cloud. The project does not require uploading logs to a remote service. The AI Context Generator only creates local Markdown for you to copy or export; it does not call any external AI API. When sharing exported logs, session files, or AI context, avoid leaking sensitive device information, user data, tokens, package names, or internal business logs.

License

This repository does not include a license file yet. Before public distribution or accepting external contributions, add a LICENSE file and declare the license here.