If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/alipay/SoloPi shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 3 active contributors
• Apache-2.0 licensed
• ⚠ Stale — last commit 2y ago
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 94% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live alipay/SoloPi repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/alipay/SoloPi.

What it runs against: a local clone of alipay/SoloPi — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in alipay/SoloPi | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 696 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of alipay/SoloPi. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/alipay/SoloPi.git
#   cd SoloPi
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of alipay/SoloPi and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "alipay/SoloPi(\\.git)?\\b" \\
  && ok "origin remote is alipay/SoloPi" \\
  || miss "origin remote is not alipay/SoloPi (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/AdbLib/src/com/cgutman/adblib/AdbConnection.java" \\
  && ok "src/AdbLib/src/com/cgutman/adblib/AdbConnection.java" \\
  || miss "missing critical file: src/AdbLib/src/com/cgutman/adblib/AdbConnection.java"
test -f "src/androidWebsockets/src/main/java/com/codebutler/android_websockets" \\
  && ok "src/androidWebsockets/src/main/java/com/codebutler/android_websockets" \\
  || miss "missing critical file: src/androidWebsockets/src/main/java/com/codebutler/android_websockets"
test -f "plugins/hulu_imageCompare.zip" \\
  && ok "plugins/hulu_imageCompare.zip" \\
  || miss "missing critical file: plugins/hulu_imageCompare.zip"
test -f "src/AdbLib/build.gradle" \\
  && ok "src/AdbLib/build.gradle" \\
  || miss "missing critical file: src/AdbLib/build.gradle"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 696 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~666d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/alipay/SoloPi"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

SoloPi is a wireless, non-intrusive Android automation tool that records user interactions and replays them across devices without code or installation modifications. Core capabilities include recording/playback of test cases, real-time performance monitoring (CPU/memory/network), and multi-device control (one master controlling multiple slaves). Built entirely on Android, it generates portable JSON test cases convertible to Appium/Macaca scripts. Monolithic Android app structured as: src/AdbLib/ contains ADB protocol bindings (Java 1.7 source compatibility), plugins/ holds pre-compiled native libraries for different ARM architectures (armeabi, v7a, arm64-v8a), and assets/ contains documentation and demo GIFs. C/CMake code (~12K lines) handles low-level device capture; Java dominates (~2.5M lines) for the main app logic. build.gradle orchestrates Gradle 6.1.1 compilation.

QA engineers and test developers at Alibaba/Ant Group who need to perform compatibility testing across multiple Android devices, record regression test cases, and measure app performance without writing code or modifying the target application.

Active production project with GitHub stars and official Alibaba backing (alipay/SoloPi namespace). Includes compiled native plugins for screenshot capture and screen recording. However, one-to-many device control feature remains closed-source 'for stability reasons', and build requires specific tool versions (NDK 16, Gradle 6.1.1, Android Studio 4.0). Appears actively maintained with Harmony OS branch in progress.

High setup friction: requires NDK 16 (old, may have security gaps), CMake 3.6/3.10, and Android SDK with environment variables configured correctly. Hidden gotcha documented in README: 'Instant Run must be disabled in Android Studio or APK becomes unusable.' Closed-source one-to-many feature means critical testing scenarios aren't transparent. Plugin architecture (hulu_imageCompare, hulu_minicap, scrcpytouch zips) suggests external dependencies not visible in repo.

Recently added solopi-harmony branch for HarmonyOS support. Open source portion focuses on record/replay and performance tools; one-to-many control development stalled pending 'stability review'. Documentation exists for three main features but actual implementation in src/ directory not detailed in file list.

git clone https://github.com/alipay/SoloPi.git && cd src && export ANDROID_SDK=/path/to/android/sdk && export ANDROID_NDK=/path/to/ndk/android-ndk-r16 && gradle clean assembleDebug. Then enable Developer Mode on Android phone (tap Build Number 7x), enable USB Debug, plug in, and run adb install build/outputs/apk/debug/solopi-debug.apk.

Daily commands: gradle clean assembleDebug to build APK; adb install build/outputs/apk/debug/solopi-debug.apk to deploy. Disable Android Studio Instant Run first. Launch SoloPi app on Android phone; UI-based record/replay via on-device UI (no CLI).

