Peeku: a tiny companion for your coding agents

You start a few Claude Code or Codex sessions in iTerm, Terminal and VS Code, switch to something else, and one of them quietly stops to ask for permission. Ten minutes later you notice.

Peeku fixes that. It sits invisibly inside the notch, or in its own menu bar icon, while your agents work. When one needs you, Peeku drops out, a notification opens, and Open Session takes you straight to the exact terminal tab or editor window. Then Peeku tucks itself away again.

01 · IN THE NOTCH

Invisible until it isn't.

Idle, Peeku is invisible: the notch is just the notch. While agents work, two eyes glance around beside the camera. When something needs you, Peeku drops out.

Three notch states: working, dropping out, and folded

02 · IT TELLS YOU WHY

The exact command, question or error.

Permission requests show the exact command, questions show their choices, errors show the error, and finished runs show the agent's last reply.

Peeku's notch expanded into a permission notification

03 · ONE CLICK BACK

Straight to the right tab.

Opens the precise iTerm tab, Terminal tab or VS Code window, and outlines it with a brief focus ring. Several agents waiting become one list, most urgent first.

Three agents need you, each with an Open button

04 · NOTCH OR MENU BAR

No notch? It lives in the menu bar.

On an external display or an older MacBook there's no fake notch. Peeku moves into its own menu bar icon, and the icon's eyes show what it's doing. When an agent needs you, Peeku climbs down from the icon and holds the alert. Prefer it there on a MacBook too? Pick Menu Bar in Settings.

On a display without a notch, Peeku hangs from its menu bar icon above a frosted panel: Claude needs your permission to run npm install stripe@17.2.0

05 · YOUR DEV COMMANDS

Your dev server, one shortcut away.

Save the commands you run all day, like npm run dev, with their folder. Run, restart and stop them from the dock at the bottom of the session manager, or press ⌥⌘. to open them. When one exits with an error, Peeku tells you with its last line of output.

A notch alert: Dashboard exited with code 1, with the last line Error: listen EADDRINUSE: address already in use :::5173, and Show Output, Restart and Later buttons

06 · YOUR SKILLS

Every skill your agents load, in one place.

See what Claude Code and Codex load, globally and in each project, and turn a plugin off without uninstalling it. Browse their marketplaces, see where each plugin's code lives, and install one for everything or just one project. Add your own skill folders, or share one with the other agent. Press ⌥⌘/.

Skills in two panels. Installed: a panel to add a skill folder for Claude globally, superpowers expanded with its four skills and a switch, code-review turned off, GitHub for Codex and a changelog skill. Discover: marketplace plugins with install counts and GitHub links, and playwright asking to install for the payments-api project

Everything it does, and nothing it doesn't.

Knows why a session is waiting.Permission requests show the exact command, questions show their choices, errors show the error, and finished runs show the agent's last reply.

Takes you to the right place.Opens the precise iTerm tab, Terminal tab or VS Code window, and outlines it with a brief focus ring.

One queue, most urgent first.Several agents waiting become one list: permission, then questions, then errors, oldest first. Cycle through it with ⌥⌘↓.

Every session at a glance.Click the notch or the menu bar icon for a live list of what's waiting, working and finished, plus a week of history. Any row jumps to its session.

Knows how much you have left.See how much of your Claude and Codex 5-hour and weekly limits you've used, when each resets, and get an alert at a threshold you set.

Knows what you spent.What today, the last 7 or the last 30 days cost at API prices, the tokens used, and a bar per day split by model.

Commands in the session manager: a dev server running, a worker that exited, and a docs preview waiting for input

Runs your dev commands.Commands lives in the dock at the bottom of the session manager, never in the tabs. Start, restart and stop saved commands, read their output, answer their prompts, and see how many are running at a glance.

Skills in the session manager: Claude Code and Codex plugins and skills, globally and per project, with a switch to turn a plugin off

Manages your skills.Skills sits in the dock too. Browse the Claude Code and Codex marketplaces, install a plugin for everything or one project, turn it off, uninstall it, and add or share skill folders between agents.

Sounds you can tell apart.A different chime for permission, questions, errors and finished runs, each one changeable or silenced in Settings.

Stays out of the way.Unanswered alerts fold into a small pill. In full screen Peeku shrinks to a thin glow, and it goes quiet while Zoom shares your screen or when you ask it to.

