Skip to main content

Changelog

Full release history is also on GitHub Releases.

1.0.0​

New​

  • The CLI is now published as stim. All five packages move together to the first stable release, 1.0.0. 256516b0ff
  • Select a shared Xcode app scheme with ios --scheme <name>. Explicit schemes use separate build directories and cache keys, and resolve the actual product even when its name differs. 33ecb66ff9
  • Reset one app's Metro transforms and file-map state with start --reset-cache, preserving other apps and native build caches. 7cc5276586
  • Each monorepo app reads its own committed .stim.json beside its package manifest. App-relative profiles and cache-provider paths resolve from that directory. c9fb9568a4

Fixes​

  • Android's unverified-launch remedy uses the resolved launcher activity or dev-client URL to restart the app. Printed URLs preserve query parameters through both host and device shells. f2dd053af5

  • Android launch previews compact nested Metro error JSON into a readable module diagnosis, code frame and import stack. Previously unseen context is retained; logs and JSON preserve full captured evidence. 912b8fd863

  • Doctor warns about effective multi-architecture Debug simulator settings, including generated Pods and imported configuration. It reports but does not rewrite project policy. 7afb23c8da

  • Doctor identifies linked native libraries whose Git metadata enters the fingerprint and prints narrow ignore entries for projects that do not build from that metadata. 89e9280f0c

  • Android workspaces with the same app-directory name receive distinct owned emulators instead of failing on a name collision. Existing device assignments are preserved. 529f7c68f2

  • Bare iOS reload failures include an exact-app relaunch fallback when no Reload control is visible, preserving the automation session, simulator and Metro port. The remedy warns about losing in-memory state. 71484ba0ae

  • iOS resolves a listed app scheme from the static app.json name when a differently named workspace and multiple schemes make the existing selection ambiguous. The error distinguishes a naming mismatch from an unshared scheme. 5aa719fcfd

  • iOS simulator launches allow up to 60 seconds for CoreSimulator to respond, preventing the previous 10-second deadline from aborting a slow successful launch. App readiness and crash checks remain unchanged. 8221162342

  • A workspace waiting for a shared native build no longer reports failure just because native preparation changed the cache key. It retains the wait result after validating the artifact under its own final key. fd65de16ec

  • stim worktree warm copies ignored state directly into the destination, avoiding the extra staging and publication passes. Same-volume APFS copies request copy-on-write; missing paths are copied and existing entries are kept. 49ae2fce16

  • Doctor checks the actual source and destination volumes when reporting worktree-copy performance. 49ae2fce16

Docs​

  • Refresh startup-crash benchmark results and keep timeline endpoint circles visible. 2d192f66e7, 591df79435
  • Document that warming must finish before editing, installing dependencies, starting Metro, building, or running another warm in the destination. Concurrent destination writes are unsupported. 49ae2fce16

