Android Agent Harness is a repository-local workflow and verification system for teams that use AI agents on real Android codebases. It does not replace Android Studio, Gradle, ADB, Git, CI, or your model. It coordinates them so the agent receives relevant context, follows an approved scope, runs proportionate checks, and cannot label work ready without evidence from the current change set.

It is designed for existing Kotlin, Java, Compose, XML, multi-module, library, dynamic-feature, and Android/KMP projects. Runtime code uses only the Python standard library.

Why it exists

Raw coding agents are useful, but Android delivery has failure modes that a prompt alone cannot reliably control:

The goal is not more ceremony. The goal is to spend model time and developer attention only where they materially reduce risk.

What you get

• Approval-first execution — discovery is read-only; implementation starts only after the developer approves a concrete outcome, scope, and verification plan.
• Android-aware change classification — detects multiple simultaneous surfaces instead of collapsing a diff to its least risky file.
• Bounded Project Intelligence — resolves the smallest useful live context for a file or symbol, handles ambiguous identities safely, and keeps default previews compact.
• Adaptive verification — micro, standard, and critical changes receive different gates. Presentation-only UI work is not forced through the same path as auth, billing, crypto, or Room schema changes.
• Deterministic Android guards — localization parity, Room migration safety, test attribution, performance hazards, environment classification, Gradle diagnostics, and device identity checks.
• Evidence-backed delivery — gate output and reviews must match the frozen final tree. Stale, partial, malformed, or mismatched evidence fails closed.
• Safe lifecycle operations — install, update, repair, rollback, and uninstall are transactional and preserve project-owned hooks, configuration, source, and task evidence.
• Model-agnostic operation — works with supported hosts and lets teams map abstract STANDARD and STRONG review capabilities to the models they choose.
• Local, dependency-light runtime — installed project commands run from .agents/harness.py with no third-party Python runtime packages.

How it works

The workflow is a persisted state machine:

INTAKE -> DISCOVERY -> PLAN_DRAFTED -> AWAITING_DEVELOPER_APPROVAL
       -> IMPLEMENTING -> VERIFYING -> READY_FOR_DELIVERY -> DELIVERED
                                    \-> BLOCKED -> IMPLEMENTING

The harness separates three concerns:

1. Understanding the project — discovers modules, variants, source sets, architecture signals, symbols, and relevant dependencies without forcing an architecture rewrite.
2. Controlling the task — binds approval, scope, risk, selected skills, and allowed operations to one task lifecycle.
3. Proving the result — records deterministic gate and review evidence against one immutable delivery snapshot.

Install

Requirements

• Python 3.10–3.14;
• a Git checkout with a root Gradle Wrapper;
• JDK and Android SDK when selected build gates require them;
• ADB only when the task requires device verification.

Chat installation (recommended)

Open the Android project root in your coding agent and paste this exact pinned prompt:

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

The installer discovers the project in read-only mode, asks only the configuration questions it needs, shows the installation plan, waits for approval, installs the pinned kit, and runs Doctor. Application source is not modified during setup.

Terminal installation (alternative)

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

# Configure an Android project.
android-harness setup --repo /path/to/android-project

# Verify the installation and environment.
android-harness doctor --repo /path/to/android-project --json

To use a source checkout instead:

git clone --depth 1 --branch v1.0.57 --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 setup, normal work uses the repository-local launcher, so the global kit path is not required for daily commands:

python .agents/harness.py doctor --json
python .agents/harness.py task-context --file app/src/main/kotlin/com/acme/ProfileScreen.kt --json
python .agents/harness.py task status --task-id profile-edit --next

See the Quickstart and Setup Wizard reference for update, repair, rollback, uninstall, and non-interactive options.

Daily workflow

The developer can describe work naturally. A typical request is:

Add retry handling to profile loading, preserve the existing architecture, add regression coverage, and verify the affected screen.

The agent should then:

1. resolve bounded context for the affected file, symbol, or feature;
2. inspect the relevant application code and existing conventions;
3. present the proposed outcome, files/surfaces, risks, tests, and device needs;
4. wait for one explicit approval;
5. implement the approved work without changing unrelated architecture;
6. freeze the final change set and run the policy-selected gates and reviewers;
7. perform assemble/device/UI verification only when the policy requires it;
8. report the result and leave application changes unstaged for developer review.

For a bug with a meaningful deterministic seam, the workflow records a real failing result before the fix and a passing result afterward. For a documentation or mechanical change, it avoids pretending that an empty or irrelevant test run adds confidence.

Canonical Sequential Lifecycle (Steps 1–15)

Every task follows a strict, sequential lifecycle. Direct engine commands and local CLI wrappers adhere to this contract:

Quick CLI Shortcuts

Android-aware verification

