iPhone-use 0.2.1

iPhone-use 0.2.1 completes the packaged brand update: the Runner now includes the approved phone/swipe Logo, and the release includes updated installation guidance and the separate client plugin 0.1.6 with the iphone-use.com homepage.

Stable release. These are the exact locally verified candidate files, published without rebuilding. The public Homebrew formula and local upgrade are verified. Existing 0.2.0 release assets are unchanged.

Current CLI and plugin channels (2026-10-11)

Installation channel	Version	Contents
CLI / Homebrew	0.2.1	Published CLI and optional Runner; unchanged.
Plugin ZIP attached to this Release	0.1.6	The original verified archive and checksum; unchanged.
Git marketplace plugin	0.1.7	Approved Codex plugin/skill icons and display metadata; device workflow unchanged.

CLI and plugin versions are independent. To get the new plugin icons, update the Git marketplace and plugin; no new CLI release is required. Upgrading Homebrew alone does not update the plugin. These commands follow the marketplace's default branch; pinned sources need the steps in the repository plugin guide.

# Codex
codex plugin marketplace upgrade iphone-use
codex plugin add iphone-use@iphone-use

# Claude Code
claude plugin marketplace update iphone-use
claude plugin update iphone-use@iphone-use

Start a new client session and check the installed plugin version; restart the client if the display has not refreshed. Public Git upgrades from 0.1.6 to 0.1.7 and installed-file checks passed in both clients. The user confirmed the Codex icons display correctly. This later plugin verification does not add a phone-task acceptance or change the original 0.2.1 build evidence below. All existing Release attachments are retained; this note does not publish a new version or a replacement ZIP.

Changes from 0.2.0

• Adopt the approved Logo in the precompiled Runner's Home Screen icon.
• Update packaged installation guidance for the published channels, Homebrew migration/trust prompts, and standard-mode Apple PNG observations. Screenshot observation does not require an active media stream; recording owns its media session separately.
• Include plugin 0.1.6 as a separate ZIP for Codex and Claude Code. Both manifests point to https://iphone-use.com. CLI and plugin versions are independent; the CLI archive does not include the plugin.
• Retain the iphone-use command, agentsoma compatibility command and standard/Runner mode contracts. Device-control source did not change from 0.2.0; this is a branding and distribution update.

Provenance and assets

• Source: 0d8fe37d74e468165aebf30584c2640e3924b24a, clean main checkout.
• Built locally on Apple Silicon, macOS 27.0 (26A428), Xcode 27.0 (27A266a), Swift 6.4. These assets were not rebuilt by the GitHub release workflow.
• CLI archive: iphone-use-0.2.1-macos-arm64.tar.gz, SHA-256 2bb66dda320f789b27218fd5e7a9d1beea7475603e3a9d0c15b5215b369b64d8.
• Plugin archive: iphone-use-plugin-0.1.6.zip, SHA-256 5619f70065a199732e4b73d4b7fc4333ee264dd86315b83f3460a1796cd0b251.
• Each archive has a checksum sidecar. The attached iphone-use.rb was generated from this exact CLI archive; it references this versioned public release URL and exact checksum.

Completed host acceptance

• Swift: 427 tests, 1 skipped, 0 failures. Python: 55 passed after the debug build completed. Node: 18 passed. Runner event-bridge host runtime tests passed.
• Release CLI and unsigned iOS Runner built successfully. Archive checksum, complete file inventory, portable test manifest, licenses, strict CLI ad-hoc signature and allowed system-library dependencies passed verification.
• Relocated execution from a path containing spaces, symlink entry points, both command names, and isolated standard/Runner preferences passed.
• Manual 0.2.0 → 0.2.1 installation and rollback preserved isolated preferences. Runner payload verification covered all 12 files. Packaged icon was visually checked against the approved Logo.
• Homebrew installed the archive in an unlinked, separately named local candidate keg; only the test formula class/name changed. The install and test bodies were unchanged. brew test --force, CLI digest, all Runner digests and both command versions passed. That pre-publication check was separate from the production upgrade verified below.
• Plugin ZIP checksum, both manifests and all packaged files matched source. Public Git installation and plugin 0.1.4 → 0.1.6 upgrades had also been checked with Codex CLI 0.146.0 and Claude Code 2.1.250, including cache contents, skill discovery and preflight.

