https://github.com/superwall/supervibes
Vibecode native Swift apps without Xcode
https://github.com/superwall/supervibes
Last synced: 10 months ago
JSON representation
Vibecode native Swift apps without Xcode
- Host: GitHub
- URL: https://github.com/superwall/supervibes
- Owner: superwall
- Created: 2025-08-26T03:51:03.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-08-27T21:32:57.000Z (10 months ago)
- Last Synced: 2025-08-28T04:27:43.903Z (10 months ago)
- Language: Shell
- Size: 314 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Supervibes ⚡️
An opinionated Claude Code workflow to build native iOS apps in Swift, mostly without (but definitely alongside) Xcode. Built by [Superwall](https://superwall.com).
```
/$$$$$$$
/$$__ $$
| $$ \__/ /$$ /$$ /$$$$$$$ /$$$$$$ /$$$$$$
| $$$$$$ | $$ | $$| $$__ $$ /$$__ $$| $$__ $$
\____ $$| $$ | $$| $$ \ $$| $$$$$$$$| $$ \__/
/$$ \ $$| $$ | $$| $$ | $$| $$_____/| $$
| $$$$$$/| $$$$$$/| $$$$$$$/| $$$$$$$| $$ /$$ /$$|
\______/ \______/ | $$____/ \_______/|__/ |__/ | $$|
| $$ /$$ /$$ /$$ | $$$$$$$ | $$$$$$ /$$$$$$$
| $$ | $$ /$$/| $$ | $$__ $$| $$__ $$ /$$_____/
|__/ \ $$/$$/ | $$ | $$ \ $$| $$$$$$$$| $$$$$$
\ $$$/ | $$ | $$ | $$| $$_____/ \____ $$
\ $/ | $$ | $$$$$$$/| $$$$$$$ /$$$$$$$/
\_/ |__/ |_______/ \_______/|_______/
```
## Features
- 🚀 **Quick Setup** - Generate a complete iOS project in seconds
- 📱 **Build to Device** - Automatically builds to connected iOS devices
- 🎨 **SwiftUI Templates** - Modern SwiftUI app structure out of the box
- 🛠 **Build Scripts** - Scripts for building, running, and testing from the terminal
- 🧪 **Test Configuration** - Separate schemes for development with unit and UI tests
- 🎯 **XcodeGen Integration** - Create files outside of Xcode while maintaining interoperability
- 🤖 **Claude AI Ready** - Battle tested Agents & CLAUDE.md files
## Quick Install
```bash
curl -fsSL https://raw.githubusercontent.com/superwall/supervibes/refs/heads/main/install.sh | bash
```
## Usage
### Create a new project
```bash
supervibes # Interactive mode - prompts for all details
supervibes --test # Quick test mode - uses saved settings
```
### Regenerate project configuration
```bash
supervibes --init # Regenerate config from supervibes.local.json
# (preserves source code and assets)
```
### Maintain Supervibes
```bash
supervibes --update # Update to latest version
supervibes --uninstall # Remove Supervibes from your system
supervibes --help # Show all available commands
```
### Working with generated projects
```bash
cd YourProject
scripts/build # Build the app
scripts/run # Build and run on device/simulator
scripts/install # Install and launch latest build
scripts/xcode # Open in Xcode
scripts/unit-test # Run unit tests
scripts/ui-test # Run UI tests
# Use flags for different configurations
scripts/run --debug # Debug configuration with test support
scripts/run --simulator # Target iOS simulator
scripts/run --debug --simulator # Combine flags
```
## Generated Project Structure
```
projects/YourProject/
├── project.yml # XcodeGen configuration
├── YourProject/ # Source code
│ ├── YourProjectApp.swift # App entry point
│ └── ContentView.swift # Main view
├── YourProjectTests/ # Unit tests
├── YourProjectUITests/ # UI tests
├── scripts/ # Automation scripts
│ ├── build # Build only
│ ├── run # Build and run on device
│ ├── install # Install and run latest build
│ ├── unit-test # Run unit tests
│ ├── ui-test # Run UI tests
│ └── xcode # Open project in Xcode
├── CLAUDE.md # Project documentation for Claude AI
└── .claude/ # Claude AI configuration
└── agents/ # Specialized AI agents
```
## Build Scripts
All scripts are generated in the `scripts/` directory of your project:
| Script | Description | Flags |
| ----------- | ---------------------------------- | ------------------------ |
| `build` | Builds the project | `--debug`, `--simulator` |
| `run` | Builds and runs the app | `--debug`, `--simulator` |
| `install` | Installs and launches latest build | `--debug`, `--simulator` |
| `unit-test` | Runs unit tests (debug scheme) | - |
| `ui-test` | Runs UI tests (debug scheme) | - |
| `xcode` | Opens project in Xcode | - |
**Flag descriptions:**
- `--debug` - Uses debug configuration with test support
- `--simulator` - Targets iOS simulator instead of physical device
- Flags can be combined: `scripts/run --debug --simulator`
### Prerequisites
Before using Supervibes, ensure you have all the required tools installed.
**Quick check:** Run our setup checker to see what's missing:
```bash
supervibes-check # After installation
# or
~/.supervibes/check-setup.sh # Direct path
```
#### Required Tools
#### 1. **Xcode & Command Line Tools**
Make sure Xcode is installed from the App Store and command line tools are set up:
```bash
xcode-select --install
```
#### 2. **Homebrew**
The package manager for macOS. If not installed:
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
#### 3. **XcodeGen**
For generating Xcode projects from YAML specifications:
```bash
brew install xcodegen
xcodegen --version # Verify installation
```
#### 4. **SwiftFormat**
For consistent code formatting across generated projects:
```bash
brew install swiftformat
swiftformat --version # Verify installation
```
#### 5. **GitHub CLI**
For repository operations and pull request management:
```bash
brew install gh
gh auth login # Follow the prompts to authenticate
```
#### 6. **Claude Code** (Optional but Recommended)
For AI-powered development assistance:
```bash
npm install -g @anthropic-ai/claude-code
claude -v # Verify installation
```
If you don't have npm, install Node.js first:
```bash
brew install node
```
#### 7. **Apple Developer Setup**
You'll need your Apple Developer Team ID. To find it:
1. Visit https://developer.apple.com/account
2. Sign in with your Apple ID
3. Scroll down to "Membership details" and copy your Team ID:
```
┌────────────────────────────────┐
│ Membership details │
├────────────────────────────────┤
│ Entity name: Your Company │
│ Team ID: XXXXXXXXXX │ <- copy this
│ Entity type: Organization │
└────────────────────────────────┘
```
## Getting Started
Once Supervibes is installed, you can use it from any directory:
### Interactive Mode
Navigate to where you want your project and run:
```bash
supervibes
```
You'll be asked for:
- Project name (lowercase, alphanumeric)
- Display name
- Bundle identifier
- Development Team ID (with visual guide to find it)
- Device selection (optional, for deployment scripts)
- Project description (for AI assistance)
### Quick Test Mode
Generate a test project with a random name using saved settings:
```bash
./supervibes --test
```
This requires running the interactive mode at least once to save your Team ID and device.
### Init Mode
Regenerate project configuration from an existing `supervibes.local.json` file:
```bash
supervibes --init
```
This mode allows you to:
- Regenerate all project configuration files (project.yml, scripts, CLAUDE.md, etc.)
- Preserve your source code files (Swift, assets, tests)
- Update build settings or fix corrupted configuration
- Useful when pulling a project from git or sharing projects between developers
### Command Line Options
```bash
supervibes [options]
Options:
--test # Quick test mode with random project name
--projects-dir=PATH # Specify custom projects directory
--init # Regenerate project config from supervibes.local.json
--update # Update Supervibes to latest version
--uninstall # Uninstall Supervibes (with confirmation)
--help, -h # Show help message
Examples:
supervibes # Interactive mode in current directory
supervibes --test # Create test project with random name
supervibes --init # Regenerate project config (preserves source code)
supervibes --update # Update to latest version
supervibes --uninstall # Remove Supervibes from your system
```
## Configuration
### Schemes
Two schemes are generated:
1. **Release** (`YourProject`) - Optimized for production
- No test targets
- Release configuration
- Used by default in scripts
2. **Debug** (`YourProject-debug`) - For development and testing
- Includes unit and UI test targets
- Debug configuration with symbols
- Used with `--debug` flag in scripts
### Saved Settings
Your Team ID and device selection are automatically saved in `supervibes.json` for future use.
### Finding Your Team ID
The generator shows a visual guide:
```
Visit https://developer.apple.com/account
Scroll down and copy your Team ID:
┌────────────────────────────────┐
│ Membership details │
├────────────────────────────────┤
│ Entity name: Your Company │
│ Team ID: XXXXXXXXXX │ <- copy this
└────────────────────────────────┘
```
## Claude AI Integration
Each project includes:
- **CLAUDE.md** - Project-specific documentation with your project overview
- **.claude/** - Configuration directory with specialized AI agents
- Modern Swift development guidelines
- XcodeGen documentation integration
## Acknowledgments
Supervibes stands on the shoulders of giants. Special thanks to:
- **[XcodeGen](https://github.com/yonaskolb/XcodeGen)** by Yonas Kolb - The foundation of our project generation
- **[SwiftFormat](https://github.com/nicklockwood/SwiftFormat)** by Nick Lockwood - Keeping our code beautifully formatted
- **[Claude Code](https://claude.ai/code)** by Anthropic - AI-powered development assistance
## Contributing
This is an internal Superwall tool (for now)! Please implement the features you think are necessary for launch.
## License
Private repository - Superwall internal use only.
## Development Setup
If you want to contribute to Supervibes or run the development version:
```bash
# Clone the repository
git clone https://github.com/superwall/supervibes.git
cd supervibes
# Run the development setup
./setup-dev.sh
```
This creates `supervibes-dev` command that runs from your development directory.
## Uninstall
To remove Supervibes:
```bash
rm -rf ~/.supervibes ~/.local/bin/supervibes
```
For development version:
```bash
rm -rf ~/.supervibes-dev ~/.local/bin/supervibes-dev
```
---
Built with 💙 by [Superwall](https://superwall.com)