FlowSnap 🪟⚡

Your Mac. Your Layout. Your Flow.
High-performance native macOS window manager and intent-based workspace orchestrator built with Swift 6.

🇻🇳 Tiếng Việt • 🌐 Live Website & 3D Simulator • ⚡ Quick Install • Key Features • Installation • Shortcuts • Architecture • Docs

Tip

Experience FlowSnap in your browser before downloading: Try the 3D Desktop Simulator, interactive snap layouts, and shortcut matrix live at ahauy.github.io/FlowSnap.

⚡ Quick Install (Recommended)

Run this single command in your macOS Terminal to download, configure permissions, and launch FlowSnap seamlessly:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/ahauy/FlowSnap/main/scripts/install.sh)"

Note

Privacy & Security Assurance: FlowSnap is 100% free and open-source, built strictly with public Apple APIs and zero telemetry. Running the one-line terminal installer prepares permissions cleanly and launches FlowSnap without triggering macOS Gatekeeper verification warnings. (Manual .dmg download is also available below under Installation & Getting Started).

🌟 Why FlowSnap?

The default macOS window management experience forces you into constant manual resizing, clunky full-screen Split Views, or jarring transitions that break your flow.

Even worse is unwanted Space hopping: opening an app suddenly pulls you across monitors or virtual desktops, destroying your mental context.

FlowSnap solves this with a singular principle:

You decide where windows belong. FlowSnap takes care of the rest.

FlowSnap pairs an intuitive Top-Edge Snap Layout Flyout with an Intent-Based Workspace Engine engineered specifically for macOS. It delivers instant, fluid window tiling without sacrificing the flexibility of floating windows.

✨ Key Features

1. 🪟 Interactive Top-Edge Snap Layout Picker

Drag any window towards the top center edge of your screen to summon an instant layout picker. Hover over partition zones (50/50, 70/30, 3-column, 4-quarters) and release to snap windows into place with zero effort.

2. ⚡ Interactive Drag-to-Snap & Real-Time HUD Overlay

Drag windows to screen borders or display corners to trigger real-time translucent HUD snap overlays with smooth spring physics. Drop to snap; drag away to cancel.

3. ↔️ Adaptive Collinear Resize & Custom Window Gaps

Resizing one window shouldn't require manually readjusting its neighbor. FlowSnap automatically detects collinear shared dividers between tiled windows—dragging the boundary line resizes both windows simultaneously in real time locked at 60 FPS.

Configure customizable inner and outer window gaps for aesthetic, modern tiling desk setups.

4. 🪐 Current Space Anchoring (Zero Unwanted Space Jumping)

Never get pulled away from your active Desktop again. FlowSnap continuously observes application launches and guarantees that new windows appear strictly within your active Space and Display, preserving your flow state without using any private Apple APIs.

5. 🗂️ Intent-Based Workspaces & Workflow Presets

Save your multi-window layout as a named Workspace (e.g., Coding, Research, Writing). Workspaces store geometric intent rather than rigid pixel values, allowing seamless restoration across different display resolutions and external monitors.

Curated Builtin Presets: Instant templates for common two-window and three-window setups.
Linked Window Groups: Group related windows so minimizing or repositioning one keeps the set together.

6. 📌 Per-App Window Policies & Smart Floating Stack

Define dedicated rules per application bundle ID:

Floating Utilities: Keep lightweight tools (Calculator, Dictionary, Notes) floating above your tiled workspace.
Remember Position: Automatically clamp and remember last-closed positions.
Smart Focus Return: Closing a floating window immediately restores keyboard focus to the underlying tiled application.

7. ⌨️ Menu Bar Quick Controls & Global Hotkeys

Trigger any snap zone instantly with system-wide keyboard shortcuts powered by low-latency Carbon Event Hotkeys, or click and drag across the Interactive Visual Snap Grid directly from the menu bar companion.

💻 System Requirements & Permissions

Requirement	Specification
Operating System	macOS 14.0 (Sonoma) or macOS 15.0+ (Sequoia)
Hardware	Apple Silicon (M1 / M2 / M3 / M4) or Intel (x86_64)
System Permission	macOS Accessibility (`AXUIElement` window manipulation)

Important

Granting Accessibility Permission: FlowSnap requires Accessibility access to position windows. On first launch, macOS will prompt you to open System Settings → Privacy & Security → Accessibility and toggle FlowSnap ON. FlowSnap uses 100% public Apple APIs and runs in a hardened runtime with zero private framework calls.

🚀 Installation & Getting Started

For Users: Download & Install

Option 1: One-Line Terminal Install (Recommended ⚡)

Open your Terminal and run this single command to automatically download, install to /Applications, remove Gatekeeper quarantine, and launch FlowSnap:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/ahauy/FlowSnap/main/scripts/install.sh)"

Option 2: Direct Download for macOS (.dmg) 📥

Click the link below to immediately trigger the native browser download dialog:

Download for macOS (FlowSnap.dmg)
~ Compatible with macOS 14.0 Sonoma and later (Apple Silicon & Intel) ~

