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.

The 6 Parallel Quality Guardians

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

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

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.