5-Tier Adaptive Execution Lanes

Review policy evaluates blast radius and assigns an adaptive risk lane dynamically:

Reviewer Evidence & Finding Adjudication

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

• Clean reviews pass with cites=0 and are recognized as PASS.
• If a reviewer reports a false positive, the lead agent adjudicates it via workflow.py validate-finding --status FALSE_POSITIVE --reason "<rationale>".
• The technical rationale is embedded directly into review-package.md under ## LEAD AGENT FINDING VALIDATIONS, allowing re-reviewers to accept the explanation without manual bypass.
• Companion surfaces (localization strings, UI layouts, navigation) are automatically recognized alongside code surfaces, preventing spurious material drift blocks.

The central policy routes checks from the actual diff. Examples:

Example: Room schema change

If an agent adds a field to a Room entity, the harness classifies the change as ROOM_SCHEMA, discovers the owning database, requires an explicit migration path, runs configured migration tests, routes the data-focused review lane, and binds the final assemble/device evidence to the same frozen tree. A changed entity cannot be disguised as a low-risk documentation change by placing both in one diff.

Safety model

The harness is deliberately precise about what it can and cannot enforce.

Important boundaries:

• This is not an OS sandbox. A process with arbitrary local access can bypass repository files.
• Cryptographic hashes make evidence tampering and staleness detectable; they do not make the host machine trusted.
• The harness never claims that configuring a CI matrix proves it passed. Hosted CI results are separate evidence.
• It does not silently modernize architecture, replace DI, migrate XML to Compose, or rewrite persistence choices.
• It does not automatically pair wireless ADB, clear app data, uninstall an app, downgrade builds, make purchases, or grant every permission.
• It does not commit, push, reset, or stage client application work for the developer.
• Zoho Sprints behavior is preserved, but live tracker mutation requires explicit update zoho authorization and idempotent operation identity.

For the complete boundary and threat analysis, read Security, Threat Model, and Compatibility Matrix.

Supported project and host shapes

The validated project boundary includes:

• Kotlin, Java, and mixed projects;
• Jetpack Compose, XML Views, and hybrid UI;
• application, library-only, multi-module, dynamic-feature, and Android/KMP targets;
• Kotlin or Groovy Gradle DSL;
• discovered flavors and custom build types;
• existing tests, no-test repositories, and explicitly recorded baseline debt;
• normal Git checkouts and worktrees;
• Linux, macOS, and Windows hosts.

Host adapters are available for Claude Code, GitHub Copilot, Cursor, Windsurf, Roo Code, Gemini CLI, and Antigravity. Enforcement strength depends on the capabilities of each host; see Tool Support for the current matrix.

Lifecycle and non-interference

Harness lifecycle operations are designed not to take ownership of the Android project:

• managed files live under .agents/ plus documented host adapters;
• local state is excluded through .git/info/exclude rather than changing the application’s tracked ignore policy;
• project-owned hooks and Git configuration are preserved byte-for-byte;
• same-major updates are transactional and fail closed on conflicting managed-file edits;
• repair restores immutable engine files from the pinned checksum inventory;
• uninstall starts as a dry run and preserves modified harness material in recovery when applied;
• interrupted lifecycle operations use journals for deterministic recovery.

android-harness update --repo /path/to/android-project --kit /path/to/new-kit
android-harness repair --repo /path/to/android-project --kit /path/to/pinned-kit
android-harness uninstall --repo /path/to/android-project
android-harness uninstall --repo /path/to/android-project --apply

Verification and release quality

This repository verifies the harness itself; it does not run Android Gradle or ADB against the harness source tree.

# Complete deterministic suite.
python harness_cli.py selftest

# Syntax validation.
python -m compileall -q harness_cli.py agents/scripts agents/mcp/zoho_sprints

# Release metadata, prompt pins, checksums, and package contract.
python scripts_dev/validate_release.py

CI runs the complete selftest suite across every supported Python version on Linux and on the canonical Python runtime for Windows and macOS. Wheel install/update/uninstall lifecycles run separately on all three operating systems, alongside performance regression and release-metadata checks. Release tags receive a second cross-platform validation before trusted PyPI publication.

Documentation

What this project is not

• not an AI model, model proxy, or provider lock-in layer;
• not a replacement for Gradle, Android Studio, Git, CI, or human code review;
• not a generic autonomous-agent swarm framework;
• not a promise that every host offers hard pre-execution enforcement;
• not a reason to run every expensive gate for every trivial edit.

Contributing

Issues and focused pull requests are welcome. Please read CONTRIBUTING.md, preserve the standard-library-only runtime, add deterministic regression coverage for behavior changes, and run the complete selftest before opening a pull request.

Security issues should follow the private reporting process in SECURITY.md.

License

MIT License. See LICENSE.