Skip to main content

Getting started

Install Stim​

Install the CLI globally or run it with npx. The package and command are both stim. If you previously installed stim-cli globally, run npm uninstall --global stim-cli first. The @stim-cli/* packages keep their names.

npm install --global stim
stim <command>

Install the bundled skill for your coding agent:

npx skills add appandflow/stim

The skill stays small and asks the installed CLI for version-specific guidance, so upgrading Stim does not require reinstalling the skill.

Ask the agent to run the app​

Ask for the outcome:

Build and run

Run the app on iOS.

You normally do not need to name Stim. Installing the skill lets a compatible agent route build, run, device, log, and worktree requests to Stim. Say "use Stim" only when you want to force that choice instead of a project-specific wrapper.

The agent normally runs:

stim doctor           # inspect the main checkout and warm-state gaps
stim start            # start this workspace's dev server
stim ios              # build or restore, install, launch, and verify
stim logs --errors    # check for errors in the captured logs
stim stop             # release the live environment

Use stim android for Android. Stim works with React Native Community CLI and Expo projects. It needs no project initialization and writes no runtime state into the repository.

After a build, the agent should report only the exact device and app, launch state, cache result, total duration, and whether the error log is clean. Ask for build-performance details when you want history across runs.

Common prompts​

Each prompt has a copy button and an illustrative agent response. Simulator results use the Trailhead run above; device and PR flows show the same compact reporting style.

Choose an iOS simulator

Run the app on an iPhone 17 simulator with iOS 26.5.

Run on a connected phone

Run the app on my connected iPhone.

Inspect recent errors

Show app errors from the last 10 minutes.

Check the environment

What is running for this workspace?

Review build performance

Show iOS build performance.

Work in parallel

Make this change in a separate worktree and validate it on iOS.

Record PR validation

Fix this in a separate worktree. Record the affected flow before and after on iOS with agent-device, then open a PR with the recordings in a Before/After table.

Run work in parallel​

The current checkout is the default. An agent creates a separate worktree only when the task needs isolation or parallel work, or when you ask for one:

git worktree add -b feature-name ../feature-name HEAD
cd ../feature-name
stim worktree warm
stim start
stim ios

# After the work is preserved:

stim stop
stim worktree remove

If a harness already created the linked worktree, skip Git creation and run stim worktree warm there. Warm copies missing ignored state from main, including dependencies, native output, and eligible .env and local config. Existing entries stay untouched. See worktree isolation for exclusions and cleanup; removal works whether or not the worktree was warmed.

The worktree gets a separate port and device. It can still use native and Metro cache entries created by the main checkout or another worktree.

What success means​

stim ios and stim android install and open the app, then report launch evidence. The summary includes the exact device, app identifier, cache result, Metro state, launch state, and log path.

An OK summary without a launch qualifier confirms a bundle request or a live release process. bundle requested, still building means Metro is still working. For launch UNVERIFIED, follow the printed remedy before claiming success. None of these checks proves that the screen rendered correctly.

Use a device automation tool only when the task requires visual interaction or a screenshot. Stim owns the build and launch. It does not require a separate device tool for that workflow.

Next steps​

  • Read Why Stim for the design and benefits.
  • Read the concept guides for caches, devices, logs, and worktrees.
  • Use the command reference for every command and option.
  • Run stim guide for reference text that matches the installed version.