ProcessLens

A process observatory for Android that refuses to make things up.

Watch what your phone is actually doing — processes, threads, CPU, memory, wake locks, network, battery — and record an investigation you can scrub back through afterwards.

_{Android 8.0 or newer · 12 MB · no account, no network permission · all releases}

The idea

Every system monitor on Android runs into the same wall. Since Android 7 an app can no longer read /proc for processes it does not own, and each release since has closed another door. Most apps respond by quietly showing you a plausible number anyway.

ProcessLens does the opposite. Every reading it displays is wrapped in a type that can only be one of three things:

sealed interface Observed<out T> {
    data class Value<out T>(val value: T, val source: DataSource, val precision: Precision)
    data class Restricted(val reason: RestrictionReason, val unlockedBy: AccessLevel?, val detail: String)
    data class Failed(val detail: String, val cause: String?)
}

There is no fourth case, and no default. If the platform will not tell ProcessLens something, the screen says so — which permission or access level would reveal it, and why it is hidden. A dash is never a zero, and the app says as much where you might mistake one for the other.

The same rule governs the analysis. A spike that lines up with an app waking the device is reported as a potential correlation, never a cause, because timestamps that happen to agree are not proof. Battery figures the platform does not expose are absent rather than estimated.

What it does

Watch — a live dashboard of CPU, memory, storage and battery, refreshing every 1, 2, 5 or 10 seconds, or only when you ask. Per-core utilisation and clock speeds where the kernel exposes them, load average, thermal zones.

Inspect — the full process list with sorting and filtering, then per-process detail: state, UID, start time, CPU time, threads, and the parent/child tree. Installed apps with their components, requested permissions and grant state, and which of their services are running right now.

Investigate — start a recording, use your phone normally, then stop. ProcessLens samples throughout and gives you a timeline of colour-dotted events: resource spikes against thresholds you set, wake locks acquired, processes appearing and vanishing. Scrub back through it, compare two apps side by side, and export the whole thing as JSON, CSV or plain text.

Understand its own limits — a Capabilities screen listing all 37 metrics ProcessLens knows how to read, grouped into nine areas and each marked available or not on your device, computed at runtime from what actually works rather than assumed from a version number.

Access levels

Most of the app works with no special access at all. Two optional paths widen what the kernel will admit to:

Shizuku is not root and ProcessLens does not pretend otherwise — it distinguishes all six states it can be in (not installed; installed but not running; running with permission not yet requested; running with permission denied; running with permission granted; running an unsupported version) and tells you which capabilities each would unlock.

There is no "kill everything" button, no arbitrary shell, and no one-tap destructive command. Process Details will not offer you a bare Kill button, because a tool for understanding a system should not make it trivially easy to break one.

Privacy

Not a policy — a property of the build.

• android.permission.INTERNET is not in the manifest. The app cannot open a socket even if it wanted to. Verified absent from the shipped APK.
• No account, no sign-in, no cloud, no analytics, no telemetry, no crash reporting service.
• Recordings, favourites and settings live in a local Room database and never leave the device unless you export a file and share it yourself.
• If the app ever crashes it writes the stack trace to your Downloads folder — a plain text file, yours to read, delete or send on.

Build it yourself

git clone https://github.com/Dreamucxe/ProcessLens.git
cd ProcessLens
chmod +x gradlew
./gradlew assembleRelease

Requires JDK 17 and an Android SDK with platform 34 and build-tools 34.0.0.

gradle.properties is committed exactly as it was when the released APK was built — on an aarch64 Android device under proot, not a workstation. That is why it pins org.gradle.java.home, overrides aapt2 with a native ARM binary, disables the Gradle daemon and runs the Kotlin compiler in-process. On a normal machine, delete those four lines.

Release builds are signed only if you drop a keystore.properties next to settings.gradle.kts:

storeFile=release.keystore
storePassword=…
keyAlias=…
keyPassword=…

Without it you get an unsigned APK; the signing key for the published release is not in this repository.

Tests

./gradlew testDebugUnitTest          # 396 JVM tests
./gradlew connectedDebugAndroidTest  # 90 instrumented tests, needs a device

The unit tests cover the /proc parser against fixture filesystems, CPU rate sampling, spike detection, export rendering, investigation recording and the search, sort and filter logic. The instrumented tests drive the real UI and deliberately use no testTag anywhere in production code — every node is found by its visible text or its content description, so a test that cannot find something is also telling you a screen reader could not.

Architecture

core/
  common          Observed<T>, AccessLevel, formatters, fuzzy matching
  designsystem    theme, glass cards, charts, bottom sheets
  system          SystemObserver + Standard / Shizuku / Root implementations
  permissions     runtime and special-access checks
data/
  database        Room entities, DAOs, migrations, exported schemas
  repository      repository implementations
domain/
  model           Capability, ProcessInfo, Investigation, UserSettings
  usecase         spike detection, recording, summarising, export
feature/          19 screens, one package each, MVVM with Hilt

Kotlin · Jetpack Compose · Material 3 · MVVM · Hilt · Room · Coroutines. The UI never calls a shell command or a privileged API directly; everything goes through SystemObserver, which routes to the highest access level currently available and falls back cleanly when it is withdrawn.

Licence

MIT — see LICENSE.

ProcessLens is a process observatory for Android that refuses to make things up.

Since Android 7 an app can no longer read /proc for processes it does not own, and every release since has closed another door. Most system monitors respond by showing you a plausible number anyway. ProcessLens wraps every reading in a type with exactly three cases — a value, a restriction, or a failure — and no default. Where the platform will not answer, the screen names the restriction and the access level that would lift it. A dash is never a zero.

What is in this build

• Live dashboard: CPU (overall and per core), memory, storage, battery, thermal zones, load average, at 1 / 2 / 5 / 10 second or manual refresh.
• Processes: full list with sorting and filtering, per-process detail with state, UID, start time, CPU time, threads, and the parent/child tree.
• Applications: installed packages, their components, requested permissions and real grant state, and which of their services are running now.
• Investigations: start a recording, use the phone normally, stop. You get a timeline of colour-dotted events — resource spikes against your own thresholds, wake locks, processes appearing and vanishing — plus side-by-side comparison and export to JSON, CSV or text.
• Capabilities: all 37 metrics ProcessLens knows how to read, each marked available or not on your device, detected at runtime rather than assumed from a version number.
• Optional Shizuku and root paths for ADB-level and unrestricted observation. No arbitrary shell, no kill-everything action.

Privacy

android.permission.INTERNET is not in the manifest, so the process cannot open a socket. No account, no backend, no analytics, no telemetry. Data stays in a local database unless you export a file yourself.

Install

Download ProcessLens.apk below and open it. Android will ask you to allow installing from your browser or file manager, because this is a sideloaded build rather than a Play Store one.

Requires Android 8.0 (API 26) or newer. Targets API 34.

sha256  d82426dc5a792d24059e83a2e350516cc406dae9446c24bf0878203228025db6
size    12,409,655 bytes
signer  CN=ProcessLens, RSA 2048, APK Signature Scheme v2
cert    sha256 40ad75c659e2878b4fa891315589861bc06040852f89772c279f424587f76c54

396 unit tests pass against this source tree. Full source, architecture notes and build instructions are in the repository.