Claude Code and Codex, connected across iPhone, Apple Watch and Mac. Step away from your desk. Check progress, see what needs you, and handle supported approvals and questions—with a little cat keeping you company.
⬇️ Download for macOS · Features · How it works · Build from source · 简体中文
The 1.3 candidate is a major step beyond the original phone dashboard. The first release focused on session status and local alerts. This update brings deeper Codex integration, Watch complications and a more consistent companion experience.
| Upgrade | What it means for you |
|---|---|
| Updated agent integrations | Improved task, permission and question handling for Claude Code and Codex. See the capability limits below. |
| Deeper Codex integration | Observe Desktop and CLI tasks; answer questions, send follow-up instructions and start tasks through supported connections. |
| New Apple Watch complications | Followed tasks in a rectangular slot; Claude, Codex or combined remaining quota in a circular slot, with five display styles. |
| Refreshed icons and interactions | A shared cat identity and agent icons across devices, a simpler phone connection menu and clearer task states. |
| Updated macOS UI | Menu-bar status, notch glance and task cards, with improved dashboard reopening and glance position recovery. |
These are current-source and 1.3 candidate features, pending release and device acceptance. The latest public Mac download is currently 1.1. Update the Mac companion when the new release is available. Watch refresh timing is system-controlled; quota depends on available provider data.
- Download the free Mac companion. Under Assets, choose the DMG and drag the app into Applications. Requires Apple Silicon and macOS 14 or later.
- Open “Pair a phone” in the Mac menu bar, with your iPhone and Mac on the same local network.
- Tap “Scan to pair” on iPhone and scan the Mac's QR code. Follow Setup in the Mac settings to connect your agent.
- Just exploring? Tap “See the demo (no Mac needed)” on the iPhone connection screen. Live tasks require a reachable paired Mac.
Apple Watch also requires a paired iPhone. See Download below for current iPhone availability; the new App Store listing is being prepared.
You kick off three Claude Code sessions, switch to Codex for a fourth, walk away to make coffee — and now you have no idea which agent is stuck waiting on you, which is still grinding, and which already finished and is sitting idle.
vibebuddy is a tiny menu-bar cat on your Mac plus a companion app on your iPhone. It watches every coding-agent session and answers the only three questions that matter:
No more walking back to the desk to find a session has been blocked on a permission prompt for ten minutes. Your phone buzzes, you review the diff preview, and you tap Approve — or you tap the cat and say "approve it."
The Mac menu-bar app — every session in three buckets, the voice pet, and a remote-approval detail pane.
Notch glance — lives beside the notch like a Dynamic Island: nothing when idle, the cat + the count that matters when not, hover to expand, and approvals drop down as cards you answer in place.
On your iPhone — tap a session for the inline diff and Approve / Deny.
One icon, three platforms — the same kitten on your Mac, iPhone and Apple Watch, masked by each system.
The app icon is a white kitten with green ears and eyes on muted slate blue — one soft silhouette, three colors, still readable at 16 px. It was designed with the ip-as-logo skill and picked from six generated candidates; the same 1024 px artwork ships on macOS, iOS and watchOS.
The in-app buddy is the same cat, drawn in code from one shared geometry on iPhone, Apple Watch, the Dynamic Island, the Mac dashboard, the notch glance and the menu bar. Its mood (ears, eyes, mouth) and small reactions change with the sessions; on compact surfaces (menu bar, collapsed glance, Dynamic Island, Watch header) it shrinks to the head alone, the menu bar shows it as a monochrome template silhouette, and only iPhone and the Mac animate it. All screenshots above are Demo mode (sample data) — no real session data.
Voice is off by default. Select a provider, enter your own API key, accept the data disclosure, and grant microphone access before explicitly starting a conversation. Ask about task status or respond to supported requests. Audio and selected task context go directly to your chosen provider (OpenAI, Google Gemini, or Alibaba DashScope / Qwen); provider fees may apply. Available actions depend on the connection and request. The dashboard and button approvals work without voice.
Every session grouped into Needs response / Working / Done, each row showing project · branch · model · live token & context-window usage · the tool the agent is currently running · and a peek at its most recent output. Priority is honest: needs response always outranks working.
When an agent asks to run a command or edit a file, review the command or diff preview in the phone dashboard. Diff previews show up to eight lines per side; inspect the full change on the Mac when more context is needed. Approve / Deny from the dashboard or a lock-screen notification (Approve requires unlocking); answerable question notifications offer text input. Always allow this / Allow all this session remain in the dashboard, not notification buttons. A read-only wait tells you to respond in the Mac's native prompt. Actions require pairing and a reachable Mac.
Approval and question banners request Time Sensitive delivery when their final delivery level includes sound; Quiet makes them ordinary silent banners. Other categories remain ordinary. Your category switches and system notification / Focus settings still apply. ActivityKit puts live counts on the Lock Screen and Dynamic Island, updated while the app is foregrounded or connected.
The current source supports APNs notifications with the iPhone app closed when the Mac sender is running, APNs signing is configured for the iPhone build, the phone has registered, and notifications are allowed. This is not yet a public-download setup promise: the distribution approach awaits DEC-APNS, and lock-screen / Focus / Watch delivery still needs device acceptance. Responding requires a reachable paired Mac; away from that network, return to it before acting (an existing Tailscale connection is an advanced option).
The first-class roadmap covers Claude Code, Codex, Grok, and Cursor: three-state tracking and remote approval are the required baseline; quota and jump support are best effort. Claude Code, Codex and Grok have adapters today; Cursor is planned and is not yet supported. Device acceptance remains a separate gate for each agent. Qwen, Kimi, OpenCode, and Antigravity adapters are community-tier, unverified, and fail-open. See the hook setup guide for agent-specific setup.
The Mac shows a QR encoding host:port + a bearer token. The phone scans it once — no manual IP entry. (The same QR can carry a Tailscale 100.x address later, with no code change.)
A MenuBarExtra glance with live counts, a macOS notch glance, jump-to-terminal (open the right session with one click), launch-at-login, and a LAN bearer token persisted in the owner-only (0600) file ~/Library/Application Support/vibebuddy/token. ⏎ / ⌘F dashboard shortcuts included. v1.1 uses a signed Sparkle update feed; original v1.0 users need a one-time manual installation.
vibebuddy talks directly between your Mac and your phone over your own network. Session data never touches a vibebuddy server — there is no vibebuddy cloud, no account, no analytics, no tracking. Daemon routes are bearer-token gated. When APNs is configured, notification payloads (including titles and bodies) pass through Apple's push service. (The optional voice companion sends microphone audio and selected session context only to the provider you chose, with your key, when you turn it on.)
Full English and Simplified-Chinese UI on both apps. Plus a Demo mode that loads the whole interface with sample data — explore sample tasks with no Mac required.
Download the latest Mac Companion → · Apple Silicon · macOS 14+
The v1.1 DMG is Developer ID signed and notarized. Open it and drag VibeBuddyMacApp to Applications. No quarantine-removal command is needed.
Updating from v1.0: install v1.1 manually once. The original v1.0 shipped with an invalid update URL, so it cannot discover this release automatically. v1.1 uses the published Sparkle feed for future releases. The installed source build and the GitHub release are separate: use the latest release asset for the supported download.
Build it from source for now — see Build & run. Install on your own iPhone; there is no public iPhone download.
Claude Code / Codex / Qwen / … ──hooks──▶ vibebuddy (macOS menu-bar app)
• reduce hooks → needsResponse / working / done
• parse JSONL transcript → model / tokens / summary
• serve over LAN (HTTP /snapshot, WebSocket /ws)
│ scan QR to pair (host:port + token)
▼
vibebuddy (iPhone, SwiftUI)
• 3-bucket dashboard + Live Activity
• notify + remote approve + voice companion
shared VibeBuddyKit — one Codable wire model, written once
The hard part — detecting session state — is solved by hooks that each agent CLI fires on its lifecycle events (UserPromptSubmit, PreToolUse, Notification, Stop, …). vibebuddy reduces them to the three states and broadcasts a token-gated snapshot. The hooks fail open: if vibebuddy isn't running, your agents are completely unaffected.
Deployment targets: iOS 17 / macOS 14. The 1.2 candidate is built with Xcode 26.6. Xcode 27 work is deferred until a later update.
| Path | What |
|---|---|
VibeBuddyKit/ |
Shared Codable wire model (SwiftPM) |
VibeBuddyMac/ |
macOS core lib + vibebuddyd headless CLI (SwiftPM) |
VibeBuddyMacApp/ |
macOS menu-bar app (xcodegen) — owner-only LAN-token file, launch-at-login, Sparkle |
VibeBuddyApp/ |
iOS app (xcodegen) |
docs/planning/ |
overview, PRD, architecture, roadmap, prior-art |
Mac side (menu-bar app):
cd VibeBuddyMacApp && xcodegen generate
open VibeBuddyMacApp.xcodeproj # build & run (⌘R)A menu-bar-only app: live counts, a "Pair a phone" QR, and launch-at-login; the Mac daemon's TokenStore keeps the LAN token in the owner-only file ~/Library/Application Support/vibebuddy/token. (vibebuddyd in VibeBuddyMac/ is the headless equivalent: swift run vibebuddyd.)
iOS app:
cd VibeBuddyApp && xcodegen generate
open VibeBuddyApp.xcodeproj # run on a Simulator/devicePair by scanning the QR, or enter host/port/token manually. On iOS, ConnectionStore persists the pairing payload in UserDefaults. (Simulator: use 127.0.0.1 and the token from ~/Library/Application Support/vibebuddy/token.)
Hooks (feed real agent sessions):
python3 hooks/install-claude-hooks.py --dry-run # preview
python3 hooks/install-claude-hooks.py --install # back up + install
python3 hooks/install-claude-hooks.py --uninstall # revertInstalls fail-open curl POSTs for each lifecycle event. See docs/multi-cli-hook-setup.md for every supported CLI.
Tests:
cd VibeBuddyKit && swift test # wire-model tests
cd VibeBuddyMac && swift test # daemon / reducer / transcript testsvibebuddy stands on the shoulders of two clever projects that first proved you can detect coding-agent state from hooks and a transcript tail — we re-pointed that idea at a phone (and added two-way voice). We studied their architecture and wrote our own Swift; no code was copied.
- op7418/m5-paper-buddy — showed your agent's RUNNING / WAITING status on an M5Paper e-ink gadget via transcript-tail JSONL parsing and fail-open hook
curl. vibebuddy borrows the detection concept and moves the display from a desk gadget to your pocket. - Octane0411/open-vibe-island — a source-agnostic
SessionStatereducer across 10+ agents, surfaced in the macOS menu bar / notch. It shaped vibebuddy's multi-agent model and Mac-side glance.
The Mac v1.1 source includes Codex Desktop 0.153.3 monitoring, bounded UTF-8 rollout handling, graceful daemon shutdown, observation diagnostics and Watch companion support. Mac, iPhone and Apple Watch have been installed locally; real phone approvals, recovery and phone-to-Watch state relay were verified. Full wrist approval, notification perception, voice and accessibility acceptance remain user follow-ups. App Store availability is separate from the Mac GitHub release. See the latest Mac release and roadmap.
MIT © 2026 Xianwei Zhang