FlashSpace

https://github.com/wojciech-kulik/flashspace
Admin
FlashSpace is a blazingly-fast virtual workspace manager for macOS that enhances native macOS Spaces...
Tokens:11,242
Snippets:80
Trust Score:9.4
License:GPL-3.0
Update:10 months ago
Show doc for...
Tokens:
Raw
### CommandRequest Usage Examples (Swift)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Examples demonstrating how to use the `SocketClient` in Swift to send various commands to FlashSpace. These examples cover activating workspaces, navigating between them, assigning applications, managing profiles, and listing data.

```swift
// Activate workspace
SocketClient.shared.sendCommand(
    .activateWorkspace(name: "Development", number: nil, clean: false)
)

// Navigate workspaces
SocketClient.shared.sendCommand(
    .nextWorkspace(skipEmpty: true, clean: false, loop: true)
)

// Assign app
SocketClient.shared.sendCommand(
    .assignApp(
        app: "Safari",
        workspaceName: "Browsing",
        activate: true,
        showNotification: true
    )
)

// Profile management
SocketClient.shared.sendCommand(.activateProfile(name: "Work"))
SocketClient.shared.sendCommand(.nextProfile)

// List operations
SocketClient.shared.sendCommand(.listWorkspaces(withDisplay: true, profile: nil))
SocketClient.shared.sendCommand(.listApps(
    workspace: "Development",
    profile: nil,
    withBundleId: true,
    withIcon: false,
    onlyRunning: true
))
```

--------------------------------

### YAML Configuration Example

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

An example of a YAML configuration file for Flashspace. This format mirrors the JSON structure, defining profiles and workspaces with similar properties including display, shortcuts, applications, and activation settings. YAML is often preferred for its readability.

```yaml
profiles:
  - id: 550e8400-e29b-41d4-a716-446655440000
    name: Work
    workspaces:
      - id: 650e8400-e29b-41d4-a716-446655440000
        name: Development
        display: Built-in Display
        shortcut:
          keyCode: 18
          modifiers:
            - command
            - shift
        apps:
          - name: Xcode
            bundleIdentifier: com.apple.dt.Xcode
          - name: Terminal
            bundleIdentifier: com.apple.Terminal
        symbolIconName: hammer.fill
        openAppsOnActivation: true
```

--------------------------------

### TOML Configuration Example

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

An example of a TOML configuration file for Flashspace. This format organizes settings using tables and arrays, representing profiles, workspaces, shortcuts, and applications. TOML is known for its straightforward syntax and clear structure.

```toml
[[profiles]]
id = "550e8400-e29b-41d4-a716-446655440000"
name = "Work"

[[profiles.workspaces]]
id = "650e8400-e29b-41d4-a716-446655440000"
name = "Development"
display = "Built-in Display"
symbolIconName = "hammer.fill"
openAppsOnActivation = true

[profiles.workspaces.shortcut]
keyCode = 18
modifiers = ["command", "shift"]

[[profiles.workspaces.apps]]
name = "Xcode"
bundleIdentifier = "com.apple.dt.Xcode"

[[profiles.workspaces.apps]]
name = "Terminal"
bundleIdentifier = "com.apple.Terminal"
```

--------------------------------

### JSON Configuration Example

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

An example of a JSON configuration file structure for Flashspace. It defines profiles, each containing workspaces with settings like display, shortcut, associated applications, icon, and an option to open apps on activation. This structure is used for defining application layouts and shortcuts.

```json
{
  "profiles": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Work",
      "workspaces": [
        {
          "id": "650e8400-e29b-41d4-a716-446655440000",
          "name": "Development",
          "display": "Built-in Display",
          "shortcut": {
            "keyCode": 18,
            "modifiers": ["command", "shift"]
          },
          "apps": [
            {
              "name": "Xcode",
              "bundleIdentifier": "com.apple.dt.Xcode"
            },
            {
              "name": "Terminal",
              "bundleIdentifier": "com.apple.Terminal"
            }
          ],
          "symbolIconName": "hammer.fill",
          "openAppsOnActivation": true
        }
      ]
    }
  ]
}
```

--------------------------------

### Install FlashSpace with Homebrew

Source: https://github.com/wojciech-kulik/flashspace/blob/main/README.md

