← Back to Help Center

🧙 The AI Wizard

How to prompt, build, iterate, and troubleshoot.

What Is the Wizard?

The Wizard is SaaSClaw's core building experience. It's a chat interface where you describe what you want, and the AI agent plans, writes, and iterates on your application code in real time.

Getting Started

1. Create a project (choose a framework or import from your GitHub repo).
2. Click 🧙 Wizard on the project page to start a session.
3. Type what you want to build.
4. Review the agent's tool activity as it reads files, writes code, and runs commands.
5. Click 🚀 Deploy when you're happy with the result.

📋 Prompting Tips

The better your prompt, the better the output. Here's what works:

Break Big Projects Into Steps

Don't ask the wizard to build everything at once. Start with the core, then iterate:

1. First message: "Build a task management app with a list view, add/edit/delete tasks, and local storage persistence."
2. Second message: "Now add a calendar view that shows tasks on their due dates."
3. Third message: "Add drag-and-drop reordering to the list view."

Each step is smaller, more testable, and easier to debug.

Tell It What Framework You're Using

The wizard detects your framework, but it helps to reference it:

• "Use Vue 3 Composition API with TypeScript"
• "Write it as a Django app with template inheritance"
• "Make it a single-page React app with Tailwind CSS"

Static Sites & Data Storage

Static sites don't have a server or database, but the wizard knows how to use the SaaSClaw Form API to store data server-side:

• "Add a contact form that submits to the Form API — name, email, and message fields"
• "Build a waitlist signup form that POSTs to /api/forms/{slug}/"
• "Add a newsletter subscription form at the bottom of the landing page"

Just ask the wizard to store, save, submit, or persist data — it will use the Form API automatically. You can view submissions on the project page under Submissions.

Reference Existing Code

The wizard reads your project files automatically. You can also:

• "Update the header in App.vue to match the new color scheme"
• "Refactor the API calls in utils/fetch.js to use async/await"
• "Fix the bug in the handleSubmit function in Login.svelte"

🔧 Troubleshooting

The Agent Seems Stuck

Sometimes the stream goes silent mid-turn. If the wizard indicator shows "thinking" for more than 30 seconds with no tool activity:

1. Wait — complex operations (large file writes, npm installs) can take time.
2. If you see ⚠️ Agent seems stuck, click ⟳ Retry to reset the UI.
3. Click ⏹ End to end the session, then start a new one.

The Agent Wrote Broken Code

• Ask it to fix specific issues: "The button doesn't do anything when clicked — check the event handler."
• If it keeps failing, be more specific: "In App.vue, the submitForm function needs to call the API endpoint POST /api/tasks."
• Start a new session if context is getting confused.

Deploy Failed

• Check the deploy status on the project page — error details are shown there.
• Python projects: Version pin conflicts are common (e.g., a library pinned to a version not available on Python 3.14). Check requirements.txt.
• Node projects: Dependency conflicts between vite and plugins can cause npm install to fail.
• Try deploying again — sometimes a second attempt resolves transient issues.

Preview Shows Errors / 400 / 500

• 400 Bad Request: Usually Django's ALLOWED_HOSTS. Make sure your settings read from environment variables.
• 500 Server Error: Often unapplied migrations. The wizard doesn't always run migrations — check if manage.py migrate is needed.
• 404 Not Found: The app might not have a root route, or the build didn't generate the expected output.

Changes Aren't Showing Up

• You need to click 🚀 Deploy after the wizard makes changes — code is only in the repo until deployed.
• Hard-refresh the preview URL (Ctrl+Shift+R) to bypass browser cache.
• Check that static files were collected (Django projects).

⌨️ Wizard Controls

• Send — Send your message to the agent.
• ✕ Stop — Halt the agent mid-turn. Code written so far is preserved.
• 🔄 New — Start a fresh wizard session for this project.
• 🚀 Deploy — Commit changes and deploy to preview.
• ⏹ End — End the session and return to the project page.

🧠 Agent Activity

While the agent works, you'll see tool messages in the chat:

• 📖 read — Reading an existing file to understand the codebase.
• ✏️ write — Creating or overwriting a file.
• 📝 edit — Making targeted edits to a specific file.
• 💻 bash — Running a shell command (install, test, build).

Each tool message shows a preview of what was read/written. Click [collapse] to hide details.

💡 Best Practices

• Be specific about tech stack, styling, and behavior.
• Build incrementally — core first, features later.
• Deploy and test frequently rather than building everything before checking.
• If the agent goes off track, stop it and redirect with a clearer prompt.
• Start a new session when context gets long — keeps things focused.