AgentPeek docs

Grab the DMG from agentpeek.app/download. Drag AgentPeek.app into Applications, then open it.

On first launch, AgentPeek adds hooks to each CLI.

• Claude Code: adds hooks to ~/.claude/settings.json (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PermissionRequest, Notification, Stop, PreCompact, SessionEnd) and a status-line command for usage.
• Codex: writes ~/.codex/hooks.json (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd) and sets codex_hooks = true in ~/.codex/config.toml.

New sessions pick it up on their own. Desktop and IDE apps stay untouched.

Open Settings → General → Agent hooks. Each CLI shows Ready, Needs repair, or Not installed. Flip the toggle to install or remove.

Thin pill shaped like the notch. Shows what the agent is doing:

• Idle: nothing is running.
• Active: a session is running; a count badge shows when there are more than one.
• Attention needed: a permission or question is waiting.
• License blocked: greyed out with a lock.
• Confirmation flash: green check after allow or always allow, red x after deny.

Click the pill to open it. Three tabs:

• Sessions: recent and active sessions.
• Quick Routes: shortcuts to agent config folders.
• Local Servers: dev servers that are listening.

Pending permissions and questions take over the panel until you answer. The gear opens Settings.

Cards show the agent, project, activity, usage, files touched, commands run, and diff stats. Click a card to see the last reply and a recent timeline.

• Transcripts: read from ~/.claude/projects/ and ~/.codex/history.jsonl + ~/.codex/sessions/. Read-only.
• Diffs: shown for edit prompts and Codex apply_patch sessions.
• Session state: saved to ~/.agentpeek/sessions.json.
• Right-click: copy project or cwd, show in Finder, open Terminal.

Claude Code and Codex permission requests show up inside AgentPeek. The notch shows the prompt, context, and the buttons you can use.

• Shell commands, file paths, arguments, plans, and diffs when we have them.
• Actions: Allow, Deny, Deny with feedback, Always Allow (Claude only), Open Terminal.

Always Allow shows up on Claude prompts that support it. It is hidden on plan prompts and prompts with no reusable rule. Open Terminal jumps back without answering the prompt.

Claude and Codex can ask for input through the hook bridge. AgentPeek shows the choices or text field right in the notch.

• Single-choice prompts show buttons.
• Freeform prompts show a text field and a Send button.
• Multi-question prompts ask for one answer per line.

Shortcuts to each CLI’s config folders. Missing folders show dimmed.

Folders open in Finder. Config shows the file. You can toggle the path display in Appearance.

Shows servers that are listening on ports 3000-9999. We guess the framework from the process name (Rust, Python, Ruby, Bun, Deno, Node, Go).

• Port, framework, uptime.
• Click to open http://localhost:<port>.
• Copy the URL or stop the server from the row.

Uses /usr/sbin/lsof and only sees your own processes. If the list is empty, see Local servers empty.

A chip in the header shows rate-limit use (5-hour and 7-day windows, when the CLI gives them).

• Claude: status-line snapshots in ~/.agentpeek/claude-statusline-usage/, updated every 5 seconds.
• Codex: read from codex app-server --listen stdio://.

Old data shows as stale. Missing data shows as unavailable.

Three tabs: General, Appearance, License.

General

• Launch at login: start with macOS.
• Auto-expand on attention: opens the notch for permissions and questions.
• Agent hooks: flip each CLI to install or remove it.
• Claude usage: a Refresh button shows up when Claude usage is disconnected.
• Quit AgentPeek.

Appearance

License: paste your key, click Activate or Re-check. See Licensing.

2 days, all features, no account. The clock runs on your Mac. When it ends, paste a key to keep going.

Buy at agentpeek.app/checkout. Paste the key from your receipt email.

1. Open Settings → License.
2. Paste the key into the License key field.
3. Press Return or click Activate.

The first check activates with LemonSqueezy. Later checks just confirm the saved activation. The key and activation ID live in your Keychain.

Tied to this Mac’s IOPlatformUUID. Got a new Mac or changed hardware? Message @brenhuberr on X for a reset.

A CLI session starts, but the notch stays empty.

1. Open Settings → General → Agent hooks.
2. If a CLI shows Needs repair or Not installed, flip the toggle off and back on to reinstall.
3. Start a new session. Old sessions do not pick up new hooks.

If install still fails, check ~/.claude/settings.json and ~/.codex/hooks.json for broken JSON.

Sessions hang after AgentPeek crashes or is force-quit.

osascript -e 'quit app "AgentPeek"'
rm ~/.agentpeek/hook-transport.json
open -a AgentPeek

AgentPeek makes a new socket path and token the next time it starts.

• Claude: open Settings → General. If you see a Claude usage row, click Refresh. If not, flip Agent hooks → Claude Code off and back on, then start a new session. Make sure ~/.agentpeek/claude-statusline-usage/ has recent files.
• Codex: make sure codex is on your PATH and signed in, then hit refresh.

The session card shows up, but the body or diff is empty.

ls ~/.claude/projects/*/<sessionId>.jsonl
grep -l "\"session_id\":\"<sessionId>\"" ~/.codex/history.jsonl
find ~/.codex/sessions -name "*-<sessionId>.jsonl"

Non-ASCII characters in the working directory path can trip up Claude’s lookup.

• We only scan ports 3000-9999.
• lsof only sees your processes, not sudo or other users.
• Servers with no start time show no uptime.

Check System Settings → General → Login Items & Extensions. If AgentPeek is missing, flip Launch at login off and back on to re-register.