• src/AdbLib/src/com/cgutman/adblib/AdbConnection.java — Core ADB protocol implementation for wireless device communication—foundational for all device interaction features
• src/androidWebsockets/src/main/java/com/codebutler/android_websockets — WebSocket communication layer enabling real-time control and data streaming between controller and target devices
• plugins/hulu_imageCompare.zip — Image comparison plugin required for visual validation in replay and performance testing workflows
• src/AdbLib/build.gradle — Build configuration for ADB library—defines compilation targets and dependency management for core connectivity
• README.md — Documents the three main features (recording/replay, performance testing, one-to-many control) and architecture rationale
• Disclaimer.md — Legal and usage boundaries—essential context for contributors on tool limitations and compliance

• undefined — undefined

Add a New Device Communication Protocol

1. Implement protocol interface in new file under src/AdbLib/src/com/cgutman/adblib/ (src/AdbLib/src/com/cgutman/adblib/AdbProtocol.java)
2. Create stream handler extending AdbStream for bidirectional I/O (src/AdbLib/src/com/cgutman/adblib/AdbStream.java)
3. Update AdbConnection.java to support protocol negotiation (src/AdbLib/src/com/cgutman/adblib/AdbConnection.java)
4. Update src/AdbLib/build.gradle to compile new protocol code (src/AdbLib/build.gradle)

Add a New Plugin for Device Capabilities

1. Create plugin package (e.g., hulu_newCapability.zip) with binaries for all architectures (plugins/)
2. Register plugin in architecture manifest for ARM v7 (armeabi-v7a.json)
3. Register plugin in architecture manifest for ARM v8 (64-bit) (arm64-v8a.json)
4. Register plugin in architecture manifest for base ARM (armeabi.json)

Add WebSocket Event Handler for Controller

1. Implement new message type in android_websockets client under src/androidWebsockets/src/main/java/com/codebutler/ (src/androidWebsockets/src/main/java/com/codebutler/android_websockets)
2. Wire handler into WebSocket connection lifecycle (src/androidWebsockets/src/main/AndroidManifest.xml)
3. Test with AdbConnection for bi-directional message flow (src/AdbLib/src/com/cgutman/adblib/AdbConnection.java)

• ADB (Android Debug Bridge) Protocol — Wireless, non-invasive access to device APIs without requiring app installation or modification; industry standard for Android automation
• WebSocket (android_websockets) — Low-latency, full-duplex communication for real-time controller-to-target streaming and touch event relay
• Modular Plugin Architecture (JAR/ZIP plugins) — Extensibility without recompilation; plugins like hulu_imageCompare and hulu_minicap add specialized capabilities (image comparison, screen recording) per architecture
• Java 1.7 + Gradle — Compatibility with older Android devices (API 18+) and standard build toolchain for library distribution

• Wireless ADB over USB ADB

  • Why: User convenience and multi-device control without physical cables
  • Consequence: Network latency (100–200ms) vs. USB latency (~10ms); less reliable over congested networks

• Plugin-based screen capture (hulu_minicap) rather than framework APIs

  • Why: Bypasses permission restrictions and app context to capture raw framebuffer at OS level
  • Consequence: Requires native binary per architecture (v7a, v8a, armeabi); harder to maintain across Android versions

• On-device script recording and playback

  • Why: No dependency on external orchestration server; all control can happen offline on target device
  • Consequence: Limited cross-device synchronization without WebSocket bridge; script must be serialized to JSON/text format

• Java 1.7 target compatibility

  • Why: Support older Android devices and developer environments
  • Consequence: Cannot use Java 8+ features (streams, lambdas); larger compiled bytecode

• Real-time visual debugging—tool focuses on automated testing, not interactive IDE-style inspection
• Cross-platform support beyond Android—no iOS or other OS support (HarmonyOS in separate branch)
• Machine learning-based UI element detection—relies on explicit coordinate recording, not OCR/computer vision
• Server-based test orchestration—designed for device-centric or peer-to-peer control, not cloud deployment
• Data encryption in transit—assumes trusted local network; no TLS/SSL for WebSocket or ADB