Read-only by design.Peeku never types into your terminal and never approves anything. Answers always happen in the real session.

Private.Your sessions stay on your Mac. The only network request Peeku makes is its update check to GitHub. Plugins you choose to install are downloaded by Claude Code or Codex.

Native.Swift and SwiftUI, light and dark mode, Reduce Motion, about 6 MB.

Every session, at a glance.

Click the notch or the menu bar icon for a live list of what's waiting, working and finished, plus a week of history. Any row jumps to its session.

The session manager with sessions that need you, working and finished — **Session manager**What needs you, what's working, what finished.

History of today's permission requests, finished runs and errors — **History**A week of permission requests, errors and finished runs.

The Usage tab with spend and Claude and Codex limits — **Usage**What you spent, and your 5-hour and weekly limits for Claude and Codex.

Utilities in the dock. Settings behind the gear.

The tabs at the top are always about your agents. Commands and Skills sit in the footer dock, and everything you can change is one click away in the same panel.

Commands: Dashboard running npm run dev, payments-api exited with code 1, and Docs waiting for input on a port question — **Commands**Your dev servers and workers, with their latest output. Press ⌥⌘. to open it.

Skills, Discover: Claude Code and Codex marketplace plugins with install counts, and playwright asking which project to install into before it runs — **Skills**Every plugin and skill both agents load. Install globally or into one project. Press ⌥⌘/ to open it.

Settings inside the session manager: appearance, notch or menu bar, login, updates and notifications — **Settings**Opened from the gear, in the same panel. No separate window.

State lives in the eyes.

Sleepy, busy, curious, eager, worried and happy.

Idle

Working

Question

Permission

Error

Success

Multiple

Light mode: Peeku hangs below the black notch above a frosted light panel

Native, light and dark.

The notch stays black, so Peeku hangs from it and holds a light panel instead. Swift and SwiftUI, Reduce Motion, about 6 MB.

HOW IT WORKS

Read-only by design. Everything stays on your Mac.

The collector only records. It never answers, approves or blocks anything, prints nothing, and always exits immediately, so it can't slow your agent down or change what it does. The only network request Peeku makes is its update check to GitHub.

Claude Code's session listSays which sessions are running and whether they're busy, idle or waiting. Read with no setup.~/.claude/sessions

Claude Code hooksSay why a session is waiting. The collector keeps only what Peeku shows and drops the rest, including transcripts.~/.claude/settings.json

Codex hooksWork the same way if Codex is installed. Trust Peeku's entries once with /hooks in Codex.~/.codex/hooks.json

UsageCodex writes rate limits to its session logs. For Claude, Peeku reads them from the status line.~/.codex/sessions

SkillsLists what the agents load. Plugins install and uninstall through Claude Code and Codex themselves, only when you click; removed skill folders go to the Trash.~/.claude/skills · ~/.agents/skills

Stays out of the way.

Unanswered alerts fold into a small pill. In full screen Peeku shrinks to a thin glow, and it goes quiet while Zoom shares your screen or when you ask it to. Peeku never takes the keyboard from your editor on its own, and every shortcut can be changed in Settings.

Show or hide your agents: ⌥⌘,
Open Now, History or Usage: ⌥⌘, 1–3
Show or hide Commands: ⌥⌘.
Show or hide Skills: ⌥⌘/
Move to the next waiting agent: ⌥⌘↓
Open the highlighted session: ↵
Fold the alert, or go back to your agents: Esc
Open a row by number: ⌘1–9

Get Peeku.

Free and open source. Requires macOS 14 Sonoma or later and Claude Code in a terminal, VS Code or the Claude app. Codex CLI is optional. Works with or without a notch.

Download latest release Star on GitHub

1Download Peeku-x.y.z.zip from the latest release and unzip it.
2Move Peeku.app to your Applications folder.
3Open Peeku, and let macOS open it once.
4Follow the short setup. It finds where your agents run and connects to Claude Code and Codex.

Peeku isn't notarized yet. On first launch, click Done, then Open Anyway in Privacy & Security, or run:

xattr -dr com.apple.quarantine /Applications/Peeku.app

Or build from source (Xcode 26, Swift 6.2):

git clone https://github.com/ahrefabhi/peeku.git
cd peeku
swift run Peeku --demo

A tiny creature in your notch or menu bar that watches over your agents.