Acceptance limits

No physical-device acceptance was performed for these exact 0.2.1 bytes. This round did not connect to an iPhone, perform Runner setup or signing renewal, capture screenshots, or run a Moments task. Prior device results are not counted as new 0.2.1 acceptance.

The CLI is ad-hoc signed and is not Developer ID signed or notarized. Fresh-Mac onboarding, browser quarantine/Gatekeeper behavior, free Personal Team setup/renewal and additional hardware/toolchain combinations remain unverified. Plugin installation checks do not establish a new model-driven phone-task result or desktop UI refresh.

Installation and upgrade

Both modes require full Xcode. Standard mode currently requires macOS/iOS 27 and needs device trust, Developer Mode and an unlocked phone, but no Runner setup or developer signing. Optional Runner mode requires your own Apple development signing and provisioning. The new Runner content hash can require preparing this package again with iphone-use setup; do not assume an old prepared payload has the new icon.

Download the CLI tarball and matching .sha256, verify the checksum, and keep the complete extracted directory together. Follow its README for manual installation. Disconnect active sessions before switching versions. Retain the previous directory for rollback. Check command -v iphone-use and iphone-use --version to avoid invoking another installed version.

Plugin installation and upgrade instructions: client plugins. Disable the old AgentSoma plugin and any separately installed legacy skill before enabling the new identity.

Public-channel verification (2026-10-11)

All five anonymous downloads match the original candidate files; the public tag resolves to the recorded source commit. The Homebrew update workflow passed, and the Tap formula matches the attached formula byte for byte. A real local upgrade from the public 0.2.0 formula to 0.2.1 passed brew test, CLI and all 12 Runner file digests, and both command-version checks. Existing user preferences were unchanged and the old keg was retained. No phone operation was performed.

Install with brew install HughLee824/tap/iphone-use, or upgrade an existing installation with brew update followed by brew upgrade HughLee824/tap/iphone-use. The packaged README retains the pre-publication channel snapshot; current channel versions are recorded here and in the online guides. Existing 0.2.0 assets remain unchanged.

iPhone-use 0.2.0

iPhone-use 0.2.0

AgentSoma becomes iPhone-use, with native standard mode for screenshot/HID control and an explicit XCTest Runner mode for developer workflows. External agents plan and interpret the screen; iPhone-use reports device-access and execution facts.

Changes

• Standard mode observes through Apple PNG and executes native HID gestures, keyboard actions and clipboard-backed Unicode text, without starting Runner or silently switching to XCTest.
• Actions revalidate their original observation, with explicit Agent-confirmed caret/video exclusions and bounded post-action readiness. Unknown input is never automatically replayed.
• Native media is used for recording, with ownership-aware cleanup; it is no longer the standard screenshot source.
• Preserve optional Runner operation, shared recording support, and mode preferences. Reject Runner pinch callbacks arriving after the action deadline.
• Rename CLI, Swift targets, bundle identifiers and plugin to iPhone-use. Keep the agentsoma command compatibility entry and existing Logo.
• Correct the packaged installation guide: distinguish repository, Release, Homebrew and plugin availability, and explain Apple PNG observation, recording-only media sessions and read-only conflict checks before input.

Exact build

• Source: d79263dd58554705924f87459d2840c950c0eee2 (clean merged main).
• Toolchain: Xcode 27.0; Apple Silicon macOS package.
• Archive: iphone-use-0.2.0-macos-arm64.tar.gz.
• Archive SHA-256: 7c2c73f2451d093883b61b445981a1dc2f6714eaa14621d89c347ea1fd11af81.
• Plugin: iphone-use-plugin-0.1.4.zip.
• Plugin SHA-256: 060c8409ec4f8471dab3db50dee07aae3f309d03ce414b6bfb7d84ab42c0d983.
• Draft build and package workflow.
• Installation-guide PR CI.

