Save and restore window positions across displays
Perfect for switching between different monitor setups (home vs office, docked vs undocked)
brew tap riyasyash/tools
brew install nishkuFeatures • Installation • Usage • Documentation • Contributing
Nishku is a command-line tool that captures and restores window positions and sizes on macOS. It's designed for people who frequently switch between different monitor configurations and want their window layouts to adapt automatically.
- 🏠 Home/Office Setup: Different monitor configs? No problem.
- 💻 Docked/Undocked: Seamlessly switch between laptop-only and multi-monitor.
- 🎯 Smart Adaptation: Windows automatically adapt when displays change.
- ⚡ Fast & Light: Single binary, no runtime dependencies.
- 💾 Save window layouts as named profiles
- 🔄 Restore layouts instantly with one command
- 🖥️ Multi-display support with automatic adaptation
- 🎯 Smart window matching - handles multiple windows per app
- 📐 Position + Size - captures both location and dimensions
- 🔒 Secure & Private - local storage only, no network access
- Hybrid Matching: Works with apps that have multiple windows (Chrome, iTerm2, VS Code)
- Display Adaptation: Automatically adjusts when monitors are disconnected
- Bounds Checking: Ensures windows stay visible on screen
- Built-in Diagnostics:
nishku doctorchecks your setup
The easiest way to install nishku on macOS:
brew tap riyasyash/tools
brew install nishkuDownload the latest release from GitHub Releases:
# Apple Silicon (M1/M2/M3)
curl -L https://github.com/riyasyash/nishku/releases/latest/download/nishku-darwin-arm64.tar.gz | tar xz
sudo mv nishku /usr/local/bin/
# Intel Mac
curl -L https://github.com/riyasyash/nishku/releases/latest/download/nishku-darwin-amd64.tar.gz | tar xz
sudo mv nishku /usr/local/bin/go install github.com/riyasyash/nishku@latest# Clone the repository
git clone https://github.com/riyasyash/nishku
cd nishku
# Build and install
make build
sudo make install
# Verify installation
nishku version- macOS 10.14 (Mojave) or later
- ~5MB disk space
- Accessibility permissions (one-time setup)
brew tap riyasyash/tools
brew install nishkunishku doctorThis will show your current status and guide you through any required setup.
To move windows, nishku needs accessibility permissions:
- Open System Settings → Privacy & Security → Accessibility
- Click the 🔒 lock icon and authenticate
- Click the + button
- Add your terminal app (Terminal.app, iTerm.app, etc.)
- Enable the checkbox ✓
- Restart your terminal
# Save current window positions
nishku save work-setup# Restore to saved layout
nishku load work-setup# Save current window layout
nishku save <profile-name>
# Restore window layout
nishku load <profile-name>
# List all profiles
nishku list
# Delete a profile
nishku delete <profile-name>
# Check setup and permissions
nishku doctor
# Show version
nishku version# At the office with dual monitors
nishku save office-dual-monitor
# At home with laptop only
nishku save home-laptop
# Switching between setups
nishku load office-dual-monitor # When at office
nishku load home-laptop # When at homeNishku uses a hybrid approach to match windows:
- Groups windows by application (e.g., all Chrome windows)
- Sorts by screen position (top-to-bottom, left-to-right)
- Assigns indices for reliable matching
- Matches on restore by app + window index
This means:
- ✓ Works with multiple windows per app
- ✓ Handles dynamic window titles (browser tabs, document names)
- ✓ Gracefully skips windows if app isn't running
When your display configuration changes:
- Stores both absolute and relative positions
- Adapts automatically if displays are missing
- Ensures visibility - windows never go off-screen
- Silent operation - no prompts or warnings needed
Example: Profile saved with 2 monitors, restored with 1 monitor:
- Windows from Display 1 → Restored to same position
- Windows from Display 2 → Moved to primary display (equivalent relative position)
- TESTING.md - Testing guide and troubleshooting
- SECURITY.md - Security considerations
- CHANGELOG.md - Version history
| Platform | Status | Notes |
|---|---|---|
| macOS (Apple Silicon) | ✅ Supported | arm64 |
| macOS (Intel) | ✅ Supported | amd64 |
| Linux | 🚧 Planned | X11/Wayland support coming |
| Windows | 🚧 Planned | Win32 API support coming |
- Requires accessibility permissions (macOS security requirement)
- Apps must be running before restore (doesn't launch apps)
- Minimized windows may not restore correctly
- Full-screen windows may exit full-screen when restored
- Some system apps don't support Accessibility API
Run nishku doctor and follow the permission instructions. Make sure to restart your terminal after granting permissions.
This is normal when:
- Profile has more windows than currently open
- App isn't running
- Window index doesn't exist
- Check permissions:
nishku doctor - Verify app is running
- Try with a single-window app first
- See TESTING.md for detailed troubleshooting
# Build for current platform
make build
# Build for all platforms
make build-all
# Run tests
make test
# Format code
make fmt# Build with version
VERSION=v0.0.1 make build
# Check version
./nishku version --verboseContributions are welcome! Please feel free to submit issues or pull requests.
- 🐧 Linux support (X11/Wayland)
- 🪟 Windows support (Win32 API)
- 🧪 Testing and bug reports
- 📚 Documentation improvements
- ✨ Feature suggestions
git clone https://github.com/riyasyash/nishku
cd nishku
make deps
make build
./nishku doctorMIT License - see LICENSE file for details.
Created by Riyas Yash
- 📫 Issues
- 💬 Discussions
- ⭐ Star this repo if you find it useful!
Made with ❤️ for productivity enthusiasts