android-agent-harness

Deterministic Android Engineering for the AI Era

Turn Any AI Assistant into an Uncompromising Senior Android Engineering Team.

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:

Android Failure Mode	Bare AI Assistant	Android Agent Harness
Room Migrations	Modifies `@Entity` without migration -> app crashes on user upgrade.	Room Guard (`room_guard.py`): Hard-blocks un-migrated Kotlin & Java entities.
Localization & RTL	Hardcodes strings, drops Arabic (`values-ar`), scrambles placeholders.	Adaptive String Guard (`check_strings.py`): Sub-second diff-scoped parity check.
ANR & Main-Thread I/O	Runs disk/network I/O on `Dispatchers.Main`; leaks sensor listeners.	Perf & ANR Guardian: Enforces 60/120 FPS fluidity and lifecycle unregistration.
Review Verification	Model declares "LGTM!" and assumes its own fix works.	Cryptographic Barrier: Assembly (`:assembleDebug`) locked until 6 guardians emit SHA-256 tokens.
Rogue Git Commits	Runs `git commit` or `git push --force` to hide compilation mistakes.	OS Interceptor (`pre_tool_safety.py`): Hard-denies unauthorized Git and ADB mutations.
Legacy Codebases	Linters output 4,000 legacy errors, stalling delivery.	Zero Legacy Penalty: Diff-scoped AST lint (`fast_kt_lint.py`) inspects modified lines in <1s.

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:

bug-reviewer-agent (BUG_PASS): Logic bugs, Kotlin null-safety across Java boundaries, and coroutine cancellation leaks.
convention-reviewer-agent (CONVENTION_PASS): Clean Architecture, MVI StateFlow immutability, zero inline FQCNs.
security-reviewer-agent (SECURITY_PASS): OWASP Mobile Top 10, unexported components, and credential isolation.
perf-anr-guardian-agent (PERF_PASS): ANR elimination, Main-thread I/O prevention, and Compose recomposition fluidity.
regression-impact-reviewer-agent (REGRESSION_PASS): Blast radius analysis, caller graph impacts, and API signature changes.
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:

Resolves connected physical devices via ADB (prioritizing physical devices over emulators).
Builds and installs via run_device.py install-start, launching the target Activity directly.
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/v0.27.6/docs/install-or-update-prompt.md and follow all its instructions.

Option B: Via Terminal CLI

pipx install git+https://github.com/rabee-elkholy/android-agent-harness.git
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.