Installation

OverviewInstallationPill, panel & menu barSessionsPermissions & questionsFollow-up promptsHost matrixSupported agentsToken usageLocal serversQuick RoutesFast ActionsViewsWidgetsAgent BoardNotificationsSettingsLicensing & pricingTermsPrivacyTroubleshooting & support

Requirements#

  • An Apple silicon Mac running macOS 14 or later.
  • At least one supported coding agent: Claude Code, Codex, Command Code, Cursor, Qoder, CodeBuddy, Gajae Code, Grok Build, Kimi Code, Hermes, OpenCode, MiMo Code, GitHub Copilot, Kilo Code, Factory Droid, Antigravity, Qwen Code, Pi, Oh My Pi, Goose, Kiro, Cline, Mistral Vibe, ZCode, Aider, and Devin.
  • A notch is optional. The notch and the menu bar are independent surfaces, so a Mac Studio, Mac mini, or external display works fine.

Install the app#

  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 setup: pick the agents you use, connect at least one, and choose Start free trial or paste a license key. AgentPeek configures only the supported integration for each selected agent. Hook-based agents get AgentPeek-owned entries; read-only integrations are not modified.
  3. Open Settings then Doctor and press Run checks. Each selected agent shows Ready when its supported tracking requirements pass. Doctor offers the exact repair or sign-in action when one needs attention.
  4. Start any selected agent in its normal terminal or desktop app. New sessions appear as supported activity arrives.

How agents connect#

Each agent gets only its exact integration, and nothing more. Most agents connect through hooks or a plugin that AgentPeek installs into the agent's own config. A few need no install at all because AgentPeek can read the session records the agent already keeps.

On launch, AgentPeek checks enabled managed integrations and repairs only AgentPeek-owned hook entries. Read-only integrations remain untouched. If something still needs you, a banner appears under the session header with an Open Doctor button, and it clears when that integration becomes ready. Depending on your Codex version, you may need hooks enabled in its config first, which AgentPeek sets up for you.

The exact hook, plugin, config, and log paths for every agent are listed on the Quick Routes page, and each agent's own page under Supported agents documents its integration in full.

What gets written, per agent#

A few agents deserve an explicit note on exactly what their connection touches:

  • Cline connects through a plugin at ~/.cline/plugins/agentpeek.ts; monitored sessions stay view-only, and AgentPeek does not claim Cline Direct Chat or monitored-session resume.
  • ZCode: ZCode monitoring merges seven observer commands under ~/.zcode/cli/config.json, preserving whatever you already have there. Permission decisions stay in ZCode.
  • MiMo Code: MiMo Code monitoring writes only ~/.config/mimocode/plugins/agentpeek.js.
  • Kiro: Kiro's built-in default agent has no global hook file; hooks exist only in the custom-agent JSON files you select under ~/.kiro/agents or .kiro/agents, and AgentPeek does not install or mutate those selected JSON files.
  • Mistral Vibe: AgentPeek preserves user TOML while adding marker-bounded observers to ~/.vibe/hooks.toml, reads ~/.vibe/logs/session, and launches vibe-acp for Direct Chat.
  • Aider: Aider monitoring also installs nothing and changes no configuration: AgentPeek reads your configured chat history file, plus analytics only where already enabled. AgentPeek never enables analytics or assigns them to a chat history.

Your first session#

With the selected integration ready, start your agent exactly the way you always do, in its normal terminal, editor, or desktop app. The session appears in the notch panel as supported activity arrives, labeled by project, with its state readable at a glance. From there, the Sessions page covers everything a session row can show, and Permissions covers what happens the first time an agent asks for something.