I’ve been experimenting with using Claude Code on iOS to build projects from my phone. It’s been a great learning experience, and I wrote about the broader experiment in I Built an App That’s Only Useful Three Weeks a Year. But before that project went smoothly, I hit some friction that’s worth sharing on its own.
Most of these tips are specific to starting greenfield projects from your phone. If you’re making changes to an existing repo that already has the right files in place, the experience is significantly smoother from the start.
Create Your Repo With a Default README
When you start a brand new project from your phone, you need a GitHub repo. The GitHub iOS app doesn’t let you create repos, so you’ll have to authenticate into GitHub in the mobile browser to do it.
Here’s the important part: have GitHub create a default README when you set
up the repo. Not for the README content, but just to get a main branch.
Claude Code on iOS works in cloud-prefixed branches (starting with
claude/). For reasonable security, it can’t create or edit the main
branch or any other non-claude/ branch. If there’s no main branch when
Claude pushes its working branch, that branch becomes the default branch
of your repo. There’s no easy way to create a main branch from your phone
after the fact. Not from the GitHub iOS app, not from the mobile web. It’s a
mess to sort out, and Claude can’t help you fix it because of those same
branch restrictions.
Set Up a CLAUDE.md Early
A brand new repo won’t have a CLAUDE.md or AGENTS.md file. On desktop,
Claude Code has access to your global configuration file with your
preferences for things like commit message conventions. On iOS, it doesn’t.
So a new project has no context for how you like things done: commit style,
language preferences, TDD, commit frequency, any of it.
On my first project from a phone, Claude defaulted to vanilla JavaScript when I
would have preferred TypeScript. I just didn’t catch it because everything was
moving so quickly in the autonomous mode. That’s the kind of thing a CLAUDE.md
would have prevented.
Consider a Template Repo
I’m pretty confident now that the right move is to set up a template repo with sensible defaults for phone-first development:
- A
CLAUDE.mdwith your preferences (language, commit conventions, testing approach) - Basic Gitleaks workflows for secret scanning
- Whatever project scaffolding makes sense for the kind of things you build
I haven’t built this yet, but it’s next on my list. The goal is to remove as much of the initial setup friction as possible so that starting a new project from my phone is as smooth as working on an existing one.