This command installs the FlashSpace application using the Homebrew package manager. Ensure Homebrew is installed and updated before running this command. This is the recommended installation method for most macOS users.

```bash
brew install flashspace
```

--------------------------------

### Swift API: Define Workspace Structure

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Example of defining a `Workspace` structure in Swift, including properties like name, display, shortcuts, assigned applications, and default app to focus. Requires importing Foundation.

```swift
import Foundation

// Create new workspace
let workspace = Workspace(
    id: UUID(),
    name: "Development",
    display: "Built-in Display",
    activateShortcut: AppHotKey(
        keyCode: 15,  // R key
        modifiers: [.command, .shift]
    ),
    assignAppShortcut: AppHotKey(
        keyCode: 15,
        modifiers: [.command, .shift, .option]
    ),
    apps: [
        MacApp(
            name: "Xcode",
            bundleIdentifier: "com.apple.dt.Xcode",
            iconPath: "/Applications/Xcode.app"
        ),
        MacApp(
            name: "Terminal",
            bundleIdentifier: "com.apple.Terminal",
            iconPath: "/System/Applications/Utilities/Terminal.app"
        )
    ],
    appToFocus: MacApp(
        name: "Xcode",
        bundleIdentifier: "com.apple.dt.Xcode",
        iconPath: "/Applications/Xcode.app"
    ),
    symbolIconName: "hammer.fill",
    openAppsOnActivation: true
)
```

--------------------------------

### Swift API: Navigate Workspaces Programmatically

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Provides examples for navigating between workspaces programmatically using WorkspaceManager, including options for moving to the next/previous workspace, skipping empty ones, looping, and activating the most recently used workspace.

```swift
// Navigate to next workspace with options
workspaceManager.activateWorkspace(
    next: true,           // true for next, false for previous
    skipEmpty: true,      // skip workspaces without running apps
    loop: true            // loop back to first when reaching last
)

// Activate most recently used workspace
workspaceManager.activateRecentWorkspace()
```

--------------------------------

### Flashspace CLI: Get App and Display Information

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Commands to retrieve information about the active application, including its window count, and to get the current display name.

```bash
flashspace get-app --with-windows-count
flashspace get-display
```

--------------------------------

### Get Current State (Bash)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Retrieves the current active workspace, either on the current display or a specified one. This is useful for scripting and automation to determine the current context.

```bash
# Get active workspace on current display
flashspace get-workspace

# Get workspace on specific display
flashspace get-workspace --display "Built-in Display"
```

--------------------------------

### Generate Xcode Project with Custom Team ID

Source: https://github.com/wojciech-kulik/flashspace/blob/main/README.md

This command generates the Xcode project using xcodegen, allowing you to specify a development team ID for signing configurations. Ensure you have xcodegen installed and replace 'YOUR_TEAM_ID' with your actual Apple Developer Team ID. This is crucial for building and running the application.

```bash
XCODE_DEVELOPMENT_TEAM=YOUR_TEAM_ID xcodegen generate
```

--------------------------------

### Workspace Management

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Commands for activating, navigating, creating, and deleting workspaces.

```APIDOC
## Workspace Management

### Activate Workspace by Name

**Description**: Activates a workspace by its given name.

**Method**: CLI Command

**Endpoint**: `flashspace workspace --name "<workspace_name>"`

### Activate Workspace by Number

**Description**: Activates a workspace by its numerical index.

**Method**: CLI Command

**Endpoint**: `flashspace workspace --number <workspace_number>`

### Navigate Between Workspaces

**Description**: Navigates to the next, previous, or most recently used workspace, with options to skip empty workspaces or loop.

**Method**: CLI Command

**Endpoint**: `flashspace workspace --next [--skip-empty] [--loop]`
**Endpoint**: `flashspace workspace --prev [--skip-empty] [--loop]`
**Endpoint**: `flashspace workspace --recent`

### Clean Up Unassigned Apps

**Description**: Activates a workspace and hides all applications not assigned to it.

**Method**: CLI Command

**Endpoint**: `flashspace workspace --name "<workspace_name>" --clean`

### List All Workspaces

**Description**: Lists all defined workspaces, with options to include display assignments or filter by profile.

**Method**: CLI Command

**Endpoint**: `flashspace list-workspaces [--with-display] [--profile "<profile_name>"]`

### Create New Workspace

**Description**: Creates a new workspace with specified name, display, and optional shortcut.

**Method**: CLI Command

**Endpoint**: `flashspace create-workspace --name "<workspace_name>" --display "<display_name>" [--shortcut "<shortcut_keys>"]`

### Delete Workspace

**Description**: Deletes a workspace by its name.

**Method**: CLI Command

**Endpoint**: `flashspace delete-workspace --name "<workspace_name>"`
```

