Build an AI App from Your iPhone

Build and deploy an AI text adventure game using only your iPhone.

Introduction

30 Second Summary

You don't need a laptop to build an AI app. Your iPhone is powerful enough to write, test, and deploy a full project to the internet.

In this project, you will build an interactive AI text adventure game entirely from your phone. You'll use Replit's mobile app to craft system prompts that shape the AI's storytelling, manage conversation history, and deploy a live web app that anyone can play.

What You'll Build

Picture texting a link to a friend who taps it, picks a genre, and within seconds is exploring an AI-generated choose-your-own-adventure story where every choice takes the plot in a different direction.

By the end of this project, you'll have:

An AI-powered text adventure game where players pick a genre and get dropped into a branching story with vivid, atmospheric writing.
Prompt engineering skills that transform a generic AI response into structured, immersive storytelling.
A live URL you can text to friends so they can play their own adventures on any device.
An optional Secret Mission to push your skills further.

Are there any prerequisites?

All you need is an iPhone running iOS 18 or later and a GitHub account. You'll set up a Replit Core subscription ($25/month) in Step 1.

Before We Start

Before we dive in, let's lock in what you're about to build and why it matters to you.

Set Up Replit on Your iPhone

Every app needs a place where its code lives and runs. Normally that's a laptop, but this project is different. You'll build everything from your iPhone, so you need a development environment that runs entirely in the cloud.

Replit is a cloud platform with a full iOS app that lets you build, run, and deploy web apps without a laptop. In this step, you'll install the app, activate the Core plan, and create your first project.

In this step, get ready to:

Install the Replit iOS app and create your account.
Activate the Core plan to unlock AI-powered development.
Create your first project and explore the development interface.

Install the Replit app and create your account

Replit runs your code on its servers, not on your phone. That means your iPhone is just the screen and keyboard. The heavy lifting happens in the cloud.

Open the App Store on your iPhone.
Search for Replit and tap Get to install the app.
Once installed, tap Open to launch the Replit app.
Tap Sign up to create a new account, or tap Log in if you already have one.
If you created a new account, check your email for a verification link and tap it to verify your address.

After signing in, you should see the Replit home screen with a prompt box at the top.

What is Replit?

Replit is a cloud development platform. Your code, your server, and your database all run on Replit's infrastructure. You describe what you want to build in plain English, and Replit Agent writes the code for you.

This means you can build a full web app from your phone without installing any programming languages or tools locally.

🙋‍♀️ Can't find the app or verification email?

Make sure your iPhone is running iOS 18 or later. The Replit app requires it. Check in Settings > General > About.
If the verification email hasn't arrived, check your spam or junk folder. You can also request a new verification email from the Replit login screen.
Still stuck? Help me install the Replit iOS app and verify my account.

Upgrade to the Core plan

The free Starter plan lets you explore Replit, but it doesn't include the two features you need for this project: Replit Agent (which builds apps from your descriptions) and AI Integrations (which connects your app to AI models like Claude).

In the Replit app, tap your Account icon.
Tap Upgrade.
Select the Core plan ($25/month).
Tap Continue with Core and complete the payment prompts.

Once the upgrade completes, you should see your account reflect the Core plan.

What does the Core plan unlock?

Core unlocks two features that make this project possible.

Replit Agent builds entire apps from natural language descriptions. You describe what you want, and Agent writes the code, sets up the files, and configures the project.
AI Integrations connects your app to AI models like Anthropic's Claude. Replit manages the API credentials for you, so you never have to create a separate AI account or handle API keys.

🙋‍♀️ Not seeing the Upgrade option?

Make sure you're signed in to your Replit account. The upgrade option only appears for authenticated users.
If the payment doesn't go through, try force-closing the Replit app and reopening it. Then navigate back to Account and tap Upgrade again.
Still stuck? Help me upgrade to the Replit Core plan from the iOS app.

Create your first project

In Replit, you start a project by describing what you want to build. Agent takes your description and sets up the files, dependencies, and configuration automatically.

On the Replit home screen, find the prompt box at the top of the screen.
Type the following and send it:

Create a web app

Agent starts building your project. Wait for it to finish setting up the initial files.

