Guide

PolePole won't launch after installing

On first launch, macOS Gatekeeper shows a confirmation dialog for apps obtained from the Internet. What you should do depends on which dialog appears.

"PolePole.app is an application downloaded from the Internet. Are you sure you want to open it?"

Just click Open. This is the normal flow and no System Settings changes are needed. You can launch normally from then on.

"PolePole cannot be opened because the developer cannot be verified."

Occasionally this stricter dialog appears. Allow it as follows:

1. Click Cancel in the dialog (do not move it to Trash).
2. Open System Settings → Privacy & Security.
3. Scroll down and you'll see "'PolePole' was blocked because it is not from an identified developer." Click Open Anyway next to it and authenticate with Touch ID or your password.
4. Launch PolePole again from Finder and click Open in the dialog that appears.

You can launch normally by double-click from then on.

How do I apply a purchased license to the app?

After purchase, the order completion page and the confirmation email contain your email address and license key. Use them to activate as follows:

1. Launch PolePole.
2. Open PolePole → Settings… from the menu bar (or ⌘ + ,).
3. Select the License tab at the top.
4. Enter the email address and license key from your purchase, then click Activate.

Once activated, the trial limitation is removed and you can use PolePole under the Lifetime License.

Up to 3 devices per license

One license can activate up to 3 devices. If you try to activate a 4th device while all 3 slots are taken, you'll see a screen to choose which existing device to deactivate.

If you didn't receive or lost your license key

Send us your purchase email address via the contact form and we'll resend it.

How do I update PolePole to the latest version?

When a new version is released, PolePole automatically notifies you and updates itself via Sparkle. To check manually:

Check from inside the app

Choose PolePole → Check for Updates… from the menu bar. If an update is available, it'll download and apply after a restart.

All major version updates are free (Lifetime License).

Are my Ghostty settings (font, theme, keybindings) applied?

Yes. PolePole's built-in terminal is powered by libghostty and reads your existing ~/.config/ghostty/config as-is.

• If the config file exists: your font, theme, keybindings, etc. are applied.
• If the config file does not exist: the defaults bundled with PolePole are used.

After changing the config, open a new terminal tab or restart PolePole to reflect the changes.

Note: a few keybindings essential to PolePole (project switching, full-text search, etc.) are handled by the app first, so they win even if you bind the same keys in Ghostty config.

Are Claude / Codex bundled with PolePole?

No. PolePole does not bundle Claude Code (Anthropic) or Codex CLI (OpenAI). You launch them from the terminal as usual.

Install each AI tool separately, following their official docs. Once installed, run claude or codex in PolePole's terminal to start them.

PolePole automatically detects which AI tool is running by process name and shows an icon on the tab and a completion notification when the AI's turn ends.

No notification (sound or badge) when Claude / Codex finishes its turn

PolePole detects when Claude or Codex finishes thinking and is waiting for your input, and notifies you with a sound plus a red unread badge on the sidebar / tab. If it's not working as expected, check the following in order.

Sound plays but no badge appears

This is by design. If the AI finishes in the tab you're currently viewing, no badge is shown (you're assumed to have noticed already). Badges appear when the AI completes in a tab or project you're not currently viewing.

Neither sound nor badge appears

1. macOS sound settings: In System Settings → Sound, confirm that "Play user interface sound effects" is on, and that Focus mode (Do Not Disturb / Work) is off.
2. Claude / Codex version: Completion detection relies on the progress sequence (OSC 9;4) emitted by the AI tool. Older versions may not emit this — update to the latest version.
3. How Claude / Codex was installed: PolePole identifies the AI by process name. If you installed it via npm install -g, the actual process may be node and PolePole may fail to identify it. Run file $(which claude) in your terminal — if it does not report Mach-O ... executable (a native binary), switch to a native distribution (official native build, Homebrew, etc.) and the notification should start working. The same applies to codex.

If none of the above resolves it

Please contact us and attach the log file (see "Where logs and data are stored" below).

Where logs and data are stored

PolePole stores local data in the following locations. Attaching the log file when contacting support helps us help you faster.

• Logs: ~/Library/Logs/polepole/polepole-YYYY-MM-DD.log (rotated daily, up to 7 days retained)
• Pinned project list: ~/Library/Application Support/polepole/projects.json
• Shortcut settings: ~/Library/Application Support/polepole/shortcuts.json
• License & trial info: macOS Keychain (and ~/Library/Application Support/polepole/token.json / trial.json)
• Clipboard preview cache: ~/Library/Caches/polepole/clipboard/

All of these are stored locally only and never sent to external servers. See our Privacy Policy for details.

Removing all data on uninstall

After removing the app (brew uninstall --cask polepole or moving to Trash from Finder), manually delete the directories listed above. License info stored in the Keychain can be removed from the Keychain Access app by searching for polepole.