Agent skill

adb-karrot

Karrot app automation with AI Vision - bypass Play Integrity and LIAPP detection, login, and interaction workflows with Claude Vision API integration

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/adb-karrot

SKILL.md

Quick Reference (30 seconds)

Karrot App Automation & Play Integrity + LIAPP Bypass

Package: com.towneers.www LIAPP Class: com.lockincomp.wfcwxdz

What It Does: Automates Karrot app interactions. Enables Play Integrity API and LIAPP security SDK bypass via Magisk hooks to allow app usage on unsupported environments.

Core Capabilities:

  • App Launching: Open Karrot with auto-detection
  • Detection Checking: Verify if app detects emulator (Play Integrity + LIAPP)
  • Login Automation: Automated login with detection-aware taps
  • Bypass Validation: Confirm Play Integrity and LIAPP bypass success
  • Safe Tap: Random delay (500-2000ms) and coordinate variance (+/-10px)
  • LIAPP Monitor: Real-time monitoring for security events
  • AI Vision: Claude Vision API for semantic element detection (~$0.005/request)
  • Smart Detection: Multi-layer fallback (UIAutomator → Template → OCR → AI)
  • Auto-Recovery: Package verification and misclick recovery

When to Use:

  • Testing Karrot app on emulator
  • Implementing Play Integrity + LIAPP bypass
  • Automating login and basic navigation
  • Validating bypass effectiveness
  • Multi-device automation

Documentation: .moai/docs/guides/liapp-bypass/

Scripts

adb-karrot-launch.py

Launch Karrot application.

bash
# Launch on default device
uv run .claude/skills/adb-karrot/scripts/adb-karrot-launch.py

# Specify device
uv run .claude/skills/adb-karrot/scripts/adb-karrot-launch.py --device 127.0.0.1:5555

# Wait for login screen
uv run .claude/skills/adb-karrot/scripts/adb-karrot-launch.py \
    --wait-text "Login" \
    --timeout 10

# JSON output
uv run .claude/skills/adb-karrot/scripts/adb-karrot-launch.py --json

adb-karrot-check-detection.py

Check if Karrot detects emulator or spoofed environment.

bash
# Quick detection check
uv run .claude/skills/adb-karrot/scripts/adb-karrot-check-detection.py \
    --device 127.0.0.1:5555

# Detailed check (launch and monitor)
uv run .claude/skills/adb-karrot/scripts/adb-karrot-check-detection.py \
    --device 127.0.0.1:5555 \
    --launch \
    --detailed

# Check for error-18 (PlayIntegrity CLIENT_TRANSIENT_ERROR)
uv run .claude/skills/adb-karrot/scripts/adb-karrot-check-detection.py \
    --device 127.0.0.1:5555 \
    --check-logcat

# JSON output
uv run .claude/skills/adb-karrot/scripts/adb-karrot-check-detection.py --json

adb-karrot-test-login.py

Test login functionality with bypass enabled.

bash
# Basic login test
uv run .claude/skills/adb-karrot/scripts/adb-karrot-test-login.py \
    --device 127.0.0.1:5555 \
    --email test@example.com \
    --password testpass123

# Login with verification
uv run .claude/skills/adb-karrot/scripts/adb-karrot-test-login.py \
    --device 127.0.0.1:5555 \
    --email test@example.com \
    --password testpass123 \
    --verify-success \
    --timeout 30

# Test bypass effectiveness (should NOT get error-18)
uv run .claude/skills/adb-karrot/scripts/adb-karrot-test-login.py \
    --device 127.0.0.1:5555 \
    --email test@example.com \
    --password testpass123 \
    --check-bypass

# JSON output
uv run .claude/skills/adb-karrot/scripts/adb-karrot-test-login.py --json

adb-karrot-safe-tap.py

Detection-aware tap with random delay and coordinate variance to avoid detection patterns.

bash
# Basic safe tap (uses defaults: 500-2000ms delay, +/-10px variance)
uv run .claude/skills/adb-karrot/scripts/adb-karrot-safe-tap.py \
    --device 127.0.0.1:5555 \
    --x 720 --y 2374

# Custom delay range
uv run .claude/skills/adb-karrot/scripts/adb-karrot-safe-tap.py \
    --device 127.0.0.1:5555 \
    --x 720 --y 2374 \
    --delay-min 1000 --delay-max 3000

# Custom coordinate variance
uv run .claude/skills/adb-karrot/scripts/adb-karrot-safe-tap.py \
    --device 127.0.0.1:5555 \
    --x 720 --y 2374 \
    --variance 20