Verification — host and package checks passed

The workflow passed Swift/Python/Node tests, CLI and unsigned Runner compilation, archive verification, relocated execution, plugin packaging, and Homebrew installation with CLI/Runner file-digest checks.

On 2026-10-11, the draft's actual five assets were downloaded and independently checked on the local Mac. Version, clean source commit, checksums, CLI/Runner manifests, relocated and symlink execution, isolated standard/runner preferences, ad-hoc signature and system-linked dependencies passed. The formula and plugin ZIP reproduced byte for byte from matching source; the downloaded plugin's preflight passed with the downloaded CLI.

The temporary cloud acceptance Tap warned that it had no old agentsoma formula. Installation and digest checks passed; the compatibility-command conflict rule remains for migration from the public Tap.

Device evidence and limits

No new physical-device acceptance was performed on this 0.2.0 archive. Earlier local candidate 0.1.0-dev.firstuse.20261011.21, source b8a5824032a4cc7b846802fc5c6beea7f1b8ec82, passed controlled standard-mode real-device browsing, Chinese draft input, paste-permission/menu recovery, visible verification, clearing, clipboard restoration and owned-session cleanup on iPhone 12 Pro / iOS 27.0.1. Those are prior-candidate results, not verification of these exact archive bytes. The subsequent Runner deadline fix has host regression coverage only.

Full Xcode is required. Standard mode currently targets macOS/iOS 27; Runner additionally needs the user's Apple development signing and matching provisioning. Free Personal Team onboarding/renewal and fresh-Mac browser/Gatekeeper installation are not established. The CLI is ad-hoc signed, without Developer ID signing or notarization.

Upgrade and remaining rollout

Disconnect active sessions before switching versions. Use iphone-use; the agentsoma compatibility command remains. Preferences move to ~/.iphone-use/config.json, with documented legacy preference migration. Renamed Runner identities require setup/re-signing; existing apps and signing state are not automatically removed.

The repository is now HughLee824/iphone-use. The attached Homebrew formula and plugin ZIP belong to this release. The public Homebrew formula is available from HughLee824/tap. The website at https://agentsoma.dev has been updated to the iPhone-use name and dual-mode installation guidance; the original Logo and domain remain. When the new formula is published, uninstall the old agentsoma formula before installing iphone-use because both expose the compatibility command. Avoid enabling duplicate old/new phone skills. Keep the current Logo and domain.

Packaged installation guidance now reflects the renamed repository, independent channel availability, Apple PNG observation and recording-only media ownership. The embedded README was verified byte for byte against this source. Public Tap and website rollout remain separate. Public channel verification is recorded separately from package and device evidence.

Public channel verification

On 2026-10-11, all five assets were downloaded anonymously from their public URLs and matched the verified draft digests. The public v0.2.0 tag points to the source commit above. The Tap update workflow passed and the public formula matches the release asset byte for byte. No assets were rebuilt or replaced during publication.

On Homebrew versions enforcing Tap Trust, installation may stop while reading the legacy agentsoma conflict formula. It must be explicitly trusted in addition to iphone-use before installation can complete; this does not require trusting the entire Tap. On the maintainer Mac, the formula-scoped trust was explicitly authorized; migration from agentsoma 0.1.0, installation of iphone-use 0.2.0, brew test, CLI/Runner digest checks, and both command version checks passed. No device operation was performed.

The bilingual website passed seven tests, checks of 17 pages and 574 local links/anchors, deployment dry-run, GitHub CI and Cloudflare deployment. Public site files and the 404 response matched the local build; the subsequent Tap Trust guidance was also verified live. The four previously reported website development-dependency findings were resolved on 2026-10-11 in website commit 0dee544: Wrangler 4.149.0 supplies sharp 0.35.5 and undici 7.29.1. A clean npm ci and full npm audit (including development dependencies) reported zero findings; website tests, local preview, deployment dry-run, GitHub CI and Cloudflare deployment passed. This website-only change does not modify the CLI release assets.

AgentSoma 0.1.0

Precompiled macOS CLI and iOS XCTest Runner for Apple Silicon. First stable release, under the MIT license.

Changes since 0.1.0-rc.1

• Add optional --observe to input commands so agents receive the action outcome and a fresh observation together. Action success and observation success remain separate; unknown input is not automatically replayed.
• Improve swipe diagnostics and guidance for precise wheel adjustments.
• Add tested action/observation orchestration guidance and clarify execution completion, screenshots, and authorized task verification.
• Document the tested command-line download channel and browser-download limitations.

Installation

Install the stable release:

brew install HughLee824/tap/agentsoma
agentsoma --version

For manual installation, follow the installation instructions and retain the complete CLI/Runner directory layout.

Compatibility

Apple Silicon / macOS 15+. Device setup requires full Xcode, a paired and unlocked iPhone with Developer Mode enabled, and your own Apple development signing certificate/private key and matching provisioning profile. Setup re-signs the precompiled Runner locally; it does not compile source.

The macOS CLI is ad-hoc signed, without Developer ID signing or Apple notarization. Command-line and Homebrew distribution are the intended channels. Browser download / Gatekeeper first-run acceptance is not claimed. Free Personal Team provisioning and renewal, a Mac without existing development signing, Intel Macs, and broader device/Xcode combinations are not validated.

Build and automated checks

• Version: 0.1.0
• Source commit: 25bef5092aac42a3f60bf1ec01b7ba79e12bee5d
• Archive: agentsoma-0.1.0-macos-arm64.tar.gz
• SHA-256: c2eb4f1ee1e2c61cf05bfae46076f38d18c3385a6b0a5ab2c9181ed933fec80d
• CI and release checks: passed.
• Swift/Python tests, archive integrity, relocated CLI execution, code-signature integrity, Homebrew installation and installed CLI/Runner digests: passed. Hosted checks do not connect to a physical phone.

Exact-package local device acceptance — passed

Maintainer: Hugh Lee. Date: 2026-09-07. Environment: Apple Silicon, macOS 15.0.1, Xcode 16, iPhone 12 Pro on iOS 26.6.1, existing paid development signing.

• Downloaded the release artifact, matched the source/version/archive SHA-256 above, and installed the complete package outside the source checkout. No rebuild was used for acceptance.
• Setup passed without compilation; repeat setup reused the prepared Runner without compilation. Upgrade from a previous stable release: not applicable (first stable release).
• Connect, app discovery, open, observe, guarded input with --observe, and disconnect passed. A stale-screen guard rejection dispatched no input and recovered after a fresh observation.
• Calculator produced 125 × 8 = 1,000; both screenshot and accessibility text were checked. After disconnect/reconnect, History retained today's calculation and result; screenshot and text were checked again.
• Setup verification sessions and both explicit sessions cleaned up successfully. Both explicit sessions acknowledged shutdown, exited xcodebuild with code 0, and removed observation caches; host/process exit was independently checked. Private device identifiers, signing details, screenshots, and command logs remain local.

Public distribution acceptance — passed

• Tap update passed. Formula commit: ab3cc80fc7af9db4483177f334c9f3cd686e1505.
• All three anonymously downloaded release assets were byte-for-byte identical to the accepted files; the public tag points to the accepted source commit.
• Actual brew install HughLee824/tap/agentsoma and brew test HughLee824/tap/agentsoma passed. The installed CLI and all Runner file hashes match the manifest.
• The Homebrew-installed CLI connected to the same iPhone, captured and visually verified Calculator history, completed a guarded tap with a fresh observation, and disconnected with normal process/cache cleanup.

The attached agentsoma.rb pins the same versioned download URL and archive checksum.

AgentSoma 0.1.0-rc.1

Precompiled macOS CLI and iOS Runner for Apple Silicon, under the MIT license. This is the first release candidate.

