Overview

Android Agent Harness is a repository-local governance and verification control plane designed specifically for real-world Android codebases.

General-purpose coding agents (such as Claude Code, GitHub Copilot, Cursor, Windsurf, Roo Code, and Gemini CLI / Antigravity) excel at code generation but lack systemic understanding of Android platform constraints: Gradle variant matrices, Room schema migrations, localized XML string parity, multi-module dependency graphs, main-thread blocking hazards, and device deployment continuity. Left unguided, agents introduce runtime crashes, trigger unanchored grep cascades across large trees, or claim tests passed based on stale terminal logs.

The harness does not replace Android Studio, Gradle, ADB, Git, CI, or your AI model. Instead, it coordinates them through an immutable state machine:

• Zero Python dependencies: The entire runtime relies exclusively on the Python standard library (Python 3.10–3.14).
• Approval-first execution: Repository discovery is strictly read-only; implementation requires explicit developer sign-off on scope, risks, and verification criteria.
• Strict cryptographic evidence binding: Assemble, test, and device results are cryptographically bound to the final frozen change set. Stale or partial evidence fails closed.
• Respects project ownership: Git checkouts, commit history, and existing git hooks remain 100% developer-owned. Client application code is never auto-committed or staged by the harness.

Why it exists

Raw coding agents frequently suffer from platform-specific failure modes when working on Android repositories. The harness provides deterministic boundaries for each:

Core Architecture

The harness coordinates discovery, execution control, and verification proof:

Lifecycle State Machine

Every task is governed by an immutable state machine persisted in .agents/task-state/:

[INTAKE] ──► [DISCOVERY] ──► [PLAN_DRAFTED] ──► [AWAITING_DEVELOPER_APPROVAL]
                                                         │ (Developer Approves)
                                                         ▼
                                                  [IMPLEMENTING] ◄────────┐
                                                         │                │
                                                         ▼                │ (Resume on Fixes)
                                                   [VERIFYING] ───────────┘
                                                    │        │
                                   (Checks Pass)    │        │ (Findings / Blockers)
                                                    ▼        ▼
                                       [READY_FOR_DELIVERY] [BLOCKED]
                                                    │
                                                    ▼
                                               [DELIVERED]

1. Discovery & Scoping: Explores project topology, build variants, source sets, and symbols without modifying any application files.
2. Task Planning & Single Approval: Establishes target outcomes, predicted surfaces, and required verification tiers. The developer approves once via chat or terminal.
3. Implementation: Code modifications are confined strictly to the approved scope. Material architectural drift or unplanned module edits fail closed.
4. Verification & Proof: Final code is frozen. Preflight checks, unit tests, specialist reviewer subagents, Gradle assemble, and device deployment run in strict topological order.

Install

Requirements

• Python: 3.10 to 3.14 (standard library only; no virtual environment or external packages required).
• Project: Git checkout of an Android project with a root Gradle Wrapper (gradlew / gradlew.bat).
• Build Tools: JDK and Android SDK configured for your project.
• Device (Optional): Connected physical device or running Android emulator (only needed if task triggers device verification).

Chat installation (recommended)

Open your Android project in your AI coding agent (Claude Code, GitHub Copilot, Cursor, Windsurf, Roo Code, or Gemini CLI / Antigravity) and paste this exact pinned bootstrap prompt into the chat:

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

The installer runs non-destructively:

1. Discovers existing Gradle modules, build variants, and architectural conventions.
2. Interactively asks only necessary configuration questions (e.g., target build variant, device policy).
3. Presents a clear installation plan and awaits developer approval.
4. Installs the immutable engine under .agents/ and configures host adapter files.
5. Runs the 12-point Doctor diagnosis to verify full environment readiness.

Terminal installation (alternative)

You can install the harness CLI globally using pipx:

# Install the CLI in an isolated environment
pipx install android-agent-harness

# Run interactive setup in your Android repository root
android-harness setup --repo /path/to/android-project

# Verify system health across all 12 diagnostic dimensions
android-harness doctor --repo /path/to/android-project --json

Or run directly from a pinned source clone without global installation:

git clone --depth 1 --branch v1.0.58 --single-branch \
  https://github.com/rabee-elkholy/android-agent-harness.git ~/.android-harness/kit

python ~/.android-harness/kit/harness_cli.py setup \
  --repo /path/to/android-project \
  --kit ~/.android-harness/kit

After installation, daily work uses the repository-local launcher:

python .agents/harness.py doctor --json

Daily workflow

Developers interact naturally with their coding agent. For example:

"Add retry handling to profile image loading, preserve our existing MVI architecture, add unit test coverage, and verify the screen on emulator."

The harness orchestrates the agent's work through the 15-step sequential lifecycle:

Canonical Sequential Lifecycle

5-Tier Adaptive Risk Lanes

Tasks are not evaluated uniformly. The harness inspects the actual working tree diff and dynamically selects an adaptive risk lane based on blast radius:

Cryptographic Review Evidence & Finding Adjudication

Specialist reviewers execute independently as subagents and attach cryptographically bound evidence footers: EVIDENCE pkg=<sha12> cites=<n>

