Crabshell

Crabshell is an open-source iPhone-native dev shell backed by a local Mac agent.

The intended flow is simple: install the bridge on your Mac, build Crabshell onto a real iPhone, then use the phone to chat with your local agent. The agent edits the app in place, fixes compile errors, and keeps shipping the next version back to your device.

What Crabshell Is

• A protected iOS shell that always keeps an assistant entry point on device
• A local Mac bridge that relays chat turns to codex or another agent/CLI
• A project layout where the shell stays stable and the generated product lives in a separate app layer

Crabshell is not meant to be a cloud IDE. The Mac remains the execution environment for code generation, Xcode builds, signing, and installation.

Product Flow

1. Clone the repository on your Mac.
2. Install and start the local bridge.
3. Build Crabshell onto a real iPhone.
4. Open the app and tap Start Building.
5. Connect to your Mac by QR code, Bonjour/local network discovery, or manual URL.
6. Chat from the phone and ask the Mac agent to build your app.
7. The agent edits UserApp/, fixes red build errors, and deploys the next version back to the same device.
8. After the first app version exists, Crabshell keeps an in-app floating assistant entry for further iteration.

Architecture Boundary

Crabshell is split into two layers:

• Crabshell/Core/
  • Shell entry
  • Bridge connectivity
  • Agent chat UI
  • Recovery path
  • Floating assistant entry
• Crabshell/UserApp/
  • The user's actual product surface
  • Screens, components, models, and assets that the Mac agent should edit by default

Rule of thumb:

• Preserve Core/ unless you are intentionally upgrading the shell itself.
• Default all product generation and iteration work to UserApp/.
• Avoid unnecessary .xcodeproj edits.

Agent-First Install

The primary install path is to hand the repository to a local coding agent.

Copy the prompt below into Codex, Claude Code, or a similar local agent running on the Mac:

You are setting up Crabshell on this Mac as a local iOS dev shell.

Tasks:
1. Inspect this repository and understand its iOS app target and bridge target.
2. Verify local prerequisites for iOS development: Xcode, simulators, signing visibility, node, and codex.
3. Set up the Mac bridge and ensure it can run locally.
4. Build the iOS app and prepare it for installation to a real iPhone.
5. Keep Crabshell Core intact. Do not remove the shell, bridge, recovery path, or assistant entry.
6. Treat future generated product work as living under `Crabshell/UserApp`.
7. If something is missing, create the minimal required structure rather than stopping early.
8. Summarize blockers clearly, but continue as far as possible.

Manual Install

If you want to do the setup without an agent:

1. Install Xcode and confirm command line tools work.
2. Install your local coding CLI, such as codex.
3. Set up and run the bridge from the sibling bridge project.
4. Open Crabshell.xcodeproj.
5. Configure signing for your Apple Developer team.
6. Build and run the app on a real iPhone.
7. Pair the app with your Mac bridge from inside the shell chat UI.

Repository Layout

Crabshell/
├─ Crabshell/
│  ├─ Core/
│  │  ├─ App/
│  │  ├─ AgentUI/
│  │  └─ Bridge/
│  └─ UserApp/
├─ Crabshell.xcodeproj/
└─ README.md

Related local bridge project used during development:

• /Users/leitong/Downloads/CrabshellBridge

Current iPhone UX

• First launch shows a blank starter shell with Create your own app just with a click
• Tapping Start Building enters the assistant flow
• The assistant can connect to the Mac over QR, Bonjour/local network discovery, or a manual bridge address
• Once the product surface is activated, the assistant remains available as a floating in-app button

Safety Model

• The Mac agent should default to editing UserApp/
• Core/ should remain usable even if user-level product generation fails
• Build failures should be repaired in place rather than leaving the app in a broken state
• The shell must always preserve a path back into the assistant

Status

The repository currently includes:

• An iOS shell chat client
• Bonjour discovery for nearby Mac bridges
• QR code pairing import
• A Core/ and UserApp/ split for future generated app work

The next major milestone is tightening the real-device build loop so a local Mac agent can repeatedly ship UserApp changes back to the phone with minimal manual steps.