Troubleshooting

The sidebar doesn't appear.

• Is Claude or Codex the frontmost app?
• Is the app's own sidebar collapsed, or the window too narrow for one? Then Pairbar shows only its round button (so it doesn't cover the chat): click it, press ⌃⌥S, choose Show or hide Pairbar in the menu bar, or open Pairbar from Spotlight, and the sidebar shows over the app until you hide it again.
• Did you collapse Pairbar? Press ⌃⌥S, or open Pairbar from Spotlight.
• On another Space or with the app in full screen, the sidebar moves there with the app's window.

Claude's or Codex's own sidebar is gone after Pairbar quit or crashed. Pairbar hides the apps' own sidebars in the basket and gives them back when you go back to Overlay or quit Pairbar (including an update's relaunch and logging out). If Pairbar crashed or was force-quit while docked, the next launch gives them back, or, when it docks the basket again, keeps them hidden and gives them back when you leave it. It never presses Codex's toggle for a Codex that was restarted meanwhile (it can't tell which way that would go): press ⌘B in Codex, or its View → Toggle Sidebar.

The basket came back by itself after a restart. Pairbar remembers that Claude and Codex were docked, and docks them again at launch once both windows are open (where the basket was last on these displays). Choose Overlay to leave it; that's remembered too.

Dictation doesn't hear me, or the words go somewhere else. See Voice dictation → When things go wrong: the microphone permission (Settings → Voice → Microphone), the input level in System Settings → Sound, where the words go (Settings → Voice → Setup → Insert text into), and Accessibility for typing into Claude or Codex. The shortcut doesn't work if another app already uses ⌃⌥Space: pick another in Settings → Shortcuts → Dictate.

Pairbar says the trial has ended, or shows the lock screen. Subscribe or paste your licence key there (see Trial, licence and updates). Reinstalling or deleting preferences doesn't restart the trial.

"Subscription ended — renew to keep using Pairbar". Your yearly or monthly subscription was cancelled or its payment couldn't be taken (a Lifetime licence never ends). Pairbar keeps working until the date shown, then locks. Renew (a new subscription comes with a new key: paste it), or fix the payment in Manage subscription… and press Renewed? Check again.

"Couldn't reach the licence server". Activation and the checks (at launch and weekly) talk to api.lemonsqueezy.com. A firewall, VPN or content blocker that stops it makes activation fail; the weekly check failing only matters after three weeks.

"This key is already active on … Macs". Open Settings → Licence on a Mac you no longer use and choose Deactivate this Mac…. If that Mac is gone, email support.

"Can't check for updates". A build made from source (not the downloaded app) has no update feed. Download the app from the website.

A layout doesn't move a window, or it lands a bit off. A window in full screen, on another Space or minimised is left alone, and Pairbar says so under the search field. An app that won't get as small as the layout asks keeps its own minimum size, and the other window takes what's left. With Stage Manager on, it may move one window into its own stage. See Window layouts → Limits.

Moving one app moves the other too. They're in the basket: they move as one window. Switch to Overlay (the layout menu, the basket's pill, its red button, or ⌘K "Overlay").

Docking doesn't glide. Check Settings → Windows → Animate the basket and swaps, and that Reduce Motion is off. Allowing Screen Recording (optional) makes it smoother.

Switching to the other app puts its window somewhere else. Allow Accessibility in System Settings → Privacy & Security → Accessibility (called Device Control and Data Access on newer macOS). The sidebar's Allow Accessibility banner and Settings → General → Permissions both lead there.

System Settings shows Pairbar switched on, but Pairbar still asks for Accessibility. macOS ties the permission to the copy of Pairbar that got it. After an update (or any new copy of the app) the switch can stay on while macOS answers "no" to the new copy: a stale permission. Pairbar remembers that Accessibility worked before, so instead of the plain ask its banner says Accessibility needs a refresh: "macOS still lists Pairbar as allowed, but the permission went stale after an update." To fix it:

1. Click Open Accessibility Settings in the banner (or Open Settings… in Settings → General → Permissions).
2. Turn Pairbar off and on again in the list. If that doesn't do it, select Pairbar, remove it with −, then allow it again.
3. The banner goes by itself the moment macOS says yes: Pairbar checks twice a second while it's off. If it doesn't, click Restart Pairbar: some changes apply only to a fresh launch.

The same banner reads Accessibility stopped working when it worked in this very copy and stopped (turned off, or changed while Pairbar was running), and Allow Accessibility with the same buttons once you've asked and it isn't on yet. Not now hides it until Accessibility works again.

Screen Recording is on in System Settings, but Pairbar says Off. macOS applies a new Screen Recording permission only to a fresh launch, and an update can leave a stale one behind as for Accessibility. Once you've asked (Settings → General → Permissions, or Settings → Voice → Setup → Find Claude's message box), the row shows Open Settings… and Restart Pairbar instead of Allow…, with a line saying which case it is. Turn Pairbar on (or off and on, or remove it with − and allow again), then click Restart Pairbar. The rows re-check every couple of seconds while Settings is open.

