Android Toolkit

A modular, non-root Android optimization and diagnostics toolkit

Works with ADB (USB/wireless) or Shizuku/rish backends.
Targets Android 13–16 and Samsung One UI 5–8, with special attention to the Galaxy S23 Ultra.

Philosophy: Safe, reversible, device-aware operations.
Prefer verified actions over aggressive or speculative tweaks.
No root required. No bootloader unlock. No warranty void.

Features

Area	Capabilities
Device Detection	Android version, SDK, model, manufacturer, One UI version, build fingerprint, ABI
Backend	Auto-detects ADB, Shizuku/rish, or local shell. Selectable via `--backend`
Performance	Animation scales, GPU/HWUI rendering, cached app freezer, ART dexopt profiles
Battery	Battery stats reporting, power saver toggle, automatic/dynamic power savings
Display	Resolution/density reading, refresh rate display, override with rollback
Network	Mobile data always-on toggle, BLE/WiFi scanning, DNS flush, connectivity check
Packages	Disable/enable packages with protected list, backup before disable
Maintenance	ART bytecode compilation (`bg-dexopt-job`), cache clearing, fstrim
Reporting	Quick status overview, comprehensive device report
Samsung	One UI version detection, GOS disable/uninstall, refresh rate control, multi-core scheduler, Light Performance Profile, RAM Plus management, touch optimization, battery/display/network optimizations, comprehensive bloatware listing (100+ packages, 6 categories), Samsung Customization Service management, app background restriction/whitelist
Safety	Probe-before-write settings, backups before destructive actions, protection list for critical packages, dry-run mode, configurable timeouts
Capability Detection	Comprehensive probe of device properties, runtime environment, and feature support; results cached for downstream use
Settings Database	Canonical JSON reference of 38 settings with Android/OEM constraints, defaults, recommendations, risk levels
Automatic Validation	7-step write protocol: probe namespace → read current → compare → record rollback → dry-run check → apply → verify
Rollback Engine	Journal-based rollback with `--rollback latest`, `--rollback <timestamp>`, `--rollback list`; auto-restore on validation failure
Doctor Command	Comprehensive system diagnostics with PASS/WARNING/FAIL; checks backend, storage, modules, profiles, capabilities, permissions
Benchmark	CPU (cores, frequency, governor), memory, storage, battery, thermal, GPU rendering, package compilation state — output as JSON + Markdown
Plugin System	Pluggable architecture — third-party scripts auto-loaded from `plugins/` with registration, execution, and cleanup lifecycle
OEM Framework	Device-aware OEM modules for Samsung, Google, OnePlus, Nothing, Xiaomi, Motorola, Oppo, Vivo with per-OEM settings validation

Architecture

                    ┌─────────────────────────────────┐
                    │         toolkit.sh               │
                    │    CLI Parser + Dispatcher        │
                    └──────────┬──────────────────────┘
                               │
            ┌──────────────────┼──────────────────────┐
            ▼                  ▼                       ▼
    ┌──────────────┐   ┌──────────────┐   ┌──────────────────┐
    │  lib/        │   │  modules/    │   │  plugins/         │
    │  Core Libs   │──▶│  Features    │──▶│  Third-party      │
    │  ──────────  │   │  ──────────  │   │  Extensions       │
    │  backend.sh  │   │  perf.sh     │   └──────────────────┘
    │  detection.sh│   │  battery.sh  │
    │  config.sh   │   │  network.sh  │   ┌──────────────────┐
    │  plugin.sh   │   │  samsung.sh  │   │  configs/        │
    │  rollback.sh │   │  doctor.sh   │   │  settings-db.json│
    │  ...         │   │  ...         │   │  default.conf    │
    └──────┬───────┘   └──────┬───────┘   └──────────────────┘
           │                  │
           ▼                  ▼
    ┌─────────────────────────────────────┐
    │        Backend Abstraction           │
    │  ADB (USB/Wireless) │ rish │ Local   │
    └─────────────────────────────────────┘

Key design choices:

Backend-agnostic: All device operations go through backend_exec(), which translates to ADB shell, rish shell, or direct local execution.
Journaled writes: Every settings put is recorded in a rollback journal before execution. Failed writes auto-revert.
Capability probing: No assumptions about device capabilities. Everything is probed at runtime and cached.
OEM framework: Per-OEM modules extend the core with device-specific settings and validation rules.

Requirements

Termux from F-Droid (not Google Play — Play version is outdated)
Bash (default in Termux)
Optional: adb (pkg install android-tools)
Optional: Shizuku app + rish for on-device elevated access

Installation