# Tap welcome screen "Get Started" button (1440x2560 resolution)
uv run .claude/skills/adb-karrot/scripts/adb-karrot-safe-tap.py \
    --device 127.0.0.1:5555 \
    --x 720 --y 2374

# Tap "Log In" link
uv run .claude/skills/adb-karrot/scripts/adb-karrot-safe-tap.py \
    --device 127.0.0.1:5555 \
    --x 872 --y 2493

adb-karrot-liapp-monitor.py

Monitor logcat for LIAPP security events and detection triggers.

bash
# Default monitoring (60 seconds, standard keywords)
uv run .claude/skills/adb-karrot/scripts/adb-karrot-liapp-monitor.py \
    --device 127.0.0.1:5555

# Extended monitoring with custom duration
uv run .claude/skills/adb-karrot/scripts/adb-karrot-liapp-monitor.py \
    --device 127.0.0.1:5555 \
    --duration 300

# Custom keywords
uv run .claude/skills/adb-karrot/scripts/adb-karrot-liapp-monitor.py \
    --device 127.0.0.1:5555 \
    --keywords "LIAPP,security,com.lockincomp.wfcwxdz"

# JSON output for parsing
uv run .claude/skills/adb-karrot/scripts/adb-karrot-liapp-monitor.py \
    --device 127.0.0.1:5555 \
    --json

adb-karrot-multi-device.py

Run Karrot automation across multiple connected devices.

bash
# Auto-detect all connected devices
uv run .claude/skills/adb-karrot/scripts/adb-karrot-multi-device.py

# Specify devices
uv run .claude/skills/adb-karrot/scripts/adb-karrot-multi-device.py \
    --devices "127.0.0.1:5555,127.0.0.1:5556,127.0.0.1:5557"

# Run login test on all devices
uv run .claude/skills/adb-karrot/scripts/adb-karrot-multi-device.py \
    --action login-test \
    --parallel

# Sequential execution (safer)
uv run .claude/skills/adb-karrot/scripts/adb-karrot-multi-device.py \
    --action detection-check \
    --sequential

karrot_ai_vision.py

AI-powered screen understanding using Claude Vision API.

bash
# Analyze current screen (full AI interpretation)
uv run .claude/skills/adb/adb-game-karrot/adb-karrot/scripts/karrot_ai_vision.py \
    --action analyze_screen \
    --device 127.0.0.1:5555

# Find element by semantic description
uv run .claude/skills/adb/adb-game-karrot/adb-karrot/scripts/karrot_ai_vision.py \
    --action find_element \
    --query "Get Started button" \
    --device 127.0.0.1:5555

# Detect current game state
uv run .claude/skills/adb/adb-game-karrot/adb-karrot/scripts/karrot_ai_vision.py \
    --action get_game_state \
    --device 127.0.0.1:5555

# Check for errors or popups
uv run .claude/skills/adb/adb-game-karrot/adb-karrot/scripts/karrot_ai_vision.py \
    --action detect_error \
    --device 127.0.0.1:5555

# Example output (find_element):
# {
#   "found": true,
#   "element": "Get Started button",
#   "location": {"x": 720, "y": 2350},
#   "confidence": "high",
#   "description": "Large blue button at bottom center"
# }

Cost: ~$0.005 per request (0.5 cents) Response Time: 2-5 seconds Best For: Dynamic UIs, complex layouts, fallback detection

karrot_smart_detector.py

Adaptive detection with multi-layer fallback strategy.

bash
# Auto-detect element (tries all methods in order)
uv run .claude/skills/adb/adb-game-karrot/adb-karrot/scripts/karrot_smart_detector.py \
    --action find_element \
    --target "Get Started" \
    --method auto \
    --device 127.0.0.1:5555

# Wait for element with exponential backoff
uv run .claude/skills/adb/adb-game-karrot/adb-karrot/scripts/karrot_smart_detector.py \
    --action wait_for \
    --target "Login" \
    --timeout 30 \
    --device 127.0.0.1:5555

# Detect game state using state machine
uv run .claude/skills/adb/adb-game-karrot/adb-karrot/scripts/karrot_smart_detector.py \
    --action detect_state \
    --device 127.0.0.1:5555

# Force specific detection method
uv run .claude/skills/adb/adb-game-karrot/adb-karrot/scripts/karrot_smart_detector.py \
    --action find_element \
    --target "Get Started" \
    --method ai \
    --device 127.0.0.1:5555