Once the project loads, swipe left to see the Tools pane. This is where you'll find the file editor, secrets, and project settings.
Swipe left again to see the Tasks pane. This shows what Agent has worked on and completed.
Swipe back to the right to return to the Agent pane. This is where you'll chat with Agent to build and modify your app.

Tools pane

Tasks pane

Agent pane

What are these three panes?

Agent is your main workspace. You type what you want, and Agent builds it. Think of it as a conversation with your developer.
Tools gives you direct access to project files, secrets, packages, and settings. You won't need it often in this project, but it's useful for inspecting what Agent built.
Tasks tracks Agent's progress. Each task shows what Agent did, so you can review its work.

Before moving on, what do you expect to see on the Agent pane right now?

You should see your chat history with the Create a web app message you sent and Agent's response confirming it set up the project.

Agent not responding or project not loading?

Confirm your Core plan is active. Agent requires a Core subscription to function fully. Check in Account to verify your plan status.
If the project seems stuck, try closing and reopening the Replit app. Then return to your project from the home screen.
Make sure you have a stable internet connection. Replit runs entirely in the cloud, so everything requires connectivity.
Still stuck? Help me get my first Replit project working on my iPhone.

Your development environment is ready to go. In the next step, you'll put it to work by telling Agent to build your AI text adventure game.

Build the First Version of Your Adventure Game

Your Replit workspace is set up with a Core plan and an empty project ready to go. Now it's time to build something with it.

The fastest way to understand how AI APIs work is to see one in action. You'll describe an entire text adventure game to Replit Agent in plain English, watch it wire up the Anthropic AI integration, and then play the result to experience AI-generated content responding to your choices in real time.

In this step, get ready to:

Describe the text adventure game to Replit Agent and watch it build the app.
Play through the game in Preview and experience AI-generated storytelling.
Discover why the AI's default output needs improvement.

Describe your game to Replit Agent

Replit Agent builds apps from natural language descriptions. You describe what you want, and Agent writes the code, sets up the backend, and configures any integrations automatically.

In the Agent chat, send this prompt to tell Agent exactly what to build:

Build an interactive AI text adventure game. It should have a genre selection screen where the player picks from Fantasy, Sci-Fi, Horror, or Mystery. After picking a genre, the AI generates an opening scene with 3 choices. When the player picks a choice, the AI continues the story based on what they picked. Use Anthropic to power the AI. Keep the UI dark-themed and atmospheric.

What does this prompt tell Agent to do?

The prompt describes the full game: a genre picker, AI-generated story scenes, and player choices that drive the narrative forward.

The phrase "Use Anthropic" tells Agent to integrate with the Anthropic API for AI text generation. Since you're on the Core plan, Agent uses Replit AI Integrations to handle the API credentials automatically. No API key setup needed.

Watch Agent build the app. This takes a couple of minutes as Agent writes code, sets up the backend, and configures the AI integration.
Look for Anthropic (Replit managed) in Agent's response. This confirms Replit is handling the API credentials for you.

What is Replit AI Integrations?

Replit AI Integrations is a feature available on the Core plan that manages API credentials for supported AI providers like Anthropic, OpenAI, and Google. When you mention an AI provider in your prompt, Agent automatically uses managed credentials so you never have to sign up for a separate API account or paste in keys.

AI usage is billed at the provider's public API rate and deducted from your Replit credits. For this project, API costs should be minimal.

🙋‍♀️ Agent not building the app?

Make sure you're on the Core plan. AI Integrations require Core.
If Agent seems stuck, try scrolling down to confirm the chat sent, then wait a minute. The first build can take a little longer.
If Agent asks clarifying questions, answer them and let it continue building.

Need more help? Why isn't Replit Agent building my text adventure game?

Play your first adventure

Agent has built your game. Time to see if the AI can actually tell a story.

Tap the artifact bar at the bottom of the screen to open the Preview.
You should see a dark-themed genre selection screen with four options: Fantasy, Sci-Fi, Horror, and Mystery.
Tap a genre to start your adventure.

Before you tap your first choice, make a prediction. Do you think the AI-generated story will read like a polished novel, or more like a chatbot trying its best?

