aerospace-config

# AeroSpace Configuration Assistant

This skill provides comprehensive assistance for configuring AeroSpace, a tiling window manager for macOS. AeroSpace uses TOML for configuration and offers extensive customization for keyboard-driven window management, workspaces, layouts, and window behavior.

## Configuration Location

**Config File:** `/Users/alex/.config/aerospace/aerospace.toml`

Alternative locations: `~/.aerospace.toml`

## Core Principles

### ALWAYS Follow This Workflow

1. **Read Current Config**: Use Read tool to examine existing configuration
2. **Fetch Documentation**: Use WebFetch to get current documentation for the specific feature
3. **Research Thoroughly**: Check multiple doc pages if needed for complex features
4. **Implement Carefully**: Preserve existing config, validate TOML syntax
5. **Explain Clearly**: Document what changed and why
6. **Guide Testing**: Explain how to reload config (`aerospace reload-config`)

### Documentation Strategy

**Never embed documentation text.** Always use WebFetch to retrieve current information from the AeroSpace documentation.

AeroSpace documentation is comprehensive and continuously updated. The configuration system supports many options across window management, keybindings, and layouts.

## Full Configuration Capabilities

AeroSpace supports configuration across these comprehensive areas. For each request, fetch the relevant documentation:

### 1. Getting Started & Overview
- **Installation & Setup**: Initial configuration, first-time setup
  - https://nikitabobko.github.io/AeroSpace/guide
- **Default Config**: Understanding the default configuration
  - https://nikitabobko.github.io/AeroSpace/goodness#default-config

### 2. Keybindings & Modes
- **Key Bindings**: Main mode, custom modes, key syntax
  - https://nikitabobko.github.io/AeroSpace/guide#key-bindings
  - https://nikitabobko.github.io/AeroSpace/guide#binding-modes
- **Key Syntax**: Modifier keys, key names, key combinations
  - https://nikitabobko.github.io/AeroSpace/guide#key-syntax

### 3. Window Management
- **Tree Structure**: Understanding the window tree paradigm
  - https://nikitabobko.github.io/AeroSpace/guide#tree
- **Layouts**: BSP (Binary Space Partitioning), columns, rows, accordion, tiles
  - https://nikitabobko.github.io/AeroSpace/guide#layouts
- **Floating Windows**: Float rules, floating toggle
  - https://nikitabobko.github.io/AeroSpace/guide#floating-windows

### 4. Workspaces & Monitors
- **Workspaces**: Workspace configuration, assignment, switching
  - https://nikitabobko.github.io/AeroSpace/guide#workspaces
- **Multiple Monitors**: Monitor assignment, workspace-to-monitor mapping
  - https://nikitabobko.github.io/AeroSpace/guide#multiple-monitors

### 5. Application-Specific Rules
- **Window Detection Callbacks**: on-window-detected, app-specific behavior
  - https://nikitabobko.github.io/AeroSpace/guide#on-window-detected-callback
- **App Identifiers**: Bundle IDs, window titles for rules

### 6. Visual Appearance
- **Gaps**: Inner gaps, outer gaps, per-workspace gaps
  - https://nikitabobko.github.io/AeroSpace/guide#gaps

### 7. Commands Reference
- **All Commands**: Complete command reference for keybindings and exec
  - https://nikitabobko.github.io/AeroSpace/commands
- **Individual Commands**: (fetch specific command pages as needed)
  - https://nikitabobko.github.io/AeroSpace/commands#focus
  - https://nikitabobko.github.io/AeroSpace/commands#move
  - https://nikitabobko.github.io/AeroSpace/commands#resize
  - https://nikitabobko.github.io/AeroSpace/commands#workspace
  - https://nikitabobko.github.io/AeroSpace/commands#move-node-to-workspace
  - https://nikitabobko.github.io/AeroSpace/commands#layout
  - https://nikitabobko.github.io/AeroSpace/commands#split
  - https://nikitabobko.github.io/AeroSpace/commands#join-with
  - https://nikitabobko.github.io/AeroSpace/commands#flatten-workspace-tree
  - https://nikitabobko.github.io/AeroSpace/commands#exec-and-forget
  - https://nikitabobko.github.io/AeroSpace/commands#mode
  - https://nikitabobko.github.io/AeroSpace/commands#reload-config

### 8. Configuration Options
- **TOML Configuration**: Full config reference
  - https://nikitabobko.github.io/AeroSpace/guide#config-syntax
- **Config Options Reference**: All available configuration options
  - https://nikitabobko.github.io/AeroSpace/config-reference

### 9. Advanced Features
- **Exec Commands**: Running shell commands, exec-and-forget
  - https://nikitabobko.github.io/AeroSpace/commands#exec-and-forget
- **Focus Behavior**: Focus follows window, mouse handling
- **Normalization**: Container normalization options

### 10. Troubleshooting & Debugging
- **Troubleshooting Guide**: Common issues, debugging
  - https://nikitabobko.github.io/AeroSpace/guide#troubleshooting
- **Config Validation**: Checking config syntax
- **Logs & Debugging**: Finding logs, debug information

## Configuration File Structure

AeroSpace configs use TOML format:

```toml
# Start AeroSpace at login
start-at-login = true

# Gaps between windows
[gaps]
inner.horizontal = 10
inner.vertical = 10
outer.left = 10
outer.bottom = 10
outer.top = 10
outer.right = 10

# Main mode keybindings
[mode.main.binding]
alt-h = 'focus left'
alt-j = 'focus down'
alt-k = 'focus up'
alt-l = 'focus right'

# Workspace keybindings
alt-1 = 'workspace 1'
alt-2 = 'workspace 2'

# Move windows to workspaces
alt-shift-1 = 'move-node-to-workspace 1'
alt-shift-2 = 'move-node-to-workspace 2'

# Layout commands
alt-slash = 'layout tiles horizontal vertical'
alt-comma = 'layout accordion horizontal vertical'

# Window detection callbacks
[[on-window-detected]]
if.app-id = 'com.apple.finder'
run = 'layout floating'
```

## Research Process for Each Request

When user requests any configuration change:

1. **Identify Category**: Determine which configuration area(s) are involved
2. **Fetch Core Docs**: Get main documentation page for that category
3. **Fetch Specifics**: If needed, get specific command reference or examples
4. **Check Commands**: If keybinding involves commands, fetch command documentation
5. **Verify Syntax**: Check TOML syntax and available options
6. **Cross-Reference**: Look at related features that might enhance the solution

## Implementation Guidelines

### Code Quality
- Use clear section organization and comments
- Follow TOML best practices
- Validate syntax before suggesting
- Use consistent indentation

### Config Organization
- Group related settings together (gaps, keybindings, rules)
- Add section comments for clarity
- Preserve user's existing organizational structure
- Keep keybindings logically grouped by function

### Error Prevention
- Check for config file existence before editing
- Validate that TOML syntax is correct
- Ensure keybinding commands exist
- Verify app bundle IDs for window rules

### User Guidance
- Explain what each change does
- Link to relevant documentation pages
- Suggest how to test changes (`aerospace reload-config`)
- Offer related enhancements when appropriate
- Mention keyboard shortcuts in clear format (alt-shift-1)

## Common Tasks Quick Reference

### Testing Changes
```bash
aerospace reload-config
```

### Finding App Bundle IDs

**Method 1: Using osascript (preferred for known app names)**
```bash
osascript -e 'id of app "AppName"'
```
Example:
```bash
osascript -e 'id of app "Finder"'
# Returns: com.apple.finder
```

**Method 2: List all running apps**
```bash
aerospace list-apps
```

**Method 3: Using mdls on the app bundle**
```bash
mdls -name kMDItemCFBundleIdentifier /Applications/AppName.app
```

### Listing Windows

**List all windows:**
```bash
aerospace list-windows --all
```

**List windows in specific workspace:**
```bash
aerospace list-windows --workspace TER
```

**List windows as JSON (for detailed analysis):**
```bash
aerospace list-windows --all --json
```

**Filter windows by app (example for Ghostty):**
```bash
aerospace list-windows --all --json | python3 -c "import json,sys; data=json.load(sys.stdin); filtered=[w for w in data if 'AppName' in w.get('app-name','')]; print(json.dumps(filtered, indent=2))"
```

**List active workspaces:**
```bash
aerospace list-workspaces --monitor all --empty no
```

## Debugging & Log Inspection

When troubleshooting issues (window resizing, layout problems, unexpected behavior), use these debugging techniques:

### Check if AeroSpace is Running
```bash
pgrep -l AeroSpace && echo "AeroSpace is running" || echo "AeroSpace is NOT running"
```

### View System Logs

AeroSpace logs to the macOS unified logging system. Use the `log` command to retrieve logs:

**Get recent AeroSpace logs (last 30 minutes):**
```bash
/usr/bin/log show --predicate 'processImagePath CONTAINS "AeroSpace"' --last 30m --info --debug | tail -200
```

**Get logs for specific time period:**
```bash
/usr/bin/log show --predicate 'processImagePath CONTAINS "AeroSpace"' --last 10m --style compact
```

**Stream live logs (useful during testing):**
```bash
/usr/bin/log stream --predicate 'processImagePath CONTAINS "AeroSpace"' --style compact
```

Note: Use `/usr/bin/log` with full path to avoid shell interpretation issues.

### Debug Windows Session

To debug a specific problematic window:

1. Start debug session:
```bash
aerospace debug-windows
```

2. Focus the problematic window

3. Run the command again to get results:
```bash
aerospace debug-windows
```

### Common Debugging Scenarios

**Window not floating/tiling as expected:**
1. List windows to see current state: `aerospace list-windows --workspace WORKSPACE_NAME --json`
2. Check if on-window-detected rule is correct
3. Note: Rules only apply to NEW windows - existing windows keep their state

**Layout issues after config change:**
1. Reload config: `aerospace reload-config`
2. Close and reopen the problematic app for new rules to apply
3. Check logs for any errors

**App windows behaving unexpectedly:**
1. Verify app bundle ID: `osascript -e 'id of app "AppName"'`
2. List all windows from that app to see how AeroSpace perceives them
3. Some apps (like Ghostty) report tabs as separate windows - this is a known macOS limitation

### Debug Mode
```bash
aerospace enable-debug-mode
```

## Remember

- **Never paste documentation** - always use WebFetch
- **Always read config first** - understand existing setup
- **Research thoroughly** - fetch multiple doc pages if needed
- **Explain clearly** - user should understand the changes
- **Link resources** - provide documentation URLs for reference
- **Test guidance** - explain how to verify changes work

AeroSpace is actively developed. When in doubt, fetch the documentation.