# Example output (wait_for):
# {
#   "found": true,
#   "method": "uiautomator",
#   "attempts": 2,
#   "time_elapsed": 1.3,
#   "coordinates": {"x": 720, "y": 2350}
# }

Detection Order: UIAutomator → Template Matching → OCR → AI Vision Backoff Strategy: 0.5s → 0.75s → 1.125s → 1.6875s (exponential) Loop Prevention: Max 10 attempts, 30s timeout

karrot_unified_automation.py

High-level automation integrating AI vision with traditional methods.

bash
# Tap element by semantic description
uv run .claude/skills/adb/adb-game-karrot/adb-karrot/scripts/karrot_unified_automation.py \
    --action tap_element \
    --target "Get Started button" \
    --device 127.0.0.1:5555

# Navigate to specific screen
uv run .claude/skills/adb/adb-game-karrot/adb-karrot/scripts/karrot_unified_automation.py \
    --action navigate_to \
    --target "login_screen" \
    --device 127.0.0.1:5555

# Execute workflow with AI fallback
uv run .claude/skills/adb/adb-game-karrot/adb-karrot/scripts/karrot_unified_automation.py \
    --action execute_workflow \
    --workflow .claude/skills/adb/adb-game-karrot/adb-karrot/workflow/karrot-login-v3.toon \
    --device 127.0.0.1:5555

# Handle errors with auto-recovery
uv run .claude/skills/adb/adb-game-karrot/adb-karrot/scripts/karrot_unified_automation.py \
    --action handle_error \
    --target "play_store_popup" \
    --device 127.0.0.1:5555

# Example output (tap_element):
# {
#   "success": true,
#   "method": "ai_vision",
#   "tap_coordinates": {"x": 720, "y": 2350},
#   "verification": "package_correct",
#   "time_elapsed": 3.2
# }

Features:

  • Semantic element detection ("Tap the blue button")
  • Auto-navigation with state tracking
  • Workflow orchestration with AI fallback
  • Error recovery with smart retry

AI Vision Integration

Overview

The Karrot skill integrates Claude Vision API for robust screen understanding when traditional methods fail.

Why AI Vision?

  • Dynamic UIs that change layout
  • Complex screens with overlays
  • Fallback when UIAutomator/OCR fails
  • Semantic element detection ("Find login button")

Cost Optimization:

  • AI used only as fallback (Layer 4)
  • ~$0.005 per request (0.5 cents)
  • Traditional methods tried first
  • Caching for repeated queries

Architecture

Detection Stack (4 Layers):

Layer 1: UIAutomator (Fast, Free)
   ├─ XML hierarchy parsing
   ├─ Resource ID matching
   └─ 0.1-0.3s response time

Layer 2: Template Matching (Fast, Free)
   ├─ OpenCV template matching
   ├─ Pre-saved UI templates
   └─ 0.2-0.5s response time

Layer 3: OCR (Medium, Free)
   ├─ Tesseract text recognition
   ├─ Text-based element detection
   └─ 0.5-1.5s response time

Layer 4: AI Vision (Slow, Paid)
   ├─ Claude Vision API
   ├─ Full semantic understanding
   └─ 2-5s response time, $0.005/request

Detection Methods Comparison

Method Speed Cost Accuracy Use Case
UIAutomator 0.1-0.3s Free 95% Static elements with resource IDs
Template 0.2-0.5s Free 85% Known UI patterns
OCR 0.5-1.5s Free 75% Text-based elements
AI Vision 2-5s $0.005 99% Dynamic/complex UIs, fallback

Smart Detection Flow

python
# Example: Find "Get Started" button

Step 1: UIAutomator
  try_find("com.towneers.www:id/btn_get_started")
  → FOUND: Return coordinates immediately
  → NOT FOUND: Continue to Layer 2

Step 2: Template Matching
  match_template("get_started_button.png")
  → FOUND: Return coordinates (0.5s)
  → NOT FOUND: Continue to Layer 3

Step 3: OCR
  find_text("Get Started")
  → FOUND: Return text location (1.2s)
  → NOT FOUND: Continue to Layer 4

Step 4: AI Vision (Fallback)
  ai_find_element("Get Started button")
  → FOUND: Return coordinates with confidence (3.5s)
  → NOT FOUND: Report failure

Total attempts: 4 layers
Max time: 5.5s
Success rate: 99%+

Loop Prevention

Problem: Detection loops can waste time and money (AI calls)

Solution: Smart timeout and attempt limits

python
# Exponential Backoff Strategy
attempts = [0.5, 0.75, 1.125, 1.6875, 2.53, 3.79, 5.69, 8.53, 12.8]
max_attempts = 10
total_timeout = 30s