--------------------------------

### Floating Apps and Window Management

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Commands for managing floating applications and focusing windows.

```APIDOC
## Floating Apps and Window Management

### Floating Apps Management

**Description**: Commands to float, unfloat, toggle floating status, and list floating applications.

**Method**: CLI Command

**Endpoint**: `flashspace float-app [--name "<app_name>"] [--show-notification]`
**Endpoint**: `flashspace unfloat-app --name "<app_name>"`
**Endpoint**: `flashspace toggle-float-app [--name "<app_name>"]`
**Endpoint**: `flashspace list-floating-apps [--with-bundle-id]`

### Focus Window Management

**Description**: Commands to focus windows in different directions or navigate between windows and applications.

**Method**: CLI Command

**Endpoint**: `flashspace focus-window --direction <left|right|up|down>`
**Endpoint**: `flashspace focus-next-window`
**Endpoint**: `flashspace focus-previous-window`
**Endpoint**: `flashspace focus-next-app`
**Endpoint**: `flashspace focus-previous-app`
```

--------------------------------

### FlashSpace Command-Line Interface Help

Source: https://github.com/wojciech-kulik/flashspace/blob/main/README.md

This command displays the help information for the FlashSpace command-line interface. It lists all available commands and their usage, which is essential for users wanting to manage workspaces, apps, and profiles programmatically.

```bash
flashspace --help
```

--------------------------------

### Create MacApp Instance (Swift)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Demonstrates how to create `MacApp` instances in Swift. Instances can be created directly from an `NSRunningApplication` object or manually by providing the application's name, bundle identifier, and icon path. This requires the `AppKit` framework.

```swift
import AppKit

// From NSRunningApplication
let runningApp = NSWorkspace.shared.frontmostApplication!
let macApp = MacApp(app: runningApp)

// Manual creation
let macApp = MacApp(
    name: "Safari",
    bundleIdentifier: "com.apple.Safari",
    iconPath: "/Applications/Safari.app"
)
```

--------------------------------

### Flashspace CLI: Open Space Control and Applications

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Commands to open the Space Control UI for previewing workspaces and to open specific applications by name.

```bash
# Open the Space Control UI to preview all workspaces
flashspace open-space-control

flashspace open-app --name "Safari"
```

--------------------------------

### Swift API: Activate Workspace with WorkspaceManager

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Demonstrates how to activate a workspace using the WorkspaceManager, with options to set focus or maintain current focus. It requires importing AppKit.

```swift
import AppKit

// Get workspace manager instance
let workspaceManager = AppDependencies.shared.workspaceManager

// Get workspace from repository
let workspace = workspaceRepository.workspaces.first { $0.name == "Development" }

// Activate workspace with focus
workspaceManager.activateWorkspace(workspace, setFocus: true)

// Activate without changing focus
workspaceManager.activateWorkspace(workspace, setFocus: false)
```

--------------------------------

### Create New Workspace (Bash)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Creates a new virtual workspace with specified parameters, including name, assigned display, and an optional hotkey shortcut.

```bash
flashspace create-workspace \
  --name "Gaming" \
  --display "Built-in Display" \
  --shortcut "cmd+shift+g"
```

--------------------------------

### Profile Management

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Commands for managing workspace profiles.

```APIDOC
## Profile Management

### List All Profiles

**Description**: Lists all available workspace profiles.

**Method**: CLI Command

**Endpoint**: `flashspace list-profiles`

### Get Active Profile

**Description**: Retrieves the name of the currently active profile.

**Method**: CLI Command

**Endpoint**: `flashspace get-profile`

### Create New Profile

**Description**: Creates a new workspace profile, with options to activate it upon creation or copy settings from the current profile.

**Method**: CLI Command

**Endpoint**: `flashspace create-profile --name "<profile_name>" [--activate] [--copy]`

### Activate Profile

**Description**: Activates a specified workspace profile.

**Method**: CLI Command

**Endpoint**: `flashspace profile "<profile_name>"`

### Navigate Profiles

**Description**: Navigates to the next or previous profile in the list.

**Method**: CLI Command

**Endpoint**: `flashspace profile --next`
**Endpoint**: `flashspace profile --prev`

### Delete Profile

**Description**: Deletes a specified workspace profile.

**Method**: CLI Command

**Endpoint**: `flashspace delete-profile --name "<profile_name>"`
```

