Before you start
- Pairbar installed (install Pairbar).
- The Claude desktop app (its Code tab) or the
claudecommand line, and/or the Codex app, thecodexcommand line or the IDE extension. - For Claude: a folder Claude already trusts. For Codex: a minute to trust the hooks once with
/hooks.
Steps
- Open Settings → IntegrationsFind Live status for Claude (hooks) and Live status for Codex (hooks). Or use Install… on the "Get instant status" card that appears once at the top of the chat list: when neither app's hooks are installed, it offers both with one confirmation (Not now hides the card for good; Settings keeps the button).
- Install and confirmPress Install… on the Claude row, the Codex row, or both. Pairbar asks you to confirm first, then backs up the file it's about to change, adds only its own entries, and reads the file back to check it. How it works in Settings shows what Install writes and what is sent.
- Trust the hooks once in CodexCodex runs a hook only after you've reviewed it. In Codex, type
/hooks, look at Pairbar's (they run~/.pairbar/bin/pairbar codex-hook <event>) and trust them. Codex remembers this in[hooks.state]in~/.codex/config.toml, for the app and the command line together. Settings shows how many of Pairbar's hooks Codex trusts so far. - Start a new chatBoth apps read their hooks when a chat starts. In Claude, chats already open start sending events after their next message; in Codex, start a new chat. Quitting and reopening the app works for both.
- Check that events arriveBack in Settings → Integrations, each row should say Installed with "Last event received 12 s ago". "No events received yet" means it's installed but nothing has come yet: see the troubleshooting below.
What changes with live status
| From the files alone | With the hooks | |
|---|---|---|
| A Claude chat waiting to run a shell command | can only be guessed | Needs you at once, with the command ("Bash · git push") |
| A Codex chat waiting for approval | looks like it's still working (Codex writes nothing while it waits) | Needs you at once, with what it wants to run |
| A working chat | working | the tool it's running now ("Bash · npm test", "Edit · Store.swift", "apply_patch · Store.swift", "Compacting") |
| A finished turn | after the files settle | the moment Claude stops; Waiting for you the moment a Codex turn ends or is interrupted |
| Subagents and Codex helper threads | from their files | working or done when they start and stop |
What Install writes for Claude
- One entry per event in
~/.claude/settings.json, added after your own hooks for that event:SessionStart,UserPromptSubmit,PreToolUse,PostToolUse,PostToolUseFailure,PermissionRequest,PermissionDenied,Notification,Elicitation,PreCompact,Stop,StopFailure,SubagentStart,SubagentStop,SessionEnd. The tool events match every tool ("*"). - Each entry runs the helper inside the app, for example
'/Applications/Pairbar.app/Contents/Helpers/pairbar' hook PreToolUse, with a 5-second timeout. - The tool events, which run on every tool call, are marked
"async": true, so Claude starts the helper and carries on without waiting. The other events stay synchronous so a permission prompt or a stop arrives in order. With a Claude Code older than 2.1.23 (noasync), every entry is synchronous. - Claude Code's status line runs through the helper too, so your plan limits come from what Claude hands it and Pairbar needn't start
claudeto read them. If you have a status line, the helper runs yours after--, with the same input, so it looks exactly the same; only itscommandtext changes. Without one, the helper shows a short line of its own (5h 23% · week 41%). - Nothing else changes: your hooks, other settings, their order and the file's layout stay as they are.
- A backup goes to
~/.pairbar/backups/claude-settings-<date>.jsonfirst (the latest 10 are kept).
If the file isn't valid JSON, or its "hooks" isn't what Claude expects, Pairbar doesn't touch it and says why.
What Install writes for Codex
- Normally one block at the end of
~/.codex/config.toml(created if missing), between Pairbar's comment lines# >>> Pairbar: live status for Codex … >>>and# <<< Pairbar: live status for Codex <<<, with one[[hooks.<Event>]]entry per event:SessionStart,UserPromptSubmit,PreToolUse,PermissionRequest,PostToolUse,PreCompact,PostCompact,SubagentStart,SubagentStop,Stop,Interrupt,SessionEnd. - Or entries in
~/.codex/hooks.jsoninstead, when that file already has your hooks andconfig.tomlhas none (Codex warns at every start when both have hooks). - Each entry runs
'<your home>/.pairbar/bin/pairbar' codex-hook <Event>with a 5-second timeout (2 seconds forSessionEndandInterrupt, under Codex's 3-second cap).~/.pairbar/bin/pairbaris a link to the helper inside the app, so the entries never need to change, and Codex never asks you to trust them again. - Pairbar doesn't rewrite
config.toml; it adds text after it. Your settings, comments, MCP servers and their environment, and your own hooks stay exactly as they are. It checks the file is valid TOML before and after. - A private backup goes to
~/.pairbar/backups/codex-config-<date>.toml(orcodex-hooks-<date>.json). Your config can hold secrets such as an MCP server's API key: Pairbar never logs, shows or sends any of it.
If config.toml isn't valid TOML, or writes its hooks inline (hooks = { … }), Pairbar leaves it alone and says why: adding to it would mean rewriting yours.
What the helper sends, and where
For each event the helper keeps only metadata: the chat's id, folder and transcript (or rollout) path; the event's name, and a subagent's id and type; the tool's name and a short summary (a command's program and subcommand such as "git push", a file's name, a URL's host); for notifications their kind and short message. It never passes on your prompts, a tool's input or output, a full command, a patch, or the agent's replies.
It hands that one line to Pairbar over a private socket on your Mac (~/.pairbar/run/events.sock, usable only by your account) and exits in about a millisecond, always successfully and without printing anything, so it never slows the agent down or changes what it does. If Pairbar isn't running, the event is dropped; nothing is queued, and nothing goes over the network.
Repair, update and uninstall
| Settings shows | What to do |
|---|---|
| Needs repair | You moved or renamed Pairbar, or entries are missing. Repair points them at this copy. For Codex it fixes the link, so Codex's config doesn't change and you don't trust the hooks again. |
| Update available | An older Pairbar wrote the Claude entries and updating them at launch didn't work. Update hooks rewrites only Pairbar's own entries, after a backup. |
| Can't read settings | The file can't be changed safely; Settings gives the reason (and for Codex, the line). |
| Limits: reconnect | You changed Claude's status line yourself, so it's yours and Pairbar never puts its own back by itself. Reconnect runs the status line you have now inside Pairbar's, the same way. |
| Uninstall | Removes exactly Pairbar's entries (or Codex block), and puts your own status line back as it was (or removes Pairbar's, if you had none), after another backup. The file is then as it was before you installed, apart from what you changed in between. |
Troubleshooting
- "No events received yet from the Claude app"
- Send a message in a chat, or quit and reopen Claude: it reads hooks when a chat starts. Claude doesn't run hooks in a folder it doesn't trust yet, in cloud chats, or with
"disableAllHooks": true(Settings warns about that one). An organisation's managed settings can also allow only their own hooks. - "No events received yet from Codex"
- Trust Pairbar's hooks with
/hooksin Codex (untrusted hooks don't run), then start a new chat or reopen Codex.hooks = falseunder[features]turns hooks off (Settings warns), as can an organisation's managed config. Cloud tasks run elsewhere and send nothing. - Install says the file can't be changed
- Pairbar won't touch
settings.jsonthat isn't valid JSON, or aconfig.tomlthat isn't valid TOML or writes its hooks inline. Fix the file (or let the app rewrite it), then try Install… again. - Status stopped updating after moving Pairbar
- The entries point at the old location. Settings shows Needs repair: press Repair.
Frequently asked questions
- Does Pairbar need the hooks to show status?
- No. Without them it works status out from the files Claude and Codex write, as it always has. The hooks make it instant and show things the files can't, such as a command waiting for approval.
- Do the hooks send my prompts or code anywhere?
- No. The helper passes only metadata (chat id, folder, event, tool name and a short summary) over a private socket on your Mac. Nothing goes over the network.
- Will the hooks slow Claude down?
- No. The helper exits in about a millisecond, always successfully and silently, and Claude's tool events run it with
async, so Claude doesn't wait for it on tool calls. - Does it work with the Codex command line as well as the app?
- Yes. The Codex app, the
codexcommand line and the IDE extension read the same config, so one install covers all three. - Does Pairbar use Codex's notify setting?
- No. It uses only hooks, so another tool relying on
notifykeeps it.
Related
- DocsIntegrationsLive status for Claude and Codex through their hooks, Pairbar's tools for their chats (the plugin, the `pairbar` command, the tool reference, who's calling, agent activity), and agent actions: second opinions, reviews, helper chats, handoffs, workflow runs and drafts, and check-ins that agents ask for and you approve, with budgets and guardrails
- GlossaryAgent hooksCommands an AI coding agent runs automatically at set points in its loop, such as before a tool call, on a permission request or when a turn stops.
- Use caseKnow the moment Claude Code or Codex stops to ask for your approvalOptional hooks for Claude and Codex show Needs you the instant a chat asks for approval, the tool a chat is running, and when it finishes.
- GuideLet Claude and Codex query Pairbar (MCP tools)Install Pairbar's plugin so Claude and Codex chats can call its 22 tools (MCP or the pairbar command): read what Pairbar knows, ask for approved actions.
- Use caseGet notified when Claude Code or Codex finishes or needs your inputBanners, sounds and a count on the menu-bar icon tell you when a Claude or Codex chat finishes or needs you.
Try Pairbar free for 7 days
One sidebar for the Claude and Codex desktop apps. Everything on for 7 days, no card needed; then $49/year ($39 first year with LAUNCH), $9/month or $129 lifetime (first 200 buyers). macOS 26 or later, Apple silicon.