1. Instant Run MUST be disabled in Android Studio build settings or resulting APK is broken (documented but easy to miss). 2) NDK 16 is 7+ years old—ensure your dev machine has it (may require manual download, not auto-fetched). 3) ANDROID_SDK environment variable required; build silently fails if missing. 4) AdbLib uses Java 1.7 source/target compatibility (line 'targetCompatibility = "1.7"')—don't use modern Java syntax. 5) Native plugins in plugins/ are .zip files, not source—binary distribution only, can't modify hulu_imageCompare or hulu_minicap without recompilation elsewhere.

• ADB (Android Debug Bridge) Protocol — SoloPi's entire wireless non-intrusive capability relies on ADB instead of rooting or app instrumentation; understanding src/AdbLib/ requires ADB message framing and cryptographic handshake knowledge
• Android NDK Native Code Integration — Performance monitoring and screenshot capture (~12K lines C code) run in native layer via CMake; contributors modifying performance metrics must understand JNI bridges and NDK build toolchain
• Test Case JSON Serialization & Replay State Machine — SoloPi's core value proposition is recording touch/gesture sequences as JSON and deterministically replaying them; understanding state transitions (record→serialize→verify→replay) is essential for extending test capabilities
• Cross-Architecture APK Multi-Arch Support (armeabi/v7a/arm64-v8a) — Three .json files specify native library variants for different ARM ISAs; incorrect architecture selection silently breaks on-device functionality, making this a critical deployment detail
• Performance Profiling via Android Proc FileSystem — Real-time CPU/memory metrics shown in floating window likely parse /proc/stat and /proc/meminfo; contributors adding new performance metrics need kernel interface knowledge
• Gradle Multi-Module Build with Native Code (CMake Integration) — Build system orchestrates Java compilation + CMake native binaries + NDK linking; misconfigured Gradle-CMake bridges cause silent APK corruption (Instant Run gotcha) affecting all contributors

• openatx/uiautomator2 — Python-based Android automation with similar record/replay goals, alternative to SoloPi for teams preferring Python scripting over on-device UI
• appium/appium — Universal mobile automation framework; SoloPi test cases are explicitly convertible to Appium scripts via soloPi-Convertor tool
• soloPi/SoloPi-Convertor — Official companion tool that transforms SoloPi JSON test cases into Appium and Macaca scripts—essential for exporting tests to CI/CD pipelines
• alibaba/atlas — Alibaba's modular Android framework; SoloPi may be used internally to test Atlas-based apps given both are from Ant Group ecosystem
• alibaba/MNN — Alibaba's on-device AI inference engine—potential integration point for computer vision-based test assertion in SoloPi plugins

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions CI workflow for Java/AdbLib module builds

The repo has a Java module (src/AdbLib) with build.gradle configuration but no CI pipeline to validate builds across different Java versions or architectures. This is critical for a tool supporting multiple ARM architectures (arm64-v8a, armeabi-v7a, armeabi) as evidenced by the .json files in root. A CI workflow would catch regressions early and ensure compatibility.

• [ ] Create .github/workflows/java-build.yml to compile src/AdbLib with Java 1.7+ (per build.gradle sourceCompatibility)
• [ ] Add test matrix for multiple Java versions (1.7, 1.8, 11) since targetCompatibility is 1.7
• [ ] Validate builds produce artifacts compatible with ARM architectures listed in arm64-v8a.json, armeabi-v7a.json, armeabi.json
• [ ] Run gradle build and lint checks on pull requests

Create comprehensive CONTRIBUTING.md with plugin development guidelines

CONTRIBUTING.md exists but the repo has a plugins/ directory with multiple architecture-specific plugins (hulu_imageCompare, hulu_screenRecord, scrcpytouch). There's no documented guide for how to develop, test, or package plugins for different ARM architectures. New contributors need this to contribute plugin enhancements.