--------------------------------

### SKHD Custom Hotkey Configuration (bash)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

This snippet shows a basic configuration for SKHD (Simple hotkey daemon) located in the `~/.skhdrc` file. It's a placeholder demonstrating where custom hotkey bindings for managing workspaces or applications within Flashspace would be defined.

```bash
# ~/.skhdrc


```

--------------------------------

### Profile Management (Bash)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Manages user profiles, which can store different workspace configurations. Includes commands for listing, creating, activating, copying, and deleting profiles.

```bash
# List all profiles
flashspace list-profiles

# Get active profile
flashspace get-profile

# Create new profile
flashspace create-profile --name "Personal"

# Create and activate
flashspace create-profile --name "Work" --activate

# Copy current profile settings
flashspace create-profile --name "Work-Copy" --copy --activate

# Activate profile
flashspace profile "Work"

# Navigate profiles
flashspace profile --next
flashspace profile --prev

# Delete profile
flashspace delete-profile --name "Personal"
```

--------------------------------

### Navigate Between Workspaces (Bash)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Navigates through workspaces sequentially. Options include moving to the next or previous workspace, skipping empty ones, looping, and activating the most recently used.

```bash
# Activate next workspace
flashspace workspace --next

# Activate previous workspace
flashspace workspace --prev

# Skip empty workspaces when navigating
flashspace workspace --next --skip-empty

# Loop back to first workspace when reaching the end
flashspace workspace --next --loop

# Activate most recently used workspace
flashspace workspace --recent
```

--------------------------------

### Application Assignment

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Commands for assigning and unassigning applications to workspaces.

```APIDOC
## Application Assignment

### Assign Application to Workspace

**Description**: Assigns an application (active or specified by name/bundle ID) to a workspace. Can optionally activate the workspace and show a notification.

**Method**: CLI Command

**Endpoint**: `flashspace assign-app [--name "<app_name_or_bundle_id>"] [--workspace "<workspace_name>"] [--activate <true|false>] [--show-notification]`

### Unassign Application

**Description**: Unassigns an application (active or specified by name) from its current workspace. Can optionally show a notification.

**Method**: CLI Command

**Endpoint**: `flashspace unassign-app [--name "<app_name>"] [--show-notification]`

### Assign All Visible Apps

**Description**: Assigns all currently visible applications on the active display to a specified workspace. Can optionally show a notification.

**Method**: CLI Command

**Endpoint**: `flashspace assign-visible-apps [--workspace "<workspace_name>"] [--show-notification]`

### List Applications in Workspace

**Description**: Lists applications assigned to a specific workspace, with options to include bundle IDs, filter for running apps, and show icons.

**Method**: CLI Command

**Endpoint**: `flashspace list-apps --workspace "<workspace_name>" [--with-bundle-id] [--only-running] [--with-icon] [--profile "<profile_name>"]`
```

--------------------------------

### Focus Window Management (Bash)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Provides commands for navigating and focusing windows within the current workspace. Users can direct focus in cardinal directions or cycle through windows and applications.

```bash
# Focus window in specific direction
flashspace focus-window --direction left
flashspace focus-window --direction right
flashspace focus-window --direction up
flashspace focus-window --direction down

# Focus next/previous window
flashspace focus-next-window
flashspace focus-previous-window

# Focus next/previous app
flashspace focus-next-app
flashspace focus-previous-app
```

--------------------------------

### List All Running Applications (Bash)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Retrieves a list of all currently running applications on the system. This command provides a system-wide overview of active applications.

```bash
flashspace list-running-apps
```

--------------------------------

### SketchyBar All Workspaces Display (bash)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Configures SketchyBar to display all available workspaces as individual items. It iterates through workspaces fetched from FlashSpace, creates a labeled item for each, and assigns a script to visually indicate the currently active workspace by changing its label color. It subscribes to workspace change events to update the display dynamically.

