Reporting Bugs

Thanks for helping make AltWindow better! Here's how to file a useful bug report.

Before you report

Update to the newest build. Grab the latest installer from the Releases page — your issue may already be fixed.
Check existing issues. Search the open issues to see if it's already been reported. If so, add a 👍 or a comment with your details instead of opening a duplicate.

Open the Report a bug form and fill in:

What happened — what went wrong, and what you expected instead.
Steps to reproduce — the exact steps that trigger the problem.
AltWindow build — latest or a versioned release (vX.Y.Z).
macOS version — from → About This Mac. AltWindow requires macOS 15+ on Apple silicon.
Is jq installed? — AltWindow requires jq; check with jq --version.
Logs / screenshots — anything that helps us see the failure.

Won't launch on first run? The bundle is ad-hoc signed (not notarized), so a browser-downloaded app is quarantined and on macOS 15 (Sequoia) Gatekeeper blocks it with a dead-end "Apple could not verify…" dialog (no Open button). Easiest fix — install via the one-liner, which isn't quarantined: curl -fsSL https://github.com/dharmaje/AltWindow-releases/releases/download/latest/install.sh | sh. Already dragged it from the DMG? Clear the quarantine: xattr -dr com.apple.quarantine /Applications/AltWindow.app (or System Settings → Privacy & Security → Open Anyway). The old right-click → Open no longer works on Sequoia.
No companion windows appear? AltWindow renders from Claude Code's hook events — make sure you accepted the hook install on first run, and that jq is installed.

Have an idea instead of a bug? Use the Feature request form.