# Loop Prevention Rules
1. Max 10 detection attempts across all layers
2. 30s hard timeout regardless of attempts
3. Exponential backoff between retries
4. Skip AI layer after 3 consecutive failures (cost protection)
5. Cache AI results for 60s to prevent duplicate calls

AI Vision Use Cases

When to Use AI Vision:

  • Element has no resource ID
  • UI layout changes dynamically
  • OCR fails (non-standard fonts)
  • Need semantic understanding
  • Fallback after traditional methods fail

When NOT to Use AI Vision:

  • Element has stable resource ID
  • Template matching works reliably
  • Text is OCR-friendly
  • Cost is a constraint
  • Real-time detection required (<0.5s)

Usage Examples

Example 1: Traditional Detection (Fast, Free)

bash
# Use UIAutomator for known resource IDs
uv run .claude/skills/adb/adb-game-karrot/adb-karrot/scripts/karrot_smart_detector.py \
    --action find_element \
    --target "com.towneers.www:id/btn_login" \
    --method uiautomator \
    --device 127.0.0.1:5555

# Result: 0.2s, Free, 95% accuracy

Example 2: AI Vision Fallback (Slow, Paid)

bash
# Use AI when traditional methods fail
uv run .claude/skills/adb/adb-game-karrot/adb-karrot/scripts/karrot_smart_detector.py \
    --action find_element \
    --target "Get Started" \
    --method auto \
    --device 127.0.0.1:5555

# Auto tries: UIAutomator → Template → OCR → AI
# Result: 3.5s, $0.005, 99% accuracy

Example 3: Semantic Element Detection

bash
# Find element by description (AI-only)
uv run .claude/skills/adb/adb-game-karrot/adb-karrot/scripts/karrot_ai_vision.py \
    --action find_element \
    --query "The blue button at the bottom that says 'Get Started'" \
    --device 127.0.0.1:5555

# Result: 2.8s, $0.005, returns coordinates + confidence

Example 4: Error Detection with AI

bash
# Detect any error popup or overlay
uv run .claude/skills/adb/adb-game-karrot/adb-karrot/scripts/karrot_ai_vision.py \
    --action detect_error \
    --device 127.0.0.1:5555

# Result:
# {
#   "error_detected": true,
#   "error_type": "play_store_overlay",
#   "suggested_action": "press_back_twice",
#   "confidence": "high"
# }

Example 5: Workflow with AI Fallback

bash
# Run workflow with automatic AI fallback
uv run .claude/skills/adb/adb-game-karrot/adb-karrot/scripts/karrot_unified_automation.py \
    --action execute_workflow \
    --workflow .claude/skills/adb/adb-game-karrot/adb-karrot/workflow/karrot-login-v3.toon \
    --device 127.0.0.1:5555

# Workflow uses smart_detector for each step
# Falls back to AI only when needed
# Total cost: ~$0.01-0.02 per full workflow

UI Coordinates (1440x2560 Resolution)

Screen Element X Y Safe Description
Welcome Get Started 720 2350 Yes Main action button (SAFE: upper part of button)
Welcome Log In 872 2493 No Log In link (WARNING: may be in ad zone)
Neighborhood Find Nearby 720 216 Yes Find nearby neighborhoods button
Verification Verify Now 720 2484 Yes Verify now button (30 sec)
Login Phone Input 720 400 Yes Phone number field
Login Confirm 720 2400 Yes Confirm/Continue button
Navigation Back 64 104 Yes Back navigation

Important: The "Get Started" button coordinate was changed from y=2374 to y=2350 to avoid the BlueStacks ad banner zone (y > 2187).

Banned Zones (BlueStacks Air 1440x2560)

NEVER tap in these zones - they will open Play Store or BlueStacks launcher:

Zone ID Description X Range Y Range Severity
bluestacks_game_banner POPULAR GAMES TO PLAY banner 0-1440 2187-2560 Critical
bluestacks_ad_container Side ad container 840-1440 162-2422 High
bluestacks_search Search bar 240-1200 178-258 Medium

Auto-Recovery: When a tap accidentally opens Play Store or BlueStacks launcher, the karrot_resilient_tap.py script automatically:

  1. Detects wrong package (com.android.vending, com.uncube.launcher3)
  2. Presses back button twice
  3. Force stops interfering apps
  4. Relaunches Karrot

Detection Avoidance Settings