```bash
# sketchybarrc
sketchybar --add event flashspace_workspace_change

SID=1
WORKSPACES=$(/Applications/FlashSpace.app/Contents/Resources/flashspace list-workspaces)

for workspace in $WORKSPACES; do
  sketchybar --add item flashspace.$SID left \
    --subscribe flashspace.$SID flashspace_workspace_change \
    --set flashspace.$SID \
    background.color=0x22ffffff \
    background.corner_radius=5 \
    label="$workspace" \
    script="$CONFIG_DIR/plugins/flashspace.sh $workspace"
  SID=$((SID + 1))
done
```

```bash
# plugins/flashspace.sh
#!/bin/bash
if [ "$1" = "$WORKSPACE" ]; then
  sketchybar --set $NAME label.color=0xffff0000
else
  sketchybar --set $NAME label.color=0xffffffff
fi
```

--------------------------------

### SketchyBar Integration: Display All Workspaces

Source: https://github.com/wojciech-kulik/flashspace/blob/main/README.md

This configuration displays all workspaces in SketchyBar, highlighting the active one with a different color. It fetches the list of workspaces and creates an item for each, subscribing to workspace change events to update their appearance. This provides a comprehensive overview of all available workspaces.

```bash
#!/bin/bash

if [ "$1" = "$WORKSPACE" ]; then
  sketchybar --set $NAME label.color=0xffff0000
else
  sketchybar --set $NAME label.color=0xffffffff
fi
```

```bash
sketchybar --add event flashspace_workspace_change

SID=1
WORKSPACES=$(/Applications/FlashSpace.app/Contents/Resources/flashspace list-workspaces)

for workspace in $WORKSPACES; do
  sketchybar --add item flashspace.$SID left \
    --subscribe flashspace.$SID flashspace_workspace_change \
    --set flashspace.$SID \
    background.color=0x22ffffff \
    background.corner_radius=5 \
    background.padding_left=5 \
    label.padding_left=5 \
    label.padding_right=5 \
    label="$workspace" \
    script="$CONFIG_DIR/plugins/flashspace.sh $workspace"

  SID=$((SID + 1))
done
```

--------------------------------

### Activate Workspace by Number (Bash)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Activates a virtual workspace using its numerical index. The first workspace is represented by '1'.

```bash
# Activate the first workspace
flashspace workspace --number 1
```

--------------------------------

### FlashSpace CLI Commands

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Command-line interface commands for FlashSpace, used for controlling workspaces, applications, profiles, and window focus. These are typically invoked via shell commands or keyboard shortcuts.

```shell
# Workspace navigation
cmd + shift - 1 : /Applications/FlashSpace.app/Contents/Resources/flashspace workspace --number 1
cmd + shift - 2 : /Applications/FlashSpace.app/Contents/Resources/flashspace workspace --number 2
cmd + shift - 3 : /Applications/FlashSpace.app/Contents/Resources/flashspace workspace --number 3

# Navigate with arrows
cmd + ctrl - right : /Applications/FlashSpace.app/Contents/Resources/flashspace workspace --next --loop
cmd + ctrl - left : /Applications/FlashSpace.app/Contents/Resources/flashspace workspace --prev --loop

# App assignment
cmd + shift + alt - a : /Applications/FlashSpace.app/Contents/Resources/flashspace assign-app --show-notification

# Profile switching
cmd + shift - p : /Applications/FlashSpace.app/Contents/Resources/flashspace profile --next

# Focus management
cmd + alt - h : /Applications/FlashSpace.app/Contents/Resources/flashspace focus-window --direction left
cmd + alt - j : /Applications/FlashSpace.app/Contents/Resources/flashspace focus-window --direction down
cmd + alt - k : /Applications/FlashSpace.app/Contents/Resources/flashspace focus-window --direction up
cmd + alt - l : /Applications/FlashSpace.app/Contents/Resources/flashspace focus-window --direction right

# Space control
cmd + shift - s : /Applications/FlashSpace.app/Contents/Resources/flashspace open-space-control
```

--------------------------------

### SocketClient for FlashSpace Communication (Swift)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

A Swift implementation of a SocketClient to communicate with the FlashSpace daemon via a Unix domain socket. It handles sending commands and receiving responses, facilitating programmatic control over FlashSpace features.

