AgentPeek docs.

Install AgentPeek

AgentPeek runs on Apple silicon Macs with macOS 14 Sonoma or later. Download the signed DMG, drag AgentPeek.app to your Applications folder, and launch it once.

• Download from agentpeek.app/download/latest.
• On first launch, AgentPeek asks for your license key. Activate once to unlock the app.
• After activation, AgentPeek installs the shared Claude Code and Codex hooks used by both the CLI tools and the desktop apps.
• Open Settings → General → Agent hooks. Claude Code and Codex should show Ready. Toggle a hook off and on, or press Repair, to reinstall it.

Run Claude Code or Codex from the terminal or their desktop apps. New sessions appear in AgentPeek within seconds.

How does the AgentPeek pill and panel work?

The notch surface has two states:

• Pill: the compact, always-on bar under the notch. It shows glanceable status - an active-session count or live usage gauges, depending on your appearance settings.
• Panel: the expanded view for sessions, permission and question prompts, token usage, local servers, and Quick Routes. AgentPeek can auto-expand it when an agent needs attention.

The menu bar is a separate, summary-grade surface that can run alongside the notch. It shows token usage, local servers, and Quick Routes at a glance; full session detail stays in the notch panel. Turn the notch and menu bar on or off in Settings → General.

View Claude Code and Codex sessions

Each row in the panel is one active agent session. You see:

• Agent (Claude Code or Codex), shown by its avatar, and the project name.
• State, shown by the avatar's color and motion: executing, thinking, waiting, or idle.
• Most recent activity (file edited, command running, plan adopted).
• Reported token usage, files-touched and commands-run counts, diff +/− lines, host app or terminal, and elapsed time.

Click a row to expand it: the latest reply snippet and a timeline of session events (tools run, prompts, permissions). Diff totals appear as +/− counts on the collapsed row.

Handle Claude Code and Codex permissions

When Claude Code or Codex requests permission for a tool call, file edit, or command, AgentPeek opens the prompt inline. Keyboard actions stay close:

• ⌘ A: Allow.
• ⌘ N: Deny.
• ⌥ A: Always Allow (Claude Code only).
• ⌥ T: Open Terminal.

A Deny with feedback button is also available for both agents. For plan and review prompts the buttons read Approve and Reject. AgentPeek keeps prompts visible where you already watch the session, and only responds when you choose an action - or you can leave approvals to the terminal with the prompt-handling setting.

Answer agent questions

When Claude Code or Codex asks a question, AgentPeek shows it in the panel with the title, detail, and any choices. Click an option to answer, or type a custom reply when the agent allows one and press Return. Use ← / → to move between pending prompts in the queue.

Open Quick Routes

Quick Routes are per-agent shortcuts to the Claude Code and Codex folders developers open often:

• Skills: ~/.claude/skills · ~/.codex/skills
• Plugins: ~/.claude/plugins · ~/.codex/plugins
• Config: ~/.claude/settings.json · ~/.codex/config.toml
• Logs: ~/.claude/projects · ~/.codex/sessions
• Root: ~/.claude · ~/.codex

AgentPeek opens each route in Finder in one click - folders open directly, and Config files are revealed in their folder. Only routes that exist on your Mac are shown.

Track token usage

AgentPeek reads token usage reported locally by Claude Code and Codex:

• 5-hour window: short-term usage, with the resets in… countdown when reported.
• 7-day window: longer-term usage, with the refills… day and time when reported.

The panel stacks the two progress bars per agent so you can plan longer runs with live usage visible. Usage shows -- when it is unavailable or stale, and you can refresh it manually. Budget notifications fire when usage crosses your configured thresholds.

Manage local dev servers

AgentPeek watches ports 3000-9999 for listening dev servers. Each is labeled by its runtime (Node, Bun, Deno, Python, Ruby, Rust, or Go); anything else shows its process name. Servers appear as a flat list sorted by port, and each row shows the project folder taken from the process's working directory.

• One click to open the URL in your browser.
• One click to copy the URL.
• One click to stop the process (SIGTERM, then SIGKILL if it keeps running).

Settings & Notifications

Settings has four tabs:

• General: launch at login (via macOS service registration), enable the notch and/or menu bar, auto-expand on attention, prompt handling (notch or terminal), and Agent hooks (install, uninstall, or repair per agent).
• Notifications: a master toggle plus sound, permission requests, 5-hour and 7-day budget alerts (threshold 50-100%), stuck-session alerts, and task-complete alerts.
• Appearance: expanded and collapsed widths, density, session-list sizing, title weight, 12/24-hour clock, and what the collapsed pill shows (count, usage, hide when idle, expanded only).
• About: check for updates with Sparkle, plus links to docs, the log file, and acknowledgements.

Pricing and licensing

A $15 one time license unlocks AgentPeek on one Apple silicon Mac, with future updates included. Enter your license key during onboarding.

• One payment unlocks the full app.
• Future updates are included.
• On activation, AgentPeek validates the key once and stores a signed receipt locally, bound to your Mac. After a hardware migration it may ask you to activate again.

Privacy

AgentPeek is local-first:

• Session transcripts, diffs, prompts, and token usage stay on your Mac.
• No accounts, no analytics, no telemetry.
• Network activity is limited to license checks and Sparkle update checks.
• License activation sends the license key, machine ID, and app version.

Support

Need help? Re-check the Install and Settings sections above, confirm Agent hooks show Ready, then update AgentPeek and retry. Still stuck? Reach out on X @brenhubr.