The Problem

Manual phone tasks (sending a message, logging a call, updating a calendar) require a device in hand and repetitive UI navigation. Scaling such chores across many devices or integrating them into larger workflows is painful because Android’s UI is not script‑friendly and existing automation tools lack natural‑language reasoning.

What This Does

droidclaw turns an Android phone into an AI‑driven agent. A user supplies a plain‑English goal; the agent reads the accessibility tree, asks an LLM what UI actions are needed, and executes them via ADB (src/actions.ts). The core loop lives in src/kernel.ts, which orchestrates reading the screen, sanitising LLM output (src/sanitizer.ts), and stepping through a flow (src/flow.ts). Example workflows are stored as JSON/YAML under examples/workflows/ and examples/flows/, ready to be invoked without code changes.

How It Is Wired

  1. Entry point – bun run src/kernel.ts launches the CLI.
  2. Kernel (src/kernel.ts) reads the goal, loads configuration (src/config.ts), creates a Flow object, and repeatedly calls flow.next() until the flow reports done.
  3. Flow (src/flow.ts) decides the next action by: calling sanitize() (in src/sanitizer.ts) to clean LLM output, consulting the LLM provider (src/llm‑providers.ts) for a plan, * delegating concrete UI commands to actions.ts. Flow has the highest instability (1.0) and contains 56 branch points over 191 lines, so it is a hotspot for future refactoring.
  4. Actions (src/actions.ts) translate high‑level intents (launch, tap, type, enter, done) into ADB commands executed via Bun.spawnSync.
  5. Skills (src/skills.ts) expose reusable primitives (e.g., openApp, search) that the LLM can invoke; they are imported by the kernel and flow.
  6. Constants & Config (src/constants.ts, src/config.ts) supply static values and environment‑driven settings (LLM_PROVIDER, GROQ_API_KEY, OLLAMA_MODEL).
  7. Logger (src/logger.ts) provides console output for each step.
  8. Workflow loader (src/workflow.ts) parses the JSON/YAML files in examples/ and feeds them to the kernel when the --workflow flag is used.

The import graph shows 11 internal modules with 23 edges and no circular dependencies. src/actions.ts is the most imported (Ca = 6) and thus has the widest blast radius; changes there affect every flow step.

How To Use It

# clone the original repository
git clone https://github.com/moses-y/droidclaw.git
cd droidclaw

# install Bun (required) and project deps
curl -fsSL https://bun.sh/install | bash
bun install

# copy example env and set your LLM credentials
cp .env.example .env
# edit .env: set LLM_PROVIDER=groq and GROQ_API_KEY=your_key
# or use ollama: LLM_PROVIDER=ollama, OLLAMA_MODEL=llama3.2

# connect a phone with USB debugging enabled
adb devices   # should list the device

# run a single goal
bun run src/kernel.ts
# > enter your goal: open youtube and search for "lofi hip hop"

# or execute a stored workflow
bun run src/kernel.ts --workflow examples/workflows/messaging/whatsapp-reply.json

No Dockerfile or Makefile is present; the only build artifact is the TypeScript compilation performed by Bun at runtime.

Real‑World Use

A support team could automate ticket triage on a shared device: a Slack bot posts a ticket description, the team runs bun run src/kernel.ts --workflow examples/workflows/productivity/github-check-prs.json, and the agent opens the GitHub app, searches the PR, copies the status, and replies in Slack—all without manual UI steps.

Code Health & Issues

  • HIGH – No LICENSE – repository root lacks any licence file; reuse is legally ambiguous.
  • HIGH – No test suite – 11 source files, only one ad‑hoc test (test-ollama.ts) and no structured tests.
  • HIGH – No lockfile – package.json present without bun.lockb; builds are non‑reproducible.
  • HIGH – No CI pipeline – no .github/workflows/ or other CI config; changes are not automatically built or tested.
  • MEDIUM – Dependabot missing – no dependabot.yml; security updates rely on manual checks.
  • MEDIUM – Cognitive load – src/sanitizer.ts and src/flow.ts contain dense branching (56 branches in 191 lines); refactoring into strategy tables would improve maintainability.

The Bottom Line

droidclaw delivers a functional prototype for AI‑guided Android automation, with clear entry points and extensible workflow files. However, the codebase lacks basic production safeguards (license, tests, CI, lockfile) and contains complex branching that will hinder scaling. It is suitable for experimentation or internal tooling, but any external deployment should first address the health issues and add a solid test suite.