The microphone is on in System Settings, but dictation says it's off. Settings → Voice → Setup → Microphone re-checks every couple of seconds while it's open and when you come back to Pairbar. After an update macOS may ask again on your next dictation; if it says Off while the switch is on, turn Pairbar off and on in Privacy & Security → Microphone.

No notification banners, and "Allow…" doesn't show a prompt. macOS asks for notifications only once. After that, Pairbar's button reads Open Settings… and opens System Settings → Notifications → Pairbar: turn on "Allow notifications" there. A copy of Pairbar that isn't in Applications (for example one run from a build or temporary folder) may not be allowed to notify at all; move it to Applications.

A chat shows Working while it waits for me to allow a command. Turn on live status for the exact, instant answer. Without it, Pairbar learns about a shell command's permission prompt from the record Claude Code keeps in ~/.claude/sessions while the chat runs. An older Claude Code doesn't write one: update Claude, or check that ~/.claude/sessions has a file for the chat's process. Codex's approval prompts aren't in its files, so without live status for Codex a Codex thread waiting for approval shows Working. See How the status is worked out.

Live status says "No events received yet from the Claude app". Claude reads its hooks when a chat starts: send a message in a chat, or quit and reopen Claude. Hooks don't run in a folder Claude doesn't trust yet, in cloud chats, or when Claude's settings have "disableAllHooks": true (Settings says so). Until events come, status comes from the files as before. See Integrations.

Live status says "Needs repair". Pairbar's hooks in ~/.claude/settings.json point at a Pairbar that was moved or renamed (for example from Downloads to Applications). Press Repair in Settings → Integrations; your own hooks aren't touched.

Live status says "Can't read settings". ~/.claude/settings.json isn't valid JSON, or its "hooks" isn't in the shape Claude expects; the reason is shown. Pairbar never writes to a file like that. Fix it (or undo your last edit to it), then press Install… again. Earlier copies Pairbar made are in ~/.pairbar/backups.

Live status for Codex says "No events received yet from Codex". Codex runs a new hook only after you trust it: in Codex, type /hooks and trust Pairbar's (Settings → Integrations says how many Codex trusts so far). Then start a new chat, or quit and reopen Codex: it reads its hooks when a chat starts. Codex runs no hooks when its config has hooks = false under [features] (Settings says so). See Integrations.

Live status for Codex says "Needs repair". The link ~/.pairbar/bin/pairbar points at a Pairbar that was moved or renamed, or some of Pairbar's entries are missing. Press Repair in Settings → Integrations. Fixing the link doesn't change Codex's config, so Codex doesn't ask you to trust the hooks again.

Live status for Codex says "Can't read settings". ~/.codex/config.toml isn't valid TOML (the line is shown), writes its hooks inline (hooks = { … } or Stop = [ … ]), or Pairbar's block was edited or moved by hand. Pairbar never writes to a file like that. Fix it (or undo your last edit to it), then press Install… again. Earlier copies Pairbar made are in ~/.pairbar/backups (only you can read them: they hold the whole file, keys included).

A chat doesn't have Pairbar's tools. Start a new chat after installing: the apps load plugins when a chat starts. In Claude, /mcp should list plugin:pairbar:pairbar as connected (a folder Claude doesn't trust yet loads no plugins); in Codex, pairbar:guide should be in the skills. If Settings says Needs repair (you moved Pairbar, or the app's plugin list lost it), press Repair. See Pairbar's tools.

A chat says Pairbar isn't running. Open Pairbar (it lives in the menu bar). With Start Pairbar when an agent needs it on (Settings → Integrations), a tool call opens it by itself.

A chat says not_allowed when it lists chats. It asked for chats in another project. A chat sees only its own project's chats and tasks unless you turn on Agents can see chats in other projects in Settings → Integrations.

Claude asks for permission before every Pairbar tool. That's Claude's own question, asked for any MCP tool. Add mcp__plugin_pairbar_pairbar__* to Claude's allowed tools (Settings → Integrations → How it works has it, with Copy). Allowing them only lets a chat ask: agent actions still run only as your Agent actions settings allow or after you approve them in Pairbar.

A chat says its request was refused (paused_by_user, turned_off, limited, too_deep, no_escalation). Pairbar refused an agent action: agent actions are paused, that kind is Off, a budget or the plan you keep for yourself is used up, you declined three of the chat's requests in 10 minutes, it asked for the same thing twice, it's a helper asking for more than a helper may, or it asked for more access than it has itself. The chat is told why and carries on. See Guardrails and budgets; the settings are in Settings → Integrations → Agent actions.

