services-guide - SKILL.md Agent Skill

name: services-guide description: System services configuration guide including AeroSpace, JankyBorders, and AltTab on macOS

Services Configuration

This document provides information about the macOS window-management stack configured in this repository: AeroSpace, JankyBorders, and AltTab.

Note: This guide is specific to macOS (darwin). For NixOS window management, see /hyprland-cheatsheet and /nixos-keybindings.

Stack Overview

AeroSpace manages tiling, workspaces, and keybindings
JankyBorders highlights the focused window
AltTab provides a macOS app/window switcher with previews

Installation and Setup

Packages are managed via Homebrew in darwin/homebrew/default.nix:

nikitabobko/tap/aerospace
FelixKratz/formulae/borders
alt-tab

User configuration is managed via Home Manager:

darwin/home-manager/aerospace/aerospace.toml
darwin/home-manager/borders/bordersrc

Apply changes with:

make home-manager-apply
make nix-darwin-apply

AeroSpace

Runtime config: ~/.aerospace.toml
Source of truth in this repo: darwin/home-manager/aerospace/aerospace.toml

Current Behavior

Starts automatically at login
Uses US keyboard key names such as /, ,, ;, -, =
Default layout is tiles
alt + f is not native fullscreen; it switches the current workspace into an accordion-style focused view

Daily Usage

Use AeroSpace with these mental models:

alt + / returns the current container to normal tiling
alt + , switches to accordion layout
alt + f is a stable pseudo-fullscreen inside AeroSpace, not macOS native fullscreen
alt + shift + f toggles the focused window between floating and tiling
alt + ; enters service mode for less common operations

Common flows:

Make one window effectively dominant: alt + f
Return from pseudo-fullscreen to tiling: alt + /
Clean up a messy workspace tree: alt + ;, then r
Move a window to another workspace and follow it: alt + shift + 1..9
Jump back to the previous workspace: alt + tab
Use real macOS fullscreen: alt + ;, then shift + f

Keyboard Shortcuts

Below are the primary shortcuts configured for AeroSpace in this repo.

Window Navigation

Shortcut	Action
`alt + h`	Focus left
`alt + j`	Focus down
`alt + k`	Focus up
`alt + l`	Focus right

Window Movement

Shortcut	Action
`alt + shift + h`	Move window left
`alt + shift + j`	Move window down
`alt + shift + k`	Move window up
`alt + shift + l`	Move window right

Workspaces

Shortcut	Action
`alt + 1..9`	Switch to workspace 1..9
`alt + shift + 1..9`	Move window to workspace 1..9 and follow it
`alt + tab`	Toggle between recent workspaces

Layout and Resize

Shortcut	Action
`alt + /`	Switch current container to tiles layout
`alt + ,`	Switch current container to accordion layout
`alt + f`	Flatten workspace tree and emphasize the focused window in accordion layout
`alt + shift + f`	Toggle floating / tiling
`alt + enter`	Open Ghostty
`alt + r`	Enter resize mode
`alt + ;`	Enter service mode

Resize Mode

Shortcut	Action
`h` / `l`	Resize width
`j` / `k`	Resize height
`shift + h/j/k/l`	Fine-grained resize
`esc`	Return to main mode

Service Mode

Shortcut	Action
`esc`	Reload config and return to main mode
`r`	Flatten workspace tree
`f`	Toggle floating / tiling
`shift + f`	Toggle macOS native fullscreen
`backspace`	Close all windows except current
`arrow keys`	Join with adjacent container

Fullscreen and Layout Notes

alt + f is the recommended "focus one window" shortcut in this setup
alt + f is intentionally implemented without AeroSpace fullscreen, because AeroSpace fullscreen can collapse when focus changes across workspaces
To go back to ordinary tiling after alt + f, press alt + /
To use true macOS fullscreen, enter service mode with alt + ; and press shift + f
If a workspace feels structurally odd, run alt + ; then r, and then choose alt + / or alt + , again

Startup and Reload

This configuration enables automatic startup at login:

start-at-login = true

Typical maintenance flow:

# Apply dotfiles changes
make home-manager-apply
make nix-darwin-apply

# Reload AeroSpace config manually if needed
aerospace reload-config

JankyBorders

Runtime config: ~/.config/borders/bordersrc
Source of truth: darwin/home-manager/borders/bordersrc

Current settings:

rounded borders
width 4.0
HiDPI enabled
pink-ish active color and blue inactive color inspired by the article setup

Manual restart if needed:

pkill borders || true
/opt/homebrew/bin/borders

AltTab

AltTab is installed as a cask and used for app/window switching. Detailed preferences are not repo-managed yet.

Typical first-run steps:

Open AltTab
Grant Accessibility permission
Enable launch at login from AltTab preferences if desired

Troubleshooting

AeroSpace keybindings do not work: Check Accessibility permissions for AeroSpace
aerospace reload-config cannot connect to server: Make sure AeroSpace.app is running, then reopen it if necessary
A window was pseudo-fullscreen and you want tiling back: Press alt + /
A workspace looks split strangely after moving windows around: Press alt + ;, then r, then reapply alt + / or alt + ,
Native fullscreen and AeroSpace layout feel inconsistent: Prefer alt + f for normal use and reserve alt + ; + shift + f for apps that truly need macOS fullscreen
Borders are missing: Restart borders and verify ~/.config/borders/bordersrc
AltTab does not appear: Open the app once manually and grant Accessibility permissions
Config changes do not apply: Run aerospace reload-config; for border changes restart borders

Verification

# Confirm packages are installed
brew list --cask | grep aerospace
brew list --cask | grep alt-tab
brew list --formula | grep borders

# Confirm managed config exists
ls -l ~/.aerospace.toml
ls -l ~/.config/borders/bordersrc

Customization

To customize the setup:

Edit darwin/home-manager/aerospace/aerospace.toml
Edit darwin/home-manager/borders/bordersrc for border style/colors
Run make home-manager-apply
Reload AeroSpace or restart the affected process