Your browser will prompt to save FlowSnap.dmg (or save it directly into your Downloads folder).
Double-click the downloaded .dmg and drag FlowSnap into your Applications folder.
First-time launch (macOS Gatekeeper): Because FlowSnap is an open-source project without a paid Apple Developer certificate ($99/year), macOS may show an "Apple could not verify FlowSnap" warning on first launch. You can allow it via either:
- Terminal (Fastest): Run xattr -cr /Applications/FlowSnap.app
- System Settings: Go to System Settings → Privacy & Security, scroll down to Security, and click Open Anyway.

Option 3: Package DMG from Source Locally

If you prefer to build the release .dmg yourself:

git clone https://github.com/ahauy/FlowSnap.git
cd FlowSnap
./scripts/build-dmg.sh
open build/FlowSnap-*.dmg

For Developers: Building from Source

Prerequisites

macOS 14.0+
Xcode 16.0+
XcodeGen (brew install xcodegen)

Build & Run Commands

Generate the Xcode project and compile:

xcodegen generate
xcodebuild -project FlowSnap.xcodeproj -scheme FlowSnap -destination 'platform=macOS' build

Launch the built app:

open $(find ~/Library/Developer/Xcode/DerivedData/FlowSnap-*/Build/Products/Debug -name "FlowSnap.app" | head -n 1)

Run the automated test suite (358 Tests across 55 Suites):

xcodebuild -project FlowSnap.xcodeproj -scheme FlowSnapTests test

Run FlowSnapLab (Interactive QA Testbed):

xcodebuild -project FlowSnap.xcodeproj -scheme FlowSnapLab -destination 'platform=macOS' build
open $(find ~/Library/Developer/Xcode/DerivedData/FlowSnap-*/Build/Products/Debug -name "FlowSnapLab.app" | head -n 1)

⌨️ Keyboard Shortcuts

Action	Default Shortcut	Description
Snap Left Half	`⌥ ⌃ ←`	Snap window to left half of screen
Snap Right Half	`⌥ ⌃ →`	Snap window to right half of screen
Snap Top Half	`⌥ ⌃ ↑`	Snap window to top half of screen
Snap Bottom Half	`⌥ ⌃ ↓`	Snap window to bottom half of screen
Maximize Window	`⌥ ⌃ ↩`	Maximize within visible screen bounds
Restore Previous Size	`⌥ ⌃ ⌫`	Restore window to frame before snapping
Center Window	`⌥ ⌃ C`	Center window on current display
Next Display	`⌥ ⌃ ⇥`	Move focused window to next monitor
Previous Display	`⌥ ⌃ ⇧ ⇥`	Move focused window to previous monitor
Save Workspace	`⌥ ⌃ S`	Open quick save workspace dialog
Restore Workspace	`⌥ ⌃ R`	Cycle through or restore last workspace

Note

All hotkeys can be fully customized or disabled in FlowSnap Preferences → Shortcuts.

🏗️ Architecture & Engineering

FlowSnap is built on Domain-Driven Design (DDD) and John Ousterhout’s Deep Modules philosophy, isolating pure geometric business logic from macOS system adapters:

FlowSnap/
├── Domain/           # Pure business rules, math, coordinate transforms & interfaces (Zero OS deps)
│   ├── Model/        # ManagedWindow, LayoutZone, Workspace, AppPolicyRule
│   ├── Services/     # SnapEngine, LayoutEngine, CollinearEdgeDetector
│   └── Ports/        # AccessibilityServing, DisplayManaging, GlobalHotkeyManaging
├── Core/             # High-leverage coordination services
│   ├── Workspace/    # WorkspaceManager, PresetResolver, WindowGroupManager
│   ├── Policy/       # WindowPolicyManager, SmartFocusStack, FrameClampingHelper
│   └── Dispatcher/   # CommandDispatcher, LiveResizeThrottler
├── Infrastructure/   # macOS System Adapters (Ports implementation)
│   ├── Accessibility/# AXUIElement adapter, AXObserver lifecycle
│   ├── Hotkey/       # Carbon RegisterEventHotKey daemon
│   ├── Display/      # AppKit NSScreen observer & monitor topology
│   └── Persistence/  # Atomic JSON storage & UserDefaults PreferencesStore
└── UI/               # Declarative SwiftUI & non-activating NSPanels
    ├── SnapPreview/  # Translucent ghost overlay panel
    ├── LayoutPicker/ # Interactive top-edge visual flyout
    ├── MenuBar/      # NSStatusItem & popover visual snap grid
    └── Settings/     # Full-featured tabbed settings & shortcut recorder

Engineering Guarantees

100% Swift 6.0 Concurrency: Full actor isolation, @MainActor UI dispatch, and thread-safe domain entities. Zero data races.
100% Zero Private APIs: Audited via scripts/audit-no-private-apis.sh. No undocumented CGS* or SLS* calls. Notarization and App Store ready.
Sub-Millisecond Execution: Snap calculations compute in < 1ms. Boundary resizing maintains continuous 60 FPS. Idle CPU consumption is ~0.0%.
Rigorous Verification: Backed by 358 automated tests across 55 test suites with mock doubles.

