Project Overview

Mission

Clawperator is a deterministic actuator tool for LLM-driven Android automation. It provides a stable execution layer that allows agents to perform actions on a dedicated Android device on behalf of a user.

Clawperator can operate either a physical Android device or a local Android emulator.

The emulator option is intended primarily for development and testing. Some applications may detect or block emulator environments.

In both environments, the user owns app installation, sign-in, and app configuration. Clawperator only operates the device UI.

This approach ensures that the user's primary phone (e.g., an iPhone) remains undisturbed while the actuator device handles automation tasks. Physical device setups have virtually no hardware requirements - any cheap or old Android device works.

Core Philosophy: The Brain and the Hand

Clawperator is designed as the execution "hand" for an LLM "brain":

  1. The Agent (The Brain): An external LLM (e.g., OpenClaw) that owns reasoning, planning, and decision-making. It supervises the automation and decides which actions to take based on the user's intent.
  2. Clawperator (The Hand): A deterministic actuator tool. It provides the reliable "fingers" to observe UI state (snapshot_ui), perform precise interactions (taps, scrolls), and report structured results back to the brain.

Clawperator is intentionally not intelligent. It does not perform autonomous multi-step reasoning or agentic planning. It follows instructions and provides high-fidelity feedback so the Agent can drive the process.

Architecture

The system consists of two primary layers:

  • Android Runtime (apps/android): An Android application that leverages Accessibility APIs to inspect the UI tree and perform actions (taps, scrolls, text entry, and system hard-keys like back/home). It listens for commands via a broadcast receiver.
  • Node Runtime/CLI (apps/node): The primary interface for agents. It wraps adb interactions, validates execution payloads, dispatches commands to the Android device, parses canonical result envelopes from logs, and owns the full Android emulator lifecycle (discovery, provisioning, creation, and teardown).

Website Surfaces

This repository also contains two separate public website builds:

  • Landing site (sites/landing): The static Next.js site for https://clawperator.com. This is the marketing homepage and install/download entrypoint.
  • Docs site (sites/docs): The MkDocs site for https://docs.clawperator.com. This is the technical documentation surface.

Keep them distinct when editing:

  • Landing-site root files such as install.sh, robots.txt, llms.txt, and sitemap.xml belong to sites/landing/public/.
  • Docs content should be changed in docs/, apps/node/src/, or ../clawperator-skills/docs/, not directly in sites/docs/docs/.
  • Docs-site root files such as robots.txt and llms.txt live in sites/docs/static/ and are copied into the built site by ./scripts/docs_build.sh.
  • Both public sites deploy automatically to Cloudflare after changes are merged to main.

The Role of Skills

Skills are reusable templates for app-specific workflows (e.g., "get thermostat temperature" or "check grocery prices").

  • Canonical Home: ../clawperator-skills (a dedicated sibling repository).
  • Project-local maintenance skills: Repository-specific Codex workflows live in .agents/skills/. For example, .agents/skills/docs-generate/ regenerates the MkDocs site content in sites/docs/docs/ from the canonical doc sources.
  • Nature of Skills: Due to the dynamic nature of mobile apps (A/B tests, server-side flags, unexpected popups), skills are treated as highly informed context for the Agent rather than purely deterministic scripts.
  • Agent Responsibility: The Agent uses skill templates as a baseline, modifying them at runtime to handle personal configurations (variable substitution) or UI drift.

Package Identifiers

  • com.clawperator.operator: The production/release package name.
  • com.clawperator.operator.dev: The local development package name (used when building from source).

Safety & Privacy

  • Full-fidelity results: By default, result envelopes contain exactly what is on screen, including sensitive text. Agents should not forward raw results to long-term storage without user consent.
  • Control: The "Two-Handed" model ensures that agents can only execute within the safety bounds defined by the Clawperator runtime.
  • Observability: Agents use snapshot_ui (hierarchy_xml) and screenshots to "see" the device state.