Stay in deep focus while the world stays async.
Modern builders juggle Codex/Claude runs, CI builds, and a constant stream of teammate pings while they still need to read dense specs or textbooks. Each “just checking” moment shatters flow, and real‑time notifications splinter attention even further. VibeFlow treats the human brain like the single-threaded processor it is and orchestrates external I/O so you can stay immersed in the cognitively expensive work.
- Flow requires a synchronous loop: The brain’s working memory, procedural memory, and dopamine feedback form a tight control loop. When the loop stays uninterrupted, we enter the “flow state” Mihaly Csikszentmihalyi describes—a high-efficiency mode with minimal cognitive latency.
- Human async is lossy: Unlike computer async, the brain cannot snapshot and restore working memory accurately. Every switch forces the prefrontal cortex to rebuild context. Altmann & Trafton (2002) measured resumption lags of ~20–30 seconds after an interruption, while working memory decay begins at ~10–15 seconds. Multiply that by dozens of micro-checks and the day dissolves.
- Notification overload fragments reward loops: Mark, Gudith, & Klocke (2008) showed that frequent interruptions raise stress and reduce perceived productivity. Dopamine spikes from constant context switches mimic busyness but erode the satisfaction of deep progress.
- LLM wait debt: Teams increasingly run several Codex/Claude sessions in parallel. Each run may take 5–60 seconds; waiting idly wastes time, but switching away risks context loss. Our brainstorming analysis identified ~5–10 seconds as the cognitive tolerance window—beyond that, developers launch a new mental thread, fragmenting attention.
- Build/CI lag: Continuous integration jobs often run 3–10 minutes. Developers either poll logs (fragmentation) or tab to unrelated tasks (context drift). VibeFlow’s adaptive polling aims to align check-ins with these completion likelihoods instead of constant meta-checking.
- Message pings: Knowledge-workers receive 46 notifications/day on average (Slack’s 2023 usage pulse), with peaks during collaborative coding sessions. Real-time alerts often break focus for low-severity updates. Batching into digests retains awareness without constant preemption.
- Empirical productivity loss: A UC Irvine study (Mark et al., 2015) found it takes ~23 minutes to regain deep focus after a significant interruption. Developers report feeling “busy but unproductive”—an attention residue effect created by juggling asynchronous tasks manually.
- Treat the human as a single-threaded CPU with scarce working memory.
- Shift async orchestration from the developer’s brain into software.
- Provide explicit “yield points” that align with natural cognitive recovery intervals.
- Preserve dopamine coherence by delivering meaningful progress cues rather than noisy alerts.
- Preserve uninterrupted focus blocks by batching non-critical updates.
- Pull status from async tasks at adaptive intervals that respect deep work.
- Escalate only when a task’s urgency policy truly demands it.
- Provide gentle ambient awareness and intentional “safe peek” checkpoints.
- Learn from user feedback to refine polling and notification policies locally.
- Register monitored tasks: Add Codex runs, build pipelines, or message channels with expected duration, priority, and time-slice policy.
- Run focus sessions: Start a session that stretches polling windows, manages overrides, and tracks pending digests.
- Digest updates: View batched non-critical results in a condensed safe peek without breaking flow.
- Handle escalations: Immediately surface failures or critical messages defined by task-specific urgency rules.
- Manually intervene: Force checks, snooze alerts, or pin a task to “always notify” when being on call.
- Human async is expensive: every interruption burns 20–30 seconds of context rebuild time; keep external polling aligned with natural cognitive recovery windows and the ~5–10 second wait tolerance.
- Focus windows over reactive checking: treat deep work as 25–40 minute blocks with explicit yield points for batched updates.
- Ambient > intrusive: use an always-visible indicator and safe peek overlay instead of real-time pop-ups.
- User agency: provide clear consent, visibility into monitored sources, and quick overrides.
| Layer | Highlights |
|---|---|
| Domain | Task, TimeSlicePolicy, FocusSession, FocusProfile, FocusDigest. |
| Services | In-memory repository, adaptive polling heuristic, digest manager, escalation handler, profile presets, override controller, feedback tracker, focus coordinator. |
| View Models | AppViewModel composes task list, focus session, and safe peek view models. |
| Views | Gradient-backed SwiftUI shell with glassmorphism cards for tasks, session controls, and safe peek indicator. |
Directory structure:
VibeFlow/
├─ Domain/ // Core models and policies
├─ Services/ // Coordinators, repositories, heuristics
├─ ViewModels/ // Bridge between services and SwiftUI
├─ Views/ // Task dashboard, session controls, safe peek UI
├─ Assets.xcassets
├─ VibeFlowApp.swift
└─ ContentView.swift
- Open
VibeFlow.xcodeprojin Xcode 16.4 or later (macOS deployment target 15.5). - Build & run the
VibeFlowscheme on macOS. - Use the Tasks tab to register sample monitored tasks and explore profile presets.
- Switch to the Session tab to start focus blocks, manage overrides, and try the safe peek digest overlay.
Heads-up: When building via CLI inside a sandbox, Xcode’s
ldmay complain about unsupported linker flags. Running inside the full IDE avoids that limitation.
- Integrate real data connectors for Codex/Claude, CI pipelines, and messaging APIs.
- Implement adaptive polling using completion probability and historical duration models.
- Add learning loops from the feedback service to auto-tune policies.
- Provide local logging dashboards and exportable focus reports.
- Expand UI with timeline visualizations and notification center integration.
This repository currently tracks a UI/architecture skeleton. Contributions should:
- Preserve the separation between domain models, services, view models, and views.
- Include lightweight documentation of new heuristics or policies.
- Add preview fixtures or tests when introducing new logic.
MIT © 2025 VibeFlow contributors.