AgentPeek docs.

Getting started

Install AgentPeek

AgentPeek runs on Apple silicon Macs with macOS 14 or later. Setup takes about two minutes:

1. Download the signed DMG from agentpeek.app/download/latest and drag AgentPeek.app to your Applications folder.
2. Launch AgentPeek. First launch walks you through a short setup: pick the agents you use, connect at least one, and choose Start free trial or paste a license key. Connecting an agent installs AgentPeek's hooks into the same config your CLI tools and the desktop apps already read, so one setup covers both.
3. Open Settings → Doctor and press Run checks. Each agent shows Ready when it's tracking, with Repair hooks or Install hooks when one needs attention.
4. Run Claude Code, Codex, Cursor, Grok, Hermes, or OpenCode from the terminal or their desktop apps, or start an Antigravity conversation. New sessions appear in AgentPeek within seconds.

Every launch, AgentPeek re-checks each agent and quietly reinstalls or repairs a broken hook. If something still needs you, a banner appears under the session header with an Open Doctor button, and it clears itself the moment that agent's activity arrives. Depending on your Codex version, you may need hooks enabled in its config first, which AgentPeek sets up for you.

Getting started

How the 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. You can keep it always visible, hide it when idle, or show it only while expanded.
• Panel: the expanded view for sessions, permission and question prompts, plans, 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 runs alongside the notch, or instead of it. It shows token usage, local servers, and Quick Routes at a glance; full session detail stays in the notch panel. The notch and menu bar are independent toggles in Settings → General, so you can run either one or both.

Live sessions

View Claude Code, Codex, Cursor, Grok, Hermes, OpenCode, and Antigravity sessions

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

• Agent (Claude Code, Codex, Cursor, Grok, Hermes, OpenCode, or Antigravity), shown by its avatar, and the project name.
• State, shown by the avatar's color and motion: executing, thinking, waiting, idle, or an attention state when a session stalls.
• What it's doing right now, with a per-tool icon so a read, an edit, and a command each read differently at a glance.
• Quick metrics: reported token usage, files touched, commands run, diff +/- lines, elapsed time, an estimated cost, and the terminal it's running in (Terminal, iTerm, Ghostty, Warp, and others).

Click a row to expand it: the latest reply, rendered as Markdown with a Show more toggle, and a timeline of everything that happened (tools run, prompts, permissions, questions). Right-click for more, including jump back to the terminal, copy the session as Markdown, reveal paths in Finder, and end the session when AgentPeek can safely target it. Dismiss a quiet row with the trash button; ended sessions retire from the list on their own. Run as many parallel sessions as your Mac can handle.

Live sessions

Handle Claude Code, Codex, Cursor, Grok, Hermes, OpenCode, and Antigravity permissions

When an agent requests permission for a tool call, file edit, or command, AgentPeek opens the prompt inline, with the command, file path, or diff laid out so you can decide fast. Keyboard actions stay close:

A Deny with feedback option lets you send a note back when the agent accepts one. For a plan the buttons read Approve and Reject. In-notch answers work for Claude Code, Codex, Cursor, Hermes, and OpenCode; Grok and Antigravity prompts are observation-only, so AgentPeek flags the waiting session and ⌥ T takes you to it to answer there. AgentPeek only responds when you choose an action, so nothing is ever sent on your behalf. Prefer to keep approvals in the terminal? Set Settings → General → Prompt handling to Native, or set global hotkeys in Settings → Shortcuts to allow or deny the frontmost prompt without opening AgentPeek at all.

Live sessions

Answer agent questions

When an agent asks a question, AgentPeek shows the title, detail, and any options. Click an option to answer, or type a custom response and press Return when the agent allows one. For a multi-part question, each card carries its own choices, single or multi-select, with a Send button that lights up once you've answered them all. Use ← / → to move between pending prompts, or hand any one back with Answer in terminal.

Toolkit

Open Quick Routes

Quick Routes are one-click shortcuts to the Claude Code, Codex, Cursor, Grok, Hermes, OpenCode, and Antigravity folders you open often:

• Claude Code: Skills ~/.claude/skills · Plugins ~/.claude/plugins · Config ~/.claude/settings.json · Logs ~/.claude/projects · Root ~/.claude
• Codex: Skills ~/.codex/skills · Plugins ~/.codex/plugins · Config ~/.codex/config.toml · Logs ~/.codex/sessions · Root ~/.codex
• Cursor: Hooks ~/.cursor/hooks.json · Root ~/.cursor
• Grok: Hooks ~/.grok/hooks · Config ~/.grok/config.toml · Logs ~/.grok/sessions · Root ~/.grok
• Hermes: Config ~/.hermes/config.yaml · Skills ~/.hermes/skills · Logs ~/.hermes/logs · Root ~/.hermes
• OpenCode: Plugins ~/.config/opencode/plugins · Config ~/.config/opencode/opencode.json · Logs ~/.local/share/opencode/log · Root ~/.config/opencode
• Antigravity: Logs ~/.gemini/antigravity/brain · Root ~/.gemini/antigravity

