Troubleshooting
The short list of things that occasionally go sideways, and what actually fixes them. Not here? Email support@terminalcandy.com — a human (the developer) reads it.
License & trial
“My key isn’t accepted.” Paste it exactly as it appears in the purchase email — keys start with CNDY- (older TJIG- keys remain valid forever). Watch for a trailing space from the copy.
“I reinstalled / wiped my Mac and now it says my trial ended, but I own a license.” Paste your key in Settings → License and it reactivates. Lost the key? Email support from the address you bought with — we’ll resend it.
“Device limit reached.” Email support; limits exist to stop key-sharing, not to inconvenience you between your own Macs.
Agent alerts
The toggle won’t stay on. Terminal Candy checks that the agent is actually set up (its config directory exists). Run the agent once, then toggle again.
Alerts don’t fire for Claude Code. The alert rides Claude Code’s own hook system. If you’ve recently edited ~/.claude/settings.json by hand, toggle the alert off and on in Settings → Alerts to reinstall the hook. If another tool manages your hooks, Terminal Candy wraps it — but a third tool overwriting the file afterward can drop the chain.
Codex/Gemini alerts are delayed a beat. Those agents expose no hooks, so Terminal Candy polls their session logs (~1.5 s). A short delay is normal.
Skins
A skin folder I dropped in doesn’t appear. Check skin.json parses (any JSON linter) and that frame.image matches the actual PNG filename. See the format reference.
Clicks go through my skin / don’t go through. Hit-testing follows the PNG’s alpha channel. Alpha-0 areas pass clicks through; near-invisible-but-opaque pixels catch them. Re-export with a genuinely transparent background.
The terminal doesn’t line up with the screen area. The viewport is defined in logical points (pixels ÷ 2 for an @2x image). If you hand-edited coordinates, verify against frame.width/height.
Skin effects aren’t visible. Effects render only when Settings → General → Skin effects is on, and only for skins that define them.
Hotkeys
⌥Space does nothing. Another app may own the chord (Spotlight replacements are the usual suspects). Remap either side — Terminal Candy’s binding is changeable in Settings → Keys.
A shortcut won’t remap. Assignments are conflict-checked; if a chord is taken by another Terminal Candy action, the assignment is rejected rather than silently stealing it. Free the chord first.
The app itself
Terminal Candy won’t open (“damaged” or unverified). Download the DMG again from terminalcandy.com/download — builds are signed and notarized by Apple; a corrupted download is almost always the cause.
Intel Mac? Not yet — Terminal Candy is Apple-Silicon-only today. An Intel build is in the works; the FAQ has the current status.