Migration notes​

  • Replace npx stim-cli with npx stim. For global installations, uninstall stim-cli before running npm install --global stim so the old and new packages do not compete for the same executable. The command remains stim; the four @stim-cli/* companion package names are unchanged.
  • Keep worktrees on the source checkout's filesystem for copy-on-write warming. STIM_TMPDIR does not relocate this direct copy. Wait for warm to complete before writing to its destination.
  • In monorepos, move repository-root runtime settings into each relevant app's .stim.json; apps no longer inherit that root file. Keep repository-wide worktree.exclude rules at the main checkout root. Machine-level project and repository overrides retain their precedence.

1.0.0-rc.23​

Fixes​

  • Launch errors show compact, labeled error, component, and native stacks with up to 10 frames each, prioritizing app code. Every stim logs query retains full captured stacks. be15388437, dfd342114e
  • Resolve JavaScript stack locations through the workspace's Metro and preserve the symbolicated context for later queries. Capture attributable native crashes on iOS simulators and Android, combine duplicate reports, and preserve Java cause chains. Native symbolication uses matching symbols where available. dfd342114e
  • Show a warning when the native app stays alive with a JavaScript launch error, and explain when a delayed iOS crash report needs another logs query. Launch JSON and exit-code contracts remain unchanged. dfd342114e

Docs​

  • Clarify stack previews, full captured logs, symbolication limits, and delayed native crash reports in the version-matched guides and website. dfd342114e

QA​

Expedited RC authorized on 2026-09-09. Omitted locally before the version commit: format:check, lint, typecheck, knip, unit tests, test:e2e, test:runtime, and the pre-tag native/manual matrix. Retained before the version commit: candidate build, CLI version/help/guide, and tarball inspection. Retained after push: exact-release-commit CI, including its format, lint, build, typecheck, knip, unit, cross-platform e2e, and published-runtime jobs.

Pre-merge evidence includes JS errors on iOS and Android, Swift fatalError, Java IllegalStateException, JNI abort, and repaired app launches on both platforms. Captured command output. This evidence predates the version bump; the full native matrix is not rerun against the release candidate. Physical and remote devices were not tested.

1.0.0-rc.22​

New​

  • Recycle compatible Android emulators across worktrees. Adoption clears app data, retains matching APKs to skip installation, and recovers from signer or version conflicts. The default pool holds three emulators. ea0292b1
  • Wait for optional [stim:readiness] pending and ready device logs during launch, and report whether readiness completed, timed out, or failed. 689ad047

Removed (breaking)​

  • Remove the legacy caches.injectMetroStore machine setting. Use optimizations.metroSharedCache instead. 2c585854

Fixes​

  • Wait for Metro to deliver the bundle before starting launch-stability checks. a4832aa3
  • Align Android device-log timestamps with the host clock so launch filters include the current app's logs. dd0f2c5e
  • Resolve dynamic imports from nested modules when bare Metro uses a hoisted metro-runtime package. 1fe471f5
  • Restart a stuck Android app when following the unverified-launch remedy. 6230e4aa

Docs​

  • Document build optimizations, Android CAS, emulator recycling, and optional readiness reporting. Refresh the website and publish activity-timed Android and iOS launch-error benchmarks. 2c585854, 1f9fc1e8, c2f848b4

Migration notes​

  • Replace caches.injectMetroStore: false with optimizations.metroSharedCache: false to keep shared Metro caching disabled.
  • Set pool.androidParkedMax to 0 when a fresh emulator is required. Recycling preserves system apps, shared storage, accounts and device settings; app data is cleared at adoption. Older AVDs without recorded creation settings are deleted when removed.

QA​

  • Full preflight: formatting, lint, build, typecheck, knip, 3,737 unit tests, 66 end-to-end tests, Node 20.19.4 runtime checks, website build, and all five packed tarballs passed.
  • Native loop and cache suites passed for bare React Native and Expo on both iOS and Android. Both device-pool suites passed.
  • Manual QA covered readiness success, timeout and error; nested dynamic imports; healthy, broken and repaired logs; UI interactions; and Trailhead on both platforms, including native cache reuse across worktrees.
  • Android release QA verified current JS in the installed, signed and aligned APK after adopting an emulator with a differently signed app.
  • A newly booted Android emulator can initially return unverified. Follow the printed restart remedy and verify the UI. The recovery instruction was corrected during this QA pass. iOS may require the printed UI Reload fallback when Metro cannot identify its peer. Earlier client errors remain visible until the next launch, as documented.
  • Authenticated remote providers, physical-device signing, Android flavors, and iOS release swapping were omitted because those implementations did not change. Shared launch and lease behavior has simulator/emulator and unit coverage.

1.0.0-rc.21​

Fixes​

  • Persist exact process identities for Stim-owned supervisors, log collectors, and managed tunnels instead of inferring host-process ownership through ps. Use unique-pid@0.1.1 so permitted process inspection works in macOS sandboxes that deny boot-session metadata. Cleanup retains unverified records and leaves replacement processes and their device claims alone. dfaeae32

Removed (breaking)​

  • Remove stop --force. Stim no longer terminates externally started Metro servers or infers process ownership from a port, command name, or directory. dfaeae32

Migration notes​

  • Stop a still-running legacy supervisor manually before starting a replacement when its saved state has no verifiable process token. Externally started Metro remains reusable but must be stopped by its owner.
  • Process checks and signals are separate OS operations. On macOS, a token captured without boot identity cannot distinguish a repeated PID and exact start timestamp after a reboot or clock reset. Denied process inspection is not treated as proof that a process exited.

QA​

Expedited RC authorized on 2026-09-07. Omitted locally before the version commit: format:check, lint, typecheck, knip, unit tests, test:e2e, test:runtime, and the pre-tag native/manual matrix. Retained before the version commit: candidate build, CLI version/help/guide, and tarball inspection. Retained after push: exact-release-commit CI, including its format, lint, build, typecheck, knip, unit, cross-platform e2e, and published-runtime jobs.

The included PR passed independent review, 3,602 unit tests, 66 end-to-end tests, and required CI before merge. Forty collector-ownership and reclaim tests also passed inside the actual Codex sandbox with the published library. These checks are not a substitute for the omitted candidate native/manual QA.

1.0.0-rc.20​

When Stim is not installed globally, replace stim with npx stim-cli.

New​

  • Configure build optimizations with machine defaults and repository/project overrides: artifact and remote caches, release bundle swapping, Metro sharing, iOS compilation caching and prefix mapping, and Android compiler cache, PCH, Gradle cache, and target ABI settings. See stim guide settings. a4e2251
  • Opt into experimental Android PCH caching across worktrees using Apple Clang CAS on macOS. This requires a manually prepared compatible compiler/NDK toolchain; see the Android CAS report for setup, evidence, and compatibility limits. f45d9e2

Fixes​

  • Distinguish harmless executable lookups from actual device commands when auditing benchmark isolation, while retaining checks for real invocations. a563dad

Docs​

  • Complete the published Android benchmark coverage and omit private inventory data from benchmark exports. df12e17

Migration notes​

  • Shipping defaults are unchanged: Stim-supplied Android ccache disables PCH. CAS is a mutually exclusive opt-in through optimizations.android.compilerCache and a toolchain manifest.
  • Android compiler/PCH modes use separate generated CMake profiles so switching backends does not retain a previous compiler. Old profiles accumulate; worktree removal reclaims them.
  • CAS is experimental. Automatic toolchain installation, broader project compatibility, and CAS eviction/diagnostics remain unfinished.

QA​

Expedited RC authorized on 2026-09-07. The pre-tag native and manual QA matrix was omitted. The candidate passed formatting, lint, build, typecheck, knip, all 3,664 unit tests, all 66 E2E tests, the runtime check, CLI version/help/guide checks, and inspection of all five tarballs. Publishing remains gated on CI for the exact release commit, including Node 22, Node 24, and the published Node 20.19.4 runtime.

1.0.0-rc.19​

When Stim is not installed globally, replace stim with npx stim-cli.

Fixes​

  • Enforce benchmark runner filesystem isolation for coordinator data and sibling runs, with verified access checks before timing starts. 5751260
  • Correct benchmark auditing of quoted shell commands and separate crash launch/error capture. e2cb47a d53bebf

Docs​

  • Require worktree warming to finish successfully before starting Metro, building, or installing dependencies. A shell job ID is not completion. 35a77e4
  • Refresh validated Android and launch-recovery benchmark results on the website. e62e6f7

QA​

Expedited RC authorized on 2026-09-06. Omitted locally before the version commit: format:check, lint, typecheck, knip, unit tests, test:e2e, test:runtime, and the pre-tag native/manual matrix. Retained before the version commit: candidate build, CLI version/help/guide, and tarball inspection. Retained after push: exact-release-commit CI, including its format, lint, build, typecheck, knip, unit, cross-platform e2e, and published-runtime jobs.

1.0.0-rc.18​

When Stim is not installed globally, replace stim with npx stim-cli.

Fixes​

  • Warming an Android worktree excludes generated autolinking caches, including nested apps, so Gradle resolves native dependencies inside the new checkout. 1fac645
  • Keep large temporary copies on the operation's volume, including worktree warming and cached app preparation. STIM_TMPDIR or machine tempDir overrides placement; doctor reports cross-volume copies. 20232f3
  • Repair stale Android CMake launcher configurations with stim doctor --fix --platform android, including installed native modules. Stop all native builds before repair; custom launchers and shared ccache entries are preserved. 008d057
  • Validate benchmark cache entries with the pinned CLI's fingerprint library. 0079fb3
  • Audit benchmark device-session scoping per shell command, accepting correctly scoped delayed navigation and rejecting unscoped invocations later in a chain. 782b8c5

Docs​

  • Explain the workflows where Stim adds little value on the homepage. fb82b23

QA​

Expedited RC authorized on 2026-09-06 after disk pressure paused the native matrix. The product candidate passed formatting, lint, build, typecheck, knip, 3,605 unit tests, 66 end-to-end tests, runtime smoke, and tarball inspection. Real Gradle autolinking regeneration and CMake launcher repair were verified. Native bare Android and bare/Expo iOS workflow checks passed, as did the bare iOS cache suite.

Omitted before the version commit: the remaining native cache matrix, Expo Android workflow, and manual Release-artifact checks. Final candidate build, version, help, guide, and all five tarball inspections are retained, together with blocking CI on the exact release commit, including Node 22, Node 24, and the Node 20.19.4 published-runtime job.

1.0.0-rc.17​

If Stim is not installed globally, replace stim below with npx stim-cli.

Fixes​

  • Android builds disable CMake precompiled headers by default when Stim supplies ccache, improving compiler-cache reuse across worktrees. Explicit project PCH settings are preserved; builds without Stim's ccache setup and iOS builds are unchanged. The tradeoff is slower cold C++ compilation. (9418d3d)
  • The repository's benchmark harness flags missing or below-target Android compiler-cache evidence, retains failed attempts for investigation, and excludes them from published comparisons. Android preparation and preflight also require a doctor report without cost findings. (872bb1f)

Docs​

  • stim guide agent keeps the workflow, safety rules, and recovery actions up front. Optional cache warm-up, ABI selection, fingerprint fallback, and build-sharing details live in the build and concurrency guides. (1c420aa)

QA​

Expedited RC authorized on 2026-09-06. Omitted locally before the version commit: format:check, lint, typecheck, knip, unit tests, test:e2e, test:runtime, and the pre-tag native/manual matrix. Retained before the version commit: candidate build, CLI version/help/guide, and tarball inspection. Retained after push: exact-release-commit CI, including its format, lint, build, typecheck, knip, unit, cross-platform e2e, and published-runtime jobs.

1.0.0-rc.16​

If Stim is not installed globally, replace stim below with npx stim-cli.

New​

  • stim doctor reports the running CLI version, the first stim executable resolved from PATH, and every distinct Stim installation found on PATH. It flags the setup when the resolved executable is older than the CLI currently running. (0070bae)

Fixes​

  • The benchmark harness accepts ABI-scoped Android APK cache keys when validating a native-change run. (93bfeb1)
  • Benchmark run guards reject the wrong Stim version inside the timed shell, enforce inactivity and hard timeouts across process trees, and preserve failures hidden inside shell chains. (e3410c2)

Docs​

  • The release guide defines an explicitly authorized expedited lane for release candidates, including the checks it may omit and the package, CI, tagging, and publishing safeguards it must retain. (5da0e95)

QA​

Expedited RC authorized on 2026-09-05. Omitted locally before the version commit: format:check, lint, typecheck, knip, unit tests, test:e2e, test:runtime, and the pre-tag native/manual matrix. Retained before the version commit: candidate build, CLI version/help/guide, and tarball inspection. Retained after push: exact-release-commit CI, including its format, lint, build, typecheck, knip, unit, cross-platform e2e, and published-runtime jobs.

1.0.0-rc.15​

If Stim is not installed globally, replace stim below with npx stim-cli.

New​

  • stim worktree warm copies missing ignored dependencies, native output, and local configuration from the main checkout into an existing linked worktree. Existing entries and tracked files are preserved. (6412169)
  • stim reload [ios|android] reloads JavaScript on a running owned simulator or emulator without rebuilding or reinstalling the app. It reports the requested reload, selected device, Metro port, and strategy; app-side completion still needs verification. (43da17e, 24d6d71)
  • Sectioned guide topics support stim guide <topic> <section>, including direct error-code lookup such as stim guide errors STIM_NO_METRO. (d377e92)
  • Owned Android emulators use Quick Boot where supported. Shutdown waits for the emulator and snapshot save to finish, and uncertain process locks prevent deletion. Displayless Linux keeps snapshots disabled. (e6ddc3a)

Removed (breaking)​

  • worktree create, --carry-ignored, and creation-only settings are removed. Use Git to create worktrees, then run stim worktree warm when you need ignored files from main. Tracked edits are no longer copied. (834b338)

Fixes​

  • Warming preserves APFS clones through file publication on macOS, avoiding full data copies while keeping existing files safe. Files remain independent of the main checkout. (0a5c2fa)
  • Benchmark overview links open the selected platform's audit, including Luna's Android JavaScript result. (5d3aced)
  • Android shutdown flushes guest writes before killing the emulator, with a five-second limit so a stalled flush cannot block cleanup. (3abbb87)
  • iOS skips cache lookup and storage when the final fingerprint cannot be computed, preventing an artifact from being stored under its earlier key. (74d9a3e)
  • Commands waiting for a native build keep waiting when another process takes over a failed builder's lock. (70f3108)
  • Android Debug builds target the selected device's ABI and route eligible CMake compilation through ccache. (0e5eb6d, b9743cd)
  • start, ios, and android reject directories that are not React Native or Expo apps; doctor reports the problem as a finding. Invalid relative registry paths are reported as invalid records, and worktree Git commands pass paths as arguments. (360d871, c93997f, b7100dd)

Docs​

  • Native cache QA uses a normally built disposable source checkout and separate empty test caches. (8865207)

  • The agent workflow verifies UI changes on the reported device and checks logs again before cleanup. (0dff4a2)

  • Error-guide headings match emitted messages, and shared-lock guidance covers the records those locks protect. (8576b5e)

  • Setup, platform requirements, device ownership, and reload guidance now agree across the CLI and website. A successful log query is distinguished from a clean log result. (b264ffa, 0ab7174, cc34d57)

  • The skill description names common agent tasks while retaining its single version-matched guide command. (82e7ac9)

  • The benchmark website has separate platform/model selectors, visible unavailable combinations, and published Android results. (ebe5359, 9c54814, 8fde8cc)

Migration notes​

stim worktree create and --carry-ignored are removed. Create the checkout with Git, then warm it from inside the new directory:

git worktree add -b my-feature ../my-feature HEAD
cd ../my-feature
stim worktree warm

If an agent harness already created the worktree, run only stim worktree warm. Warming never applies the main checkout's tracked edits. Remove worktreeDir, worktree.baseRef, worktree.include, and .worktreeinclude from project setup; worktree.exclude and .worktreeexclude still control warming. stim worktree remove works with warmed and unwarmed worktrees and retains Git-created branches.

stim guide errors, lifecycle, facts, and cleanup now print a section index. Add the section name to read its full guidance. The agent, Metro, logs, and settings topics remain whole. (d377e92)

The website build retains two accepted high-severity image-size denial-of-service advisories: GHSA-5p2g-fcmc-qvqq and GHSA-w3rx-r6r6-pgpr. A malformed local image can hang a website build. The audit exceptions do not fix the parser; published Stim packages do not depend on it. Docusaurus tracks a replacement in #12231.

The remaining native-device validation continues after this candidate is published.

1.0.0-rc.14​

New​

  • a19b03a adds a separate JavaScript launch-crash benchmark that measures diagnosis and recovery without mixing those results into readiness charts.
  • ea416bf adds audited Android agent benchmark results alongside the iOS results.
  • c69d4ae adds simulated prompt responses to the benchmark website.

Fixes​

  • bdd19a6 includes available Expo and bare React Native code frames and stacks in human stim logs --errors output. Launch errors now distinguish a live native process from an exited process so agents can avoid unnecessary native rebuilds; an exited process still needs another native launch.

Docs​

  • The benchmark presentation now preserves terminal output, follows timeline playback, uses clearer event labels, aligns interaction video, and improves prompt-card spacing (573546d, 07f670a, 52f486d, 0d56b35, 9b1f822, f660636).
  • a41b6cb updates the documented cache-savings examples to match measured results.
  • 8ae44bd publishes the strict Sol iOS benchmark report.

1.0.0-rc.13​

New​

  • 91724f4 structures successful stim doctor output into labeled project, platform, shared-service, and automatically handled checks, and adds the selected platform to reports with findings.
  • f06cd45 adds stim guide agent as the version-matched coding-agent workflow. The skill installed by npx skills add appandflow/stim is now a tiny one-time router to that CLI guidance.

Fixes​

  • 58140dc removes dangling separators when Stim shortens long owned iOS simulator names.

Docs​

  • The benchmark site now includes an overview, interactive timeline, model selection, playback, valid-attempt filtering, run activity, zoom, deep links, grouped background lanes, Safari gestures, corrected device-session evidence, and clearer result labels (efb389d, 198c996, ff52efc, 0ba0db6, fbadca6, 7ab80fa, e6d8040, 47802ba, f2c2752, 7689578, d91a97e).
  • 82855e0 adds copyable prompts for common build, device, log, cache, and PR-validation workflows and clarifies when agents should use Stim or create a worktree.
  • 3390c6f adds an automated continuous benchmark replay for the website and social sharing, including the audited clock and recreated real-speed device interaction.

1.0.0-rc.12​

Fixes​

  • 98480e9 maps slash-separated worktree names to flat + paths instead of percent-encoded %2F paths, avoiding nested Xcode build failures while preserving the Git branch hierarchy.

Docs​

  • 4f1e3bd defines the benchmark v4 readiness protocol for separate JavaScript and native passes, exact device evidence, failure arms, and timeline artifacts.

Migration notes​

Existing rc.11 %2F worktrees are not migrated. Continue or remove them from their current checkout; newly created slash-named worktrees use +.

1.0.0-rc.11​

New​

  • stim doctor --platform ios|android keeps shared checks while filtering native findings and fingerprint parity to the selected platform. Android-only checks no longer invoke Xcode tooling (901b561).

Fixes​

  • stim worktree create accepts safe slash-separated names such as bench/run-1, preserves the hierarchy in the Git branch, and derives a collision-resistant single-directory checkout and device label (5b17558).

Docs​

  • Documented the v3 agent benchmark matrix across JavaScript and native changes, Stim and direct-tool control arms, and supported coding models (4a1bc15).

Migration notes​

  • Existing stim doctor and slash-free stim worktree create invocations keep their current behavior.

1.0.0-rc.10​

New​

  • Owned iOS simulators can be parked when a worktree is removed and adopted by a later matching workspace. Adoption resets app data, privacy grants, keychain state, and other user apps; ownership and cleanup remain fail-closed across crashes and concurrent garbage collection. status and gc expose the bounded pool, whose machine default is three simulators (9136251).
  • stim stats aggregates build timing and cache effectiveness without changing the build lifecycle (4d0cabb).
  • iOS runs can select an installed simulator with --device-type and --runtime; Android runs can select an installed image with --system-image (c29c6bd).

Fixes​

  • iOS fingerprints are computed while the simulator boots, and a simulator booted by the current run is not redundantly listed again (9dbba71, e66bde6).
  • Long native builds emit phase-named heartbeats sized from the project's last cold build instead of a fixed interval (91a1d6e).
  • Worktree, server, device, and platform-run output uses one consistent phase vocabulary (e759551, 1daa954, b91ca0a).
  • iOS simulator log collection anchors its process predicate to the installed app executable path, avoiding matches from unrelated processes (b3915e0).
  • Workspace overrides move uuid, serialize-javascript, and qs to patched dependency versions (029854b).

Docs​

  • Added the simulator-pool and aggregate-statistics designs, and documented the stacked pull-request workflow used for dependent changes (d8de9c8, 7ebed3e, d017f3c).

Migration notes​

  • No command migration is required. Projects that require a completely fresh simulator system image for every worktree can set pool.iosParkedMax or STIM_POOL_IOS_PARKED_MAX to 0.

1.0.0-rc.9​

Fixes​

  • Android builds are re-fingerprinted after Gradle succeeds, so inputs changed by Gradle or autolinking store the artifact, lastBuild, and JSON cache identity only under the post-build key. If re-fingerprinting fails, Stim installs the APK without caching it or reporting a stale cache identity (2b689ad).
  • Dev-client launches carry Expo's session-only disableFab=1 parameter on iOS and Android. Expo versions that support the parameter hide the floating Tools button without changing the user's persistent preferences; older versions ignore it (7c4dd23).
  • stim android --json includes durationMs, matching the documented iOS payload and reporting the wall time of the complete successful native run (adc927e).
  • A warm iOS run reports the installed-app identity proof separately from Expo dev-client preference preparation, so a slow simulator command is attributed to the step that actually ran (e858950).

1.0.0-rc.8​

New​

  • stim ios --device [udid] builds the iphoneos slice, selects a cabled iPhone, installs and launches it through devicectl, and points a Debug build at this workspace's Metro over the LAN. The phone is used, never owned: the signing gate reads the bundle's own embedded.mobileprovision and refuses one that does not name the target device, and Stim re-signs only copies it makes (02cfcb2, 43fd760).
  • stim logs --source device collects a phone's runtime logs through the devicectl console. That stream renders every os_log level alike, so a line stays info unless a crash marker or devicectl's own error prefix proves otherwise; severity is never guessed (1b79cb2).
  • A launch blocked by the phone's pending Local Network permission is named as such, and the remedy says how to accept the prompt, including from a device tool, because the grant cannot be pre-seeded from this machine (a2b3ee9).
  • stim device lock <ios|android> [id] --for <duration> holds a connected physical device across runs, from 10 seconds to 30 minutes, waiting for another workspace the way a run does. stim device unlock [platform] gives back one platform's lease or every lease this workspace holds (33141aa).
  • ios --device and android --device take a run-scoped lease from just before the install until the run exits, raising the expiry at each device step so a killed run frees the device in bounded time. --wait <seconds> waits for a device another workspace holds; --no-wait proceeds without a lease and says what that costs. status lists leases, stop and worktree remove release this workspace's, and gc --delete deletes expired lease files (3fbb460, 96f3c1f).
  • --device with no id picks from the connected pool: the device this workspace already leases when it is present, otherwise the first free one in case-folded id order. A leased device that is not connected refuses rather than moving silently to another phone (eb02f1a).
  • doctor reports the missing sandbox allowance when a write to STIM_HOME actually fails, naming the absent keys, and doctor --fix applies the findings Stim can repair itself. It writes only per-user files, refuses a settings file it cannot read back, and refuses under Codex, where the only value that clears Stim turns the sandbox off wholesale (6640771).
  • stim worktree create --dir <path> places one worktree where the run needs it, taking precedence over the worktreeDir setting; a relative --dir resolves against the current directory, and a blank one is refused (fdb60b7).

Fixes​

  • A run summary says what it proves: a verified launch no longer prints the iOS connection refusal it already recovered from, the ready line reads bundle loaded, process alive, stable for 3s -- the first screen may still be rendering, the heartbeat holds its 30-second grid without repeating a beat, and preparing an owned simulator or emulator gets its own timed line (3c86cfc).
  • Every known setting is type-checked from one shape table in start, ios, android, worktree create, gc, and doctor, and a known key is no longer also warned about as unknown. Behavior change: a non-string cache.provider is refused before the build instead of reported while the run continues (0c7c691, 278ce61).
  • worktree create judges carried Pods against the Podfile.lock the new worktree ends up with, not the one it started from (c006de1).
  • worktree create rolls back a branch it stranded, refuses --base on a branch that already exists (d60db78), and runs git worktree add under LC_ALL=C so the branch-exists guard matches git's English text on a build with translation catalogs (891e94f).
  • A relative worktreeDir setting resolves against the settings root instead of the process's working directory (0a0603f), and a non-string worktreeDir is refused instead of crashing (af1e2d3).
  • A gradle failure whose report is interleaved with task output surfaces the real cause chain instead of the surrounding tail (c1bc9ba).
  • An owned Android emulator's console port is chosen and recorded under the global config lock before boot, so concurrent workspaces cannot claim the same serial. A failed boot releases only its matching port claim while keeping the owned AVD recorded for gc (e6535b2).
  • The fingerprint ignores android/local.properties and android/.idea, machine state no native build reads, so a cache key can match across checkouts (060aeb2).
  • stop, gc --delete, and worktree remove prove a collector pid is this workspace's collector before signalling it, and report a pid they cannot prove instead of killing a process that reused it (d960785, f373e95).
  • A pool refusal gives each connected device's own reason -- Developer Mode off, unpaired, unreadable lease -- instead of asking which of several to name (15f994c).
  • stop --json, status --json, and doctor --json print their payload on exactly one stdout line, matching the documented contract and the other single-payload JSON commands (daaaeeb).
  • Release: every published tarball carries real inter-package versions, substituted by pnpm at pack time rather than bumped by hand (c96df6b), and the workflow computes its publish dist-tag, so a candidate cut after a stable release lands on next instead of latest (9ef253c).
  • The Expo dev menu stays off an app Stim launches, and on iOS so does its floating Tools button. The dev-client project url carries disableOnboarding=1 on every launch, a phone launch passes -EXDevMenuShowsAtLaunch 0 and -EXDevMenuShowFloatingActionButton 0 as launch arguments through devicectl, the simulator preference write covers the Tools button, and Android adds the EXDevMenuDisableAutoLaunch intent extra; the simulator's onboarding preference write is gone. Android's floating button still shows (#249) (4d432f4, 21ead76).

Docs​

  • The website documents doctor --fix and doctor's sandbox finding (8977ff0).
  • guide errors and the skill name the three things an agent sandbox blocks -- writes to STIM_HOME, the simulator service, the adb server -- and what to allow, instead of leaving an agent to find out by failing (4916eaf).

1.0.0-rc.7​

New​

  • stim ios and stim android skip the install entirely when the device already holds the exact artifact, going straight to launch (c07f97b).
  • A flavored Android project with no configured variant is refused before gradle runs, naming the candidates, instead of after a full assemble (168528b).

Removed (breaking)​

  • The stale-APK mtime refusal is gone: an APK older than the build that just ran is no longer treated as foreign (6941c5d).

Fixes​

  • Android installs use the APK's real applicationId instead of the gradle namespace, so suffixed and flavored ids launch correctly (a4b64d7).
  • The log collector signals its stream through the child handle rather than a pid that can be reused (f342663).
  • The real-xcodebuild diagnostic test carries its sibling's timeout instead of flaking at the 5s default (425cd13).

1.0.0-rc.6​

New​

  • stim android --device [serial] installs and launches on a connected physical Android device after the usual build. With no serial it uses the one connected device and refuses with the candidate list when adb reports several; it cannot be combined with --remote. The device is used, never owned: nothing is recorded, and stop, gc, and teardown never touch it (518965a).
  • CocoaPods runs through bundler when the project pins it: a Gemfile.lock that resolves a cocoapods spec routes pod install through bundle check --dry-run -> bundle install (when gems are missing) -> bundle exec pod install, all frozen so the tracked lockfile is never edited. A Gemfile without a lock, a lock without cocoapods (fastlane-only), or a machine without bundle keeps today's plain pod install. Doctor, worktree warnings, and the Xcode sandbox remedy share the same rule (0c636f6).

Removed (breaking)​

  • stim gc --delete --all is now stim gc --delete --cache all: the flag reaches caches only and its name says so (8e4eee1).

Fixes​

  • Android debug builds reverse port 8081 only when the debug_http_host write fails, so the reserved-port wiring is not undone by a fallback that was not needed (531833f).
  • A damaged Xcode compilation-cache object is named as the build-failure cause, with the cache path to clear (1fbde68).
  • CI: vitest 5 stops spurious worker-exit failures (1e20a7d).

Docs​

  • The cache e2e gate judges Gradle storing by entry names, accepts a warm-machine cache as engagement, and isolates GRADLE_USER_HOME so the storing leg is always measurable (86f9273, bf4640a); the bare fixture installs its pods through bundler (d8b6fa7).

1.0.0-rc.5​

New​

  • @stim-cli/cache, a fifth published package holding the cache provider contract and the local-first tier coordination behind the native artifact cache and the Metro transform cache (fadc2ce). The built-in filesystem provider is the only tier shipped; a remote provider becomes a pure addition that implements the same capabilities. On-disk cache layout, keys, APFS clone behavior, and gc reporting are unchanged, and a project with no provider configured loads nothing new.
  • cache.provider and cache.options settings select an optional second-tier provider through the existing settings layers. A committed cache.provider is executable code and is documented as such. Provider calls are bounded: load, resolve, and upload each carry a timeout with a STIM_CACHE_*_TIMEOUT_MS environment override, Metro reads are concurrency-capped, and repeated failures disable the tier for the run with one warning.
  • Contract-test helpers for provider authors ship in @stim-cli/cache, including checks for abort handling, overwrite semantics, and destination hygiene, runnable against a provider module so apiVersion and factory validation are exercised.

Fixes​

  • A slow first simulator boot no longer fails stim ios with a raw spawnSync /bin/sh ETIMEDOUT. Stim re-enters simctl bootstatus while the device still reports Booting, against a ten-minute deadline, and a failure names the udid and the wait (91900c4).
  • The warm-carry summary no longer flips its dependencies verdict when a later node_modules entry lacks a sibling package.json (bc155c1).
  • stim doctor claims the fingerprint-parity check only where it runs (a checkout without installed dependencies), and its expensive main-checkout probes are pinned behind their preconditions (400e068).
  • CI: the native e2e workflows read the renamed STIM_* environment variables again, restoring the cross-run build cache they silently lost in the rebrand (a49f7e5).

Docs​

  • stim guide errors documents every refusal code the CLI emits, enforced by a contract test that scrapes the engine sources (7c2ff5c).
  • The website documents the real carry exclusions, the real guide topics, the parity check's precondition, and the two shapes of the caches setting (7f32bf2).
  • The CLI and docs carry the Stim rebrand and the redesigned website (cc9276b).

1.0.0-rc.4​

This release candidate improves fresh-agent app launches. It also helps agents prepare the main checkout before they create native worktrees.

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

Self-contained app launch​

stim ios and stim android build or restore the app, install it, launch it, and check its readiness. The Stim skill does not require a separate device automation tool for this workflow.

The iOS launch path sets the workspace Metro address before it opens the app. The Android launch path injects the Metro preferences and uses the launcher activity when a dev-client URL is not available. These paths reduce Expo dev menu and deep-link confirmation friction.

Stim observes the app for three seconds after Metro completes the bundle. The final summary reports the process state, launch errors, device ID, app ID, Metro port, cache result, and log path.

Main checkout diagnostics​

stim doctor checks the main checkout when it runs from a linked worktree. It reports stale dependencies, CocoaPods state, native output, build-cache state, and local commits that are missing from the upstream branch.

The skill asks agents to run doctor before native work. It also recommends one main-checkout build when more native worktrees are expected. A later stim worktree create --carry-ignored can clone that prepared state with APFS copy-on-write support.

Release reliability​

The release workflow retries npm registry checks after publishing. This avoids a false release failure while a new package version propagates through the registry.

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

1.0.0-rc.3​

This release candidate adds optional SimSlim profiles for Stim-owned iOS simulators. It also prevents ignored-file carry-over from copying a nested Git worktree into a new worktree.

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

Optional SimSlim profiles​

Projects can commit a SimSlim profile and select it in .stim.json:

{
  "ios": { "simslimProfile": ".simslim/dev.json" }
}

Install SimSlim once on each Mac with brew install mobai-app/tap/simslim. SimSlim requires an iOS 18 or newer simulator.

stim ios applies the profile only to its owned local simulator. The first change can reboot the simulator. Later matching runs are fast no-ops in SimSlim. Removing the setting restores stock services when Stim applied the profile.

Stim validates the profile path before it creates or boots a simulator. The path must stay inside the repository. stim doctor reports an invalid profile or a missing SimSlim installation, including for apps inside a monorepo.

Safer ignored-file carry-over​

stim worktree create --carry-ignored now reads Git's registered worktrees and excludes them from the copied files. This prevents nested Claude, Codex, and custom worktree locations from being copied into the new worktree.

The check uses Git's worktree registry, so it does not depend on a hardcoded directory list. If Git reports only an ignored parent directory, Stim excludes that full parent. Project-specific exclusions remain available through .worktreeexclude and worktree.exclude.

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

1.0.0-rc.2​

This release candidate improves the full agent workflow. It makes worktree creation more predictable, reports native cache activity, and gives launch errors a clearer severity.

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

The platform command builds or restores the app, installs it, opens it, and checks its launch state. Plain output streams progress and ends with the full device, app, Metro, cache, and log facts.

Worktree workflow​

stim worktree create <name> now uses the current checkout as its base. Use --base fresh to start from origin/HEAD, or use --base <ref> for a branch, tag, or commit.

The command reports which ignored dependencies, CocoaPods files, and native build output can make the new worktree warm. It also finds nested lockfiles and prints the correct install command and directory.

stim worktree remove removes a Stim-owned branch only when that branch has no unique commits. It keeps the branch when another worktree uses it or its ref changes during cleanup.

Native cache reporting​

The iOS command now reports Xcode compilation-cache hits from Xcode 26. This metric stays separate from the Stim artifact-cache result. The output explains when the Xcode metric did not run or was not available.

Launch diagnostics​

The iOS log collector reduces known harmless UIKit focus messages. It also keeps a TCP refusal unless a later log record proves that the same connection succeeded. The raw log timeline remains complete.

The release also fixes a Node 22 Linux test race in tunnel cleanup.

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

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 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-<label>.
  • Stim 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 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 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_HOME, which defaults to ~/.stim. The normal workflow does not require generated project files or an initialization command.

Built-in agent guidance​

The stim-cli npm 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.