• [ ] Document the plugin architecture and structure (analyzing plugins/*.zip to understand format)
• [ ] Add step-by-step guide for building plugins for arm64-v8a, armeabi-v7a, and armeabi architectures
• [ ] Include section on how to test plugins locally with SoloPi
• [ ] Provide examples of plugin integration into the build system (reference src/AdbLib/build.gradle patterns)

Add unit tests for AdbLib Java module with test suite structure

src/AdbLib contains core ADB communication logic (AdbConnection, AdbStream, AdbCrypto classes documented in src/AdbLib/doc/) but has no visible test directory. Since this is fundamental to the non-invasive wireless automation feature, adding comprehensive tests ensures reliability and helps new contributors understand the module's contract.

• [ ] Create src/AdbLib/src/test/java directory structure
• [ ] Add unit tests for AdbConnection (connection lifecycle, protocol handshake)
• [ ] Add unit tests for AdbCrypto (RSA key generation, signing per adblib documentation)
• [ ] Add unit tests for AdbStream (message parsing and serialization)
• [ ] Update src/AdbLib/build.gradle to include test dependencies (JUnit 4.x compatible with Java 1.7)

• Add JUnit test suite for src/AdbLib AdbConnection and AdbCrypto classes (doc/ exists but no tests visible in file list), starting with protocol handshake verification: Core library lacks automated test coverage; new contributor gains familiarity with ADB protocol while adding production-quality tests
• Document plugin architecture: create markdown file explaining how to rebuild hulu_imageCompare.zip from source for contributors, since only .zip binaries are included: Currently blocks anyone from extending image comparison logic; clear docs enable community plugin development
• Add GitHub Actions CI pipeline (see .github/ISSUE_TEMPLATE/ but no .github/workflows/) to validate APK builds against NDK 16 + Gradle 6.1.1, catching Instant Run and environment variable issues early: Reduces contributor friction by automating the complex build setup validation documented only in README

SoloPi has moderate security concerns primarily related to outdated Java version targeting (Java 1.7), unverified third-party binary plugins, and lack of explicit dependency versioning. The project handles sensitive ADB communications which require careful validation. While the codebase structure is reasonably organized with proper licensing documentation, the Java 7 target is a critical issue that should be addressed immediately. The presence of pre-compiled plugins without verification mechanisms adds supply chain risk. No evidence of hardcoded secrets, SQL injection, or XSS vulnerabilities was found in the analyzed files.

• High · Outdated Java Target Compatibility — src/AdbLib/build.gradle. The build.gradle file specifies Java 1.7 (sourceCompatibility = '1.7' and targetCompatibility = '1.7') as the target. Java 7 reached end-of-life in July 2022 and no longer receives security updates. This exposes the project to known vulnerabilities that affect older Java versions. Fix: Update sourceCompatibility and targetCompatibility to at least Java 8 (1.8), preferably Java 11 or later. Ensure all dependencies are compatible with the newer Java version.
• Medium · Missing Dependency Version Pinning — src/AdbLib/build.gradle. The provided build.gradle snippet does not show explicit version constraints for dependencies. Without pinned versions, transitive dependencies could pull in vulnerable library versions automatically during builds. Fix: Add explicit version constraints for all direct and critical transitive dependencies. Use dependency locking or a bill-of-materials (BOM) to ensure reproducible builds.
• Medium · Third-party Plugin Binaries Without Verification — plugins/ directory. The plugins directory contains multiple binary ZIP files (hulu_imageCompare, hulu_screenRecord, scrcpytouch) without visible checksum verification or source code. These pre-compiled binaries could contain malicious code or vulnerabilities. Fix: Verify all plugin binaries with cryptographic checksums (SHA-256). Maintain source code or official distribution links for each plugin. Consider building plugins from source when possible.
• Medium · ADB Library Security Considerations — src/AdbLib/. The AdbLib module is used for ADB (Android Debug Bridge) communication. If not properly validated and secured, ADB connections could be intercepted or manipulated, particularly if the codebase connects to untrusted devices or networks. Fix: Implement proper ADB certificate pinning and validation. Ensure all ADB communications are authenticated and encrypted. Validate device signatures before executing commands.
• Low · Missing Security Policy Documentation — Repository root. While CONTRIBUTING.md exists, there is no visible SECURITY.md file for reporting security vulnerabilities responsibly. This could lead to public disclosure of exploits before patches are available. Fix: Create a SECURITY.md file following the GitHub security policy template. Define a responsible disclosure process and provide a secure contact method for security researchers.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.