https://github.com/lqvu-zen/zlog
A Windows-first desktop GUI for viewing Android adb logcat — built with Python + PySide6. Inspired by plog.
https://github.com/lqvu-zen/zlog
adb android desktop-app developer-tools log-viewer logcat pyside6 python qt windows
Last synced: 12 days ago
JSON representation
A Windows-first desktop GUI for viewing Android adb logcat — built with Python + PySide6. Inspired by plog.
- Host: GitHub
- URL: https://github.com/lqvu-zen/zlog
- Owner: lqvu-zen
- License: mit
- Created: 2026-06-30T13:19:52.000Z (25 days ago)
- Default Branch: main
- Last Pushed: 2026-07-08T15:14:22.000Z (17 days ago)
- Last Synced: 2026-07-08T15:18:45.694Z (17 days ago)
- Topics: adb, android, desktop-app, developer-tools, log-viewer, logcat, pyside6, python, qt, windows
- Language: Python
- Size: 922 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# zLog — Android Log Viewer
A desktop GUI for viewing Android `adb logcat`, inspired by
[plog](https://github.com/katatunix/plog). Built with **Python + PySide6 (Qt)**
and managed with **[uv](https://docs.astral.sh/uv/)**. Targets Windows first;
the code is cross-platform.
## Project layout
```
zLog/
├── pyproject.toml # project metadata, deps, tooling config
├── uv.lock # pinned, reproducible dependency versions
├── .python-version # Python version for uv
├── src/
│ └── zlog/
│ ├── app.py # entry point → main()
│ ├── __main__.py # enables `python -m zlog`
│ ├── core/ # pure logic, NO Qt (easy to test)
│ │ ├── models.py # LogEntry, level ranks
│ │ └── parser.py # logcat line parsing
│ ├── adb/
│ │ └── reader.py # background QThread running `adb logcat`
│ └── ui/
│ ├── log_model.py # Qt table model + filter proxy
│ └── main_window.py# window, toolbar, wiring
└── tests/
└── test_parser.py # unit tests for the parser (no display needed)
```
**Why this shape?** The `core` layer has no Qt imports, so it can be unit-tested
without a display and reused if the UI ever changes. `adb` owns the streaming
thread, `ui` owns everything Qt. Each concern lives in one place, which is what
makes the project easy to grow.
## Data flow
```
AdbReader (background thread)
runs `adb logcat -v threadtime`, parses each line
│ batch_ready (signal, ~50 lines at a time)
▼
LogTableModel ── master list of every line (virtualized)
│
LogFilterProxy ── decides which rows show (level + tag + text + package + exclude)
│
LogItemDelegate ─ paints one dense line per visible row (no grid)
```
Filtering is driven by a single **query bar** parsed by `core/query.py`
(`level: tag: package: -exclude /regex/ text`).
Three ideas make this scale to huge logs: reading happens **off the UI thread**;
the model is **virtualized** (Qt only asks for visible rows); and filtering is a
**proxy on top of the master list**, so clearing a filter is instant.
## Prerequisites
- [uv](https://docs.astral.sh/uv/getting-started/installation/) installed.
- [Android platform-tools](https://developer.android.com/tools/releases/platform-tools)
on your PATH (run `adb version` to confirm).
- A device with USB debugging on, or a running emulator.
> Note: `requires-python` is `>=3.14`. uv will fetch a matching Python for you
> automatically if you don't have one.
## User guide
See **[docs/GUIDE.md](docs/GUIDE.md)** for a walkthrough with screenshots.
## Roadmap
See **[docs/ROADMAP.md](docs/ROADMAP.md)** for the prioritized long-term plan.
## Run
```bash
uv run zlog
```
That's it — `uv run` creates the virtual environment, installs locked
dependencies, and launches the app. Equivalent: `uv run python -m zlog`.
Click **Start** to stream, use **Min level** and the search box to filter,
**Clear** to empty the view, **Stop** to end streaming.
## Develop
```bash
uv sync --extra dev # install app + dev tools (pytest, ruff)
uv run pytest # run the test suite
uv run ruff check . # lint
uv run ruff format . # format
```
## Build a Windows .exe
Built with [cx_Freeze](https://cx-freeze.readthedocs.io/) (run on Windows):
```bash
uv run --extra build python cxfreeze_setup.py build
```
The app lands in `build\exe.win-amd64-\zlog.exe` (with its bundled runtime).
Or double-click **build.bat**. See the `release-zlog` skill for the full release flow.
## Features
A dense, Android-Studio-style log view with a single **query bar**
(`level: tag: package: -exclude /regex/ text`), device picker, live package/PID
tracking, highlight mode, match navigation, bookmarks, filter presets, relative-time
display, light/dark themes, font zoom, and save/open. See
**[docs/GUIDE.md](docs/GUIDE.md)** for the walkthrough and
**[docs/ROADMAP.md](docs/ROADMAP.md)** for what's planned next.
## License
MIT — see [LICENSE](LICENSE).