Changelog

Full release history is also on GitHub Releases.

1.0.0-rc.1

This release candidate makes the normal agent loop easier to follow and more reliable. Plain output now streams each phase and finishes with the complete device, app, Metro, cache, and log facts. JSON output remains available for scripts that need a stable payload.

Install and run

npx skills add appandflow/stim

npx --package=stim-cli stim doctor
npx --package=stim-cli stim start
npx --package=stim-cli stim ios              # or: npx --package=stim-cli stim android
npx --package=stim-cli stim logs --errors
npx --package=stim-cli stim stop

Launch readiness

stim ios and stim android wait for Metro to finish the bundle before the launch stability window starts. The commands then observe the app for three seconds and check that its process remains alive.

The final output reports whether the app is ready, still bundling, unverified, or failed. A Metro bundle failure or an exited app process fails the command. Errors observed during the launch window are printed for the agent to assess, even when the app remains alive.

Plain agent output

The platform commands stream the important build and launch phases as they happen. Their final plain-text summary includes:

• the full simulator UDID or emulator serial;
• the app ID;
• the Metro port and state;
• the native build cache result;
• the log directory.

The bundled skill recommends plain output for interactive agent work. It uses JSON only when another program must parse the result.

Owned simulator cleanup

An explicit stim stop shuts down a Stim-owned iOS simulator even when a device automation session is still active. Stim verifies ownership before the shutdown and never shuts down an unowned simulator.

This lets an agent keep its Agent Device session active through visual proof, run stim stop, and then close the automation session.

Error reporting

Native prebuild failures now appear in stim logs --errors. Bare React Native Metro logs also retain more launch context for diagnosis.

All four packages use version 1.0.0-rc.1 and are released together.

1.0.0-rc.0

This is the first release candidate for the stim-cli package family.

stim-cli gives each React Native or Expo workspace an isolated local development environment. Each workspace gets its own Metro port and its own simulator or emulator. Native builds and Metro transforms use shared caches, so parallel worktrees can reuse work without sharing runtime state.

The CLI is designed for coding agents. Commands never prompt. Status and progress go to stderr. Commands with --json print one machine-readable result to stdout. Failures include stable error codes, focused diagnostics, and specific remedies.

New

One complete agent loop

npx skills add appandflow/stim

npx --package=stim-cli stim doctor
npx --package=stim-cli stim start
npx --package=stim-cli stim ios              # or: npx --package=stim-cli stim android
npx --package=stim-cli stim logs --errors
npx --package=stim-cli stim stop

doctor reports project settings that can prevent correct or fast builds. start runs the project dev server under a detached supervisor. ios and android build or restore the app, install it, and launch it on the owned device. logs --errors gives the agent a direct pass or fail check. An empty result with exit code 0 means that the current error window is clean.

Isolated workspaces and owned devices

• Each project or worktree gets a reserved Metro port.
• Each environment gets a simulator or emulator named stim-cli-<label>.
• stim-cli operates only on devices that it created and recorded as owned.
• Physical devices and user-created virtual devices are outside the product scope.
• worktree create creates an isolated git worktree and prints only its path to stdout.
• worktree remove checks git state before it removes a worktree and its environment.
• stop stops the supervisor and shuts down the device without deleting it.
• gc reports stale state. Only worktree remove and gc --delete delete owned resources.

Several agents can work in parallel without sharing a bundler, device, runtime state, or project log stream.

Supervised dev servers and structured logs

start runs bare React Native Metro in process. It runs the project Expo dev server as a child when the project uses Expo. Both modes use the workspace's reserved port and verify server identity before reporting success.

The CLI merges bundler, client, build, and device records into one NDJSON timeline. logs can filter by time, source, level, text, or the current error window. logs --follow streams new records. status summarizes all managed environments and reports active processes, assigned devices, ports, cache results, and errors.

Shared native build cache

ios and android calculate a native fingerprint with @expo/fingerprint. A matching artifact can be reused by another worktree. The cache key includes the platform, build configuration or variant, and target class.

• iOS supports --configuration <name>.
• Android supports --variant <name>, including product flavors.
• Release builds skip Metro and contain the current JavaScript bundle.
• A release cache hit receives the current JavaScript before installation.
• A failed JavaScript swap falls back to a full build.
• Concurrent requests for one fingerprint use a single build.
• A configured Expo build cache provider can act as a second cache tier.

stim-cli also enables Xcode's compilation cache when the installed Xcode supports it. Android builds use Gradle's shared build cache. Device boot starts in parallel with compilation.

Shared Metro transform cache

@stim-cli/metro provides a Metro transform cache shared by every worktree. The package also provides the NDJSON reporter used by bare React Native dev servers. stim-cli injects the shared store without requiring a project change when the installed React Native or Expo version supports that path.

Cache inspection and cleanup

Cache packages register their storage with the shared cache manifest. stim gc reports registered and detected caches without deleting them.

npx --package=stim-cli stim gc
npx --package=stim-cli stim gc --delete --older-than 30
npx --package=stim-cli stim gc --delete --all

Age-based cleanup removes independent entries. Atomic stores, such as Xcode's content-addressed store, are emptied only with --all.

Machine and project settings

Project settings can select the iOS device type, iOS runtime, Android system image, Android build variant, worktree defaults, and project label. Machine settings can move cache roots and set optional build or device concurrency limits. Environment variables override machine cache and concurrency settings.

The CLI keeps runtime state under $STIM_CLI_HOME, which defaults to ~/.stim-cli. The normal workflow does not require generated project files or an initialization command.

Built-in agent guidance

The stim-cli package includes an agent skill and version-matched guidance. guide prints the reference for the installed CLI version. Topics cover facts, lifecycle, Metro, logs, errors, cleanup, and settings.

Packages

• stim-cli - the command-line interface and bundled agent guidance.
• @stim-cli/core - shared cache paths, cache keys, locks, and cache registration primitives.
• @stim-cli/metro - the shared Metro transform cache and NDJSON reporter.
• @stim-cli/expo-build-cache - a local Expo build cache provider for Expo-driven native builds.

All four packages use version 1.0.0-rc.0 and are released together.

Requirements and limits

• Node.js 20.19.4 or later on Node 20, or Node.js 22.12.0 or later.
• Xcode and an installed iOS Simulator runtime for iOS work.
• Android SDK tools and an installed emulator system image for Android work.
• Bare React Native and Expo projects are supported.
• Store signing, distribution builds, and physical devices are outside scope.
• The package surface can change during the release-candidate cycle.

The source, package documentation, and issue tracker are available at appandflow/stim.