Tap a choice and watch the AI generate the next scene.
Play through 2-3 turns. Pay attention to the writing quality, how different the choices feel from each other, and whether the AI references anything from earlier in your story.

What is happening behind the scenes?

Each time you tap a choice, the app sends your selection to the Anthropic API along with the conversation history so far. The AI generates new story text and new choices based on everything that happened before.

This is the core loop of any AI-powered app: send a prompt, get a response, render it in the UI. Every AI chatbot, writing assistant, and code generator follows this same pattern.

🙋‍♀️ Preview not loading?

Make sure Agent finished building before you tap the artifact bar. Look for a completion message in the Agent chat.
If the Preview shows a blank screen, swipe back to Agent and tell it what you see. Agent can diagnose and fix the issue.
Try swiping away from the Preview and tapping the artifact bar again to reload.

Still stuck? Help me get the Preview working in the Replit mobile app.

Push the AI further

Your game works. But does the AI hold up over multiple turns? Before you keep playing, predict: will the story stay coherent and surprising, or will you start to notice patterns?

Play through a few more turns. Go deeper into the story and pay close attention to the AI's output.

At some point, you'll notice at least one of these problems:

The AI breaks character and starts talking like a chatbot instead of a narrator.
The story loses track of earlier events. Characters or details you encountered simply vanish.
The choices all feel the same. Every turn offers some variation of "go left, go right, talk to the stranger."

This is expected. The AI is doing exactly what it was told to do. The problem is that it wasn't told much.

Why does the AI's output feel generic?

A vague prompt produces vague output. Right now, the AI has no rules about writing style, no instructions to maintain story continuity, and no guidance on how to structure its response. It's improvising with no script.

You've just discovered why prompt engineering matters. The AI has the ability to write vivid, branching stories. It just needs better instructions.

Your game runs, the AI generates stories, and players can make choices. But the storytelling falls flat after a few turns. Next up, you'll learn the core skill of AI development: crafting system prompts that transform how the AI behaves.

Fix the AI with Better Prompts

Your game works. You picked genres, the AI generated opening scenes, and your choices moved the story forward.

But the AI broke character, forgot earlier events, and served up bland choices. Those problems come from one thing: the hidden instructions telling the AI how to behave were too generic.

In this step, get ready to:

Inspect the current system prompt to see why the AI's output was bland.
Rewrite the system prompt with specific rules for vivid, structured storytelling.
Test the improved game and compare it to your first playthrough.

Inspect the current system prompt

Every AI app has a system prompt: a hidden set of instructions that tells the AI how to behave. Before you can fix your app, you need to ask Agent to show you what the current instructions say.

Send this message in the Agent chat:

Show me the system prompt we're sending to the Anthropic API for story generation. Don't change anything yet, just show me what it says.

Agent displays the current system prompt in the chat. Read through it carefully.

What is a system prompt?

A system prompt is a set of instructions sent to the AI before any user messages. It controls the AI's personality, writing style, output format, and boundaries.

Every time your app calls the Anthropic API, this system prompt goes along with it. The more specific the instructions, the more predictable the AI's output becomes.

Notice how generic the current instructions are. There are no rules about writing style, scene length, or output format, which is exactly why the AI's responses felt flat.

Rewrite the system prompt with specific rules

Now you'll replace that vague prompt with detailed rules. Each rule targets a specific problem you noticed during your first playthrough.

Send this message to Agent:

Update the system prompt for the AI story generation to include these rules: (1) Write in second person present tense ('You step into the cave...'). (2) Each scene must be exactly 3-4 paragraphs of vivid, atmospheric description. (3) End every scene with exactly 3 choices that lead to meaningfully different outcomes. (4) Reference specific details from earlier in the story to maintain continuity. (5) Never break character or acknowledge being an AI. (6) Format the response as JSON with fields: 'narrative' (the story text) and 'choices' (array of 3 choice strings).

What does this prompt do?

Rules 1 through 5 fix the storytelling quality. They force the AI to write in a consistent style, create vivid scenes, offer meaningful choices, maintain story continuity, and stay in character.

Rule 6 is the most important for app development. Instead of getting freeform text, you're asking the AI to return structured JSON with two specific fields: narrative (the story text) and choices (an array of 3 options).