Setting Default Range Description
Random Delay 500-2000ms 100-5000ms Delay between taps
Tap Variance +/-10px 0-50px Coordinate randomization
Log Keywords LIAPP, security, tamper, integrity, root, magisk - Monitored keywords

Workflows

karrot-bypass-playintegrity.toon

COMPLETE PLAY INTEGRITY BYPASS WORKFLOW - Master workflow coordinating all steps from Magisk setup through Karrot login verification.

yaml
name: Karrot Play Integrity Bypass - Complete Workflow
description: Full end-to-end bypass setup and validation
version: 1.0.0

parameters:
  device: "127.0.0.1:5555"
  module_path: "/sdcard/PlayIntegrityFork.zip"
  test_email: "test@karrot.example.com"
  test_password: "bypasstest123"
  timeout: 30

phases:
  # PHASE 1: Setup Magisk with Zygisk
  - id: phase1_magisk_setup
    name: "Phase 1: Setup Magisk with Zygisk"
    steps:
      - id: launch_magisk
        action: adb-magisk-launch
        params:
          device: "{{ device }}"
          wait_text: "Modules"
          timeout: 10

      - id: navigate_settings
        action: adb-tap
        params:
          x: 100
          y: 200
          device: "{{ device }}"

      - id: enable_zygisk
        action: adb-magisk-enable-zygisk
        params:
          device: "{{ device }}"
          auto_reboot: false

  # PHASE 2: Install PlayIntegrityFork Module
  - id: phase2_install_module
    name: "Phase 2: Install PlayIntegrityFork Module"
    steps:
      - id: launch_magisk_again
        action: adb-magisk-launch
        params:
          device: "{{ device }}"

      - id: navigate_modules
        action: adb-tap
        params:
          x: 100
          y: 100
          device: "{{ device }}"

      - id: tap_install_fab
        action: adb-tap
        params:
          x: 400
          y: 800
          device: "{{ device }}"

      - id: wait_file_picker
        action: adb-wait-for
        params:
          method: text
          target: "Select"
          timeout: 5

      - id: select_module_file
        action: adb-file-select
        params:
          path: "{{ module_path }}"

      - id: wait_install_complete
        action: adb-wait-for
        params:
          method: text
          target: "Installation complete"
          timeout: "{{ timeout }}"

  # PHASE 3: Verify Magisk Module
  - id: phase3_verify_module
    name: "Phase 3: Verify Module Installation"
    steps:
      - id: check_module_list
        action: adb-magisk-launch
        params:
          device: "{{ device }}"
          wait_text: "PlayIntegrityFork"
          timeout: 10

      - id: verify_module_enabled
        action: adb-screenshot-capture
        params:
          device: "{{ device }}"

  # PHASE 4: Launch Karrot and Check Pre-Bypass
  - id: phase4_check_prebypas
    name: "Phase 4: Check Detection Pre-Bypass"
    steps:
      - id: launch_karrot
        action: adb-karrot-launch
        params:
          device: "{{ device }}"
          timeout: 10

      - id: check_detection_initial
        action: adb-karrot-check-detection
        params:
          device: "{{ device }}"
          detailed: true

  # PHASE 5: Configure PlayIntegrityFork
  - id: phase5_configure_module
    name: "Phase 5: Configure PlayIntegrityFork Module"
    steps:
      - id: wait_karrot_ready
        action: adb-wait-for
        params:
          method: text
          target: "Login"
          timeout: 10

      - id: note_configuration_needed
        action: adb-screenshot-capture
        params:
          device: "{{ device }}"

  # PHASE 6: Test Login with Bypass
  - id: phase6_test_bypass
    name: "Phase 6: Test Login with Bypass Active"
    steps:
      - id: test_login
        action: adb-karrot-test-login
        params:
          device: "{{ device }}"
          email: "{{ test_email }}"
          password: "{{ test_password }}"
          verify_success: true
          check_bypass: true
          timeout: "{{ timeout }}"

  # PHASE 7: Verify Bypass Success
  - id: phase7_final_verification
    name: "Phase 7: Final Verification"
    steps:
      - id: check_detection_after
        action: adb-karrot-check-detection
        params:
          device: "{{ device }}"
          check_logcat: true

      - id: wait_profile_screen
        action: adb-wait-for
        params:
          method: text
          target: "Profile"
          timeout: 5

recovery:
  # Retry on module installation failure
  - on_error: phase2_install_module
    action: retry
    max_attempts: 2
    delay: 3

  # Fallback for detection check
  - on_error: phase4_check_prebypas
    action: adb-screenshot-capture
    then: continue

  # Retry login test
  - on_error: phase6_test_bypass
    action: retry
    max_attempts: 2
    delay: 2

