Troubleshooting and support

Run Doctor first#

Open Settings then Doctor and press Run checks; it checks every agent's hooks, sign-in, and usage, and flags anything that needs a hook repair or a sign-in, with a one-click repair action. Every launch, AgentPeek also re-checks each agent and quietly reinstalls or repairs a broken hook on its own.

Common issues#

• A session doesn't appear: check Doctor shows that agent as Ready, then start a new session; hooks attach to sessions started after the hook is in place. A banner under the session header with Open Doctor appears when AgentPeek already knows something needs you.
• Jump back raises the wrong window: window-level jump back needs macOS Accessibility access; the host matrix lists each terminal's exact precision.
• A usage number shows --: the value is unavailable or stale; press Refresh usage, and remember AgentPeek never invents a quota an agent doesn't report.
• Codex sessions aren't tracked: depending on your Codex version, hooks may need to be enabled in its config first, which AgentPeek sets up for you when you connect it.

Update and reach support#

Update AgentPeek from the About tab (Sparkle checks for updates) and try again; the version log shows what each release fixed. Still stuck? Just message me on X @brenhubr and I'll help you out.