This is how production AI apps work. Structured input in, structured output out, predictable UI every time.

Watch Agent update the code. You should see it modify the system prompt in your project files and confirm the changes in the chat.

Agent didn't apply all the changes?

If Agent only applied some of the rules, send a follow-up message asking it to include the missing ones. Be specific about which rule numbers are missing.

You can also ask Agent to show you the updated system prompt to verify all six rules are present.

Help me get Agent to apply all 6 system prompt rules.

Test the improved game

Based on the six rules you just added, what specific differences do you expect to see in the AI's storytelling? Make a mental prediction before you play.

Select the artifact bar at the bottom to switch to the Preview.
Start a new game and select a genre.
Play through 4-5 turns.
Compare the scene descriptions, choices, and story continuity to your first playthrough.

The story should be noticeably more vivid, with choices that lead to genuinely different outcomes. The AI should reference details from earlier turns, proving that story continuity is working.

You just did prompt engineering. By writing specific, structured instructions, you transformed the same AI from a generic chatbot into an immersive storyteller.

Story still feels generic?

Ask Agent to show you the current system prompt again to verify your rules were applied. If any rules are missing, send a follow-up message with the specific rule text.

Also try refreshing the Preview and starting a completely new game. The old conversation history might still be influencing the AI's responses.

My AI text adventure still isn't generating vivid stories after updating the prompt.

Your AI storyteller is producing vivid, coherent adventures with structured output. Next up, you'll add a restart button and a turn counter so players can track their journey through the story.

Add Story Memory and a Restart Feature

Your AI adventure now tells vivid, atmospheric stories with meaningfully different choices. That's prompt engineering at work.

Every turn you play adds to the conversation history sent to the AI. That history gets expensive over time and eventually hits token limits.

In this step, you'll give players a way to start fresh, plus visual touches that make each adventure feel like its own story.

In this step, get ready to:

Add a New Adventure button that clears conversation history and returns to genre selection.
Add a turn counter and an AI-generated story title.
Test the complete gameplay loop from start to restart.

Add a New Adventure button

Right now, the only way to start a new story is to close and reopen the app. Players need a way to start fresh without losing the app entirely.

In the Agent chat, send this prompt:

Add a 'New Adventure' button in the header that, when tapped, clears all conversation history and takes the player back to the genre selection screen. Ask for confirmation before clearing.

What does this prompt do?

This prompt asks Agent to build three things at once. First, a visible button in the header so the player can always reach it. Second, a confirmation dialog so players don't accidentally erase a story they're enjoying.

Third, the actual state reset that wipes the conversation history and navigates back to genre selection. Clearing the conversation history is how real AI apps manage state. It keeps costs down and avoids hitting token limits.

Wait for Agent to finish building. You'll see it modify files and run the app.
Tap the artifact bar at the bottom to open the Preview.
Select a genre and play one turn so you have some story to clear.
Tap the New Adventure button in the header.

A confirmation dialog should appear asking if you really want to start over. Confirm it, and you should land back on the genre selection screen with a fresh slate.

Don't see the New Adventure button?

Make sure Agent has finished building. Look for the summary of changes in the Agent chat before opening Preview.
If the button appears but nothing happens when you tap it, send a follow-up prompt to Agent: "The New Adventure button doesn't clear the history. Fix the click handler so it resets the conversation state and navigates to genre selection."
If the button is missing entirely, send: "I don't see the New Adventure button. Add it as a visible button in the top header area."

Still stuck? Help me troubleshoot why my New Adventure button isn't working in Replit Agent

Add a turn counter and story title

Your game works, but every adventure feels anonymous. A turn counter lets players track how deep they are into a story. An AI-generated title gives each adventure a unique identity.

In the Agent chat, send this prompt:

Add a turn counter that shows which turn the player is on (e.g., 'Turn 3'). Also, after the first scene is generated, ask the AI to generate a dramatic title for this specific adventure and display it at the top of the screen.

What does this prompt do?

The turn counter is a simple UI addition. It increments each time the player makes a choice, giving them a sense of progression.

The story title is more interesting. After the AI generates the opening scene, it analyzes the setting and plot to create a dramatic title. This means every playthrough gets a unique name like "The Crimson Labyrinth" or "Echoes of Station 9." The title comes from the AI itself, not from a template.

