Zentro

A fast, keyboard-driven macOS window manager. Define layouts, assign apps to zones, apply instantly.

---

Requirements

Tool	Version
macOS	14.0+
Xcode	15+
Tuist	via mise (auto-installed)

Install mise if you don't have it:

brew install mise

---

Getting started

git clone <repo>
cd Zentro

# Install tools declared in .mise.toml (tuist)
mise install

# Generate the Xcode project
tuist generate --no-open

# Open in Xcode
open Zentro.xcworkspace

Or use the build script to do it all in one step:

./scripts/build.sh --launch

---

Build script

./scripts/build.sh [options]

Options:
  --launch          Build the app and launch it (implies --scheme Zentro)
  --scheme <name>   Xcode scheme to build (default: ZentroUI)
  --clean           Clean before build
  --release         Build Release configuration
  --no-generate     Skip tuist generate (faster on repeated builds)

Install xcbeautify for cleaner build output:

brew install xcbeautify

---

Project structure

Zentro/
├── Project.swift               # Tuist project definition
├── Tuist.swift                 # Tuist workspace config
├── scripts/
│   └── build.sh                # Generate + build + launch
└── Targets/
    ├── ZentroApp/              # App entry point, composition root
    ├── ZentroUI/               # SwiftUI component library
    │   ├── Theme/              # ZentroTheme (colors, spacing, typography, motion)
    │   ├── Components/         # Sidebar, Panel, Buttons, ListItem, …
    │   └── Demo/               # ZentroDemoScreen
    ├── ZentroDomain/           # Pure models (WorkspaceLayout, LayoutZone, …)
    ├── LayoutEngine/           # Layout application logic
    ├── WindowEngine/           # Accessibility API wrapper
    ├── AppEngine/              # NSWorkspace / app discovery
    ├── ScreenEngine/           # Frame math, screen geometry
    ├── CommandEngine/          # Command routing
    ├── ShortcutEngine/         # Global keyboard shortcuts
    ├── PersistenceEngine/      # JSON persistence
    └── ZentroTestingSupport/   # Fakes and fixtures

Module boundaries are strict — see claude.md.

---

Architecture

Commands flow top-down through engines. No engine calls another directly; orchestration lives in LayoutEngine.

UI / Shortcut / Menu Bar
        ↓
   CommandEngine
        ↓
   LayoutEngine
   ↙    ↓    ↘
App  Screen  Window
Engine Engine  Engine

ZentroApp is the composition root — it wires concrete implementations to protocol abstractions and owns no business logic.

---

Design system

All UI tokens (colors, spacing, typography, motion) live in ZentroTheme. Components are in ZentroUI/Components/. The demo screen (ZentroDemoScreen) shows all components together and is the reference for visual QA.

# Open ZentroUI scheme to work on the design system in isolation
./scripts/build.sh --scheme ZentroUI

Design reference: design.md

---

Docs

File	Contents
prd.md	Product requirements and MVP scope
tech-spec.md	Architecture, modules, testing strategy
design.md	Color, typography, spacing, motion
claude.md	AI agent guidelines for this codebase