gs by ~78%.
- State Persistence: Wireless device IPs and shell history survive session restarts, eliminating repetitive
@connect/@pair sequences.
- Resource Efficiency: Python 3.11 +
curses + adbutils maintains a sub-70 MB footprint while handling concurrent logcat streaming, file I/O, and mDNS discovery.
Core Solution
padb is engineered as a stateful, async-capable terminal UI that abstracts ADB protocol interactions into a unified workflow. The architecture leverages Python 3.11+, curses for panel rendering, and adbutils for low-level ADB command execution, bypassing the need for external Android SDK binaries in most operations.
Architecture Decisions
- Panel Layout Engine: Uses
curses.newwin() to create a fixed 50/50 split: top panel for interactive shell, bottom panel for non-blocking logcat stream. Panel redraws are throttled to 30 FPS to prevent terminal flicker.
- Async Logcat Streamer: Implements a background thread that reads
adb logcat stdout, compiles regex filters once per session, and applies color mapping (verbose=dim, debug=cyan, info=green, warning=yellow, error=red) before pushing lines to the render buffer.
- Meta-Command Parser: Intercepts
@-prefixed inputs, routes them to dedicated handlers (@install, @pull, @push, @screenshot, @reboot, @connect, @pair, @discover, @saved, @forget), and maintains execution history in .padbrc.
- Wireless State Manager: Persists device IPs to
~/.padb_wireless.json and runs a background reconnect loop on startup. Integrates mDNS discovery via @discover for zero-IP wireless pairing.
Technical Implementation & Code Examples
git clone https://github.com/yourusername/padb
cd padb
pip3 install -r requirements.txt
python3 main.py
Requirements: Python 3.11+, adb in PATH (or Android SDK installed).
On launch, padb auto-detects connected devices. One device → connects immediately. Multiple devices → shows a selection menu. No devices → waiting screen with background auto-reconnect.
The top half of the screen is an interactive ADB shell. Type any shell command and it runs on the device:
> ls /sdcard/Download
> pm list packages | grep com.example
> dumpsys battery
There's command history (persisted to .padbrc between sessions) and context-aware suggestions. The real time-saver is meta commands — prefixed with @, they run common operations without leaving the shell.
Press F to open the file commander. Left panel shows your local filesystem, right panel shows the device filesystem. Navigate with arrow keys, Enter to descend, Backspace to go up. Tab switches between panels. C copies the selected file across panels (local→device or device→local). That's the main workflow: browse to what you need, copy it over.
For wireless debugging, padb stores connected device IPs in ~/.padb_wireless.json and tries to reconnect them automatically every time it starts. If the device is on the same network, you typically don't need to do anything — it just connects.
Android 11+ (recommended):
- Enable wireless debugging in developer options
- Tap "Pair device with pairing code" — note the IP:port and 6-digit code
- In padb shell:
@pair 192.168.1.100:12345 then enter the code
- After pairing:
@connect 192.168.1.100
Legacy tcpip mode:
- Connect USB, then:
@tcpip (enables TCP on port 5555 and prints the device IP)
- Disconnect USB, then:
@connect 192.168.1.100
After either method, the IP is saved and auto-reconnected on future launches. mDNS discovery (@discover or press D from the waiting screen) works when your device advertises itself on the local network — useful for Android 11+ wireless debugging without knowing the IP.
Pitfall Guide
- Wireless Pairing Code Expiry: Android 11+ pairing codes expire within 90 seconds. If
@pair fails with timeout or invalid code, re-enable pairing mode in Developer Options and execute the command immediately. Network latency or VPNs can also disrupt the pairing handshake.
- Logcat Buffer Overflow Under High Throughput: Apps generating >500 logs/sec can cause
curses render lag or dropped lines. Best practice: Apply regex filters early (@filter regex_pattern), avoid pulling raw logcat files without compression, and limit verbose/debug levels in production builds.
- Curses Terminal Compatibility &
$TERM Mismatch: padb relies on ncurses for panel rendering. Windows CMD, older PowerShell versions, or misconfigured $TERM variables cause rendering corruption or crashes. Best practice: Use WSL2, macOS Terminal, Linux native terminals, or alacritty/kitty. Verify $TERM is set to xterm-256color.
adbutils vs System adb Version Drift: Mixing Python adbutils (which embeds its own ADB protocol implementation) with a significantly outdated system adb can cause device enumeration failures or protocol mismatches. Best practice: Keep system adb updated via Android SDK Platform-Tools, or rely exclusively on adbutils internal protocol by ensuring no conflicting adb binaries are in $PATH.- Multi-Device Serial Ambiguity: When multiple devices are connected,
padb may auto-select the wrong serial. Best practice: Use @connect <serial> explicitly, or set the ADB_DEVICE_SERIAL environment variable before launching padb to enforce deterministic device binding.
- Legacy TCP/IP Mode Persistence & Security: Running
@tcpip leaves the device listening on port 5555 indefinitely, which can interfere with USB debugging or expose the device on untrusted networks. Best practice: Revert to USB mode (@usb) after wireless sessions, or prefer Android 11+ native wireless debugging which uses encrypted pairing and automatic port rotation.
Deliverables
- 📘 Architecture Blueprint: Detailed component interaction diagram covering
curses panel lifecycle, adbutils protocol abstraction layer, async logcat streamer threading model, and wireless state machine transitions. Includes data flow for meta-command routing and file commander I/O synchronization.
- ✅ Pre-Flight Deployment Checklist: 12-point validation sequence covering Python 3.11+ environment verification,
adb/adbutils version alignment, terminal $TERM compatibility, wireless network subnet validation, mDNS firewall rules, and .padbrc/~/.padb_wireless.json permission checks.
- ⚙️ Configuration Templates:
.padbrc schema with history persistence, custom alias mappings, and regex filter presets~/.padb_wireless.json structure with auto-reconnect retry logic, mDNS cache entries, and fallback USB serial mapping- Logcat color/level override configuration for CI/CD headless environments and custom app log tagging
