Android Agent Harness
A local, zero-dependency development harness for Android projects. It is designed to improve AI-assisted implementation quality while keeping model calls, build work, and developer interruption proportional to the actual change.
v1 guarantees
- Analysis and planning are read-only. No implementation starts until the developer explicitly approves the exact plan.
- A deterministic classifier selects only relevant skills, tests, reviewers, build steps, and device checks.
- Every gate is bound to one repository, approved plan, complete delivery snapshot, change set, run id, harness version, and producer.
- Evidence is append-only. The final verifier is read-only and rejects stale, incomplete, forged, or cross-run evidence.
- APK output is an artifact set, so split APKs are built, hashed, installed, and launched as one identity.
- Clean install, same-major update, dry-run uninstall, backup, rollback, and user-file ownership are explicit lifecycle operations.
- Zoho Sprints keeps the existing workflow and never changes without
update zoho, an approved plan that lists--external-write zoho_sprints, and a stable operation id. - Hosts report their real enforcement level. Executable hooks can hard-enforce covered mutations; conversational approval remains
RULE_ENFORCEDunless a future host supplies non-forgeable proof.
Install
Chat installation (recommended)
Open the Android project root in your coding agent, then paste:
Read https://raw.githubusercontent.com/rabee-elkholy/android-agent-harness/v1.0.1/docs/install-or-update-prompt.md and follow all instructions.
The AI agent will:
- Perform read-only discovery of your Android project structure.
- Ask setup questions directly in chat with recommended choices marked with (Recommended).
- Present a precise installation plan with an executable non-interference snapshot guarantee.
- Wait for your explicit approval before modifying anything or provisioning the kit.
- Provision the pinned kit into
~/.android-harness/kit, verify integrity, and perform an atomic clean install or update. - Run
doctorverification and verify zero application files were altered.
(Note: In pre-release testing before the GitHub release tag v1.0.1 is published, point to the exact commit URL instead).
Terminal installation (alternative)
Use a clean Android Git checkout with its Gradle Wrapper and a kit checkout pinned to the same immutable release tag:
git clone --depth 1 --branch v1.0.1 --single-branch https://github.com/rabee-elkholy/android-agent-harness.git /path/to/android-agent-harness
python /path/to/android-agent-harness/harness_cli.py init --repo /path/to/android-project --kit /path/to/android-agent-harness
The wizard writes local answers, then the lifecycle engine stages and validates .agents, creates only selected host adapters, records ownership, and keeps all harness files out of the shared Git index through .git/info/exclude.
Legacy pre-v1 installs are intentionally not migrated in place. Preview and remove the old installation, then install v1 cleanly:
python harness_cli.py uninstall --repo /path/to/android-project --legacy
python harness_cli.py uninstall --repo /path/to/android-project --legacy --apply
python harness_cli.py init --repo /path/to/android-project --kit .
Task lifecycle
python .agents/scripts/workflow.py draft --repo . --task-id TASK-1 --outcome "Describe the result" --expected-surfaces BUSINESS_LOGIC --expected-modules :app
# Present plan and wait for explicit approval.
python .agents/scripts/workflow.py approve --repo . --task-id TASK-1 --source conversation --proof-reference MESSAGE-ID --enforcement-tier RULE_ENFORCED
python .agents/scripts/workflow.py begin --repo . --task-id TASK-1
# Implement the approved scope.
python .agents/scripts/workflow.py prepare-verification --repo . --task-id TASK-1
The developer—not the AI agent—runs the approve command. For a sensitive
final snapshot, the developer must also run approve-sensitive from their
terminal (or use non-synthesizable host-native approval) after reviewing it:
python .agents/scripts/workflow.py approve-sensitive --repo . --task-id TASK-1 --source developer_terminal --proof-reference LOCAL-CONFIRMATION --enforcement-tier RULE_ENFORCED
Read current-run.json and execute only the selected gates. If reviews are required, run review_package.py, dispatch exactly the selected reviewers, then ingest their unchanged responses or structured reports with record_review.py.
Finish with:
python .agents/scripts/workflow.py verify --repo . --task-id TASK-1
python .agents/scripts/workflow.py complete --repo . --task-id TASK-1
Lifecycle
python harness_cli.py update --repo /path/to/android-project --kit /path/to/new-kit
python harness_cli.py uninstall --repo /path/to/android-project # dry run
python harness_cli.py uninstall --repo /path/to/android-project --apply
python harness_cli.py doctor --repo /path/to/android-project --json
python harness_cli.py selftest --kit .
Updates are allowed only within architecture major 1, refuse modified managed files, preserve project-tailored Android references and Zoho defaults, validate the staged engine, and roll back on failure. Uninstall restores pre-install files and places modified harness-owned material in .harness-recovery.
See architecture, workflows, and quickstart.
1 maintainer
Release files for android-agent-harness 1.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| android_agent_harness-1.0.1.tar.gz | 281.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| android_agent_harness-1.0.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 631.9 kB
Release files / android_agent_harness-1.0.1.tar.gz
| Download URL | android_agent_harness-1.0.1.tar.gz |
|---|---|
| Size | 281.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fee95267235cd86f6679b5ddb60ecc0e3189f12091cd2752deaab5cca1571fec
|
|
BLAKE2b-256 checksum How to use checksums |
c586adc3cb03a8488742383c250a947f4e8ab3d472d0b18bb82beac627c65a15
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency logRelease files / android_agent_harness-1.0.1-py3-none-any.whl
| Download URL | android_agent_harness-1.0.1-py3-none-any.whl |
|---|---|
| Size | 350.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ed8a561b8b5d29889b2f160d95f0ee66a989937230aefde534b15e9c906b5b34
|
|
BLAKE2b-256 checksum How to use checksums |
51d171f782c05db9890f451c4ca3246ed88f7a403bbf9405be99d4555fca8eb5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 9, 2026.
Transparency log
