Troubleshooting
Most problems have a quick fix. If yours isn't here, email support with your OS, PATerminal version (Settings → Updates), and what you tried.
Written for PATerminal v1.8.3
Installing and opening
- Windows: “Windows protected your PC”
- Click More info, then Run anyway. SmartScreen warns about new apps; compare the SHA-256 on the Windows install guide if you want to be sure.
- macOS asks before opening
- Choose Open. The app is signed with a Developer ID and notarized by Apple.
Git shows an error
When something on your computer stops git, PATerminal shows Git can't run on this computer with the fix. The common cases:
| Cause | Fix |
|---|---|
| macOS: Xcode license not accepted (often right after an Xcode update) | sudo xcodebuild -license accept |
| macOS: Command Line Tools missing or broken | xcode-select --install |
| Git not installed | Install it (Windows: winget install Git.Git); PATerminal picks it up automatically. |
| “Dubious ownership” on another drive or network share | git config --global --add safe.directory <path> — only for folders you trust. |
| Windows: path too long | git config --global core.longpaths true |
Pull requests or issues don't load
Make sure gh is installed and signed in (gh auth status), and that the repository has a GitHub remote. Press Retry after fixing it.
A session stays on “Running”
- Something in it is still printing — a dev server, a watcher, or a spinner. That's real output, so the status is correct.
- Codex 0.154.0 or later started before PATerminal saved
tui.whimsy = false: restart that Codex session. An explicit project-level or command-line setting can override it. See Note for Codex users.
No notifications
- Check Settings → Notifications is on.
- Allow notifications for PATerminal in your OS settings, and check Focus / Do Not Disturb.
- Notifications are only sent for sessions you aren't looking at.
A conversation doesn't resume
- The agent may have exited before saving the conversation. Open it from History instead.
- Moving Claude Code to an unrelated folder requires Claude Code v2.1.223 or later.
- Options you passed only on the original command line aren't replayed.
An update fails
If the signed update can't be installed, PATerminal isn't restarted and nothing changes. Try again later, or download the latest installer from the download page and install over the current version — your sessions and settings are kept.
Where is my data?
Sessions, groups, notes, phrases, and settings are stored as local files on your computer; agent conversations stay in the agents' own folders (for example ~/.claude and ~/.codex). Nothing is synced to a server, and PATerminal has no telemetry.
Still stuck?
Check the FAQ, or email us with your OS, PATerminal version, and what you tried. We reply to every message.