KAIROS

Warning This project has been 100% vibe coded. Keep this in mind: best programming practices may not have been followed, and there may be dead code or unused code, as the codebase has never been thoroughly inspected.

An iOS digital wellness app that uses Apple's Screen Time API to create focused work and study environments through intelligent blocking of distracting applications.

Overview

KAIROS helps users be more present by combining physical triggers (QR codes and NFC tags) with digital app blocking. Create custom blocking profiles called "Guards" and control them through scannable "Triggers" placed in your environment.

Features

Guards (Blocking Modes)

• Custom configurations defining which apps or categories to block
• Multiple guards can be active simultaneously
• Temporary unlock system (Autolock) with configurable duration

Triggers (QR/NFC Activators)

• Physical QR codes or NFC tags that control guards
• Target Mode: Deactivates specific guards when scanned
• Swap Mode: Activates specific guards when scanned
• Perfect for offices, libraries, study spaces, etc.

Autolock

• Time-limited app access (1-60 minutes)
• Visual countdown via Live Activities
• Automatic background reactivation when time expires

Emergency Unlock

• Safety mechanism for critical situations
• Hold for 90 seconds to deactivate all guards

Requirements

• iOS 26.0+
• Xcode 26.0+
• Apple Developer account (for Screen Time entitlements)

Getting Started

1. Fork and Clone

# Fork this repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/kairos.git
cd kairos

2. Configure Bundle Identifiers

Before building, you must update the bundle identifiers to match your Apple Developer account:

1. Open Soul.xcodeproj in Xcode
2. Select the project in the navigator
3. For each target (Soul, SoulActivityMonitor, SoulWidget, SoulShieldConfiguration, SoulShieldAction):
   • Go to Signing & Capabilities
   • Change Team to your Apple Developer Team
   • Update Bundle Identifier to your own (e.g., com.yourname.kairos)

3. Update App Group

The app uses an App Group for sharing data between the main app and extensions. You need to update this:

1. For each target, go to Signing & Capabilities → App Groups

2. Remove the existing app group

3. Add your own app group (e.g., group.com.yourname.kairos)

4. Search and replace in the codebase:

   Find: group.me.inakitajes.soul
   Replace: group.com.yourname.kairos
   

   Files that reference the app group:

   • Soul/Managers/ShieldManager.swift
   • Soul/Managers/TriggerManager.swift
   • SoulWidget/SoulWidget.swift
   • SoulActivityMonitor/SoulActivityMonitor.swift
   • Various other Swift files

4. Update Background Task Identifier

Search and replace the background task identifier:

Find: me.inakitajes.soul.applyshields
Replace: com.yourname.kairos.applyshields

Update in:

• Soul/Info.plist
• Soul/Managers/ShieldManager.swift

5. Build and Run

1. Select your target device or simulator
2. Build and run (⌘R)
3. Grant Screen Time permissions when prompted

Project Structure

Soul/
├── Views/                    # SwiftUI views
│   ├── ContentView.swift     # Main screen
│   ├── SettingsView.swift    # Settings
│   ├── BlockingModesView.swift # Guard management
│   ├── ModeEditorView.swift  # Guard editor
│   ├── TriggersView.swift    # Trigger management
│   └── TriggerEditorView.swift # Trigger editor
├── Managers/
│   ├── ShieldManager.swift   # Core blocking logic
│   └── TriggerManager.swift  # QR/NFC trigger handling
├── Models/
│   ├── BlockingMode.swift    # Guard data model
│   └── Trigger.swift         # Trigger data model
└── Extensions/

SoulActivityMonitor/          # DeviceActivity extension
SoulWidget/                   # Widget extension
SoulShieldConfiguration/      # Shield UI extension
SoulShieldAction/             # Shield action extension

Architecture

Core Components

• ShieldManager: Central singleton managing all blocking functionality, autolock timers, Live Activities, and background processing
• TriggerManager: Manages QR codes and NFC tags, handles trigger persistence and lookup

Screen Time Integration

The app uses Apple's Screen Time frameworks:

• FamilyControls - App selection and authorization
• ManagedSettings - Applying app restrictions
• DeviceActivity - Background monitoring

Data Persistence

Uses App Groups for sharing data between the main app and extensions via UserDefaults.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Notes

• No automated test suite currently exists - testing is done manually
• Uses @StateObject and @EnvironmentObject for state management

Troubleshooting

"FamilyControls authorization failed"

• Ensure Screen Time is enabled in iOS Settings
• The app requires the device owner to grant Screen Time access

"App Group not found"

• Verify you've created the App Group in your Apple Developer account
• Ensure all targets have the same App Group configured

Build errors with provisioning

• Make sure your Apple Developer account has the necessary entitlements
• FamilyControls requires specific entitlements from Apple

License

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

Acknowledgments

• Built with Apple's Screen Time API
• Inspired by the need for intentional technology use

---

"The right time to do the right things" - KAIROS Philosophy