This is an unofficial fork of ovehbe/junkboy. The only change is a GitHub Actions workflow that builds the APK from source and attaches it to a release, so published binaries are reproducible from a specific commit instead of being uploaded by hand. No application code has been modified.
Use at your own risk:
- The fork setup was AI-assisted and is unreviewed by a human security auditor.
- Nothing here is endorsed by or affiliated with the upstream author.
- This app requests
READ_SMS,RECEIVE_SMS,SEND_SMS,WRITE_SMSand optionally notification-listener access. That is broad access to your private messages. Read the source yourself before installing, and prefer building it yourself over trusting any prebuilt APK, including the ones this workflow produces.- The app does not request the
INTERNETpermission, so it cannot send your messages anywhere. The workflow enforces this on every build rather than taking it on trust.- The bundled
sms_model.tfliteis an 18 KB placeholder with a 99-word vocabulary, andapp/src/main/assets/model_info.txtdescribes it as such. Treat the "AI-powered" classification described below as aspirational; in practice the keyword and regex rules do the real work.- Releases from this fork may be signed with an ephemeral CI key. See Building from source.
Upstream is the canonical project. Report app bugs there, not here.
An intelligent, AI-powered SMS filtering application for Android that automatically categorizes and manages your text messages using machine learning and customizable rules.
Inspired by Junkman for iOS, bringing similar AI-powered SMS filtering capabilities to Android with enhanced features and open-source transparency.
- AI-Powered Filtering: Uses TensorFlow Lite machine learning models to automatically categorize SMS messages
- Smart Hierarchy System: ML classification takes precedence with rule-based enhancement for optimal accuracy
- Multi-Method Filtering: Combines ML, keyword filtering, and regex patterns for comprehensive coverage
- Real-time Processing: Instant classification of incoming messages with foreground service reliability
- Material Design 3 UI: Beautiful, intuitive interface built with Jetpack Compose
- Dashboard Overview: Quick stats and system status at a glance
- Message Categories: Automatic sorting into General, Promotion, Notification, Transaction, and Junk
- Filter Testing: Built-in testing screen to verify filter effectiveness before deployment
- Conversation View: Messages grouped by sender for easy browsing in both Hub and Filtered screens
- Unified Inbox: View all SMS messages and chat notifications in one place
- Configurable Display: Choose to show SMS only, chats only, or both
- Conversation Grouping: Messages grouped by sender with tap-to-open in default SMS app
- Flexible Views: Switch between conversation view and individual message view
- Disabled by Default: Enable in Settings → Hub Settings when needed
- Category-Specific Notifications: Choose which message types to receive notifications for
- Smart Notification Channels: Separate Android notification channels for each category with appropriate priority levels
- Blocked Message Alerts: Optional notifications for filtered junk messages
- Notification Actions: Quick actions to allow senders or mark messages as read
- SMS App Notification Control: Buzzkill-like features to dismiss/mute notifications from default SMS app
- Custom Keywords: Add your own spam indicators and important terms
- Regex Patterns: Advanced pattern matching for power users
- Allowed Senders: Whitelist trusted contacts to bypass all filtering
- Under Attack Mode: Enhanced protection during spam waves
- Auto-Delete Junk: Automatically remove junk messages from system SMS database (requires default SMS app)
- Real-time Statistics: Daily and total message filtering metrics
- Category Breakdown: Detailed analysis of message distribution
- Filter Effectiveness: Performance metrics showing how well your filters work
- Export Functionality: CSV export of all filtered messages for analysis
- Local Database: Secure, offline storage using Room database
- Message Archive: Complete history of all filtered messages
- Bulk Processing: Process existing SMS messages with current filter settings
- Data Export/Import: Full data portability and backup capabilities
- Language: Kotlin with Coroutines for async processing
- UI Framework: Jetpack Compose with Material Design 3
- Database: Room persistence library with SQLite backend
- ML Engine: TensorFlow Lite for on-device AI inference
- Architecture: MVVM pattern with Repository pattern for data access
- TensorFlow Lite Model: Custom-trained SMS classification model
- Vocabulary Processing: Tokenization and text preprocessing pipeline
- Fallback Classification: Rule-based backup for model-unavailable scenarios
- Confidence Scoring: Probabilistic classification with confidence metrics
- Broadcast Receivers: Real-time SMS interception and processing
- Foreground Service: Reliable background processing with system notifications
- Default SMS App Support: Full SMS app capabilities for enhanced features
- Permission Management: Proper handling of SMS, notification, and storage permissions
- Notification Listener: Intercept and manage notifications from other apps
This fork ships .github/workflows/build.yml, which compiles the APK on GitHub's runners.
What it does
- Runs on pushes to
master/main, on pull requests, onv*tags, and on manual dispatch. - Installs JDK 17 and Gradle 8.2, checking the Gradle download against a pinned SHA-256.
- Builds
assembleRelease, then prints the APK's signing certificate and full permission list. - Fails the build if the APK ever requests
INTERNET, which upstream does not. This is the property that keeps your messages on the device, so it is enforced rather than assumed. - Publishes the APK plus a
SHA256SUMS.txtto a GitHub Release on tag pushes.
Triggering a release
git tag v1.3.0
git push origin v1.3.0Signing
app/build.gradle hardcodes a keystore path and password, so the workflow places a keystore
where that config expects it. Without configuration it generates a throwaway key on every
run, which means consecutive builds cannot be installed over one another. To get a stable
signature, create a keystore once and store it as a secret:
keytool -genkeypair -v \
-keystore junkboy-release-key.keystore \
-alias junkboy -storepass junkboy123 -keypass junkboy123 \
-keyalg RSA -keysize 4096 -validity 10000 \
-dname "CN=Your Name, O=Personal, C=US"
base64 -w0 junkboy-release-key.keystoreAdd the output as a repository secret named KEYSTORE_BASE64 under
Settings → Secrets and variables → Actions. The alias and passwords must stay as shown,
because app/build.gradle hardcodes them. Keep the keystore file itself backed up and out of
version control; anyone holding it can sign builds that your device will accept as upgrades.
Building locally instead
rm -f local.properties # committed upstream, points at another machine's SDK
./gradlew assembleDebug # output: app/build/outputs/apk/debug/Requires JDK 17 and an Android SDK with platform 34.
- Android 8.0 (API level 26) or higher
- ~50MB storage space for app and ML model
- SMS and notification permissions
-
Download and Install
# Clone the repository git clone https://github.com/ovehbe/junkboy.git cd junkboy # Build the APK ./gradlew assembleDebug # Install on connected device adb install app/build/outputs/apk/debug/app-debug.apk
-
Grant Permissions
- SMS Permissions: Allow reading and receiving SMS messages
- Notification Permission: Enable categorized notifications
- Notification Listener: For Hub and SMS app notification control features
- Storage Permission: For data export functionality
-
Initial Configuration
- Open the app and complete the setup wizard
- Configure your notification preferences
- Add custom keywords or allowed senders if desired
- Test the filtering system with the built-in testing tool
For enhanced features like auto-delete junk messages:
- Go to Android Settings → Apps → Default Apps → SMS app
- Select "Junkboy SMS Filter"
- Enable auto-delete in Junkboy settings
The app has a dynamic navigation bar that shows different items based on your configuration:
| Navigation Item | When Shown | Description |
|---|---|---|
| Hub | When enabled in settings | Unified inbox for all messages |
| SMS | When Junkboy is default SMS app | Full SMS client with send/receive |
| Filtered | Always | Browse filtered messages by category |
| Menu | Always | Access settings, stats, and tools |
Configure the Hub in Settings → Hub Settings:
- Enable Hub: Toggle to show/hide Hub in navigation (disabled by default)
- Display Mode:
- All (SMS + Chats) - Everything in one view
- SMS Only - Just filtered SMS messages
- Chats Only - Just chat app notifications
- Default View:
- Conversations - Messages grouped by sender
- Individual Messages - Flat list of all messages
Similar to Buzzkill, Junkboy can manage notifications from your default SMS app:
- Go to Settings → SMS App Notification Control
- Enable the master toggle
- Configure options:
- Dismiss SMS Notifications: Auto-dismiss notifications from default SMS app
- Blocked Only: Only dismiss notifications for messages Junkboy blocked
This prevents duplicate notifications when both apps notify for the same message.
- Enabled by default for optimal accuracy
- Automatically categorizes messages into 5 categories
- Self-improving through confidence-based decisions
Settings → Custom Keywords → Add
Examples:
- "URGENT OFFER" (promotional spam)
- "Bank Alert" (transaction indicator)
- "Verify your" (notification pattern)
Settings → Custom Regex Patterns → Add
Examples:
- \b\d{4}\s?\d{4}\s?\d{4}\s?\d{4}\b (credit card numbers)
- (?i)click\s+here (case-insensitive "click here")
- \$\d+\.?\d*\s?(off|discount) (discount offers)
- Global Settings: Enable/disable all filtered or blocked notifications
- Category-Specific: Choose which categories to receive notifications for
- ✅ General Messages (personal/important)
- ✅ Notifications (codes, alerts)
- ✅ Transactions (banking, payments)
- ❌ Promotions (marketing, sales)
- Add trusted contacts to bypass all filtering
- Supports phone numbers and sender names
- Useful for important business contacts or family members
Junkboy uses an intelligent multi-layered approach:
- ML First: TensorFlow Lite model provides primary classification
- Rule Enhancement: Keyword/regex filters enhance or override ML when confidence is high
- Confidence Weighting: Higher confidence results take precedence
- FilterType Preservation: UI always shows "ML Classification" when ML is enabled
Both Hub and Filtered screens support conversation view:
- Messages grouped by sender for easy navigation
- Tap any conversation to open in your default SMS app
- Quick actions for allowing senders or opening apps
- Toggle between conversation and message views
- Separate Channels: Each category has its own Android notification channel
- Priority Mapping:
- Transactions: HIGH (banking alerts)
- General/Notifications: DEFAULT (personal messages)
- Promotions: LOW (marketing)
- Blocked: MIN (spam notifications)
- Smart Actions: Context-appropriate quick actions per category
Enhanced protection during spam waves:
- Stricter filtering thresholds
- Expanded junk keyword detection
- Automatic temporary rule activation
- Ideal for dealing with spam campaigns
| Category | Description | Examples | Default Notifications |
|---|---|---|---|
| General | Personal and uncategorized messages | Friends, family, personal | ✅ Enabled |
| Promotion | Marketing and sales messages | Offers, discounts, ads | ❌ Disabled |
| Notification | System alerts and codes | OTP, delivery updates, alerts | ✅ Enabled |
| Transaction | Banking and payment messages | Bank alerts, payment confirmations | ✅ Enabled |
| Junk | Spam and unwanted messages | Scams, unwanted marketing | ❌ Disabled |
| Allowed | Messages from whitelisted senders | Trusted contacts, important services | ✅ Enabled |
app/src/main/java/com/ovehbe/junkboy/
├── classifier/ # AI SMS classification engine
│ └── SmsClassifier.kt
├── database/ # Room database entities and DAOs
│ ├── AppDatabase.kt
│ ├── FilteredMessage.kt
│ ├── FilteredMessageDao.kt
│ ├── ChatMessage.kt
│ └── ...
├── filters/ # Custom filtering logic
│ └── CustomFilter.kt
├── service/ # Background SMS processing
│ ├── SmsFilterService.kt
│ ├── SmsSendService.kt
│ └── NotificationListenerService.kt
├── smsreceiver/ # SMS broadcast receivers
│ └── SmsReceiver.kt
├── ui/ # Jetpack Compose UI components
│ ├── compose/
│ │ ├── JunkboyApp.kt
│ │ └── screens/
│ │ ├── ChatsScreen.kt # Hub screen
│ │ ├── MessagesScreen.kt # Filtered messages
│ │ ├── SmsScreen.kt # SMS client
│ │ ├── SettingsScreen.kt
│ │ └── ...
│ └── theme/
└── utils/ # Helper utilities and managers
├── NotificationHelper.kt
├── PreferencesManager.kt
├── SmsAppManager.kt
├── AppLauncher.kt
└── ...
# Prerequisites
# - Android Studio Arctic Fox or later
# - Android SDK 26+
# - Kotlin 1.8+
# Clone and build
git clone https://github.com/ovehbe/junkboy.git
cd junkboy
./gradlew assembleDebug
# Run tests
./gradlew test
# Generate release build
./gradlew assembleRelease- Model File:
app/src/main/assets/sms_model.tflite - Labels:
app/src/main/assets/labels.txt - Vocabulary:
app/src/main/assets/vocabulary.txt - Model Info:
app/src/main/assets/model_info.txt
- Local Processing: All SMS analysis happens on-device
- No Cloud Sync: Messages never leave your device
- Encrypted Storage: Local database uses Android's built-in encryption
- Minimal Permissions: Only requests necessary permissions for functionality
- Transparent Code: Full source code available for security auditing
- No Tracking: No analytics, telemetry, or user tracking
- Community Driven: Open to contributions and security reviews
We welcome contributions! Here's how you can help:
- 🐛 Bug Reports: Report issues via GitHub Issues
- 💡 Feature Requests: Suggest new functionality
- 🔧 Code Contributions: Submit pull requests
- 📖 Documentation: Improve README, code comments
- 🌐 Translations: Add support for new languages
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow Kotlin coding conventions
- Use meaningful variable and function names
- Add comments for complex logic
- Include unit tests for new features
- 🎯 Smart OTP Detection: Complete rewrite of OTP extraction with pattern-based detection
- 16+ high-confidence patterns for Turkish banks (İş Bankası, Vakıfbank, T.Finans, MARS, etc.)
- Support for English OTPs (Apple, international services)
- Delivery code detection (PTT, Yurtiçi, HepsiJET, DHL, KolayGelsin, TY Express)
- Alphanumeric code support (NETGSM)
- Smart exclusion of false positives (money amounts, dates, tracking numbers, phone numbers)
- Accuracy improved from ~10% to 95%+
- 🔧 Multipart SMS Fix: Fixed duplicate notifications and split messages for long SMS
- 🔔 Notification Fix: Removed non-functional "Mark Read" button from notifications
- 📱 Full SMS App: Complete SMS client with conversation view, message composer, and send functionality
- ✅ Allowed Senders Category: Messages from whitelisted senders now show as "Allowed" category
- 🎛️ SMS Display Categories: Choose which message categories to display in the SMS screen
- ⌨️ Keyboard Offset: Accessibility setting to add bottom padding when keyboard is visible (for devices with physical keyboards)
- 🎨 New App Icon: Fresh AI-themed icon with chat bubbles and brain design
- 🧪 Test Auto-Delete: Button to test auto-delete junk functionality in settings
- 🔧 Improved Test Filter: Now respects allowed senders when testing messages
- 📊 Clear All Data: Now properly resets statistics along with message data
- 📥 Hub Feature: Optional unified inbox for SMS and chat notifications
- 💬 Conversation View: Messages grouped by sender in Hub and Filtered screens
- 🔇 SMS App Control: Buzzkill-like notification dismiss/mute for default SMS app
- 🎯 Tap-to-Open: Click messages to open conversations in default SMS app
- ⚙️ Hub Settings: Configurable display mode and default view
- 🔄 Dynamic Navigation: Navigation items adapt to enabled features
- ✨ Initial Release: Complete SMS filtering application
- 🤖 AI Classification: TensorFlow Lite integration
- 🎨 Material Design 3: Modern Jetpack Compose UI
- 🔔 Smart Notifications: Category-specific notification controls
- 📊 Analytics Dashboard: Comprehensive filtering statistics
- 🛠️ Custom Filters: Keywords, regex, and allowed senders
- 🗃️ Data Management: Export, import, and bulk processing
- 🚀 Performance: Optimized background processing
This project is licensed under the MIT License - see the LICENSE file for details.
Special thanks to:
- Junkman: A.I. SMS Spam Blocker by Kerem Erkan - This project was heavily inspired by Junkman's excellent approach to AI-powered SMS filtering on iOS. Kerem's pioneering work in on-device ML classification and privacy-first design served as the foundation for bringing similar functionality to Android.
- Buzzkill - Inspiration for the notification control features
- Cursor AI - This project was built with the assistance of Cursor AI, which provided invaluable support in architecting the codebase, implementing complex features, and maintaining best practices throughout development.
- TensorFlow Team for the excellent Lite framework
- Android Team for Jetpack Compose and Material Design 3
- Kotlin Team for the amazing programming language
- Open Source Community for inspiration and best practices
- GitHub Issues: Report bugs or request features
- Discussions: Community discussions and questions
⭐ If you find Junkboy useful, please consider starring the repository to help others discover it!