🔧 Troubleshooting & Gotchas

macOS keeps asking for Accessibility permission after re-compiling

During local development, rebuilding the binary changes its code signature. macOS TCC may invalidate permissions for that debug path. Reset the permission cache using:

tccutil reset Accessibility com.flowsnap.app

Then relaunch the app and re-enable it in System Settings → Privacy & Security → Accessibility.

"FlowSnap can't be opened because Apple cannot check it for malicious software" (Gatekeeper)

If running an unsigned local build on a new machine, remove the quarantine attribute:

xattr -cr /Applications/FlowSnap.app

📚 Documentation Index

📖 Product Backlog & Roadmap — 12-Epic functional specifications and architecture roadmap.
🧩 Feature Documentation Index — Architectural design and specs for each implemented feature.
🖼️ User Guides with Screenshots — Step-by-step visual guides for all user-facing features.
📐 Architecture Decision Records (ADR) — Immutable architectural decisions (ADR-0001 through ADR-0010).
🧪 Run & Test Guide — Terminal commands for testing, packaging, and QA.
💬 Ubiquitous Language (Context) — Canonical project terminology and domain glossary.

🤝 Contributing

Contributions are welcome! Please check CONTRIBUTING.md before submitting pull requests.

Fork the repository.
Create a feature branch: git checkout -b feature/amazing-feature.
Verify test suites pass: xcodebuild -project FlowSnap.xcodeproj -scheme FlowSnapTests test.
Submit a Pull Request.

🛡️ Security

If you discover a security vulnerability, please do not open a public issue. Report it confidentially via GitHub Security Advisories or contact the maintainer directly.

📄 License

FlowSnap is released under the MIT License.

Name		Name	Last commit message	Last commit date
.github		.github
.specify		.specify
FlowSnap.xcodeproj		FlowSnap.xcodeproj
FlowSnap		FlowSnap
FlowSnapLab		FlowSnapLab
FlowSnapTests		FlowSnapTests
adr		adr
docs		docs
scripts		scripts
web		web
.gitignore		.gitignore
.swiftlint.yml		.swiftlint.yml
.worktreeinclude		.worktreeinclude
CHANGELOG.md		CHANGELOG.md
CONTEXT.md		CONTEXT.md
LICENSE		LICENSE
README.md		README.md
README.vi.md		README.vi.md
project.yml		project.yml
version.json		version.json

Navigation Menu

Repository files navigation

FlowSnap 🪟⚡

⚡ Quick Install (Recommended)

🌟 Why FlowSnap?

✨ Key Features

1. 🪟 Interactive Top-Edge Snap Layout Picker

2. ⚡ Interactive Drag-to-Snap & Real-Time HUD Overlay

3. ↔️ Adaptive Collinear Resize & Custom Window Gaps

4. 🪐 Current Space Anchoring (Zero Unwanted Space Jumping)

5. 🗂️ Intent-Based Workspaces & Workflow Presets

6. 📌 Per-App Window Policies & Smart Floating Stack

7. ⌨️ Menu Bar Quick Controls & Global Hotkeys

💻 System Requirements & Permissions

🚀 Installation & Getting Started

For Users: Download & Install

Option 1: One-Line Terminal Install (Recommended ⚡)

Option 2: Direct Download for macOS (.dmg) 📥

Option 3: Package DMG from Source Locally

For Developers: Building from Source

Prerequisites

Build & Run Commands

⌨️ Keyboard Shortcuts

🏗️ Architecture & Engineering

Engineering Guarantees

🔧 Troubleshooting & Gotchas

📚 Documentation Index

🤝 Contributing

🛡️ Security

📄 License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

FlowSnap 🪟⚡

⚡ Quick Install (Recommended)

🌟 Why FlowSnap?

✨ Key Features

1. 🪟 Interactive Top-Edge Snap Layout Picker

2. ⚡ Interactive Drag-to-Snap & Real-Time HUD Overlay

3. ↔️ Adaptive Collinear Resize & Custom Window Gaps

4. 🪐 Current Space Anchoring (Zero Unwanted Space Jumping)

5. 🗂️ Intent-Based Workspaces & Workflow Presets

6. 📌 Per-App Window Policies & Smart Floating Stack

7. ⌨️ Menu Bar Quick Controls & Global Hotkeys

💻 System Requirements & Permissions

🚀 Installation & Getting Started

For Users: Download & Install

Option 1: One-Line Terminal Install (Recommended ⚡)

Option 2: Direct Download for macOS (.dmg) 📥

Option 3: Package DMG from Source Locally

For Developers: Building from Source

Prerequisites

Build & Run Commands

⌨️ Keyboard Shortcuts

🏗️ Architecture & Engineering

Engineering Guarantees

🔧 Troubleshooting & Gotchas

📚 Documentation Index

🤝 Contributing

🛡️ Security

📄 License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages