The rule: no error shown to you requires engineering knowledge to interpret. When Prototo can’t recover automatically, it tells you what to do.
The error translation layer
| What you see | What to do |
|---|---|
| A component couldn’t be found | Run: npx proto reset |
| A screen has an error | Ask your agent: fix any errors in the [ScreenName] screen |
| Prototo is already running | Close the other terminal window first |
| Prototo needs to update | Run: proto update |
| Can’t reach your device | Check you’re on the same WiFi |
| Something went wrong | Run: npx proto reset |
The escape hatch: npx proto reset
npx proto resetThis fixes 90% of issues. Silently it kills the bundler, clears caches, and restarts the environment with the Simulator open.
You’ll see: Proto restarted. Simulator is updating.
A screen has an error
If your agent generates a screen that won’t compile, the error translation layer responds:
A screen has an error. Ask your agent:
"fix any errors in the [ScreenName] screen"Paste that into your agent. It reads the file, identifies the issue, rewrites it. Resolved without you seeing the underlying error.
The Simulator isn’t opening
Make sure Xcode is installed and you’ve run:
xcode-select --installThen try:
npx proto resetMy agent isn’t reading my design system
AGENTS.md and DESIGN.md must be at the root of your project folder, not inside any subfolder.
Start your agent from inside the project folder:
cd myapp
claude # or: codexnpx proto design isn’t working
Make sure you’re inside a Proto project folder:
cd myapp
npx proto designA custom component library isn’t generating right screens
Add 2–3 component examples to an ## Examples section in DESIGN.md, then ask your agent to regenerate the screen. Two or three examples cover most libraries. It extrapolates the rest.
I need to start fresh
Delete the project folder and run:
npm create proto@latest myappStill stuck?
Open an issue on GitHub: github.com/sherizan/proto/issues
Or reach out via prototo.app .