Getting started

You need a computer (macOS, Linux, or Windows via WSL), the device on the same Wi-Fi or a USB cable, and about ten minutes. No root, no app installed on the device.

1. Install

Node.js 22 or later.
adb from Android platform-tools 30 or later. On macOS: brew install android-platform-tools. On Debian/Ubuntu: sudo apt install adb. Or download platform-tools from the Android developer site and add it to your PATH.

npm i -g android-cleanup-agent
android-cleanup-agent doctor

Or run it without installing: npx android-cleanup-agent doctor. doctor checks adb, Wi-Fi debugging discovery and connected devices.

2. Enable developer options and debugging

The path depends on the kind of device. On all of them you tap the build number seven times until it says you are a developer.

Phone or tablet (including TVs running tablet Android)

Settings → About phone (or About tablet) → tap Build number 7 times. On some brands it is under Software information.
Settings → System → Developer options.
Turn on USB debugging for a cable, or Wireless debugging (Android 11+) for Wi-Fi. For Wi-Fi, open Wireless debugging → Pair device with pairing code; it shows an IP address and a 6-digit code.

Android TV

Settings → Device Preferences → About → tap Build 7 times.
Settings → Device Preferences → Developer options → turn on USB debugging, or Wireless debugging where offered.

Google TV

Settings → System → About → tap Android TV OS build 7 times.
Settings → System → Developer options → turn on USB debugging, or Wireless debugging where offered.

Older Android TV devices

Before Android 11 there is no Wireless debugging. Many older TVs have Network debugging (or ADB over network) in Developer options instead. It listens on port 5555 and needs no pairing code: just connect --host <ip>.

3. Connect

USB

Plug in the cable, run android-cleanup-agent devices, and accept the Allow USB debugging? prompt on the device screen. Tick Always allow from this computer.

Wi-Fi

android-cleanup-agent pair --host 192.168.1.40 --code 123456
android-cleanup-agent connect --host 192.168.1.40

Use the IP address and code shown on the device's pairing screen. You do not need to type ports: the pairing and connect ports are found automatically over mDNS (pass --port only if discovery fails on your network). Pairing is needed once per computer; after that, connect is enough.

4. First run

With Claude Code

/plugin marketplace add willcoliveira/android-cleanup-agent
/plugin install android-cleanup-agent@android-cleanup-agent
/android-cleanup-agent:cleanup

Claude runs the audit, asks what feels wrong and which features you use, explains the plan, and asks for approvals before anything changes. Use /android-cleanup-agent:audit for a look without changes. More about the plugin.

Without Claude (CLI only)

android-cleanup-agent audit --summary
android-cleanup-agent plan --uses cast,typing --power mains --symptoms slow-menus,storage --keep com.google.android.youtube.tv
android-cleanup-agent approvals init
android-cleanup-agent approvals show
android-cleanup-agent approvals set --category google-apps=true --category performance=true
android-cleanup-agent apply          # dry run
android-cleanup-agent apply --yes
android-cleanup-agent results

All approvals start off. Apps you installed and high-risk items need their own --item <id>=true. The plan can also read your answers from a file with plan --answers answers.yaml (uses, power, symptoms, keep). See the CLI reference.

Troubleshooting

What you see	What to do
`unauthorized`	The device has not accepted this computer. Look at the device screen for the Allow debugging prompt and accept it. If it never appears, revoke USB debugging authorizations in Developer options, unplug and reconnect.
`offline`	Unplug and reconnect, or run `connect` again. Over Wi-Fi, check that the computer and device are on the same network and the device is awake.
Connection refused after it worked before	Wireless debugging picks a new port each time it is turned on. Run `connect --host <ip>` again and it finds the new port; pairing is not needed again.
Nothing found after a restart	Wireless debugging turns itself off after every restart of the device. Turn it on again in Developer options, then `connect`.
Exit code 3	No device, or not authorized. See the first rows.
Exit code 5 during `apply`	The connection dropped or a different device answered. Reconnect the same device and run `apply --yes --resume`.
Exit code 6	Unsupported device (for example Fire TV).