```swift
import Foundation
import Network

final class SocketClient {
    static let shared = SocketClient()
    private let socketPath = "/tmp/flashspace.socket"

    func sendCommand(_ command: CommandRequest) {
        let connection = NWConnection(
            to: .unix(path: socketPath),
            using: .tcp
        )
        connection.start(queue: .main)

        let messageData = command.encodeSocketData()
        connection.send(content: messageData, completion: .contentProcessed { error in
            if let error {
                connection.cancel()
                print("Error: \(error)")
                return
            }
            self.receiveData(connection: connection)
        })
    }

    private func receiveData(connection: NWConnection) {
        connection.receive(
            minimumIncompleteLength: 1,
            maximumLength: 10000
        ) { data, _, isComplete, error in
            if let error {
                connection.cancel()
                print("Error: \(error)")
                return
            }

            if let data, let response = try? data.decodeSocketData(CommandResponse.self) {
                self.handleResponse(response, connection: connection)
            }
        }
    }

    private func handleResponse(_ response: CommandResponse, connection: NWConnection) {
        if response.success {
            response.message.flatMap { print($0) }
        } else {
            print("Error: \(response.error ?? \"Operation Failed\")")
        }
        connection.cancel()
    }
}
```

--------------------------------

### Compare MacApp Instances (Swift)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Shows how to compare two `MacApp` instances in Swift. The comparison logic prioritizes the `bundleIdentifier` for equality checks and falls back to the `name` if the identifier is not available. This functionality allows for determining if two instances represent the same application.

```swift
let app1 = MacApp(name: "Chrome", bundleIdentifier: "com.google.Chrome", iconPath: nil)
let app2 = MacApp(name: "Chrome", bundleIdentifier: "com.google.Chrome", iconPath: nil)

// Comparison uses bundle ID if available, otherwise falls back to name
if app1 == app2 {
    print("Same app")
}
```

--------------------------------

### Swift API: Observe Active Workspace Changes with Combine

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Shows how to observe changes in the active workspace using Combine and Swift. It involves subscribing to the `activeWorkspaceDetails` publisher and printing workspace information upon changes.

```swift
import Combine

class MyController: ObservableObject {
    private var cancellables = Set<AnyCancellable>()
    private let workspaceManager: WorkspaceManager

    init(workspaceManager: WorkspaceManager) {
        self.workspaceManager = workspaceManager

        // Subscribe to active workspace changes
        workspaceManager.$activeWorkspaceDetails
            .sink { [weak self] workspace in
                guard let workspace = workspace else { return }
                print("Active workspace: (workspace.name)")
                print("Display: (workspace.display)")
                print("Workspace number: (workspace.number ?? "N/A")")
            }
            .store(in: &cancellables)
    }
}
```

--------------------------------

### State Information

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Commands to retrieve current state information about workspaces.

```APIDOC
## State Information

### Get Current Workspace

**Description**: Retrieves the name of the active workspace on the current or a specified display.

**Method**: CLI Command

**Endpoint**: `flashspace get-workspace [--display "<display_name>"]`
```

--------------------------------

### Swift API: Assign Applications to Workspace

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Illustrates how to assign single or multiple applications to a specific workspace using the WorkspaceManager. It involves creating MacApp objects from running applications.

```swift
// Create MacApp from running application
let runningApp = NSRunningApplication.runningApplications(
    withBundleIdentifier: "com.google.Chrome"
).first!

let macApp = MacApp(
    name: runningApp.localizedName ?? "Chrome",
    bundleIdentifier: runningApp.bundleIdentifier ?? "",
    iconPath: runningApp.bundleURL?.path
)

// Assign single app (removes from other workspaces)
workspaceManager.assignApp(macApp, to: workspace)

// Assign multiple apps at once
let apps = [macApp1, macApp2, macApp3]
workspaceManager.assignApps(apps, to: workspace)
```

--------------------------------

### Floating Apps Management (Bash)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Manages applications that should remain visible across all workspaces. Commands include floating, unfloating, toggling status, and listing all floating applications, with options for notifications and bundle IDs.