Wait for Agent to finish building.
Open the Preview and select a genre.
After the opening scene loads, look at the top of the screen for an AI-generated title.
Make a choice and check that the turn counter increments.

You should see a dramatic title appear after the first scene, and a turn counter that ticks up each time you pick a choice.

Turn counter or title not showing up?

If the turn counter is missing, send Agent: "The turn counter isn't visible during gameplay. Make sure it displays on every turn as 'Turn 1', 'Turn 2', etc."
If the title doesn't appear, the AI may not be generating it in the response. Send Agent: "The adventure title isn't showing up. After the first scene, ask the AI to include a 'title' field in the JSON response and display it at the top of the story screen."
If both features appear but look oddly placed, send Agent a styling note: "Move the adventure title and turn counter so they sit neatly at the top of the gameplay screen, above the story text."

Need more help? Help me get my turn counter and story title working

Test the full gameplay loop

You've added three features across two prompts. Before moving on, you need to verify they all work together in a single unbroken flow.

Before you start testing, think about what you expect to happen. If you play several turns and then tap New Adventure, will the title and turn counter reset too, or will they carry over from the old story?

Open the Preview if it's not already open.
Select a genre and wait for the opening scene.
Verify that a dramatic title appears at the top of the screen.
Play through 4-5 turns, watching the turn counter increment with each choice.
Pay attention to the story. Does the AI reference things that happened in earlier turns?
Tap New Adventure.
Confirm when the dialog appears.
Verify you're back at the genre selection screen with a completely fresh state.

The story should stay coherent across all turns, referencing earlier events in the plot. After tapping New Adventure and confirming, you should land back on genre selection with the title, turn counter, and story all cleared.

Story losing track of earlier events?

If the AI forgets what happened a few turns ago, the conversation history may not be passing correctly. Send Agent: "The AI is losing track of earlier story events. Make sure the full conversation history is included in every API request so the AI can reference past turns."
If the restart doesn't fully clear the state (old title lingers, turn counter doesn't reset to 1), send Agent: "When the player confirms New Adventure, make sure the title, turn counter, and all conversation history are fully reset before returning to genre selection."

Still having issues? Help me debug my adventure game's state management

Your adventure game now has a complete gameplay loop. Players can start a story, play through it with a sense of progression, and start fresh whenever they want. Next up, you'll take this from a preview to a live app that anyone can play.

Deploy Your Game Live

Your adventure game has genre selection, vivid AI storytelling, a turn counter, and a New Adventure button. Everything works in Preview.

A project that only runs inside the Replit editor is not a real app yet. Publishing it to a live URL gives it a permanent address on the internet that anyone can visit and play.

In this step, get ready to:

Publish your game to a live .replit.app URL.
Verify the deployed game works in Safari on your iPhone.
Share the link with a friend so they can play their own adventure.

Publish your game with Agent

Replit handles all the deployment infrastructure for you. Hosting, SSL certificates, and a public URL are set up automatically.

In the Agent chat, send the following prompt:

Publish this app.

Agent handles the entire deployment process. Once it finishes, you'll see a live URL ending in .replit.app.

What happens when you publish?

Replit provisions a server, sets up SSL, and assigns your app a public .replit.app URL. You did not need to configure any of this yourself.

Autoscale deployments scale to zero when there is no traffic. This means your app costs nothing to host when nobody is using it.

Copy the live URL that Agent gives you. You will need it in the next substep.

Agent didn't publish successfully?

Make sure your Core plan is active. Go to Account and check your subscription status.
Try sending the prompt again. Agent sometimes needs a second attempt if the first one times out.
Help me troubleshoot why my Replit app won't publish

Test your live game in Safari

Your game is live on the internet. Before you test it, take a guess: do you think the game will look and behave exactly the same as it did in Preview, or will something be different?

Open Safari on your iPhone.
Tap the address bar and paste your live .replit.app URL.
Select a genre and play through a full adventure of at least 4-5 turns.

The experience should be identical to what you saw in Preview. The AI generates vivid scenes, your choices drive the story, and the turn counter tracks your progress.

