Coucou Agent Companion
Keep coding-agent sessions and approval requests in view on your Mac, then follow them from your iPhone.
- Source repo
- Louis-CFM/coucou
- Stars
- ★ 4k
- Last updated
- today
- License
- MIT
- Primary language
- Swift
- FA score
- 73/100 · Some gaps
At a glance
- How it runs
- Works with
- Portable with changesCodex · Claude CodeOpenAI API · Claude API (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A Claude Code user wants to watch session steps and file diffs and handle permission requests without switching away from current work.
- Not a fit if
- Users who need an iPhone App Store release
- Windows users who require a ready-to-run installer
- Source review
- 73/100 · Some gaps
What does this agent do, and when should you use it?
Coucou is a desktop companion for developers, built with Swift 6, SwiftUI, and AppKit on macOS, with Tauri 2 versions for Windows and Linux. It receives session events through hooks and plugins for Claude Code, Codex, Cursor, Gemini CLI, and other tools, then shows activity, file changes, and pending requests at the top of the Mac screen. Users can approve or deny supported requests, answer questions, inspect diffs, and jump to the relevant terminal. A companion iPhone app syncs sessions, decisions, and instructions through the user's iCloud account, with Live Activities, notifications, and widgets. Coucou can also connect to user-configured AI providers and third-party services, with some features limited by platform.
On macOS, Coucou installs hooks for Claude Code and other tools; the nb-hook script forwards events to the app over a Unix socket, where it displays session steps, files read or changed, commands, and diffs. Claude Code permission requests offer Allow, Deny, or Always in the notch, and questions can be answered from their displayed choices; Codex supports Allow and Deny. Coucou can chat with Claude, Gemini, OpenAI, or local Ollama / LM Studio models, and poll configured integrations such as GitHub, Vercel, Stripe, n8n, Resend, Notion, and Cal.com. The iPhone app reads sessions from a private CloudKit database and writes back decisions, answers, and instructions; Live Activity updates use the stateless Cloudflare Worker in relay/.
- A Claude Code user wants to watch session steps and file diffs and handle permission requests without switching away from current work.
- A developer running Codex, Cursor, or several supported coding tools wants their sessions visible in one top-of-screen interface.
- Someone stepping away from a Mac wants to handle agent requests, answer questions, or send the next instruction from an iPhone.
- An independent developer wants to view coding sessions alongside status from GitHub, Vercel, or another supported service.
- A macOS developer wants to monitor coding sessions and chat using a local Ollama or LM Studio model.
How do you install or deploy this agent?
For macOS, download Coucou.zip from Releases, unzip it, move Coucou.app to /Applications, and launch it; or build from source with the commands below. The Windows installer is temporarily unavailable, so Windows users can package from source using the repository instructions. Linux has an x86_64 beta in AppImage, .deb, and .rpm formats; source builds require the listed system development packages. The iPhone app is currently available through a TestFlight beta; its App Store release is not yet available. Hooks and service credentials are configured as needed. The iPhone companion requires the same Apple Account on the Mac and phone.
How do you use this agent?
After launching, open Settings from the menu bar or system tray. To monitor Claude Code, choose Install hooks under Settings → Claude Code; install hooks or plugins from the relevant settings pages for Codex, Gemini CLI, Antigravity, and other supported tools. Start a supported agent session to see its events in Coucou; when an approval appears, choose Allow or Deny, or select an answer to a question. To pair an iPhone, enable session sharing under Settings → General → iPhone on the Mac, install the TestFlight beta on the phone, and allow notifications. For chat or service integrations, add the required API keys or credentials in their settings; keys are stored in the platform's credential store.
What are this agent's strengths and limitations?
- Puts session steps, file diffs, and approval requests at the top of the screen, reducing the need to switch to a terminal.
- Documents support for several coding tools and a --agent <name> hook path for other agents.
- The iPhone companion syncs through CloudKit and supports lock-screen approvals, notifications, Siri, and widgets.
- The macOS app is native and has no third-party dependencies; Tauri builds are also documented for Windows and Linux.
- The Windows installer is temporarily unavailable, and Linux releases are beta and currently x86_64 only.
- Several features are platform-limited; for example, Gemini/OpenAI/local-model chat and some plugins are macOS-only.
- The iPhone companion is still a TestFlight beta and requires iOS 18+, Mac-side setup, and the same iCloud account.
- Cloud-model chat and service integrations require user-supplied credentials; the README does not state every service's pricing.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Coucou Agent Companion This agent | 73 · Some gaps | Desktop appFree + model costs | ★ 4k | today | Swift | Codex · Claude Code |
| Claude Code Skills & Plugins | 64 · Some gaps | Agent plugin / skillFree | ★ 28k | 1mo ago | Python | Codex · Claude Code |
| Diri | 59 · Major gaps | Desktop appFree + model costs | ★ 425 | today | Rust | Codex · Claude Code |
| EOC — Everything OpenAI Codex Workflow OS | 75 · Good | Agent plugin / skillFree + model costs | ★ 95 | 1mo ago | JavaScript | Codex |
How does FollowAgents rate this agent?
Why each dimension lost points
The documentation describes optional integrations, system credential stores for API keys, iCloud sync and encrypted fields, explicit approval actions, Face ID for each Allow, and matching decisions to the pending request. It also says hook installation backs up settings and shows a diff. These are concrete controls for privilege, data flow, sensitive data, and rollback, but they are mainly README claims; the supplied code does not substantiate credential access scope, encryption implementation, or a full uninstall recovery path. Integrations can re-run CI, redeploy, merge PRs, or pause workflows; the docs say Face ID protects these actions but do not show per-action authorization implementation. MIT attribution is clear, but publisher identity is unverified and the supplied materials do not clearly identify a maintainer or security update channel.
The README describes connection methods across platforms, and the version table and changelog are clear. The supplied Linux workflow includes build, test, and version consistency checks; the macOS workflow lists multiple tests and builds. However, platform support statements are interleaved with platform limits, and the supplied materials do not establish dependency availability or actual workflow results. The docs say hooks exit immediately when the app is not running so Claude is not blocked; failure cases are partly addressed, but error messages across platforms are not shown.
The project targets developers across macOS, Windows, Linux, and iPhone, with listed scenarios, supported agents, integrations, and setup steps. It identifies features limited to macOS or GitHub builds and Linux desktop environment differences. Agent connection boundaries include hooks, plugins, and a generic tagging mechanism, but the broad claim of support for other agents does not establish precise triggers or coverage for every agent.
The README is well organized around features, installation, setup, architecture, contribution, versions, and platform differences. Requirements, a demo, usage examples, limitations, and the MIT license are documented. The version table gives dates and highlights and points to a changelog. Naming shifts among Coucou, Mochi, and the internal project name NotchBuddy, which weakens stability slightly. Contribution and release paths are described, but there is no clear maintainer response commitment or security reporting process.
The documented outputs include live session steps, file diffs, approval cards, question choices, and notifications, with actions available from the desktop or iPhone. Putting agent status and approvals in the notch, Lock Screen, and notifications offers clear practical value. The product spans several platforms and includes credentials, cloud sync, and many service integrations; demo mode lowers the trial cost, but the supplied material does not let us assess resource use or ongoing maintenance cost, so cost-benefit is not full marks.
The README gives traceable filenames, steps, and architecture descriptions for features, setup, and platform limits; the Linux workflow and fake local-model server corroborate some engineering details. The supplied materials omit most implementation source, limiting cross-source corroboration, and privacy, encryption, and approval behavior are largely documented claims. The docs generally distinguish platform-specific features, but do not systematically label which claims remain unverified by the supplied source.
- The supplied materials omit key implementations for privacy, encryption, Face ID approvals, and protection of external service actions; treat these as documentation claims rather than verified implementation in this review.
- The README says the Windows installer is unsigned and displays “Unknown publisher”; checksum verification is described for Linux releases only.