Why the Harness? Prompts are Polite Requests. The Harness is an OS-Level Cage.

Prompts, .cursorrules, and SKILL.md files decay as conversation context expands. AI coding assistants eventually hallucinate success, break Room migrations, ignore RTL layouts, and push unreviewed code.

The Android Agent Harness enforces deterministic, cryptographic, and OS-level execution barriers outside the model brain:

The Cage in Action: Real-Time Interceptions

[MODEL ATTEMPTS] > git push --force origin main
[HARNESS CAGE]   [DENIED] Autonomous git push is strictly blocked. Human developer authority is absolute.

[MODEL ATTEMPTS] > python agents/scripts/run_gradle_task.py :app:assembleDebug
[HARNESS CAGE]   [LOCKED] Cryptographic Review Barrier active. Missing pass tokens: [BUG_PASS, PERF_PASS].

[PREFLIGHT GATE] python agents/scripts/room_guard.py
[HARNESS CAGE]   [FAIL] Room database AppDatabase.kt version was NOT incremented. Destructive fallback banned.

[MODEL ATTEMPTS] > Get-ChildItem -Path "C:\Users\..." -Recurse
[HARNESS CAGE]   [DENIED] Host user directory traversal is strictly blocked. Confine discovery to repository.

Universal Code Graph Engine: Graph-First Discovery vs. Brute-Force Grepping

Traditional AI coding tools explore large Android codebases blindly: they launch speculative grep_search cascades, guess whether a class is written in Kotlin (.kt) or Java (.java), read irrelevant files, and exhaust context windows before writing a single line of code.

The Android Agent Harness solves this with an integrated, pre-warmed Universal Code Graph Engine (project_graph.py):

                                  [Universal Code Graph]
                                             |
      +------------------------------+-------+----------------------+------------------------------+
      |                              |                              |                              |
      v                              v                              v                              v
  UI Layer                     ViewModel Layer                Domain Layer                   Data Layer
[Composables / XML] --deps--> [StateFlow / MVI] --deps--> [UseCases / Interactors] --deps--> [Repositories / Room]

Why the Graph Transforms Agentic Coding:

• Pre-Warmed & Instant: Parses thousands of files (Kotlin, Java, XML, Gradle) during setup into an optimized topological cache (.agents/cache/project_graph.json).
• Clean Architecture Slices: Extract the complete end-to-end stack for any feature in a single CLI call:

  python .agents/scripts/project_graph.py --feature Payment
  # Automatically returns: PaymentScreen -> PaymentViewModel -> ProcessPaymentUseCase -> PaymentRepository -> PaymentDao
  

• Architectural Trace & Dependency Paths: Find the exact dependency path between two distant components:

  python .agents/scripts/project_graph.py --path-from HomeScreen --path-to UserPreferencesDataStore
  

• UI Screen & Layout Mapping: Discover all Composables, XML Activities, and their associated ViewModels instantly:

  python .agents/scripts/project_graph.py --screens
  

• Precise Symbol Resolution: Locate exact file paths, languages ([COMPOSE], [KOTLIN], [JAVA], [XML]), and incoming/outgoing edges without guessing:

  python .agents/scripts/project_graph.py --find ProfileRepository
  

• 80%+ Token Savings: Eliminates exploratory reading loops, cutting discovery phase token consumption by over 80%.

The 6 Parallel Quality Guardians

Before :app:assembleDebug or device deployment, 6 specialized subagents review the immutable snapshot in parallel:

                            +---> [bug-reviewer-agent]              ---> BUG_PASS
                            +---> [convention-reviewer-agent]       ---> CONVENTION_PASS
[Review Package (SHA-256)] -+---> [security-reviewer-agent]         ---> SECURITY_PASS
                            +---> [perf-anr-guardian-agent]         ---> PERF_PASS
                            +---> [regression-impact-reviewer-agent] ---> REGRESSION_PASS
                            +---> [test-quality-reviewer-agent]     ---> TEST_PASS (Smart Test Promotion)

