AI agents for iOS: things to ask Claude Code or Codex

Before you start

This guide assumes:

FlowDeck is installed, your trial is active, and the FlowDeck skill pack is installed for at least one agent (Claude Code, Codex, OpenCode, Cursor, or Gemini). If not, the getting-started guide walks through both in 10 minutes.
You have an iOS project that builds. The agent needs something to drive.
You've restarted your agent at least once since installing the skill, skills load on session startup, not mid-session.

Each example below is a prompt you can paste into your agent verbatim. Each is followed by what FlowDeck commands the agent ends up running, and why the result is more reliable than the raw xcodebuild path.

Example 01

Build and confirm no errors

The most common loop. Ask for a small change, then for the agent to verify it didn't break the build:

Add a "Hello, world." Text view to the home screen, then build and confirm there are no errors.

The agent edits the file, then calls flowdeck build --json. The output is a structured stream: per-error events with file paths, line numbers, and messages. No 2,000-line stdout to scan, no regex to write, no false positives from warning lines that look like errors.

If the build fails, the agent sees the typed error events directly, locates the file and line, and either fixes the issue or reports back. The loop typically completes in one round-trip instead of three or four.

Example 02

See what's actually on screen

The verification XCUITest can't do for free-form changes, the agent looking at the running app:

Run the app on iPhone 16 and tell me what's on the home screen.

The agent calls flowdeck run -S "iPhone 16", waits for launch, then reads flowdeck ui simulator screen --json. The response includes both the rendered screen as a JPEG and the accessibility tree as structured data: every label, button, image, and text view with its frame, role, and identifier.

The agent can describe what's visible, compare it to what your prompt expected, and flag mismatches ("there's no 'Notifications' row visible on the home screen"). For longer sessions, ask it to start a background capture session so it doesn't pay the capture cost on every action:

Start a background simulator session for iPhone 16, then describe the home screen.

The session writes a fresh capture every ~500ms to ./.flowdeck/automation/sessions/<id>/latest.json and latest.jpg; the agent reads those files between actions.

Example 03

Navigate the UI and assert what changed

Tapping, typing, and verifying are the loops that make agent UI testing genuinely useful:

Tap the Settings tab, then tap the Notifications row, and confirm the screen title becomes "Notifications".

The agent uses flowdeck ui simulator tap "Settings" and flowdeck ui simulator tap "Notifications" (matching by accessibility label), then either reads the screen and confirms, or asserts directly with flowdeck ui simulator assert visible "Notifications". The assert returns a non-zero exit code on failure, so the agent gets a clean signal whether the UI did what was asked.

The same surface covers type, swipe, scroll, long-press, and gestures. None of it requires an XCUITest target, the agent talks to any running iOS app via the Apple accessibility APIs.

Example 04

Debug a runtime bug from logs

Compile errors are easy. Runtime bugs need observability. Once the app is running, the agent can stream its logs and reason about what's happening:

Run the app, navigate to login, type the password "letmein123", and check the logs to see whether the auth request actually went out.

The agent runs flowdeck run --log (launches and starts streaming together), drives the UI to the login screen, types the password, taps submit, and reads the streamed log output. Only this app's lines, no SpringBoard, no nsurlsessiond, no other process noise. With --json, the agent can filter events on subsystem, category, or level.

This is the loop where AI agents become genuinely useful for runtime debugging. Without it, the agent reads source code and guesses what runs; with it, the agent reads what actually happened.

Example 05

Implement a small feature end-to-end

The build-fix-verify loop in one prompt:

Add a "Sign out" button to the Settings screen. When tapped, it should clear the auth token and route the user back to the login screen. Build, run on iPhone 16, tap the new button, and confirm the login screen appears.

The agent edits the relevant files, builds with flowdeck build --json, runs with flowdeck run -S "iPhone 16", taps "Settings" and then "Sign out" via UI automation, and asserts the login screen rendered. If anything fails, it has structured output at each step to figure out where, code error, runtime crash, or a UI element not appearing where expected.

This is the difference between an agent that writes code and an agent that ships code.

Example 06

Run targeted tests on agent-written code

For changes that touch tested code, ask the agent to verify against the existing test suite:

Run only the LoginTests suite and tell me which tests pass.

The agent calls flowdeck test --only LoginTests --json and reads the structured per-test events: each pass, fail, and skip with the test method name and duration. Failed tests come back with file and line. Passed tests confirm coverage. No XCResult parsing required.

