diff --git a/BUILD_MACOS.md b/BUILD_MACOS.md
new file mode 100644
index 00000000..dae122a8
--- /dev/null
+++ b/BUILD_MACOS.md
@@ -0,0 +1,60 @@
+# BitChat macOS Build
+
+This Justfile provides easy commands to build and run BitChat natively on macOS while preserving the original project configuration.
+
+## Quick Start
+
+```bash
+# Build and run the app
+just run
+
+# Or see all available commands
+just
+```
+
+## Commands
+
+- `just run` - Build and run the macOS app
+- `just build` - Build the macOS app only  
+- `just clean` - Clean build artifacts and restore original files
+- `just check` - Check prerequisites (XcodeGen, Xcode, etc.)
+- `just info` - Show app information and requirements
+
+## How It Works
+
+The Justfile temporarily modifies `project.yml` to:
+- Use your local development team ID (replaces `L3N5LHJD5Y`)
+- Change bundle identifier to avoid conflicts (`chat.bitchat` → `com.local.bitchat`)
+- Disable code signing for local development (`Automatic` → `Manual`)
+- Exclude iOS-specific files from macOS build (`LaunchScreen.storyboard`)
+
+**Original files are always preserved** - modifications are only applied during builds and automatically cleaned up. The project files remain exactly as they are on the main branch.
+
+## Requirements
+
+- macOS 13.0+ (Ventura)
+- Xcode (from App Store)
+- XcodeGen (`brew install xcodegen`)
+- Bluetooth LE capable Mac
+- Physical device (Bluetooth doesn't work in simulator)
+
+## App Features
+
+- **Native macOS SwiftUI app** - not a Catalyst port
+- **Bluetooth LE mesh networking** - no internet required
+- **End-to-end encryption** - X25519 + AES-256-GCM
+- **Store-and-forward messaging** - works with offline peers
+- **Channel-based group chats** - IRC-style commands
+- **Private messaging** with delivery receipts
+- **Emergency wipe** - triple-tap logo to clear all data
+
+## Usage
+
+Once running:
+- Set your nickname and start discovering nearby peers
+- Use `/join #channel` for group chats
+- Use `/msg @user` for private messages  
+- Use `/who` to see connected peers
+- Triple-tap the logo for emergency data wipe
+
+The app creates a decentralized mesh network over Bluetooth LE that can span significant distances through multi-hop message relay.
diff --git a/Justfile b/Justfile
new file mode 100644
index 00000000..26ad3817
--- /dev/null
+++ b/Justfile
@@ -0,0 +1,116 @@
+# BitChat macOS Build Justfile
+# Handles temporary modifications needed to build and run on macOS
+
+# Default recipe - shows available commands
+default:
+    @echo "BitChat macOS Build Commands:"
+    @echo "  just run     - Build and run the macOS app"
+    @echo "  just build   - Build the macOS app only"
+    @echo "  just clean   - Clean build artifacts and restore original files"
+    @echo "  just check   - Check prerequisites"
+    @echo ""
+    @echo "Original files are preserved - modifications are temporary for builds only"
+
+# Check prerequisites
+check:
+    @echo "Checking prerequisites..."
+    @command -v xcodegen >/dev/null 2>&1 || (echo "❌ XcodeGen not found. Install with: brew install xcodegen" && exit 1)
+    @command -v xcodebuild >/dev/null 2>&1 || (echo "❌ Xcode not found. Install Xcode from App Store" && exit 1)
+    @security find-identity -v -p codesigning | grep -q "Developer ID" || (echo "⚠️  No Developer ID found - code signing may fail" && exit 0)
+    @echo "✅ All prerequisites met"
+
+# Backup original files
+backup:
+    @echo "Backing up original project configuration..."
+    @cp project.yml project.yml.backup 2>/dev/null || true
+    @# Backup other files that get modified by xcodegen
+    @if [ -f bitchat.xcodeproj/project.pbxproj ]; then cp bitchat.xcodeproj/project.pbxproj bitchat.xcodeproj/project.pbxproj.backup; fi
+    @if [ -f bitchat/Info.plist ]; then cp bitchat/Info.plist bitchat/Info.plist.backup; fi
+
+# Restore original files
+restore:
+    @echo "Restoring original project configuration..."
+    @if [ -f project.yml.backup ]; then mv project.yml.backup project.yml; fi
+    @# Restore iOS-specific files
+    @if [ -f bitchat/LaunchScreen.storyboard.ios ]; then mv bitchat/LaunchScreen.storyboard.ios bitchat/LaunchScreen.storyboard; fi
+    @# Use git to restore all modified files except Justfile
+    @git checkout -- project.yml bitchat.xcodeproj/project.pbxproj bitchat/Info.plist 2>/dev/null || echo "⚠️  Could not restore some files with git"
+    @# Remove any backup files
+    @rm -f bitchat.xcodeproj/project.pbxproj.backup bitchat/Info.plist.backup 2>/dev/null || true
+
+# Apply macOS-specific modifications
+patch-for-macos: backup
+    @echo "Temporarily hiding iOS-specific files for macOS build..."
+    @# Move iOS-specific files out of the way temporarily
+    @if [ -f bitchat/LaunchScreen.storyboard ]; then mv bitchat/LaunchScreen.storyboard bitchat/LaunchScreen.storyboard.ios; fi
+
+# Generate Xcode project with patches
+generate: patch-for-macos
+    @echo "Generating Xcode project..."
+    @xcodegen generate
+
+# Build the macOS app
+build: check generate
+    @echo "Building BitChat for macOS..."
+    @xcodebuild -project bitchat.xcodeproj -scheme "bitchat (macOS)" -configuration Debug CODE_SIGN_IDENTITY="" CODE_SIGNING_REQUIRED=NO CODE_SIGN_ENTITLEMENTS="" build
+
+# Run the macOS app
+run: build
+    @echo "Launching BitChat..."
+    @find ~/Library/Developer/Xcode/DerivedData -name "bitchat.app" -path "*/Debug/*" | head -1 | xargs -I {} open "{}"
+
+# Clean build artifacts and restore original files
+clean: restore
+    @echo "Cleaning build artifacts..."
+    @rm -rf ~/Library/Developer/Xcode/DerivedData/bitchat-* 2>/dev/null || true
+    @# Only remove the generated project if we have a backup, otherwise use git
+    @if [ -f bitchat.xcodeproj/project.pbxproj.backup ]; then \
+        rm -rf bitchat.xcodeproj; \
+    else \
+        git checkout -- bitchat.xcodeproj/project.pbxproj 2>/dev/null || echo "⚠️  Could not restore project.pbxproj"; \
+    fi
+    @rm -f project-macos.yml 2>/dev/null || true
+    @echo "✅ Cleaned and restored original files"
+
+# Quick run without cleaning (for development)
+dev-run: check
+    @echo "Quick development build..."
+    @if [ ! -f project.yml.backup ]; then just patch-for-macos; fi
+    @xcodegen generate
+    @xcodebuild -project bitchat.xcodeproj -scheme "bitchat (macOS)" -configuration Debug CODE_SIGN_IDENTITY="" CODE_SIGNING_REQUIRED=NO CODE_SIGN_ENTITLEMENTS="" build
+    @find ~/Library/Developer/Xcode/DerivedData -name "bitchat.app" -path "*/Debug/*" | head -1 | xargs -I {} open "{}"
+
+# Show app info
+info:
+    @echo "BitChat - Decentralized Mesh Messaging"
+    @echo "======================================"
+    @echo "• Native macOS SwiftUI app"
+    @echo "• Bluetooth LE mesh networking"
+    @echo "• End-to-end encryption"
+    @echo "• No internet required"
+    @echo "• Works offline with nearby devices"
+    @echo ""
+    @echo "Requirements:"
+    @echo "• macOS 13.0+ (Ventura)"
+    @echo "• Bluetooth LE capable Mac"
+    @echo "• Physical device (no simulator support)"
+    @echo ""
+    @echo "Usage:"
+    @echo "• Set nickname and start chatting"
+    @echo "• Use /join #channel for group chats"
+    @echo "• Use /msg @user for private messages"
+    @echo "• Triple-tap logo for emergency wipe"
+
+# Force clean everything (nuclear option)
+nuke:
+    @echo "🧨 Nuclear clean - removing all build artifacts and backups..."
+    @rm -rf ~/Library/Developer/Xcode/DerivedData/bitchat-* 2>/dev/null || true
+    @rm -rf bitchat.xcodeproj 2>/dev/null || true
+    @rm -f project.yml.backup 2>/dev/null || true
+    @rm -f project-macos.yml 2>/dev/null || true
+    @rm -f bitchat.xcodeproj/project.pbxproj.backup 2>/dev/null || true
+    @rm -f bitchat/Info.plist.backup 2>/dev/null || true
+    @# Restore iOS-specific files if they were moved
+    @if [ -f bitchat/LaunchScreen.storyboard.ios ]; then mv bitchat/LaunchScreen.storyboard.ios bitchat/LaunchScreen.storyboard; fi
+    @git checkout -- project.yml bitchat.xcodeproj/project.pbxproj bitchat/Info.plist 2>/dev/null || echo "⚠️  Not a git repo or no changes to restore"
+    @echo "✅ Nuclear clean complete"
diff --git a/README.md b/README.md
index 7c3cc89b..5f7ebe3c 100644
--- a/README.md
+++ b/README.md
@@ -157,3 +157,8 @@ The protocol is designed to be platform-agnostic. An Android client can be built
 - Bluetooth LE APIs
 - Same packet structure and encryption
 - Compatible service/characteristic UUIDs
+
+## MacOS
+
+Want to try this on macos: `just run` will set it up and run from source. 
+Run `just clean` afterwards to restore things to original state for mobile app building and development.