• Clean Reviews: Reviews with zero citations (cites=0) automatically evaluate to PASS.
• Finding Adjudication: When a reviewer reports a false positive or intentional design decision, the lead agent adjudicates it using workflow.py validate-finding --status FALSE_POSITIVE --reason "<rationale>".
• Audit Trails: The technical justification is permanently embedded into review-package.md under ## LEAD AGENT FINDING VALIDATIONS, allowing re-reviews to verify the decision without manual bypasses.

Deterministic Android Guards

The harness includes specialized deterministic guards that catch domain-specific regressions in milliseconds before Gradle compilation:

Safety Model & Boundaries

The harness enforces rigorous boundaries to keep the developer in complete control:

┌──────────────────────────────────────────────────────────────┐
│                    DEVELOPER BOUNDARY                        │
│  • Git commits, pushes, branches, merges, and rebases        │
│  • Application architecture & third-party dependency choices │
│  • Production release signing & secret management            │
├──────────────────────────────────────────────────────────────┤
│                     HARNESS CONTROL PLANE                    │
│  • Read-only project discovery & AST slicing                 │
│  • Approval nonce enforcement & state machine validation     │
│  • Deterministic preflight gates (<2s)                       │
│  • Autonomous reviewer subagent routing                      │
│  • Gradle gate execution & APK artifact fingerprinting       │
│  • Device deployment & interactive mobile walkthrough        │
├──────────────────────────────────────────────────────────────┤
│                      HOST ENVIRONMENT                        │
│  • Standard Library Python 3.10–3.14 (Zero pip dependencies) │
│  • Gradle Wrapper, Android SDK, ADB daemon                   │
└──────────────────────────────────────────────────────────────┘

Safety Principles

• No OS Sandbox: The harness does not sandbox host processes. A process with shell access can modify local files; cryptographic checksums ensure any tampering with harness engine code is immediately detected.
• No Git Tampering: The harness will never commit, push, reset, stash, or rebase client project code. All changes remain unstaged in the developer's working tree.
• No Silent Modernization: The harness never silently rewrites project architecture, migrates XML to Compose, or swaps dependency injection frameworks without explicit developer instructions.
• No Dangerous Device Operations: Does not clear application data, uninstall applications, downgrade versions, or automatically authorize billable actions on connected devices.

For detailed security analyses, consult SECURITY.md, Threat Model, and Compatibility Matrix.

Supported Environments & AI Hosts

Android Project Compatibility

• Languages: Kotlin, Java, and mixed codebases.
• UI Frameworks: Jetpack Compose, XML Views, and hybrid UI.
• Project Topologies: Single-module apps, multi-module apps, library projects, dynamic-feature modules, and Android/KMP targets.
• Build Systems: Gradle with Kotlin DSL (build.gradle.kts) or Groovy DSL (build.gradle), Gradle Version Catalogs (libs.versions.toml).
• Operating Systems: Linux, macOS, and Windows (native PowerShell and CMD support).

AI Host Adapters

The harness provides native adapter configurations for all major AI coding environments:

See Tool Support for full adapter configuration details.

Quality & Self-Testing

This repository tests its own engine through an extensive deterministic selftest suite covering 18 test domains and 500+ unit, integration, and scenario assertions:

# Run the complete deterministic selftest suite
python harness_cli.py selftest

# Run syntax compilation validation across all scripts
python -m compileall -q harness_cli.py agents/scripts agents/mcp/zoho_sprints

# Validate release metadata, prompt pins, checksums, and package invariants
python scripts_dev/validate_release.py

Continuous Integration (CI)

Every commit and pull request is validated by GitHub Actions across:

• Python Matrix: 3.10, 3.11, 3.12, 3.13, and 3.14.
• Platforms: Ubuntu 24.04, Windows Server 2025, and macOS 15.
• Checks: Full deterministic selftest, performance regression benchmarks, wheel lifecycle tests (install, update, uninstall), and tamper-detection validation.

Documentation

Comprehensive guides and architectural references are available in the repository:

What this project is not

To set clear engineering expectations:

• Not an AI Model or Proxy: We do not sell or wrap LLM APIs. The harness sits in your repository and works with whichever AI model or coding assistant you use.
• Not a Framework Replacement: It does not replace Android Studio, Gradle, Kotlin compiler, or Jetpack libraries.
• Not an Autonomous Swarm Gimmick: It does not spin up uncontrolled agent loops. Every task has an explicit scope, bounded context, and human-in-the-loop approval.
• Not a Reason to Run Heavy Builds Blindly: It actively avoids running slow Gradle builds or device deployments for micro edits and documentation changes.

Contributing

We welcome contributions! Please review CONTRIBUTING.md before submitting pull requests.

Key contributor rules:

1. Standard Library Only: All runtime engine code must strictly use the Python standard library.
2. Deterministic Coverage: Any behavioral change or bug fix must include deterministic regression tests in agents/scripts/_*_selftest.py.
3. Full Suite Green: Run python harness_cli.py selftest and python scripts_dev/validate_release.py before submitting.

For vulnerability disclosures, please follow the coordinated process detailed in SECURITY.md.

License

MIT License. See LICENSE.