For tighter feedback during a session, the agent can ask flowdeck test discover --json for the full test surface without compiling, then pick the right subset to run for the change at hand.

Example 07

Compare an implementation to a design

Drop in a Figma export or screenshot and ask the agent to match it:

Here's a mockup of the new onboarding screen (mockup.png). Implement it and keep iterating until the simulator screenshot matches the design.

The agent runs the build-capture-compare-fix loop with FlowDeck's CLI: implement → flowdeck run → flowdeck ui simulator screen → compare to the mockup → adjust spacing, colors, typography → repeat until the captured screenshot is indistinguishable from the reference.

For the full playbook, including how to brief the agent for best results, see the pixel-perfect design guide.

Patterns that come up most often

The build-fix loop.: Agent edits code → flowdeck build --json → reads typed error events → fixes → rebuilds. 1-2 round trips for a typical change. Most efficient when your prompt includes a clear assertion ("the change should not introduce errors").
The UI-verify loop.: Agent writes a SwiftUI view → builds → flowdeck run → flowdeck ui simulator screen --json → reads the accessibility tree → confirms the new view rendered as intended. Catches "looks right in code, doesn't render" bugs before they reach a human reviewer.
The debug-from-logs loop.: Agent reproduces a bug by driving the UI → reads flowdeck logs <app-id> --json → traces the failure to a subsystem → fixes → reproduces again to confirm. Replaces the "did you turn on verbose logging in Xcode" workflow.
The implement-and-prove loop.: The combination of all three: build, run, drive, verify. Use it when you need an agent to ship a feature instead of just propose code. Ask explicitly for the verification step in the prompt; without it, agents tend to stop at "code compiles."

When things go wrong

The agent uses xcodebuild instead of flowdeck: The skill file isn't loaded. Quit and restart the agent (skill packs load on session start, not mid-session). If a restart doesn't help, run flowdeck -i → A → Install Skills again and pick a path the agent actually reads from. Verify by checking ~/.claude/skills/ (or equivalent) for a flowdeck directory.
The agent asks you for a UDID: Same root cause: skill not loaded. With the skill, the agent passes a name like "iPhone 16" to -S and lets FlowDeck resolve it. Without it, the agent falls back to simctl-style assumptions where UDIDs are required.
The agent gets stuck on a single error and re-runs the same command: Almost always means it's reading text output instead of JSON. Make sure your skill file documents --json as the default for build, test, logs, and UI commands. The pre-installed skill packs do this; if you've customized yours, double-check.
Multiple simulators are booted and the agent picks the wrong one: Be explicit in the prompt: "use the iPhone 16 simulator." With multiple matches, FlowDeck prefers the already-booted simulator; with multiple booted, it picks one deterministically but you can't always predict which. Telling the agent the simulator name keeps the resolution unambiguous.
UI automation feels slow during long agent runs: Switch from on-demand flowdeck ui simulator screen to a background session: flowdeck ui simulator session start. The session writes a fresh capture every ~500ms; the agent reads the latest file instead of paying the capture cost on every turn.
Permission prompts block the simulator: For tests that need camera, location, or notifications pre-granted, FlowDeck doesn't wrap simctl privacy yet. Run xcrun simctl privacy <udid> grant location <bundle-id> (or the equivalent for the permission you need) before launching the app.

Annex

What changes for the agent

For reference, what the agent does without FlowDeck side by side with what it does once the skill pack is installed.

The agent wants to…	Without FlowDeck	With FlowDeck
Read build errors	Parse 2,000 lines of `xcodebuild` stdout with regex	Read typed events from `flowdeck build --json`
See what's on screen	Can't (XCUITest target required)	`flowdeck ui simulator screen --json` returns image + accessibility tree
Tap a button	Requires a compiled XCUITest target	`flowdeck ui simulator tap "Log In"` on any running app
Read this app's logs	Filter `log stream` with a predicate string	`flowdeck logs <app-id>`, per-app only
Verify a feature works	Write XCUITest, compile, run, parse XCResult	`flowdeck ui simulator assert visible "Welcome"`

The underlying tools behind both columns are still Apple's: xcodebuild, simctl, the accessibility system. FlowDeck doesn't replace them; it gives the agent a usable surface.

Things to ask your AI agent.