Run & previews

The Run panel builds your app and shows it running beside the chat that is changing it. It runs iOS apps from Xcode projects, Android apps from Gradle projects, and React Native and Expo apps with their bundler, on simulators, emulators and connected phones, in a live preview you can use. For web projects, it starts your dev servers.

Open it with ⌘⇧7 or from the rail’s Open a panel list. The first time you open Run in a folder, Codz looks for things it can run there. If it finds no app and no server, Run leaves the list for that folder.

What Run can run

Swift packages and macOS apps are not run. iOS and Android apps also need Mobile Development on in Settings ▸ Browser & tools (it is on by default); dev servers do not.

Run an app

1. Open the Run panel.
2. If the folder has more than one app, choose one from the App menu.
3. Choose a simulator, emulator or phone from the Destination menu.
4. Click Build and run, or press ⌘R.

Codz builds the app, starts the device if it is not running, installs the app, opens it and connects the preview. The card on the device follows the steps, Build, Device, Install, Open and Live, and the toolbar shows the current phase, such as Building or Running.

• Build (⌘B) builds without running.
• Stop (⌘⇧.) ends the app. A simulator or emulator stays on, and its screen keeps streaming.
• Codz remembers the app and destination for each folder. A phone is never chosen for you: pick it yourself the first time.

App builds, and the app’s own log once it is running, appear under Build output.

The live preview

The preview shows the device in its own frame. Once it is live, you can use the app in it:

• Click to tap and drag to swipe.
• Scroll with the trackpad, on a simulator or an emulator.
• Type, paste with ⌘V, and press ⌫ and ↩.

On Android, typing is limited to plain ASCII text (use the device’s own keyboard for anything else), and Esc is Android’s Back. An iPhone takes taps, swipes and typing once device control is set up (see iPhones).

Home and Rotate float over the device. Rotate turns the frame and the picture a quarter turn; it does not change the device’s own orientation. More run actions (…) also has Home, Rotate right, Back (Android) and Reconnect preview, for a preview that has stopped updating.

Open Simulator opens the same simulator in Apple’s Simulator app. Attach preview to chat attaches a screenshot of the device to the composer.

Keep the app current

Refresh (the circular arrow) rebuilds, reinstalls and relaunches the app that is running, without taking the preview down. It appears while an app is running.

• Refresh the app when the agent edits, in More run actions, does this for you. When source files change (Swift, Objective-C, Kotlin, Java, storyboards, string files, Android resources), Codz waits until the edits have stopped for two seconds, then refreshes. A change made during a build gets one more refresh when the build finishes. It is off by default.
• Reopen on launch, in the same menu, opens a URL in the app each time it launches, so a rebuild brings you back to the screen you were on. Choose one of the routes the app declares, which are read from the Android manifest or, for iOS, from the built app’s URL schemes, or enter a Custom route…. It is not available on a connected iPhone.

React Native and Expo

For a React Native or Expo app, Codz starts the project’s Metro bundler alongside the build, or uses one that is already running. Metro’s output appears in Build output, marked metro │.

JavaScript changes reach the app through Metro’s own Fast Refresh, so Codz never rebuilds for them. With Refresh the app when the agent edits on, a change to native code still rebuilds, and a change to Metro’s or Babel’s configuration or to package.json adds a note to choose Restart bundler. More run actions has Reload bundle and Restart bundler for the cases Fast Refresh cannot handle.

The app needs:

• Node.js. Codz says so if it cannot find node.
• Its packages installed. If node_modules is missing, Codz names the install command for your package manager.
• Its native folders. For an Expo app without ios/ or android/, run npx expo prebuild first; Codz does not run it for you.

Pick an element (iOS)

On a live iOS simulator, or an iPhone with device control, Select element (the arrow in a square) turns the preview into a picker.

1. Click Select element in the toolbar.
2. Move the pointer over the app. The element under it is outlined and labelled, such as Button · Continue.
3. Click to add it to the chat, or ⇧-click to keep picking. Esc stops.

Each pick attaches a screenshot of the area around the element, outlined, and adds a line to your draft describing it: its kind, label, identifier, value, and position in points. Picking never taps the app.

You can pick only what the app exposes to accessibility. Codz turns accessibility on in a simulator before every run; if it says Run the app again to select elements, run the app once more. Selecting needs the device in portrait.

Android previews without a device

For Jetpack Compose, More run actions ▸ Render previews without running draws the module’s @Preview composables with Gradle and attaches the pictures to the composer, with no emulator and no install. Render previews when the agent edits redraws them whenever a Kotlin file in the module changes; it is off by default.

The module needs Android’s screenshot-testing plugin and a preview to draw. If it is not set up, Codz asks Set up preview rendering?; Ask the agent puts a request for that setup in your composer. Codz never edits your build files itself.

Dev servers

When the folder has servers, the Run panel lists them under Servers, each with its address (such as localhost:3000) or the command that starts it.