# Clone or copy the toolkit to your Termux home
cp -r android-toolkit ~/
cd ~/android-toolkit

# Make scripts executable
chmod +x toolkit.sh lib/*.sh modules/*.sh

# (Optional) Install ADB for USB/wireless backend support
pkg install android-tools

# Run a quick status check
./toolkit.sh --status

Backend Setup

ADB (USB or Wireless)

The ADB backend requires adb installed (pkg install android-tools) and a device connected with USB debugging or wireless debugging enabled.

USB:

Enable Developer options (tap Build Number 7 times in Settings → About phone)
Enable USB debugging in Developer options
Connect your phone to your computer with a USB cable
Run adb devices to verify the connection
Run the toolkit with ./toolkit.sh --backend adb --status

Wireless (Android 11+):

Enable Wireless debugging in Developer options
Use Pairing code to connect: adb pair <ip>:<port>
Connect: adb connect <ip>:<port>
Run the toolkit

Note: ADB authorization resets after reboot. You'll need to reconnect.

Shizuku / rish

Shizuku allows apps to use system APIs without root.

Install Shizuku from Google Play
Start the Shizuku service (via Wireless debugging or ADB)
In Shizuku, go to Terminal → follow instructions to download rish
Copy rish to Termux: cp /storage/emulated/0/Android/data/moe.shizuku.privileged.api/files/rish $PREFIX/bin/
Verify: rish -c 'echo ok'
Run the toolkit: ./toolkit.sh --backend rish --status

Note: Shizuku service stops after reboot. Restart it from the Shizuku app.

Usage

toolkit.sh [OPTIONS] <ACTION>

Options

Flag	Description
`-b, --backend <type>`	Backend: `adb`, `rish`, or `auto` (default)
`-s, --serial <id>`	ADB device serial (only with `--backend adb`)
`-v, --verbose`	Enable debug-level logging
`-n, --dry-run`	Preview changes without executing them
`-h, --help`	Show help message

Actions

Action	Description
`--status`	Quick device status overview
`--report`	Full device report (battery, display, network, packages, properties)
`--backup`	Create full settings + packages backup
`--restore <file>`	Restore settings from a backup file
`--apply <profile>`	Apply a performance profile (balanced\|performance\|powersave\|light)
`--compile`	Force ART bytecode optimization (`cmd package bg-dexopt-job`)
`--trim-cache`	Clear app caches and trim filesystem
`--refresh-network`	Tune network settings and flush DNS
`--disable-package <pkg>`	Disable a system package (opt-in)
`--enable-package <pkg>`	Re-enable a disabled package
`--list-bloatware [level]`	List Samsung bloatware (safe\|moderate\|aggressive\|all)
`--samsung-light`	Apply Samsung light optimizations (battery-focused)
`--doctor [filter]`	Run system diagnostics (filter: backend\|storage\|modules\|profiles\|capabilities\|permissions)
`--rollback [target]`	Rollback changes — `latest` (default), `<timestamp>`, or `list`
`--benchmark`	Run device benchmark (CPU, memory, storage, battery, thermal, GPU)
`--plugin <name> [args]`	Execute a plugin by name, passing optional arguments

Examples

# Quick status
./toolkit.sh --status

# Full report via Shizuku
./toolkit.sh --backend rish --report

# Backup settings via ADB
./toolkit.sh --backend adb --backup

# Preview profile changes without applying
./toolkit.sh --dry-run --apply performance

# Apply balanced profile
./toolkit.sh --apply balanced

# Optimize app bytecode
./toolkit.sh --compile

# Disable a package (with confirmation)
./toolkit.sh --disable-package com.facebook.appmanager

# Re-enable a package
./toolkit.sh --enable-package com.facebook.appmanager

# List Samsung bloatware (safe only)
./toolkit.sh --list-bloatware safe

# List all Samsung bloatware candidates
./toolkit.sh --list-bloatware all

# Apply Samsung light optimizations (battery-focused)
./toolkit.sh --samsung-light

# Run diagnostics
./toolkit.sh --doctor

# Check backend connectivity only
./toolkit.sh --doctor backend

# List rollback entries
./toolkit.sh --rollback list

# Rollback latest change
./toolkit.sh --rollback latest

# Run device benchmark
./toolkit.sh --benchmark

# Execute a plugin
./toolkit.sh --plugin my-plugin --arg1 val1

# Verbose logging for debugging
./toolkit.sh --verbose --status

Profiles

Profiles are preset configurations stored in the profiles/ directory. Each profile sets animation scale, GPU rendering, app freezer, dexopt mode, battery saver, and Samsung-specific settings (GOS, RAM Plus, refresh rate, performance profile).

Profile	Animation	Dexopt	GPU Render	Battery Saver	Samsung Refresh	GOS	RAM Plus	Light Perf
balanced	0.75x	speed-profile	Default	Off	Keep current	Keep	Keep	Off
performance	Off (0x)	speed	Forced 2D + MSAA	Off	120Hz peak	Keep	0	Off
powersave	Off (0x)	verify	Default	On	60Hz capped	Disable	0	On
light	0.5x	speed-profile	Default	Off	60Hz	Disable	0	On

Apply a profile:

./toolkit.sh --apply balanced

A backup is automatically created before applying any profile.

Plugin System

The toolkit supports third-party plugins that extend its functionality without modifying core code. Plugins are auto-loaded from plugins/.

# List available plugins
./toolkit.sh --plugin list

# Run a plugin
./toolkit.sh --plugin my-plugin --arg1 val1

Example plugins are available in plugins/examples/:

Example	Demonstrates
`10-command-extension.sh`	Custom CLI commands via `plugin_commands()`
`20-reporting.sh`	Device data collection using `api_*` safe APIs
`30-validation.sh`	Config schema, dependencies, pre-run validation
`40-configuration.sh`	Persistent config via `plugin_config_get/set`

Plugin SDK reference: PLUGIN_API.md
Plugin examples: plugins/examples/
Plugin security: docs/PLUGIN_SECURITY.md
Plugin development guide: CONTRIBUTING.md

Backup and Restore

The toolkit creates timestamped backups in backups/.

Manual backup:

./toolkit.sh --backup

Creates two files:

snapshot_<timestamp>.txt — all system, secure, and global settings
packages_<timestamp>.txt — enabled, disabled, and third-party packages

Restore:

./toolkit.sh --restore backups/snapshot_20260724_120000.txt

Protected keys like adb_enabled and development_settings_enabled are skipped during restore to prevent locking the device.

Automatic backups are created before applying profiles and before disabling packages.

Dry Run Mode

Use --dry-run (or -n) to preview what would change without executing anything:

./toolkit.sh --dry-run --apply performance
./toolkit.sh --dry-run --trim-cache
./toolkit.sh --dry-run --disable-package com.example.app

Dry-run works across:

All backend_exec calls (prints the command that would run)
All backend_settings_put calls (prints the setting change)
Package disable/enable operations
Profile application
Cache trimming and ART compilation
Display resolution changes
Backup restoration

Read-only commands (status, report, settings reads) still execute in dry-run mode so the preview can show current values alongside planned changes.

Safety

No root required. The toolkit never attempts to gain root access.
Probe before write. Every settings change reads the current value first. If the value is already what's requested, no write occurs.
Protected packages. Critical system packages cannot be disabled via --disable-package. The protected list is in modules/packages.sh and includes phone, system UI, settings, launcher, keyboard, and Google Play Services.
Backups. Automatic backups are created before profile application and package disabling. Manual backup via --backup is recommended before major changes.
Confirmation. Package disabling requires interactive confirmation.
Samsung settings are guarded. Settings like peak_refresh_rate and multicore_packet_scheduler are only written if they already exist on the device.
Timeout protection. Long-running operations (ART compilation, cache clearing) have configurable timeouts (default: 300 seconds).
Dry-run available. Preview changes before applying them.
Rollback journal. Every write is recorded in a journal. Use --rollback list to see history and --rollback latest to undo the most recent change.
Settings database constraints. The settings-db.json maps each key to its minimum/maximum Android version, applicable OEM, and recommended value. Writes outside documented constraints are rejected.
Capability probing. All device/runtime features are probed before use. Capabilities are cached and never assumed.
Write verification. Every settings put is followed by a read-back and compared. If the value doesn't match, the change is automatically rolled back and the user is warned.

Supported Platforms

Platform	Support Level
Android 13 (API 33)	✅ Full
Android 14 (API 34)	✅ Full
Android 15 (API 35)	✅ Full
Android 16 (API 36)	⚠️ Experimental
Samsung One UI 5.x	✅ Full
Samsung One UI 6.x	✅ Full
Samsung One UI 7.x	✅ Full
Samsung One UI 8.x	⚠️ Experimental
Google Pixel (7-9)	✅ Full
OnePlus / OxygenOS	✅ Partial
Nothing OS	✅ Partial
Xiaomi HyperOS/MIUI	✅ Partial
Motorola My UX	✅ Partial
Oppo ColorOS	✅ Partial
Vivo Funtouch OS	✅ Partial

Compatibility Matrix

Backend	Read Settings	Write Settings	Package Ops	ART Compile	fstrim
`local`	✅	❌	❌	❌	❌
`adb` (USB)	✅	✅	✅	✅	✅
`adb` (Wireless)	✅	✅	✅	✅	✅
`rish`	✅	✅	✅	✅	⚠️

Feature	ADB	rish	Local
Device detection	✅	✅	✅
Performance profiles	✅	✅	❌
Battery optimization	✅	✅	❌
Network tuning	✅	✅	❌
Package management	✅	✅	❌
Backup & restore	✅	✅	✅
Rollback engine	✅	✅	❌
Doctor diagnostics	✅	✅	✅
Benchmark	✅	✅	✅
Plugins	✅	✅	✅

Documentation

Document	Description
README.md	This file — overview, installation, usage
CONTRIBUTING.md	Coding standards, PR process, testing
SECURITY.md	Vulnerability reporting and disclosure
CHANGELOG.md	Version history
LTS-POLICY.md	Long-term support schedule
PLUGIN_API.md	Plugin SDK v3.0 reference
docs/RELEASE_PROCESS.md	Release cadence, backport policy
ROADMAP_V5.md	Future development plans
docs/PLUGIN_SECURITY.md	Plugin security considerations
DEVELOPER.md	Internal architecture overview

Screenshots

Screenshots will be added in a future release.
The toolkit is a CLI-only tool. Example terminal output from key commands (--status, --doctor, --benchmark, --report) will be provided here.

Roadmap

Current release: v4.2.0 Stable — maintenance-only updates.

v5.0 Planning is documented in ROADMAP_V5.md, including:

Plugin namespace isolation
JSON output wiring
Android 17+ support
ShellCheck zero-warnings
Performance baselining
Generated documentation sync
Plugin SDK v4.0
CI consolidation

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for:

Coding standards (indentation, naming, quoting, error handling)
Commit message format (Conventional Commits)
PR checklist and review process
Testing requirements (BATS, ShellCheck, JSON validation)
Plugin development guide

Quick start:

# Fork and clone
git clone https://github.com/00AstroGit00/android-toolkit.git
cd android-toolkit

# Run syntax checks
bash -n toolkit.sh lib/*.sh modules/*.sh

# Run ShellCheck
shellcheck -x *.sh lib/*.sh modules/*.sh

# Run BATS tests
bats tests/bats/

Security

See SECURITY.md for:

Supported versions and LTS schedule
How to report a vulnerability
Disclosure process and timeline
GPG key information (if configured)

Do not open public issues for security vulnerabilities.
Report via the security issue template or contact maintainers directly.

License

MIT License — see LICENSE for details.

Acknowledgements

Shizuku — System API access without root
Termux — Android terminal emulator
BATS — Bash testing framework
ShellCheck — Shell script analysis
mvdan/sh — Shell formatter (shfmt)
All contributors who have helped improve the toolkit

_{Made with ❤️ for the Android community. No root required.}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Android Toolkit

Table of Contents

Features

Architecture

Requirements

Installation

Backend Setup

ADB (USB or Wireless)

Shizuku / rish

Usage

Options

Actions

Examples

Profiles

Plugin System

Backup and Restore

Dry Run Mode

Safety

Supported Platforms

Compatibility Matrix

Documentation

Screenshots

Roadmap

Contributing

Security

License

Acknowledgements

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.github		.github
configs		configs
docs		docs
lib		lib
modules		modules
plugins		plugins
profiles		profiles
reports		reports
tests		tests
validation		validation
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
DEVELOPER.md		DEVELOPER.md
FINAL_RELEASE_REVIEW.md		FINAL_RELEASE_REVIEW.md
INSTALL.sh		INSTALL.sh
LICENSE		LICENSE
LTS-POLICY.md		LTS-POLICY.md
PLUGIN_API.md		PLUGIN_API.md
README.md		README.md
RELEASE.md		RELEASE.md
ROADMAP_V5.md		ROADMAP_V5.md
SECURITY.md		SECURITY.md
STABLE_RELEASE_REPORT.md		STABLE_RELEASE_REPORT.md
SUPPORT.md		SUPPORT.md
VERSION		VERSION
toolkit.sh		toolkit.sh

Folders and files

Latest commit

History

Repository files navigation

Android Toolkit

Table of Contents

Features

Architecture

Requirements

Installation

Backend Setup

ADB (USB or Wireless)

Shizuku / rish

Usage

Options

Actions

Examples

Profiles

Plugin System

Backup and Restore

Dry Run Mode

Safety

Supported Platforms

Compatibility Matrix

Documentation

Screenshots

Roadmap

Contributing

Security

License

Acknowledgements

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages