v1.0.0-rc.0

stim-cli 1.0.0-rc.0 - isolated React Native environments for agents

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-cli

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-cli.