karrot-login.toon

Complete login flow with detection avoidance using safe taps and LIAPP monitoring.

yaml
name: Karrot Login Test (Detection-Aware)
description: Login workflow with LIAPP bypass and detection avoidance
version: 1.1.0

parameters:
  device: "127.0.0.1:5555"
  phone_number: "010-1234-5678"
  delay_min: 500
  delay_max: 2000
  tap_variance: 10

phases:
  - id: launch_and_monitor
    name: "Launch with LIAPP Monitoring"
    steps:
      - id: start_liapp_monitor
        action: adb-karrot-liapp-monitor
        params:
          device: "{{ device }}"
          duration: 120
          background: true

      - id: launch
        action: adb-karrot-launch
        params: {device: "{{ device }}"}

  - id: welcome_screen
    name: "Navigate Welcome Screen"
    steps:
      - id: tap_get_started
        action: adb-karrot-safe-tap
        params:
          device: "{{ device }}"
          x: 720
          y: 2374
          delay_min: "{{ delay_min }}"
          delay_max: "{{ delay_max }}"
          variance: "{{ tap_variance }}"

      - id: tap_login
        action: adb-karrot-safe-tap
        params:
          device: "{{ device }}"
          x: 872
          y: 2493
          delay_min: "{{ delay_min }}"
          delay_max: "{{ delay_max }}"

  - id: login_flow
    name: "Phone Number Login"
    steps:
      - id: tap_phone_input
        action: adb-karrot-safe-tap
        params:
          device: "{{ device }}"
          x: 410
          y: 254

      - id: input_phone
        action: adb-input-text
        params:
          device: "{{ device }}"
          text: "{{ phone_number }}"

      - id: tap_confirm
        action: adb-karrot-safe-tap
        params:
          device: "{{ device }}"
          x: 720
          y: 2520

      - id: wait_otp_screen
        action: adb-wait-for
        params:
          method: text
          target: "OTP"
          timeout: 30

karrot-detection-avoid.toon

Detection avoidance workflow with safe taps and real-time LIAPP monitoring.

yaml
name: Karrot Detection Avoidance
description: Workflow for operating with minimal detection footprint
version: 1.0.0

parameters:
  device: "127.0.0.1:5555"
  monitoring_duration: 300

phases:
  - id: setup_monitoring
    name: "Setup Detection Monitoring"
    steps:
      - id: clear_logcat
        action: adb-shell
        params:
          device: "{{ device }}"
          command: "logcat -c"

      - id: start_liapp_monitor
        action: adb-karrot-liapp-monitor
        params:
          device: "{{ device }}"
          duration: "{{ monitoring_duration }}"
          keywords: "LIAPP,security,tamper,integrity,root,magisk,com.lockincomp"
          background: true

  - id: detection_check
    name: "Pre-flight Detection Check"
    steps:
      - id: check_detection
        action: adb-karrot-check-detection
        params:
          device: "{{ device }}"
          detailed: true
          check_logcat: true

      - id: verify_bypass
        action: adb-bypass-verify
        params:
          device: "{{ device }}"
          modules: ["PlayIntegrityFork", "Shamiko", "HideMyApplist"]

recovery:
  - on_error: detection_check
    action: adb-screenshot-capture
    then: report_and_stop

karrot-error-recovery.toon

Error recovery and retry workflow for detection failures.

yaml
name: Karrot Error Recovery
description: Automated recovery from detection and bypass failures
version: 1.0.0

parameters:
  device: "127.0.0.1:5555"
  max_retries: 3
  retry_delay: 5

