# Winjitsu - Full Documentation

Winjitsu navigates Mac windows using a spatial system.

## Overview

Winjitsu is a keyboard-first window manager for macOS that solves the fundamental problem of navigating non-tiled window layouts. While most window managers force windows into rigid grids, Winjitsu lets you arrange windows however you want and still navigate them fluidly with keyboard shortcuts.

## The Problem Winjitsu Solves

When windows overlap, misalign, or stack freely, the question becomes ambiguous: "If I press right, which window should the focus land on?"

Traditional solutions either:
1. Force rigid tiling (removing flexibility)
2. Rely on alt-tab lists (losing spatial context)
3. Require mouse clicking (breaking keyboard flow)

Winjitsu solves this with intelligent spatial navigation that understands your visual layout.

## Core Features

### 1. True Spatial Navigation
Move focus in the direction you're looking using h/j/k/l (Vim-style) or arrow keys. The algorithm, built on game engine and chess engine principles, knows exactly where you want to go - even in complex, overlapping layouts.

### 2. Granular Window Control
- Resize individual edges (grow/shrink left, right, top, bottom)
- Nudge windows pixel by pixel
- Snap to screen edges or other windows when needed
- Shape windows precisely instead of just snapping to presets

### 3. Stack Cycling
Fully stack windows on top of each other and cycle through them fluidly. Works with partial overlaps too. Navigate through any configuration without losing context.

### 4. Mission Control Integration
Navigate Mission Control with the keyboard:
- Browse through Spaces
- Close windows
- Move windows between Spaces
- All without touching the mouse

### 5. Visual Feedback System
Optional preview borders show where focus will land before you commit. Especially useful when learning the system or navigating complex overlapping layouts.

### 6. Native macOS Integration
- Works with Mission Control, Spaces, and native window behaviors
- No System Integrity Protection (SIP) changes required
- Built to last, stable, and respectful of macOS

## Philosophy: The Third Way

Most window managers present a false choice:

**The Chaos:** Free-floating windows you hunt through with clicks and endless alt-tabbing. Zero keyboard control, no spatial awareness.

**The Cage:** Rigid tiling systems that fight macOS and lock everything into place. No overlap, no flexibility, fighting the OS.

**Winjitsu:** Control without confinement. Keyboard efficiency without fighting macOS. Order without restriction.

Core principles:
- Tile when you want
- Stack when you want  
- Leave things messy when you want
- Navigation always works

Your desktop is a canvas, not a spreadsheet.

## Technical Approach

### Spatial Navigation Algorithm
Winjitsu's navigation system considers:
- Window positions and bounds
- Overlap relationships
- Directional vectors
- Z-order (which window is on top)

The algorithm determines the most intuitive "next window" based on the direction you indicate, even in ambiguous situations.

### Platform Integration
- Built specifically for macOS
- Respects native window behaviors
- Works alongside (not against) Mission Control
- No kernel extensions or system modifications

## Use Cases

### For Developers
- Navigate between code editor, terminal, browser, and documentation
- Handle varying window sizes and arrangements
- Quick access to any tool without breaking flow

### For Designers
- Navigate between design tools, references, and previews
- Flexible layouts for different tasks
- Precise window positioning for multi-monitor setups

### For Power Users
- Keyboard-first workflow across all apps
- Flexible arrangements that adapt to different tasks
- Fast, fluid navigation regardless of layout complexity

## Comparison to Other Window Managers

Unlike traditional tiling window managers (Rectangle, Magnet, Amethyst):
- No forced grid layouts, but still works perfectly with grids
- Works with overlapping windows
- Understands spatial relationships, not just grid positions

Unlike alt-tab or Exposé:
- Maintains spatial context
- Directional navigation instead of list cycling
- Faster for visual thinkers

Unlike pure keyboard launchers (Alfred, Spotlight):
- Navigates existing windows, not just launches apps
- Spatial awareness of your desktop layout
- Integrated with window management, not just app switching

## Status and Availability

Winjitsu is currently under development.

Join the waitlist at: https://winjitsu.app

Features subject to change as the product evolves. Release timeline not guaranteed.

## Privacy and Data

Winjitsu respects your privacy:
- Does NOT collect personal files
- Does NOT capture window content
- Does NOT track keystrokes
- Does NOT monitor app usage

Only collects:
- Email (if you join the waitlist)
- Basic website analytics (when enabled)

See full privacy policy at: https://winjitsu.app/privacy

## Terms

By using Winjitsu or signing up for updates, you agree to the Terms & Conditions at: https://winjitsu.app/terms

Winjitsu is provided "as is" with no warranties. Use at your own risk.

## Technology Stack (Website)

- Next.js 14 (App Router, Static Export)
- React
- Tailwind CSS v4
- Framer Motion (animations)
- SF Pro Display font
- Hosted on Cloudflare Pages

## Contact

Email: contact@winjitsu.app
Website: https://winjitsu.app

## License and Ownership

All content associated with Winjitsu - including the name, logo, website, and software - is owned by Winjitsu and protected by applicable laws.

## Future Features (Planned)

- Customizable keyboard shortcuts
- Saved layouts and presets
- Multi-monitor optimizations
- Plugin system for extensibility
- Window tagging and filtering
- Advanced automation rules

Note: Features subject to change. Not guaranteed for initial release.

## FAQ

**Q: Does Winjitsu force windows into a grid?**
A: No. Winjitsu navigates any layout - tiled, floating, overlapping, or stacked.

**Q: Do I need to disable System Integrity Protection?**
A: No. Winjitsu uses public APIs and requires no system modifications.

**Q: Does it work with Mission Control and Spaces?**
A: Yes. Winjitsu enhances (not replaces) native macOS window management.

**Q: Is it compatible with other window managers?**
A: Winjitsu is designed to work standalone, but compatibility varies.

**Q: What about privacy?**
A: Winjitsu does not read window content, files, or keystrokes. See privacy policy.

**Q: When will it be available?**
A: Currently in development. Join the waitlist for launch notification.

## More Information

Visit https://winjitsu.app for:
- Demo videos
- Detailed feature explanations
- Waitlist signup
- Latest updates

---

Last updated: January 28, 2026
Version: Pre-release documentation