Troubleshooting

Panel Not Appearing

If the AirTower panel doesn't appear when you click the menu bar icon:

• Check that AirTower has Accessibility permissions in System Settings > Privacy & Security > Accessibility
• Try quitting and relaunching AirTower
• Make sure your terminal window is focused and visible
• Check if another app is blocking the panel's position

Git Status Not Updating

If the git status appears stale or doesn't update:

• Verify you're in a git repository (check for a .git folder)
• Ensure git is installed and available in your PATH
• Check if the poll_interval in .airtower.json is set too high
• Try clicking the refresh button in the panel (if available)

You can verify git is working by running:

git status

Wrong Repository Detected

AirTower detects the repository based on your terminal's current working directory. If it's showing the wrong repo:

• Make sure your terminal's working directory is correct (run pwd)
• If using tmux or screen, ensure AirTower can detect the active pane
• Close and reopen your terminal window

Permissions Issues

AirTower requires certain permissions to function properly:

• Accessibility — Required to detect the active terminal window
• Full Disk Access — Only needed if your repos are in restricted directories

To grant permissions:

• Open System Settings > Privacy & Security
• Select Accessibility and add AirTower
• If needed, select Full Disk Access and add AirTower
• Restart AirTower after granting permissions

Tests or Builds Not Running

If the test or build buttons don't work:

• Verify your .airtower.json has valid test_command and build_command values
• Make sure your wrapper scripts are executable (chmod +x)
• Check that the scripts exist in your repository root
• Try running the scripts manually to ensure they work

# Check if scripts are executable
ls -la run-tests.sh run-build.sh

# Make them executable if needed
chmod +x run-tests.sh run-build.sh

# Test them manually
./run-tests.sh
./run-build.sh

PLAN.md or BUG.md Not Parsed

If task or bug tracking isn't working:

• Ensure the files are named exactly PLAN.md and BUG.md (case-sensitive)
• Verify they're in the repository root directory
• Check that you're using the correct markdown checkbox format
• Confirm the features are enabled in .airtower.json

Correct task format in PLAN.md:

- [x] Completed task
- [ ] Incomplete task

Correct bug format in BUG.md:

## [x] Bug 1: Fixed bug title
## [ ] Bug 2: Open bug title

High CPU Usage

If AirTower is using too much CPU:

• Increase the poll_interval in .airtower.json (default is 2 seconds)
• Disable features you don't need (submodules, lfs) in large repos
• Check if your repository has an unusually large number of files
• Ensure you're not running resource-intensive git hooks

{
  "poll_interval": 5,
  "features": {
    "submodules": false,
    "lfs": false
  }
}

Panel Positioning Issues

If the panel appears in the wrong position or is partially off-screen:

• Try dragging the panel to reposition it
• Check if you have multiple displays — the panel may be on another screen
• Quit and relaunch AirTower to reset panel position
• Verify Accessibility permissions are granted

Still Having Issues?

If you're still experiencing problems, visit the GitHub Issues page:

• Search existing issues for known solutions
• Open a new issue with details about your setup and the problem
• Include your macOS version, terminal app, and any relevant config files