apple-agent-kit

Apple Agent Kit

Proof-driven macOS and iOS automation for coding agents.

Apple Agent Kit gives Codex, Claude Code, and CI reusable playbooks, dry-run scripts, GitHub Actions templates, schemas, and privacy-safe evidence rules for Apple app repos. The public kit owns the generic automation contracts; private adapters supply projects, schemes, runner labels, devices, signing, fixture commands, and evidence policy.

Start with eligibility. Promote only when the proof is clean.

Start Here

git clone https://github.com/neonwatty/apple-agent-kit.git
cd apple-agent-kit
python3 scripts/validate-release.py
python3 scripts/aak.py inspect --repo . --adapter templates/adapter.example.json --json
python3 scripts/aak.py render-workflows --adapter templates/adapter.example.json --output /tmp/aak-render --force

See Install and Reuse for Codex and Claude Code validation paths, including local plugin validation and source-checkout testing.

What It Enables

Stage	Use it for	Public safety boundary
Intake	Inspect an Apple repo and choose relevant automation tracks.	Read-only; no device, runner, app, or account actions.
Adapter validation	Check the private adapter shape before running workflows.	Real project, signing, runner, bundle, and device values stay outside this repo.
Workflow rendering	Render reusable GitHub Actions workflows into scratch space for review.	Rendering is dry-run oriented and reports no physical-device actions.
macOS and iOS eligibility	Prove a repo can consume AAK before product automation.	No product build/test, app launch, screenshots, WDA, simulator boot, or physical-device work.
Fixture UI smoke	Promote to deterministic GUI proof against sterile fixture apps, demo modes, or test-only surfaces.	Manual dispatch, exact approval input, validated receipts, adapter allowlisted artifacts only.
xcresult proof	Assert the expected XCTest or UI smoke method actually appeared in result-bundle output.	Emits sanitized counts and assertion results, not raw bundle internals.
Runner health	Check self-hosted Mac runner readiness.	Runner labels and host details stay private; no product or device work.
Manual remote PR session	Request exact-SHA work from a private Mac through a pull-based artifact contract.	Public workflow creates a validated request only; private adapters decide what runs.
iOS physical device	Manually prepare an approved preview-device readiness or smoke run through a private adapter.	Requires exact approval input and private approval reference; no device identifiers, raw inventories, screenshots, or app data in public evidence.

Proof-Backed Adoption

Current public proof records show the eligibility path working across macOS and iOS app repos, plus the first sanitized manual remote PR session proof:

• Foil macOS CI Eligibility Proof
• Foil iOS CI Eligibility Proof
• PRCard iOS CI Eligibility Proof
• PRCard Manual Remote PR Session Proof
• PRCard iOS Physical-Device Readiness Proof

For the source-backed capability map, adoption summary, next-step recommendation, and landing-page plan, see Apple Agent Kit Positioning And Landing Page Plan.

Public And Private Split

This public repo contains reusable patterns only:

• skills and agent playbooks;
• dependency-free scripts;
• workflow templates;
• adapter and receipt examples;
• schemas;
• privacy-safe evidence rules;
• sanitized proof records.

Private adapters belong in app repos or secrets. They provide concrete project paths, schemes, bundle identifiers, signing values, runner labels, device choices, fixture commands, and screenshot/evidence policy.

Repository Shape

• .codex-plugin/plugin.json - Codex plugin manifest.
• .claude-plugin/plugin.json - Claude Code plugin manifest.
• skills/ - Agent-facing playbooks.
• docs/ - Design, adapter contract, evidence policy, and operating notes.
• scripts/ - Generic helper scripts that must not contain app-specific values.
• templates/ - Reusable workflow and config templates.

Install And Validate

Apple Agent Kit v0 is source-first. Start with:

git clone https://github.com/neonwatty/apple-agent-kit.git
cd apple-agent-kit
python3 scripts/validate-release.py

v0 Commands

The v0 command surface is dependency-free Python and dry-run oriented: