Flowback Logo Flowback
Download GitHub

Contributing to Flowback

Flowback is an open-source, community-driven project. We welcome code contributions, bug reports, and new agent adapters.

Development Setup

Requirements: macOS 14.0+ (Apple Silicon or Intel), Swift 6.0+, and Apple Command Line Tools.

# 1. Clone repository
git clone https://github.com/rapheljr/flowback.git
cd flowback

# 2. Build local debug binaries
swift build

# 3. Run full verification test suite (61 tests)
swift run FlowbackTestRunner

Deterministic Testing & Quality Checks

Every pull request must pass all verification tests without regression:

Verification Test Suite

Flowback includes a standalone test runner testing 61 assertions across state machine transitions, event deduplication, policy hierarchy, SQLite recovery, and acceptance scenarios:

swift run FlowbackTestRunner

Linting & Formatting

Swift code is validated using SwiftLint:

make lint
# Or: swiftlint

How You Can Contribute

🤖

Add an Agent Provider

Implement the AgentProvider protocol in Sources/FlowbackProviders/ to map new AI assistants into normalized AgentEvents.

🖥️

Add an Application Adapter

Implement ApplicationAdapter in Sources/FlowbackFocus/Adapters/ to discover and raise windows in new IDEs or terminals.

🐛

Find Good First Issues

Browse our issue tracker for issues tagged good first issue to get started quickly.

Pull Request Guidelines

  1. Follow Conventional Commits (e.g., feat(provider): add Windsurf support, fix(focus): prevent focus steal).
  2. Keep pull requests focused on a single change; avoid bundling unrelated refactorings.
  3. Include unit or integration test assertions in FlowbackTestRunner or Tests/.
  4. Ensure zero personal tokens, secrets, or proprietary test paths are committed.
  5. Fill out the Pull Request Template completely.

Security Vulnerabilities

Do NOT report security vulnerabilities through public GitHub issues. Please report privately via GitHub Security Advisories:

🔒 Report Security Advisory Privately