Free BongoCat Overlay for macOS

A native macOS implementation of the beloved BongoCat overlay, written in Swift. Perfect for streamers, content creators, and anyone who wants an adorable cat companion on their desktop that reacts to their typing and interactions.

What is BongoCat?

BongoCat is a popular internet meme featuring a cat playing bongos, originally created by DitzyFlama using StrayRogue's adorable cat drawing. This project brings the interactive BongoCat experience to macOS as a native application.

✨ Features

BongoCat is a fully-featured, native macOS typing companion with extensive customization options.

🐱 Core Animation System

🪟 Transparent Overlay - Borderless, always-on-top window that works everywhere
⌨️ Smart Keyboard Detection - Cat reacts to typing with intelligent paw assignments
🖱️ Mouse Click Animations - Left and right click detection with paw responses
🎯 Consistent Key Mapping - Same keys always use the same paw for realistic typing
⚡ Real-time Response - Instant reactions to your input with smooth animations
🔄 State Management - Proper paw up/down states with minimum animation durations

🎛️ Extensive Customization

📏 Size & Scale Options

Multiple Scale Presets: Small (65%), Medium (75%), Big (100%)
Scale Pulse Animation: Optional size pulse on each keystroke/click
Dynamic Scaling: Window resizes automatically with scale changes

🎨 Visual Customization

Cat Rotation: Toggle 13° tilt (adjusts automatically with flip direction)
Horizontal Flip: Mirror the cat for left-handed setups or preference
Position Memory: Remembers your preferred placement

🎯 Advanced Positioning

Drag & Drop: Move the cat anywhere on screen by dragging
Corner Snapping: Quick positioning to screen corners (Top/Bottom × Left/Right)
Per-App Positioning: 🌟 Unique Feature! Cat remembers different positions for different applications
Position Persistence: Saves and restores positions across app restarts
Multi-Monitor Support: Works across multiple displays

🚀 Installation

📋 Requirements

macOS 13.0 (Ventura) or later
Accessibility permissions for global input monitoring
~5MB disk space for the application

📥 Download Options

🎯 Ready-to-Use (Recommended)

Download the latest BongoCat-*.dmg from Releases
Open the DMG and drag BongoCat to Applications
Right-click on BongoCat in Applications and select "Open" (see Gatekeeper Guide)
Grant accessibility permissions when prompted

💡 Pro Tip: If you're reinstalling and accessibility permissions keep being asked, use the packaged DMG instead of building from source. The official releases are code signed for consistent identity.

🔐 Security Note: On first launch, macOS may show a security warning. This is normal for apps not signed with an Apple Developer certificate. See our Gatekeeper Guide for safe launch instructions.

🛠️ Build from Source

Perfect for developers or those who want the latest features:

Building from Source

# Clone the repository
git clone https://github.com/Gamma-Software/BongoCat-mac.git
cd BongoCat-mac

# Quick build and test
./Scripts/build.sh
swift run

# Or build manually
swift build
swift run

Development Scripts

The project includes helpful scripts in the Scripts/ directory:

# Build the project
./Scripts/build.sh

# Bump version (updates all version references)
./Scripts/bump_version.sh 1.0.2

# Create distributable DMG
./Scripts/package_app.sh

# Package for App Store distribution
./Scripts/package_app.sh --app_store

# Clear accessibility permissions (if having issues)
./Scripts/clear_accessibility.sh

🍎 App Store Deployment

For developers wanting to distribute BongoCat through the Mac App Store:

# Quick App Store packaging
./run.sh --app-store

# Or use the interactive menu
./run.sh
# Select option 9: "Build release, sign and package for App Store distribution"

📋 Requirements: Apple Developer Program membership, App Store distribution certificate, and App Store Connect setup. See App Store Guide for detailed instructions.

See Scripts/README.md for detailed documentation.

🔧 Troubleshooting

Common Issues

App won't start: Right-click and select "Open" if you get a security warning
Cat not animating: Check accessibility permissions in System Preferences
Position resets: Use "Save Current Position" in the context menu

For more detailed troubleshooting, see TROUBLESHOOTING.md.

🤝 Development & Contributing

👥 Contributing

We welcome contributions from the community! Here's how you can help:

🐛 Bug Reports

Report a bug using our issue tracker
Include macOS version, BongoCat version, and steps to reproduce
Screenshots/screen recordings are super helpful

💡 Feature Requests

Open an issue with the enhancement label
Describe the use case and expected behavior
Check existing issues to avoid duplicates

🔧 Code Contributions

Fork the repository and create a feature branch
Follow Swift conventions and include tests where applicable
Update documentation for new features
Submit a pull request with a clear description

📚 Documentation

Improve README, code comments, or script documentation
Create tutorials or setup guides
Translate documentation to other languages

Project Structure

BongoCat-mac/
├── Sources/BongoCat/     # Swift source code
│   ├── BongoCatApp.swift # Main app delegate & menu logic
│   ├── OverlayWindow.swift # Overlay window management
│   ├── CatView.swift     # SwiftUI cat view & animations
│   ├── InputMonitor.swift # Global input monitoring
│   └── Resources/        # Embedded app resources
├── Assets/               # Project assets
│   ├── Icons/           # App icons (.icns, .ico files)
│   └── Images/          # Cat sprite images
├── Scripts/              # Build & development scripts
│   ├── build.sh         # Quick build script
│   ├── package_app.sh   # Create distributable DMG
│   ├── bump_version.sh  # Version management
│   └── README.md        # Script documentation
├── Build/                # Build outputs (gitignored)
│   ├── package/         # App bundle staging
│   └── *.dmg           # Distributable packages
├── Tests/                # Unit tests
├── Package.swift         # Swift Package Manager config
├── Info.plist           # macOS app bundle metadata
└── README.md            # This file

🛠️ Technical Details

Framework: SwiftUI + AppKit hybrid architecture
Global Events: CGEvent APIs for system-wide input monitoring
Language: Swift 5.9+ with modern concurrency support
Architecture: MVVM pattern with reactive UI updates
Minimum Target: macOS 13.0 (Ventura) for latest SwiftUI features
Build System: Swift Package Manager for dependency management

Tested on

The app was tested on my MacBook Pro 14 inch M2 Max (2023) with macOS 15.5

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Credits & Acknowledgments

🎨 Original Creators

🐱 Bongo Cat Meme: Created by @DitzyFlama
🎨 Cat Artwork: Original cat drawing by @StrayRogue
🎮 Windows Version: Inspiration from Irox Games Studio's Steam version

💻 Technical Inspiration

Python Implementation: mac-typing-bongo-cat for initial concept
Swift Community: For excellent documentation and examples
macOS Developer Community: For accessibility and window management patterns

🤝 Special Thanks

All beta testers and early adopters
Contributors who provided feedback and suggestions
The streaming community for feature requests
Swift/SwiftUI community for technical guidance

💖 Support BongoCat

⭐ Star the Project

If you love BongoCat, please give us a star on GitHub! It helps others discover the project.

🐛 Report Issues

Found a bug? Have a suggestion? Report a bug - we read every one!

📢 Spread the Word

Share BongoCat with fellow developers, streamers, and cat lovers
Tweet about your setup with #BongoCat
Write about it on your blog or social media

💝 Contribute

Whether it's code, documentation, or just ideas - every contribution makes BongoCat better!

Made with ❤️ by Valentin Rudloff

Bringing joy to developers, streamers, and cat lovers everywhere 🐱

🌐 Website • 🐛 Report a Bug • 📖 Documentation • 📦 Releases

FilesExpand file tree

README.md

Latest commit

History