phases:
  - id: diagnose_error
    name: "Diagnose Detection Error"
    steps:
      - id: capture_state
        action: adb-screenshot-capture
        params:
          device: "{{ device }}"

      - id: check_logcat_errors
        action: adb-karrot-liapp-monitor
        params:
          device: "{{ device }}"
          duration: 10
          keywords: "error,LIAPP,integrity,CLIENT_TRANSIENT_ERROR"

      - id: identify_error_type
        action: adb-karrot-check-detection
        params:
          device: "{{ device }}"
          detailed: true

  - id: recovery_play_integrity
    name: "Recover Play Integrity Error"
    condition: "error_type == 'play_integrity'"
    steps:
      - id: clear_app_data
        action: adb-shell
        params:
          device: "{{ device }}"
          command: "pm clear com.towneers.www"

      - id: verify_pif_module
        action: adb-magisk-module-check
        params:
          device: "{{ device }}"
          module: "PlayIntegrityFork"

      - id: relaunch_app
        action: adb-karrot-launch
        params:
          device: "{{ device }}"
          timeout: 15

  - id: recovery_liapp
    name: "Recover LIAPP Detection"
    condition: "error_type == 'liapp'"
    steps:
      - id: verify_shamiko
        action: adb-magisk-module-check
        params:
          device: "{{ device }}"
          module: "Shamiko"

      - id: verify_hide_applist
        action: adb-magisk-module-check
        params:
          device: "{{ device }}"
          module: "HideMyApplist"

      - id: force_stop_app
        action: adb-shell
        params:
          device: "{{ device }}"
          command: "am force-stop com.towneers.www"

      - id: wait_before_retry
        action: adb-wait
        params:
          duration: "{{ retry_delay }}"

      - id: relaunch_app
        action: adb-karrot-launch
        params:
          device: "{{ device }}"

recovery:
  - on_error: recovery_play_integrity
    action: retry
    max_attempts: "{{ max_retries }}"
    delay: "{{ retry_delay }}"

  - on_error: recovery_liapp
    action: retry
    max_attempts: "{{ max_retries }}"
    delay: "{{ retry_delay }}"

Usage Patterns

Pattern 1: Complete Bypass Setup

bash
# Full end-to-end bypass implementation
uv run .claude/skills/adb-workflow-orchestrator/scripts/adb-run-workflow.py \
    --workflow .claude/skills/adb-karrot/workflows/karrot-bypass-playintegrity.toon \
    --param device=127.0.0.1:5555 \
    --param module_path=/sdcard/PlayIntegrityFork.zip \
    --verbose

Pattern 2: Quick Login Test

bash
# Fast login test for bypass validation
uv run .claude/skills/adb-workflow-orchestrator/scripts/adb-run-workflow.py \
    --workflow .claude/skills/adb-karrot/workflows/karrot-login.toon \
    --param device=127.0.0.1:5555 \
    --param email=test@example.com

Pattern 3: Detection Monitoring

bash
# Monitor detection status during testing
watch -n 5 "uv run .claude/skills/adb-karrot/scripts/adb-karrot-check-detection.py \
    --device 127.0.0.1:5555 \
    --check-logcat"

Analysis Files (From Previous Research)

Located in ./analysis/:

  • detection-report.md - Detailed detection mechanism analysis
  • bypass-strategy.md - Bypass approach and reasoning
  • playintegrity-findings.md - Play Integrity API research

Integration Points

Depends On:

  • adb-magisk (Magisk setup and module installation)
  • adb-screen-detection (screenshot and OCR verification)
  • adb-navigation-base (gesture automation)
  • adb-workflow-orchestrator (workflow coordination)

Used By:

  • Custom app testing and automation
  • Play Integrity bypass validation

Karrot App Detection Mechanism

Google Play Integrity API (Primary)
  ├─ deviceIntegrity()
  ├─ serverIntegrity() (hardcoded token)
  ├─ 1000ms timeout
  └─ Error -18: CLIENT_TRANSIENT_ERROR (emulator)

LIAPP Security SDK (Secondary)
  ├─ Class: com.lockincomp.wfcwxdz
  ├─ Tamper detection
  ├─ Root/Magisk detection
  ├─ Integrity verification
  └─ Anti-debugging measures

Persona SDK Wrapper
  └─ Calls integrity verification

Bypass Stack:
  ├─ PlayIntegrityFork
  │   └─ Hooks Play Services
  │       └─ Returns spoofed device signature
  ├─ Shamiko (Required for LIAPP)
  │   └─ Hides root from LIAPP scans
  └─ HideMyApplist
      └─ Hides Magisk from app detection

LIAPP Bypass Methodology

LIAPP (Lockin Company) is a mobile security SDK used by Karrot for additional tamper/root detection.

Detection Type LIAPP Method Bypass Approach
Root Detection Binary scan for su/Magisk Shamiko hiding
Tamper Detection APK signature verification Keep original APK
Integrity Check Runtime integrity validation Hook LIAPP callbacks
Debug Detection Debugger attachment check Release mode only

Monitoring LIAPP Events

bash
# Monitor LIAPP-related log events
adb logcat | grep -iE "LIAPP|security|tamper|integrity|root|magisk|com.lockincomp"

# Specific LIAPP class monitoring
adb logcat | grep "com.lockincomp.wfcwxdz"

Required Modules for LIAPP Bypass

  1. Shamiko (Required) - Hides root from LIAPP detection
  2. HideMyApplist - Hides Magisk Manager from app list queries
  3. PlayIntegrityFork - Primary integrity bypass

Documentation Reference

For detailed LIAPP bypass implementation: .moai/docs/guides/liapp-bypass/

Version: 3.0.0 Status: App-Specific Tier with AI Integration Scripts: 10 (7 traditional + 3 AI-powered) Workflows: 4 (karrot-login-v3.toon is recommended) Last Updated: 2025-12-03 Tier: 3 (App-Specific) Package: com.towneers.www LIAPP Class: com.lockincomp.wfcwxdz AI Features: Claude Vision API integration (~$0.005/request)

Test Results (2025-12-03)

Fixes Applied

1. Target Name Mismatch Fixed (karrot_workflow.py)

  • Issue: Workflow target names (welcome_get_started, welcome_login) didn't match tap handler names (get_started, login)
  • Fix: Updated target names to match tap handler naming convention
  • Impact: Workflow can now correctly resolve and execute tap actions

2. Package Detection Improved (karrot_resilient_tap.py)

  • Issue: Primary package detection method could fail silently
  • Fix: Added fallback method using dumpsys window when pm dump fails
  • Impact: More robust package verification, reduced false negatives

3. UIAutomator Timeout Increased (karrot_smart_detector.py)

  • Issue: UIAutomator timeout of 2.0s was too aggressive, causing premature fallback
  • Fix: Increased timeout from 2.0s to 3.0s
  • Impact: Better success rate with traditional detection before AI fallback

Integration Test Status

[PENDING] - Full integration tests to be run after fixes

Planned test scenarios:

  1. Complete login workflow (launch → welcome → neighborhood → verification)
  2. Package detection verification under various conditions
  3. UIAutomator detection success rate measurement
  4. AI fallback trigger frequency analysis
  5. Multi-device coordination test (3+ devices)

Known Issues

1. LIAPP Detection Sensitivity

  • Issue: LIAPP security SDK may still trigger on some app versions
  • Workaround: Ensure Shamiko + HideMyApplist modules are enabled
  • Status: Monitoring required

2. BlueStacks Ad Overlay Interference

  • Issue: Ad overlays in banned zones (y > 2187) can intercept taps
  • Workaround: Use safe coordinates (y=2350 instead of y=2374 for Get Started button)
  • Status: Mitigated via banned zone protection in karrot_resilient_tap.py

3. Package Detection Edge Cases

  • Issue: Some devices may not support pm dump command
  • Workaround: Fallback method using dumpsys window implemented
  • Status: Resolved in v3.0.0

Changelog

v3.0.0 (2025-12-03) - AI Vision Integration

  • NEW: Added karrot_ai_vision.py - Claude Vision API for semantic element detection
  • NEW: Added karrot_smart_detector.py - Multi-layer detection with AI fallback
  • NEW: Added karrot_unified_automation.py - High-level AI-powered automation
  • NEW: AI Vision Integration section with architecture and cost analysis
  • NEW: Detection Methods Comparison table (UIAutomator, Template, OCR, AI)
  • NEW: Smart Detection Flow with 4-layer fallback strategy
  • NEW: Loop Prevention system with exponential backoff
  • NEW: Usage Examples section with 5 practical examples
  • FEATURE: Multi-layer detection (UIAutomator → Template → OCR → AI Vision)
  • FEATURE: Cost optimization - AI used only as fallback (~$0.005/request)
  • FEATURE: Semantic element detection ("Find the blue Get Started button")
  • FEATURE: Error detection with auto-recovery suggestions
  • UPDATED: Quick Reference with AI capabilities
  • UPDATED: Scripts count from 7 to 10

v2.0.0 (2025-12-03) - Auto-Recovery System

  • CRITICAL FIX: Changed Get Started button coordinate from y=2374 to y=2350 to avoid BlueStacks ad zone
  • NEW: Added karrot_resilient_tap.py with auto-recovery and banned zone protection
  • NEW: Added karrot-login-v3.toon workflow with comprehensive auto-recovery
  • NEW: Added Banned Zones section documenting BlueStacks ad overlays
  • UPDATED: UI Coordinates table with Safe column
  • UPDATED: All tap operations now use resilient tap with pre/post verification

v1.1.0 (2025-12-03) - LIAPP Bypass

  • Added LIAPP bypass documentation
  • Added safe tap script with detection avoidance
  • Added multi-device support

Didn't find tool you were looking for?

Be as detailed as possible for better results