Verify the turn counter increments with each choice.
Verify the AI-generated title appears after the first scene.
Tap New Adventure and confirm it clears the story and returns you to genre selection.

Game not loading at the live URL?

Double-check the URL for typos. It should end in .replit.app.
Wait 30 seconds and try again. Autoscale deployments can take a moment to wake up on the first visit.
Return to the Replit app and ask Agent to confirm the deployment is active.
Help me figure out why my deployed Replit app isn't loading

Share your game with a friend

A live URL is only exciting if someone else can use it. Time to put your game to the real test.

Copy your .replit.app URL from Safari's address bar.
Text or message the link to a friend.
Ask them to open it and pick a genre. They should be able to play their own adventure without any Replit account or setup.

When your friend plays, they get their own separate story. Their choices do not affect yours. This is because each session starts a fresh conversation with the AI.

Why does each player get their own story?

Every time someone opens your URL, the app starts a brand new conversation with the Anthropic API. The conversation history that tracks choices and plot points is stored per session, not globally. Your friend's horror adventure and your sci-fi adventure run completely independently.

You just built and deployed an AI-powered game from your phone. The same skills you used here, calling an AI API, crafting prompts, and managing conversation state, are the building blocks of every AI product.

Secret mission

Add a Plot Twist Button

Your story rolls along predictably. Every choice leads to the next expected beat. In this secret mission, you'll add a Plot Twist button that forces the AI to throw a dramatic, unexpected curveball into your story mid-adventure.

Clean Up Your Resources

Your Replit Core subscription costs $25/month and continues running until canceled. Decide whether to keep your resources running, pause them to come back later, or delete them entirely.

Cost warning

Your Replit Core plan charges $25/month (or $20/month billed annually) until you cancel. AI API usage through Replit AI Integrations is also billed at the provider's rate from your Replit credits.

If you're done with this project and don't plan to use Replit again, cancel your subscription from Settings to avoid ongoing charges.

Resources you used:

Replit project (web app with AI integration).
Published deployment on Replit (live URL ending in .replit.app).
Replit Core subscription ($25/month).

Keep everything running

No action needed. Choose this if you're still actively building or want your game to stay live.

Your app stays live at its .replit.app URL.
Autoscale deployments scale to zero when there's no traffic, so deployment costs are minimal when nobody is playing.
Your Replit Core subscription ($25/month) continues billing until you cancel.
AI API usage is billed at the provider's rate from your Replit credits only when someone plays the game.

Pause - I'll come back to this later

Shut down the live deployment to stop deployment charges. Your project files stay intact so you can republish later.

In your Replit project, open Publishing and select the option to shut down your deployment, then confirm.
Your app goes offline and stops incurring deployment charges. Your project files, code, and database are not deleted.
To bring the app back later, open Publishing and select Publish again.
Your Replit Core subscription still charges $25/month. To pause the subscription, open Settings then Billing and look for the pause option if eligible.

Delete - I don't want to use this again

Remove all project resources and cancel your subscription to stop all charges.

Shut down the deployment first. In your Replit project, open Publishing and select the option to shut down your deployment, then confirm.
Delete the project. From the Replit home screen, find your project card, tap the overflow menu (three dots), and select Delete. Confirm when prompted.
Cancel your Core subscription. Open Settings, then Billing, and select the option to cancel your subscription. Complete the confirmation steps. Your Core features remain until the end of the billing period, after which your account moves to the free Starter plan.

What happens after canceling?

Published apps may go offline after your plan downgrades. Deleted projects are permanently removed after 30 days and cannot be recovered.

That's a Wrap!

You just built and deployed a fully functional AI text adventure game, entirely from your iPhone. No laptop, no desktop, no local setup. Just you, Replit, and a well-crafted prompt.

You've learned how to:

Build an AI-powered web app by sending natural language prompts to Replit Agent, calling an AI API to generate structured responses, and rendering those responses in a live UI.
Practice prompt engineering by rewriting a vague system prompt into a set of precise rules that transformed generic AI output into vivid, atmospheric narratives with structured JSON output.
Manage multi-turn conversation state to maintain story continuity across turns, and deploy the finished game to a live URL that anyone can play.
Completed an optional Secret Mission to push your skills further with a bonus feature.

Ready to quiz yourself?