```bash
# Float active app (visible across all workspaces)
flashspace float-app

# Float specific app
flashspace float-app --name "Music" --show-notification

# Unfloat app
flashspace unfloat-app --name "Music"

# Toggle floating status
flashspace toggle-float-app

# List all floating apps
flashspace list-floating-apps --with-bundle-id
```

--------------------------------

### Swift API: Update and Re-activate Workspace

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Demonstrates updating the last focused application for a workspace and re-activating a workspace if it's already active, potentially for refresh purposes, using WorkspaceManager.

```swift
// Remember last focused app for workspace
let focusedApp = MacApp(app: NSWorkspace.shared.frontmostApplication!)
workspaceManager.updateLastFocusedApp(focusedApp, in: workspace)

// Re-activate workspace if it's currently active (refresh)
workspaceManager.activateWorkspaceIfActive(workspace.id)
```

--------------------------------

### Activate Workspace by Name (Bash)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Activates a virtual workspace by its given name. This is useful for quickly switching to a predefined workspace, such as 'Development'.

```bash
flashspace workspace --name "Development"
```

--------------------------------

### List Workspaces (Bash)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Lists all defined virtual workspaces. Options allow for including display assignments or filtering by a specific profile.

```bash
# Simple list
flashspace list-workspaces

# Include display assignments
flashspace list-workspaces --with-display

# List workspaces for specific profile
flashspace list-workspaces --profile "Work"
```

--------------------------------

### List Applications in Workspace (Bash)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Lists applications associated with a specific workspace. Options allow for including bundle IDs, filtering to only running applications with icons, or specifying a profile.

```bash
# List apps in workspace
flashspace list-apps --workspace "Development"

# Include bundle IDs
flashspace list-apps --workspace "Development" --with-bundle-id

# Only show running apps with icons
flashspace list-apps --workspace "Development" --only-running --with-icon

# List for specific profile
flashspace list-apps --workspace "Development" --profile "Work"
```

--------------------------------

### Assign Application to Workspace (Bash)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Assigns an application to a specific workspace. Applications can be specified by name or bundle ID, and the target workspace can also be named. Options include activating the workspace and showing a notification upon completion.

```bash
# Assign active app to active workspace
flashspace assign-app

# Assign specific app by name to specific workspace
flashspace assign-app --name "Safari" --workspace "Browsing"

# Assign by bundle ID and activate workspace
flashspace assign-app --name "com.google.Chrome" --workspace "Development" --activate true

# Show notification after assignment
flashspace assign-app --show-notification
```

--------------------------------

### SketchyBar Single Active Workspace Display (bash)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Configures SketchyBar to display a single active workspace. It adds an item named 'flashspace' to the left of the bar, sets its appearance, and assigns a script to update its label with the current workspace and display information. It also subscribes to workspace change events.

```bash
# sketchybarrc
sketchybar --add item flashspace left \
  --set flashspace \
  background.color=0x22ffffff \
  background.corner_radius=5 \
  label.padding_left=5 \
  label.padding_right=5 \
  script="$CONFIG_DIR/plugins/flashspace.sh" \
  --add event flashspace_workspace_change \
  --subscribe flashspace flashspace_workspace_change
```

```bash
# plugins/flashspace.sh
#!/bin/bash
sketchybar --set $NAME label="$WORKSPACE - $DISPLAY"
```

--------------------------------

### Swift API: Check Workspace Display Properties

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Code snippets demonstrating how to check various display-related properties of a `Workspace` object, such as the displays it's running on, its display name for printing, and whether it's on the current screen or uses dynamic display assignment.

```swift
// Get all displays where workspace apps are running (dynamic mode)
let displays: Set<String> = workspace.displays

// Get display name for printing/logging
let displayName: String = workspace.displayForPrint

// Check if workspace is on current screen
if workspace.isOnTheCurrentScreen {
    print("Workspace is visible on current screen")
}

// Check if using dynamic display mode
if workspace.isDynamic {
    print("Workspace uses dynamic display assignment")
}
```

--------------------------------

### Swift API: Hide/Show Unassigned Apps with WorkspaceManager

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Functions to control the visibility of unassigned applications. Includes hiding unassigned apps, showing unassigned apps, and hiding all apps on the current display.

```swift
// Hide all apps not assigned to current workspace
workspaceManager.hideUnassignedApps()

// Show only unassigned apps
workspaceManager.showUnassignedApps()

// Hide all apps on current display
workspaceManager.hideAll()
```

