Skip to content
DroidBot

Introduction

DroidBot is an Android automation platform with a skill ecosystem. It controls real Android phones over USB via ADB to automate app interactions — tapping, swiping, typing, reading screen elements, and navigating complex multi-step flows. What started as a TikTok marketing bot is now a general-purpose framework for building, sharing, and running Android app automation skills, with AI-powered skill creation and live device streaming.

Why Real Phones?

Section titled “Why Real Phones?”

Emulators are detectable. Apps like TikTok, Instagram, and WhatsApp fingerprint the runtime environment and flag automated actions from emulators. DroidBot uses physical Android devices connected over USB, which means:

  • No emulator detection — your actions come from a real device with a real IMEI, real sensors, and real carrier data
  • Production-identical behavior — app UI, timing, and network behavior match what real users see
  • Stealth mode — Gaussian tap jitter, variable swipe speed, and character-by-character typing simulate human interaction patterns

Emulator support is also available for development and testing, but production automation targets real hardware.

How It Works

Section titled “How It Works”
Your Python code / Dashboard / Scheduler
        |
        v
   Flask Server (132+ REST endpoints, port 5055)
        |
        v
   Device class (47+ methods wrapping ADB)
        |
        v
   ADB over USB --> Physical Android Phone
        |
        v
   App under automation (TikTok, Instagram, etc.)

Every interaction flows through the Device class, which wraps adb shell commands into a clean Python API. The server orchestrates jobs, the dashboard provides a visual control center, and the skill system packages automation into reusable, shareable units.

Core Components

Section titled “Core Components”
ComponentWhat It Does
Device class47+ methods: tap, swipe, type, stealth mode, XML parsing, screenshots, notifications
Skill systemActions (atomic operations) + Workflows (sequences) + Elements (UI locators) packaged per app
Dashboard14-tab SPA: device management, skill browsing, scheduling, analytics, live streaming
SchedulerPer-phone job queue with priority preemption, 12 job types, 30-second tick
Skill CreatorSplit-screen LLM chat + live device stream for building skills visually
App ExplorerBFS discovery of app UI states, screenshots, and transition graphs
Macro RecorderRecord/replay action sequences with speed control

What’s Included

Section titled “What’s Included”

The TikTok skill ships fully implemented as a reference:

  • 13 actions: open app, navigate, search, like, comment, follow, scroll, send DM, and more
  • 9 workflows: upload video (43-step flow), crawl influencers, send outreach DMs, engage FYP, scan inbox, scrape analytics
  • 41 UI elements with fallback locator chains (content_desc, text, resource_id, coordinates)

Production stats: 10,695+ influencers crawled, 236+ DMs sent, verified on TikTok v44.3.3 across 2 physical devices.

Architecture at a Glance

Section titled “Architecture at a Glance”
adb-marketing-agent/
  run.py                    # Entry point -> http://localhost:5055
  marketing_system/         # All application code (54 Python files)
    server.py               # Flask API + scheduler (132 routes, ~4500 LoC)
    db.py                   # SQLite ORM (~2000 LoC, 20+ tables)
    bots/common/adb.py      # Device class (47+ methods)
    skills/                 # Skill packages (tiktok, base, instagram)
    agent/                  # LLM content planner
    static/dashboard.html   # Main SPA (14 tabs, ~400K)
  data/                     # Runtime data + SQLite DB
  tests/                    # Pytest suite (19 files)

Key Design Decisions

Section titled “Key Design Decisions”
  1. One job per phone — ADB can only automate one app at a time per device
  2. Subprocess execution — bots and skills run as subprocesses to keep the server responsive
  3. Pre/post conditions — every skill action validates device state before and after execution
  4. Draft-then-publish — videos upload as drafts first, then publish at scheduled time
  5. Element fallback chains — resilient to app updates (content_desc -> text -> RID -> coords)
  6. WAL-mode SQLite — concurrent reads from dashboard while scheduler writes
  7. Multi-backend LLM — OpenRouter, Claude, Ollama selectable per use case

Next Steps

Section titled “Next Steps”