1. bug-reviewer-agent (BUG_PASS): Logic bugs, Kotlin null-safety across Java boundaries, and coroutine cancellation leaks.
2. convention-reviewer-agent (CONVENTION_PASS): Clean Architecture, MVI StateFlow immutability, zero inline FQCNs.
3. security-reviewer-agent (SECURITY_PASS): OWASP Mobile Top 10, unexported components, and credential isolation.
4. perf-anr-guardian-agent (PERF_PASS): ANR elimination, Main-thread I/O prevention, and Compose recomposition fluidity.
5. regression-impact-reviewer-agent (REGRESSION_PASS): Blast radius analysis, caller graph impacts, and API signature changes.
6. test-quality-reviewer-agent (TEST_PASS): Smart Test Promotion — automatically promoted on test/mock diffs to verify assertion depth and runTest dispatchers.

On-demand specialists: qa-diagnostics-agent (Logcat crash forensics) & android-ui-expert-agent (Compose & RTL layouts).

The Zero-Assumption Barrier & Interactive Discovery

AI assistants frequently jump into implementation based on flawed assumptions about business logic or edge cases. The harness enforces a strict Zero-Assumption Protocol:

1. Mandatory Missing-Scenario Audit: After graph discovery and before proposing an implementation plan, the agent must systematically audit for unmentioned edge cases:
   • Network States: Offline behavior, timeout policies, friendly error message mappings.
   • State Invariants: Missing/empty identifiers (e.g. empty country/ISO codes, unauthenticated sessions).
   • Data Lifecycles: Cache TTL, cache invalidation triggers, and empty list states.
2. Proactive Developer Interviewing: If any scenario is underspecified, the agent MUST interview the developer using interactive choice modals (ask_question). Guessing business logic from scratch is strictly forbidden.
3. Attached Media First-Turn Inspection: Whenever the developer provides a screenshot or video recording, the agent inspects it via view_file in the very first turn to correlate on-screen visual bugs directly with the code.

Physical Device Verification & Interactive Sign-off

Software that compiles is not necessarily software that works on mobile. The harness:

1. Resolves connected physical devices via ADB (prioritizing physical devices over emulators).
2. Builds and installs via run_device.py install-start, launching the target Activity directly.
3. Generates 2 to 3 diff-grounded manual test steps and triggers an interactive confirmation modal (ask_question): PASS -- Device testing passed successfully vs FAIL -- Issue or crash encountered.

Quickstart in 60 Seconds

Option A: Via AI Chat Prompt (Recommended)

Open a new chat session in your AI assistant (Antigravity, Claude Code, Cursor, Copilot, Windsurf) at your project root and paste:

Read https://raw.githubusercontent.com/rabee-elkholy/android-agent-harness/main/docs/install-or-update-prompt.md and follow all its instructions.

Option B: Via Terminal CLI

pip install android-agent-harness
# or via pipx for an isolated global command:
pipx install android-agent-harness
android-harness init

Supported AI Environments (14 Tools, 3 Tiers)

• Hook-Enforced: Google Antigravity, Claude Code, GitHub Copilot (deterministic Python OS-level interceptors).
• Rule-Driven: Cursor, Windsurf, Cline, Roo Code, Amazon Q, Continue, Junie, Kilo, Goose, Qwen, Codex.
• Prompt-Only: Aider, Zed, Devin, Amp, Factory, Jules, Warp, OpenCode (AGENTS.md standard).

Documentation & Deep-Dives

• Architecture Guide: 7-stage delivery lifecycle, safety interceptor mechanics, and preflight pipeline.
• Developer Workflows: 10 structured engineering playbooks (TDD, forensic triage, ANR audit, preflight).
• Quickstart & CLI: Complete CLI command matrix and environment setup.
• Threat Model & Security: Analysis of 7 threat vectors and mitigation layers.
• Architecture Decision Records (ADRs): Formal ADRs (001-006) covering review gates, human git authority, and conflict adjudication.

License

Distributed under the MIT License. See LICENSE for details.