• Codz suggests one server per package.json, in the project folder and in each folder under apps/ and packages/, using the first script named dev, start, backend, api or web. It runs the script with your package manager (npm, Yarn, pnpm or Bun, from the lockfile).
• If the project has a Start command in its environment (Chat options ▸ Project environment…), it is listed as Start. See Projects & sidebar.
• Click a server’s play button to start it and the stop button to stop it. If something is already serving on its port, Codz uses it and marks it adopted; stop it where you started it.
• With app starts the server whenever you run the app. It is on for every suggested server. In a folder with servers and no app, Start servers starts them.

Server output appears in Build output, marked with the server’s folder name. Running servers also show up in the Browser panel when it has no page open.

Several devices at once

To run on a second device, choose Run on another device from the rail’s + menu. Each Run tab has its own destination, and with more than one, each tab is named after its device.

• A destination another tab is using says In use in the Destination menu.
• One tab builds or installs at a time; the others wait.
• Closing an extra Run tab stops its run. Closing the first Run tab leaves the app running, and other chats in the same folder can still see it.

iPhones

To run on an iPhone, connect it by USB, unlock it, trust this Mac and turn on Developer Mode on the phone. Codz signs the app with your project’s signing settings and the Apple account in Xcode.

Over Wi-Fi, Codz can build and launch but not show a live preview. The preview and control of the phone need device control:

1. Connect the iPhone by USB and choose it as the destination.
2. Open More run actions ▸ iOS Development setup….
3. Install the USB tools if the sheet asks, choose your Development team, and click Enable device control.

The destination menu says when something is missing: Build and launch only, Device control not installed, USB tools not installed or Device control not enabled. Signing made with a free Apple account expires. When a phone shows Signing may have expired, choose Enable device control again.

Set up iOS development

You need Xcode, an iOS runtime and a simulator. More run actions ▸ iOS Development setup… checks your tools and can:

• Choose Xcode… when you have more than one, or Get Xcode from the Mac App Store.
• Download iOS runtime and Create iPhone simulator.
• Install simulator preview tools, needed only when the built-in simulator preview cannot be used with your Xcode, and Install USB tools for iPhones.
• Enable project generation for a project generated with XcodeGen, and Install XcodeGen.

Some installers use Homebrew. Without it, the sheet points you to Homebrew’s macOS installer; choose Recheck afterwards.

Set up Android development

You need the Android SDK with its platform tools and emulator, and a Java JDK. More run actions ▸ Android Development setup… shows what it found and has Get Android SDK tools, Install emulator tools, Download Android runtime, Create emulator, Choose SDK folder… and Recheck.

• Codz looks for the SDK in the folder you chose, then ANDROID_HOME, ANDROID_SDK_ROOT and ~/Library/Android/sdk.
• Emulators start without a window of their own; you use them in the preview.
• For a phone, turn on Developer options and USB debugging, connect it, unlock it and allow this Mac.
• Codz builds with the project’s Gradle wrapper and lists debug variants.

StoreKit testing (iOS)

More run actions ▸ StoreKit chooses the StoreKit configuration a simulator run uses: None, or a .storekit file found beside the project. New StoreKit Configuration creates Products.storekit and adds it to the scheme, which changes your project. Physical devices use the sandbox Apple ID instead.

Archive and distribute (iOS)

More run actions ▸ Archive & Distribute… archives the app and sends it to Apple without opening Xcode:

1. Choose the Configuration (normally Release) and, if needed, the Signing team.
2. Choose an App Store Connect team API key (.p8) and enter its Key ID and Issuer ID. Use an App Manager or Admin key; the private key stays in the file you choose.
3. Click Archive, then Upload to TestFlight.
4. For release, click Check App Store Release, then Submit for App Review…. The app is released automatically once Apple approves it.

The project needs working distribution signing and an app record in App Store Connect. Codz never uploads or submits on its own.

Build output

Build output sits at the bottom of the panel and opens with its first line. Its buttons send the output to the chat, save it as evidence on the chat’s last finished turn, or clear it.

When a run fails, Run error explains why and offers:

• Show details, which opens the build output.
• Retry, which runs again.
• Ask agent to fix, which puts the output in your composer.

Keyboard shortcuts

⌘R runs the Run tab on screen. When the Browser panel’s page has focus, it reloads the page instead.

Troubleshooting

Run is not in the panel list. Codz found no app or dev server in this folder, or the folder’s app is an iOS or Android app and Mobile Development is off in Settings ▸ Browser & tools.

The toolbar says Choose app. The folder has more than one app. Pick one from the App menu.

Couldn’t read the Xcode project. The reason is in Build output. Fix it, then choose Try again in the App menu.

Another Run tab is using this destination. Choose a different one, or stop the run in the other tab first.

The iPhone will not launch the app. Unlock it, keep it connected and choose Retry. If Developer Mode is off, turn it on, reconnect and retry. Signing problems are in Build output; check the team in iOS Development setup….

The preview did not produce a frame. Choose More run actions ▸ Reconnect preview, or check the development setup.

The Android emulator has not finished starting. A first boot can take several minutes. Wait, then choose Retry.

This Android project needs a Gradle wrapper. Ask the agent to add the project’s wrapper, then choose Rediscover project.