Folders open straight in Finder, and Config and Hooks files are revealed in their folder. AgentPeek only surfaces routes that exist on your Mac.

Toolkit

Track token usage

AgentPeek tracks usage for all five agents, read from what's already on your Mac, with no extra sign-in and no credentials. Claude Code, Codex, Hermes, and OpenCode report theirs locally; Cursor's comes from your Cursor account, using the Cursor sign-in already on your Mac:

• 5-hour and 7-day windows (Claude Code, Codex), each with its resets in… or refills… time when reported.
• Monthly window (Cursor), with its refill date.
• Monthly tokens (Hermes, OpenCode): a raw token total with a requests, tokens, and spend line. Neither reports a quota percentage, so there is no bar to fill, just the honest count.

Each gauge reads like a battery, green through yellow to red as you near the limit. Turn on Count down to watch it drain from full instead, and open the panel's by-day chart to see your token volume over the last two weeks. A number shows -- when it's unavailable or stale, and Refresh usage pulls the latest any time.

You control it per agent in Settings → Usage: Show usage toggles an agent's gauges, Headline gauges promotes it to the header and collapsed pill, and Usage account picks which account to report when you have more than one. Cursor adds a Monthly measure (Weighted, Spend, Auto, or API) and optional Auto and API bars. Budget alerts in Settings → Notifications fire once when your 5-hour or 7-day usage crosses a threshold you set, anywhere from 50 to 100 percent.

Toolkit

Manage local dev servers

AgentPeek watches ports 3000-9999 for listening dev servers. It labels common frameworks (Next.js, Vite, Astro, Wrangler, Storybook, Playwright, and static-site servers) and language runtimes (Node, Bun, Deno, Python, Ruby, Rust, or Go); anything else shows its process name. Each row shows the port, the project folder taken from the server's working directory, and how long it's been up, sorted by port.

• One click to open the localhost URL in your browser.
• One click to copy the URL.
• One click to stop the server: it stops cleanly, with a safety check so it never kills the wrong process.

Toolkit

Run Fast Actions

Fast Actions are your own shell commands, saved and run straight from the notch. Open them from the zap icon in the panel header.

• Press + to add a New action, give it a Name and a Command (like npm run build), then save it with Add.
• Run an action from its row and watch it go: the row shows running, then succeeded or failed with the last line of output. Stop a long run any time.
• Commands run in a login shell from your home folder, so your PATH finds the same tools your terminal would (npm, node, pnpm, and the rest). Need a specific project? cd into it as part of the command.
• Reorder or delete saved actions right from the list.

Reference

Settings

Settings has eight tabs, with a search box at the top to jump straight to any control:

• General: launch at login, turn the notch and menu bar on or off, choose which agents to track, auto-expand on attention, prompt handling (notch or native), and account labels.
• Appearance: expanded and collapsed widths, density, session-list sizing, title weight, 12/24-hour clock, glass and metric opacity, avatar style, what the collapsed pill shows, and per-tool colors.
• Usage: per-agent gauges, account, headline, and count-down, plus Cursor's measure and extra bars.
• Notifications: a master toggle plus sound, permission requests, 5-hour and 7-day budget alerts, stuck-session and task-complete alerts, and a test button.
• Shortcuts: global hotkeys to toggle the notch or allow and deny the frontmost prompt.
• Doctor: check every agent's hooks, sign-in, and usage, and repair anything that's off.
• License: your license status, and a field to activate a key.
• About: check for updates with Sparkle, plus links to the docs, the log file, and acknowledgements.

Reference

Pricing and licensing

AgentPeek is a one-time purchase: pick how many Apple silicon Macs you want it on, pay once, and every future update is included. Start with a free 3-day trial, or paste your license key during onboarding. AgentPeek is built by one person, so a license directly supports the work.

• One payment unlocks the full app on the Macs you choose, no subscription and no account.
• Every future update is included.
• The trial and the license are both tied to your Mac. After a hardware migration you may need to activate again.

Reference

Privacy

AgentPeek is local-first:

• Session transcripts, diffs, prompts, token usage, project paths, and your local server list stay on your Mac.
• No accounts, no analytics, no telemetry.
• Claude Code, Codex, Hermes, and OpenCode usage is read from what those tools already keep on your Mac, with no network call from AgentPeek.
• Cursor usage is read from your Cursor account, using the Cursor sign-in already on your Mac, only when Cursor usage is shown.
• The only regular network activity is license checks, Sparkle update checks, and those Cursor usage reads. A license check sends your license key, machine ID, and app version; starting a trial sends just your machine ID and app version.

Reference

Support

Run into something? Open Settings → Doctor and press Run checks; it flags anything that needs a hook repair or a sign-in. Update AgentPeek from the About tab and try again. Still stuck? Just message me on X @brenhubr and I'll help you out.