Flowback Logo Flowback
Download GitHub

Capabilities & System Features

A comprehensive overview of Flowback's architecture, intent detection, and multi-agent focus coordination.

Implemented

1. Agent Lifecycle Tracking & Context Capture

When an agent starts working, Flowback immediately records an immutable OriginContext snapshot before you switch tasks:

Captured Metadata

  • bundleIdentifier: The exact active application (e.g. com.microsoft.VSCode)
  • processIdentifier: POSIX PID of the editor or terminal process
  • windowIdentifier: macOS window ID via AXUIElement
  • windowTitle: Folder and file pattern matching
  • workspacePath: Absolute project root directory
  • startTimestamp: High-resolution UTC start timestamp

Proactive Background Discovery

In addition to standard lifecycle hooks, Flowback runs proactive background discovery:

  • Scans live Antigravity transcripts in ~/.gemini/antigravity-ide/brain/
  • Translates fullyIdle=true into confirmed task completion
  • Detects waiting user inputs (USER_INPUT steps)
  • Recovers active sessions across application launches
Implemented

2. Exact Window & Workspace Restoration Hierarchy

Flowback does not blindly launch apps. It executes Section 14 restoration hierarchy to bring forward the exact window you were working in:

Tier 1

Numeric Window ID

Locates the exact window using Accessibility APIs and triggers kAXRaiseAction without switching focus if you are in another space.

Tier 2

Workspace Title Match

If the window was closed, reloaded, or split, Flowback scans all windows of the target PID and matches the project title.

Tier 3

Application Fallback

Gracefully activates the parent process via NSWorkspace, or presents an actionable alert if the window is unavailable.

Implemented

3. User Intent Engine (Typing Protection)

The cardinal rule of Flowback: Never interrupt active typing.

How Intent Sensing Works:

Flowback queries macOS CoreGraphics event source idle timers (CGEventSourceSecondsSinceLastEventType) across keyboard and mouse events. If any input occurred within the configurable idle threshold (default: 5.0 seconds):

Active Input (< 5s):

Auto-restoration is suppressed. A macOS notification banner is delivered with [Focus Window] and [Review] buttons. Your typing is never interrupted.

System Idle (≥ 5s):

Hands are off the keyboard. Flowback smoothly brings the origin editor or terminal window to the front, ready for your immediate review.

Implemented

4. Attention Arbiter, Cooldowns & Focus Lock

Priority Ordering & Aggregation

When multiple agents run in parallel, completions are prioritized:

  1. permissionRequired (Urgent user review)
  2. failure (Compilation / build error)
  3. completed (Successful task finish)
  4. waiting (Subagent or background timer)
  5. informational (Progress updates)

Completions occurring within a 1.5-second aggregation window are collapsed into a single summary with a 1000ms focus cooldown.

Focus Lock Mode

In a presentation, zoom call, or deep contemplation? Enable Focus Lock directly from the status bar menu or terminal:

flowback focus-lock 30m

Focus Lock silences all automatic window raising while preserving notification banners so you stay informed without disorientation.

Planned

5. Experimental & Upcoming Milestones

Upcoming features scheduled for releases v1.1.0 and v1.2.0:

Multi-Monitor Pinning

Remember which physical display each agent originated on and restrict focus restoration to the active screen.

Terminal Deep Tab Linking

Deeper AppleScript dictionary integration to activate specific tabs in Ghostty and iTerm2.

Provider Sidecar Architecture

Author out-of-process providers in Python, Go, or TypeScript without recompiling Flowback.