Adb Karrot

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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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

Smart Detection Flow

# 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

# 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)

# 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)

# 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

# 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

# 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

# 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)

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:

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

Workflows

karrot-bypass-playintegrity.toon

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

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.

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.

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.

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

# 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

# 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

# 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.

Monitoring LIAPP Events

# 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