Build

• Version: 0.1.0-rc.1
• Source commit: 19588023d25125098946788b9eebe58b125efc71
• Archive: agentsoma-0.1.0-rc.1-macos-arm64.tar.gz
• Archive SHA-256: 52ff3e7c8e90d142a704ec1914433c506ebcc4d92245b3a48db188d0934a174d
• Automated checks: GitHub Actions (attempt 1)

Changes

• Distribute the precompiled macOS CLI with its matching iOS XCTest Runner. Device setup re-signs the Runner locally using the user's development signing; it does not compile source.
• Connect through native CoreDevice networking and reuse a device session across CLI calls.
• Capture screenshots and accessibility observations, with cached inspection and observation-bound references.
• Provide guarded taps and swipes, swipe speed and hold controls, text insertion/replacement, and explicit Return. Action outcomes distinguish completed, not dispatched and unknown; unknown actions are not automatically replayed.
• Include package manifests, SHA-256 checksums, source provenance and MIT/dependency licenses. Stable releases can be distributed through the project Homebrew Tap; this candidate uses manual installation.

Automated checks — passed

• Swift and Python tests.
• Archive integrity, relocated CLI version/help commands and Mac code signature verification.
• Homebrew installation and installed CLI/Runner file digests.

These checks ran on GitHub-hosted machines without a physical iPhone. Device checks below ran locally against the same archive.

Local device acceptance — passed for the stated environment

Validation date: 2026-09-06. Execution: Codex-assisted local acceptance. Maintainer review: approved for publication on 2026-09-06.
Environment: Apple Silicon, macOS 15.0.1, Xcode 16.0 (16A242d), iPhone 12 Pro, iOS 26.6; existing paid Apple development team signing.

• Downloaded the same archive from the build's Actions artifact and matched its version, source commit and SHA-256 to this draft.
• Installed the complete package outside the source checkout, in a path containing spaces; relocated CLI version/help commands and signature verification passed.
• Setup succeeded with compiled:false; repeated setup returned reused:true and compiled:false. Upgrade from a previous public release is not applicable to this first release.
• Connected through native CoreDevice, captured screenshots and accessibility observations, queried a cached observation, performed input actions and disconnected normally.
• Calculator task: entered 125 × 8; the final screenshot, accessibility text and cached query confirmed 1,000. After disconnecting and reconnecting, History still contained 125 × 8 = 1,000, verified by screenshot and accessibility text. The reopened input field itself showed 0.
• Both explicit sessions and both setup verification sessions ended normally: shutdown acknowledged, no forced termination, xcodebuild exit code 0, observation caches removed, and host/xcodebuild processes exited.

The initial locked-device setup attempt returned device_locked; retrying after unlocking succeeded. One tap based on an opening-animation observation was rejected with screen_changed / not_dispatched, before input started. A fresh observation allowed the intended action to complete. Nine taps completed across the calculation and history checks.

This archive's local input checks cover taps. Precise scrolling and text entry, including a non-default-duration Lark calendar task, were not exercised here. Raw device identifiers, profiles, screenshots and logs stay local.

Installation and compatibility

This candidate provides an Apple Silicon / macOS 15+ archive. Download the tar.gz and its .sha256 file together. See the package README or installation instructions. Preserve the complete package layout.

Chrome reported ERR_BLOCKED_BY_CLIENT during the Release asset redirect. The exact archive was retrieved through the GitHub Actions artifact connector and its hash matched this draft. Browser download and Gatekeeper acceptance remain pending.

Device setup requires full Xcode and your own Apple development certificate, private key and matching provisioning profile. Free Personal Team onboarding and renewal, clean-Mac onboarding, Intel Macs and broader iOS/Xcode combinations are not validated. The Mac CLI is ad-hoc signed, without Developer ID signing or notarization.

This prerelease uses manual installation. The stable Homebrew Tap does not distribute release candidates. A stable 0.1.0 release requires its own versioned build and acceptance; do not rename these RC assets.