--------------------------------

### Decode MacApp from JSON (Swift)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Demonstrates decoding `MacApp` instances from JSON data in Swift using `JSONDecoder`. This method supports both legacy V1 format (a simple string for the app name) and the V2 format (a full JSON object with name, bundle identifier, and icon path). It requires the `Foundation` framework.

```swift
import Foundation

// Supports legacy V1 format (string only) and V2 format (full object)
let jsonV1 = """
"Safari"
"""

let jsonV2 = """
{
  "name": "Safari",
  "bundleIdentifier": "com.apple.Safari",
  "iconPath": "/Applications/Safari.app"
}
"""

let decoder = JSONDecoder()

// Both formats are automatically handled
let app1 = try decoder.decode(MacApp.self, from: jsonV1.data(using: .utf8)!)
let app2 = try decoder.decode(MacApp.self, from: jsonV2.data(using: .utf8)!)
```

--------------------------------

### SketchyBar Integration: Display Active Workspace

Source: https://github.com/wojciech-kulik/flashspace/blob/main/README.md

This configuration displays the currently active workspace in SketchyBar. It sets up an item in the bar and a script to update its label with the workspace name and display. This is useful for visually tracking the active workspace.

```bash
#!/bin/bash

sketchybar --set $NAME label="$WORKSPACE - $DISPLAY"
```

```bash
sketchybar --add item flashspace left \
  --set flashspace \
  background.color=0x22ffffff \
  background.corner_radius=5 \
  label.padding_left=5 \
  label.padding_right=5 \
  script="$CONFIG_DIR/plugins/flashspace.sh" \
  --add event flashspace_workspace_change \
  --subscribe flashspace flashspace_workspace_change
```

--------------------------------

### Activate Workspace and Clean Up Apps (Bash)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Activates a specified workspace and simultaneously hides all applications not assigned to that workspace. This helps in maintaining focus on the intended applications.

```bash
# Activate workspace and hide all unassigned apps
flashspace workspace --name "Development" --clean
```

--------------------------------

### Assign All Visible Apps (Bash)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Assigns all currently visible applications on the active display to a specified workspace. This is useful for quickly organizing your current view. The operation can also show a notification.

```bash
# Assign all visible apps on current display to active workspace
flashspace assign-visible-apps

# Assign to specific workspace
flashspace assign-visible-apps --workspace "Development" --show-notification
```

--------------------------------

### Flashspace CLI: Hide Unassigned Applications

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Command to hide all applications that are not currently assigned to the active workspace.

```bash
# Hide all apps not assigned to current workspace
flashspace hide-unassigned-apps
```

--------------------------------

### Filter Workspaces with Running Apps (Swift)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Filters a list of all workspaces to include only those that have at least one running application. It then iterates through the active workspaces and prints their names. This function requires a `workspaceRepository` with a `workspaces` property and an extension `skipWithoutRunningApps()` on the workspace collection.

```swift
let allWorkspaces = workspaceRepository.workspaces

// Get only workspaces that have at least one running app
let activeWorkspaces = allWorkspaces.skipWithoutRunningApps()

for workspace in activeWorkspaces {
    print("\(workspace.name) has running apps")
}
```

--------------------------------

### Check if an App is Finder (Swift)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Provides a way to check if a given `MacApp` instance represents the Finder application in Swift. This is achieved through a boolean property `isFinder` on the `MacApp` object, which likely checks the bundle identifier against that of Finder.

```swift
let app = MacApp(name: "Finder", bundleIdentifier: "com.apple.finder", iconPath: nil)

if app.isFinder {
    print("This is the Finder app")
}
```

--------------------------------

### Delete Workspace (Bash)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Deletes an existing virtual workspace by its name. Ensure no critical applications are running in the workspace before deletion.

```bash
flashspace delete-workspace --name "Gaming"
```

--------------------------------

### Unassign Application (Bash)

Source: https://context7.com/wojciech-kulik/flashspace/llms.txt

Removes an application's assignment from its current workspace. This can be done for the currently active application or a specified application by name. A notification can be shown upon completion.

```bash
# Unassign active app
flashspace unassign-app

# Unassign specific app
flashspace unassign-app --name "Slack" --show-notification
```
Tokens:
Raw