ADE Guide
Guide

Troubleshooting

Fixes for the problems people run into most.

macOS says the app is damaged

Builds downloaded directly from GitHub aren’t notarized yet, so macOS quarantines them. Clear the flag once:

xattr -cr "/Applications/Better Terminal.app"

Installing with Homebrew (brew install --cask alvin-reyes/tap/ade) does this for you.

A shortcut types into my shell instead (Linux)

App shortcuts on Linux use Ctrl+Shift (and Ctrl+Alt+Shift), not plain Ctrl. For example, a new tab is Ctrl+Shift+T, while Ctrl+T goes to the shell. See Keyboard shortcuts.

A file path in the terminal isn’t clickable

  • The file has to exist. Links appear once the agent has written the file.
  • Relative paths resolve against the terminal’s current folder. If you cd elsewhere afterwards, older relative paths may point at the wrong place.
  • Hover the path for a moment; links are detected as the pointer moves over a line.

The app won’t start on Linux

The .deb and AppImage need WebKitGTK 4.1. On Debian and Ubuntu:

sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0

Sync fails

  • “git push failed” / authentication errors: ADE runs git non-interactively. Make sure git push to the repo works from a terminal without a password prompt: an SSH key in your agent, or a configured credential helper.
  • “Unsupported git remote”: use an https://, ssh:// or git@host:path URL.
  • A .sync-conflict file appeared in ~/.claude, the file was changed on two machines. Merge the two versions and delete the conflict file.

Start over with a clean state

Quit ADE and move its data folder aside (see the paths in Auto-save & sync). To go back to an earlier state instead, restore a snapshot.

Report a bug

Contact support through the website with your OS, the ADE version and the steps to reproduce.