Processes¶

Inspecting and stopping processes on a connected device. list_processes returns structured ps rows (pid/ppid/user/rss/name) with an optional server-side name substring filter; get_process_id resolves a process/package name to its PIDs via pidof (a list, since one name can back several processes; "not running" is a normal result, not an error); get_process_memory reads a curated dumpsys meminfo -s snapshot (the stable App Summary Pss categories plus TOTAL PSS/RSS/SWAP, in kilobytes). force_stop_app is the heavy am force-stop (stops everything and marks the package stopped); kill_background_processes is the gentler am kill (background-only, leaves package state alone).

`force_stop_app` ¶

Force-stop an Android package on a device: adb shell am force-stop.

Stops every process and component of the package, if any are running, and marks the package "stopped" until something explicitly launches it again. This is the heavy hammer — for a gentler, background-only kill that leaves package state alone, see kill_background_processes. Not a per-process kill: it operates on a package, not a single pid, which is why it isn't named kill_app.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`package_name`	`str`	The package to force-stop, e.g. "com.example.app".	required
`user_id`	`int \| None`	Force-stop the package for one specific Android user (`--user`, see list_users). Omit to stop it for every user.	`None`

Returns:

Type	Description
`ForceStopResult`	The serial, package_name, and user_id the force-stop was issued for, plus the raw (usually empty) am output. `am force-stop` normally produces no stdout at all on success — success is determined from the command's exit code, not from output content.

Error handling

An unknown serial or unresponsive adb binary raises DEVICE_NOT_FOUND/ADB_UNAVAILABLE. A blank package_name raises INVALID_ARGUMENT before anything runs. A rejection due to the caller lacking FORCE_STOP_PACKAGES raises PERMISSION_DENIED (unusual over adb shell, which is granted this by default). Any other ActivityManager/adb failure raises a generic BACKEND_ERROR. A package_name that doesn't correspond to any installed app is NOT an error — forceStopPackage() doesn't validate that the package exists; it's a silent no-op when there's nothing to stop.

Example

Called with serial="emulator-5554", package_name="com.example.app". A typical response:

{
  "status": "success",
  "message": "Force-stopped com.example.app on emulator-5554.",
  "data": {
    "serial": "emulator-5554",
    "package_name": "com.example.app",
    "user_id": null,
    "output": ""
  },
  "error": null
}

`get_process_id` ¶

Resolve a process/package name to its PIDs: adb shell pidof.

Returns a list because one name can back several processes (an app with multiple android:process entries). A name with nothing running is a normal result (running=false, empty list), not an error — pidof can't distinguish "not installed" from "installed but not running", so neither does this.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`name`	`str`	The process or package name to look up, e.g. "com.android.systemui" or "system_server".	required

Returns:

Type	Description
`ProcessIds`	The serial, the name queried, pids (a list of integers, possibly empty), and running (true when at least one PID was found).

Error handling

An unknown serial or unresponsive adb binary raises DEVICE_NOT_FOUND/ADB_UNAVAILABLE. A blank name raises INVALID_ARGUMENT before anything runs. Any non-zero exit that carries actual error output raises BACKEND_ERROR; a bare non-zero exit with no output is treated as "not running", not a failure.

Example

Called with serial="emulator-5554", name="com.android.systemui". A typical response:

{
  "status": "success",
  "message": "'com.android.systemui' on emulator-5554: pid 1224.",
  "data": {
    "serial": "emulator-5554",
    "name": "com.android.systemui",
    "pids": [1224],
    "running": true
  },
  "error": null
}

`get_process_memory` ¶

Read a curated memory snapshot for a process: adb shell dumpsys meminfo -s.

Runs meminfo in summary mode and extracts only its stable "App Summary" Pss categories and the "TOTAL PSS / RSS / SWAP" line — the volatile per-mapping detail is dropped. All values are kilobyte integers exactly as meminfo reports them; no unit conversion is applied.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`target`	`str`	A package name (e.g. "com.android.systemui") or a numeric PID as a string (e.g. "1224") to measure.	required

Returns:

Type	Description
`ProcessMemory`	The serial and the target queried; pid and process_name from meminfo's header; the per-category Pss values (java_heap_pss_kb, native_heap_pss_kb, code_pss_kb, stack_pss_kb, graphics_pss_kb, private_other_pss_kb, system_pss_kb), each null if that row was absent; and total_pss_kb / total_rss_kb / total_swap_kb (null on older builds that don't print the TOTAL line).

Error handling