An agent's request never started. It's waiting for you at the top of the chat list (or on its notification), and expires after an hour. If you approved it and the helper failed, Agent activity says why (for example, the app's command-line tool isn't installed, or Pairbar quit while it ran).

Codex warns about "loading hooks from both" files. Codex found hooks in both ~/.codex/hooks.json and ~/.codex/config.toml. Pairbar puts its own where yours already are, so this only happens when yours are in both: move them into one file.

Pairbar can't receive events. Another copy of Pairbar is already running and listening (quit it), or ~/.pairbar/run isn't a private folder of yours (remove it; Pairbar makes it again at launch).

A chat stopped showing Needs you although I haven't answered. With Claude's record, a chat stops needing you when its Claude process ends (the app was quit, or the chat was closed): the question can't be answered any more. Without the record (Codex, an older Claude), a chat needs you for up to 7 days.

Codex chats are missing. Pairbar reads Codex's database (~/.codex/state_<n>.sqlite). It adapts to schema changes and waits when Codex is mid-write, but a very different Codex version may need a Pairbar update. Please email support with your Codex version.

A Claude cloud session isn't listed. Pairbar finds cloud sessions in the Claude app's own copy of its Code sessions list. Open Code in the Claude app once so it loads the list; the row appears within a few seconds. Sessions archived in Claude are left out. If the Claude app changed how it stores that copy, cloud sessions are left out until Pairbar is updated (local chats are unaffected).

Codex cloud tasks aren't listed. They come from codex cloud list, run at most every 5 minutes while the sidebar is showing. Check that codex is installed and logged in (codex cloud list in a terminal should list them).

Plan limits show "Checking…" or "needs the Claude Code command-line tool". Install claude (see the link in the card). The limits are read with claude -p /usage.

A fork, message or workflow fails. The notice under the search field has Details with the tool's full output. Common causes:

• The CLI isn't logged in.
• The folder no longer exists.
• A permission prompt: headless runs can't ask, so use "Can run commands" on steps that must run tests or gh, and "Can edit files" on steps that need to change things.

My regular Claude chats aren't listed. Pairbar lists Claude Code and Codex chats. Hold ⌥ to peek at Claude's own sidebar for the rest.

Search inside conversations finds nothing at first. The text cache builds in the background about 20 seconds after launch. Try again in a moment.

Something else. Settings → About & advanced → Reset Pairbar… restores defaults without touching your chats or agents. For developers, defaults write <bundle id> pairbarDebug -bool true enables a debug log at $TMPDIR/pairbar-debug.log and the scripts/pairbarctl remote. Still stuck? Contact support (below).

Contact support#

Email support@pairbar.com: it's the one official support channel, and you'll usually get a reply within 2 business days (not a guarantee: Pairbar is made by one person). The easiest way is Contact support… in Settings → About & advanced, Contact Support… in the menu-bar icon's menu, or ⌘K Contact support / Report a problem. A small window shows exactly what the email will contain:

• Pairbar's version and build, the macOS version, the Claude and Codex desktop apps' versions, and your plan (trial, Monthly, Yearly or Lifetime). Never your licence key or email.
• Include diagnostics (off until you tick it) adds the last 200 lines of Pairbar's debug log, cleaned first: keys, tokens and passwords become [redacted], your home folder becomes ~, other folders under /Users lose the user's name, and quoted text longer than a few words (which could come from a chat) becomes "[text]". The log only has lines if the debug setting is on (above); turn it on, reproduce the problem, then contact support.

Email support… opens a draft in your mail app with that text, and Copy copies it (with the address and subject) to paste anywhere. Pairbar never sends anything itself: read the draft, change or delete anything, describe what happened at the top, and send it from your mail app. Help and refunds opens the support page: troubleshooting, known issues, refunds, licence help and how to report a security issue (privately, to security@pairbar.com: see SECURITY.md).

Codex says “This is open in another app”#

A background CLI turn owns that thread while it runs. Opening it in the desktop cannot transfer that running turn. Let it finish, then press Retry in Codex. Pairbar does not stop or fork an existing task to clear the lock.

New local chats, handoffs and forks opened from Pairbar use a native Codex draft. Review its settings and press Send in Codex; the desktop owns that turn and its composer stays available. Background workflow tasks still run through the CLI.

Notes capture (Coming Soon)#

Capture (Coming Soon) should show a selection overlay immediately. If macOS requests Screen Recording access, grant Pairbar access in System Settings and try again. Esc returns to Notes without creating a note. Hover highlights an available element; clicking or dragging selects it and opens a focused comment card. Save or ⌘Return saves the screenshot (Coming Soon) and comment together; Return adds a line. Without Accessibility geometry, a click selects the clearly labeled visible window. DOM (Coming Soon) selectors and CSS require the optional Chromium extension; native Capture (Coming Soon) and the embedded Codex browser do not supply DOM (Coming Soon) data. See Notes.