# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project

Mission Control Turbo (MCT) — a macOS app that replaces native Mission Control with a custom overlay featuring live window thumbnails and keyboard navigation. Menu-bar-only app (LSUIElement), no Dock icon.

**Requirements:** macOS 14.0+, Apple Silicon (arm64)

## Build

```bash
./build.sh
```

This compiles all Swift files with `swiftc`, creates the app bundle at `build/MCT.app`, code-signs it, and opens it. It kills any running instance first. There is no Xcode build — the build script is the source of truth for which files are compiled.

**When adding a new Swift file, you must add it to `build.sh`.**

There is also an Xcode project (`MCT.xcodeproj`) but the primary build method is the shell script.

## Tests

Tests are in `MCTTests/LayoutEngineTests.swift` using XCTest. There is also a standalone test harness `test_layout.swift` that can be run directly with `swift test_layout.swift` — it replicates core types to test layout logic without Xcode.

## Architecture

```
MCT/
├── App/          # Entry point: MCTApp (@main SwiftUI), AppDelegate (lifecycle, hotkey/gesture setup)
├── Model/        # Data types: WindowInfo, WindowGroup, WindowSnapshot, LayoutState/LayoutPosition
├── API/          # System bridges:
│   ├── WindowEnumerator    — CGWindowListCopyWindowInfo to enumerate windows
│   ├── ThumbnailCapture    — ScreenCaptureKit async thumbnail capture
│   ├── AccessibilityBridge — AXUIElement APIs + private _AXUIElementGetWindow
│   ├── HotKeyManager       — Carbon RegisterEventHotKey (default: Ctrl+Up)
│   └── GestureMonitor      — CGEventTap for 4-finger swipe-up
├── Layout/       # LayoutEngine (grid placement, stability/reuse) + LayoutGeometry (constants, sizing)
├── UI/           # SwiftUI views: OverlayWindowController (NSPanel per display),
│                 #   OverlayView, WindowThumbnailView, AppGroupHeaderView
└── Settings/     # Preferences (UserDefaults singleton), SettingsView
```

**Key flow:** AppDelegate registers hotkey/gesture → triggers `OverlayWindowController.show()` → enumerates windows → captures thumbnails async → LayoutEngine computes grid → OverlayView renders with keyboard nav.

**Layout stability:** LayoutEngine reuses previous positions when >70% of windows overlap with the prior snapshot. Positions are stored as normalized (0..1) coordinates for resolution resilience.

**Multi-display:** OverlayWindowController creates one NSPanel per connected screen.

## Key details

- Uses private Accessibility API (`_AXUIElementGetWindow`) for window activation — common in macOS utilities
- App sandbox is disabled (required for global hotkey and screen capture)
- Compact mode activates when >6 app groups (smaller headers)
- Gesture debug log: `/tmp/mct_gesture.log`
- Frameworks: AppKit, SwiftUI, CoreGraphics, ScreenCaptureKit, Carbon (hotkey)