Reporting Bugs

Reporting Bugs

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

Before you report

1. Update to the newest build. Grab the latest installer from the Releases page — your issue may already be fixed.
2. 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.

How to report

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.

Common gotchas

• Won't launch on first run? The bundle is ad-hoc signed (no Apple Developer ID), so Gatekeeper blocks it. Right-click → Open the first time to allow it.
• 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.

Feature ideas

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