An unknown serial or unresponsive adb binary raises DEVICE_NOT_FOUND/ADB_UNAVAILABLE. A blank target raises INVALID_ARGUMENT before anything runs. A target with no running process ("No process found for: ...") raises PACKAGE_NOT_RUNNING. meminfo running but producing output with neither a recognizable header nor a TOTAL line raises PROCESS_MEMORY_UNAVAILABLE. A permission rejection raises PERMISSION_DENIED; any other non-zero exit raises BACKEND_ERROR.

Example

Called with serial="emulator-5554", target="com.android.systemui". A typical response:

{
  "status": "success",
  "message": "com.android.systemui on emulator-5554: 105321 KB total PSS.",
  "data": {
    "serial": "emulator-5554",
    "target": "com.android.systemui",
    "pid": 1224,
    "process_name": "com.android.systemui",
    "java_heap_pss_kb": 28048,
    "native_heap_pss_kb": 21120,
    "code_pss_kb": 37168,
    "stack_pss_kb": 1632,
    "graphics_pss_kb": 0,
    "private_other_pss_kb": 4008,
    "system_pss_kb": 13345,
    "total_pss_kb": 105321,
    "total_rss_kb": 268416,
    "total_swap_kb": 0
  },
  "error": null
}

`kill_background_processes` ¶

Kill a package's killable background processes: adb shell am kill.

Semantically distinct from force_stop_app: ActivityManager kills only the package's processes it currently considers safe to reclaim (cached/background) and leaves a foreground process alone, and it does not set the package's "stopped" flag. Use this to simulate the system reclaiming memory from a backgrounded app without fully tearing its package state down.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`package_name`	`str`	The package whose background processes to kill, e.g. "com.example.app".	required
`user_id`	`int \| None`	Restrict the kill to one Android user (`--user`, see list_users). Omit to apply it across users.	`None`

Returns:

Type	Description
`KillBackgroundResult`	The serial, package_name, and user_id the kill was issued for, plus am's raw (normally empty) output. Success is read from the exit code, not output content.

Error handling

An unknown serial or unresponsive adb binary raises DEVICE_NOT_FOUND/ADB_UNAVAILABLE. A blank package_name raises INVALID_ARGUMENT before anything runs. A permission rejection raises PERMISSION_DENIED; any other non-zero exit raises BACKEND_ERROR. A package with nothing killable — not installed, or currently in the foreground — is NOT an error: am kill is a silent no-op there.

Example

Called with serial="emulator-5554", package_name="com.example.app". A typical response:

{
  "status": "success",
  "message": "Requested background-process kill of com.example.app on emulator-5554.",
  "data": {
    "serial": "emulator-5554",
    "package_name": "com.example.app",
    "user_id": null,
    "output": ""
  },
  "error": null
}

`list_processes` ¶

List running processes on a device: adb shell ps.

Runs ps with a fixed column set (PID, PPID, USER, RSS, NAME) and parses it into structured rows — no raw ps flags are exposed. Pass name_filter to keep only processes whose name contains that substring (matched on the device-reported process name, server-side), which is the usual way to find every process belonging to an app.

Parameters:

Name	Type	Description	Default
`serial`	`str`	The target device's adb serial (see list_connected_devices).	required
`name_filter`	`str \| None`	Optional case-sensitive substring; only processes whose name contains it are returned. Omit to return every process.	`None`

Returns:

Type	Description
`ProcessList`	The serial, the name_filter that was applied (or null), and a list of processes, each with pid, ppid, user, rss_kb (resident size in KB), and name. An empty list is a valid result when a filter matched nothing.

Error handling

An unknown serial or unresponsive adb binary raises DEVICE_NOT_FOUND/ADB_UNAVAILABLE. A blank name_filter (given but empty/whitespace) raises INVALID_ARGUMENT before anything runs. A permission rejection raises PERMISSION_DENIED; any other non-zero exit raises BACKEND_ERROR. Unparseable ps lines are skipped rather than raising.

Example

Called with serial="emulator-5554", name_filter="systemui". A typical response:

{
  "status": "success",
  "message": "1 process matching 'systemui' on emulator-5554.",
  "data": {
    "serial": "emulator-5554",
    "name_filter": "systemui",
    "processes": [
      {
        "pid": 1224,
        "ppid": 432,
        "user": "u0_a141",
        "rss_kb": 260040,
        "name": "com.android.systemui"
      }
    ]
  },
  "error": null
}

Processes¶

force_stop_app ¶

get_process_id ¶

get_process_memory ¶

kill_background_processes ¶

list_processes ¶

`force_stop_app` ¶

`get_process_id` ¶

`get_process_memory` ¶

`kill_background_processes` ¶

`list_processes` ¶