Flowguard
Intelligent Do Not Disturb for coding.
Flowguard watches your local editing activity, intelligently detects deep focus, and quietly batches interruptions it can control — without ever becoming a distraction itself.
Made with ❤️ by Anand Shah for the developer community.
What it does
Flowguard runs a local, deterministic focus-detection engine. When it detects sustained focused coding, it enters Flow Mode:
- A subtle status bar indicator appears
- Interruption-adjacent events (diagnostics churn, task changes) are aggregated into an end-of-session summary
- Everything returns to normal when you go idle
No ML, no network, no reading your code. Purely metadata-driven and fully transparent.
Features
- Automatic Focus Detection — Real-time 0–100 Focus Score from editing patterns, file switches, debug sessions, and tasks
- Explicit State Machine — Predictable states:
IDLE → ACTIVE → FOCUS_BUILDING → DEEP_FOCUS → COOLDOWN
- Smart Cooldown — Optional scaling of grace period based on session length (configurable)
- Manual Flow Mode — Instant toggle, timed sessions (e.g. "Flow for 30 Minutes"), and hard overrides
- Beautiful Dashboard — Themed webview with live metrics, session timer, history, and timeline
- Status Bar Controls — Clickable indicator showing state + score with quick menu
- Crash-Safe Recovery — Automatically cleans up interrupted sessions on next launch
- Managed Extensions — Advisory policies for other extensions (best-effort matching via public VS Code API)
- Privacy First — 100% local, no telemetry by default, never reads source code or terminal content
📸 Screenshots
Flowguard Dashboard
Live focus score (with animated progress bar), session timer, peak score, protected activity counters, visual timeline, and full session history table. Automatically theme-matched to VS Code.
Subtle, clickable ⚡ FLOW indicator in the status bar (shows live score). Clicking opens a rich quick-pick menu with all controls.
Real screenshots captured from the running extension (using the transparent icon and themed UI components from the resources/ folder).
📦 Installation
Recommended: Install directly from the VS Code Marketplace.
From source (development):
- Clone this repository
- Run
npm install
- Press F5 in VS Code (or Run Extension from the debug panel)
To build a .vsix package: npm run package
🎮 Usage
Start coding — Flowguard works automatically in the background.
- Click the ⚡ Flow status bar item for quick controls
- Open the Command Palette (
Ctrl+Shift+P) and type "Flowguard" for full command list:
Flowguard: Show DashboardFlowguard: Toggle Flow ModeFlowguard: Enter Flow Mode / Exit Flow ModeFlowguard: Flow for 30 MinutesFlowguard: Configure Protected Extensions- And more...
Configuration
| Setting |
Default |
Description |
flowguard.enabled |
true |
Enable/disable the extension |
flowguard.autoFocus |
true |
Automatic focus detection |
flowguard.focusThreshold |
70 |
Score required to enter Deep Focus |
flowguard.focusBuildDuration |
90 |
Seconds of sustained focus needed |
flowguard.idleTimeout |
60 |
Seconds of inactivity before cooldown |
flowguard.smartCooldown |
true |
Scale cooldown based on session length |
flowguard.batchNotifications |
true |
Aggregate events during Flow Mode |
flowguard.showStatusBar |
true |
Show status bar indicator |
flowguard.managedExtensions |
[] |
Advisory policies for other extensions |
Full configuration available in VS Code Settings (search for "Flowguard").
🔐 Privacy & Trust
- Local-only: No network requests in core functionality
- Privacy-first: Never reads, stores, or transmits your source code, keystrokes, or terminal output
- Transparent: Fully open source with detailed API limitations analysis
- Telemetry is opt-in, anonymous, and local-only (no data leaves your machine in v1)
🏗️ Architecture & Technical Details
Flowguard is built strictly on the public VS Code Extension API (see API_ANALYSIS.md for the full feasibility matrix and limitations).
Key components:
FocusScorer + FocusStateMachine (deterministic, metadata-only)ProtectionManager (event batching + advisory managed extensions)StateRestorer (crash-safe recovery)- Theme-aware
DashboardProvider (webview)
Full details, edge cases, "Why it exists", smart cooldown math, and original long-form content are preserved in the GitHub version of this README and API_ANALYSIS.md.
🧪 Development
npm install
npm run watch
Press F5 to launch the Extension Development Host. Tests run with npm test.
See CONTRIBUTING.md for full setup, guidelines, and architecture details. Check CHANGELOG.md for version history.
📋 Commands
Full list available in Command Palette or via the status bar menu.
Links:
Built for developers who value deep, uninterrupted flow states. All local. Privacy-first. Open source.
