brov-macbook/CLAUDE.md

Coucou — guide for AI coding agents

Coucou is a native macOS app (NotchBuddy/); windows/ is the Tauri version for Windows and Linux. Mochi, a small animated character living in the MacBook notch, shows AI coding agent sessions (Claude Code, Gemini CLI, Antigravity and more) and a few integrations, and lets the user approve, answer, chat and drop files from the notch.

Where things are

• NotchBuddy/Sources/App/ — Mac-only Swift code. NotchBuddy/Sources/CoucouKit/ — code shared with the iPhone app (Mochi's BotEngine and outfits, pills, diff, models). NotchBuddy/Sources/Phone/ — iPhone app (CoucouPhone target), with its widgets in Sources/Widgets/ and the expanded approval notification in Sources/NotificationContent/. NotchBuddy/Resources/sounds/ — the 28 WAV sounds. NotchBuddy/project.yml — XcodeGen project (never edit the .xcodeproj by hand).
• NotchBuddy/Sources/CoucouKit/PillCatalog.swift — single source of truth for all declared pills (workspace tools, agents, AI providers, services). Every pill ID, color, category and subtitle lives here.
• docs/SPEC.md, docs/INTEGRATIONS.md — behaviour, views, states, integrations (in French).
• design/prototype/notch-buddy.html — original prototype, the visual source of truth. design/captures/ — target screenshots.
• windows/ — the Tauri app for Windows and Linux: Rust in src-tauri/, TypeScript in src/, the coucou-hook relay in hook/. windows/README.md lists what differs from the Mac.
• docs/*.html — the GitHub Pages site (privacy, terms, support, legal notice).
• relay/ — the Coucou relay, a stateless Cloudflare Worker that forwards the iPhone Live Activity pushes (it holds the APNs key, which must never ship in an app). See relay/README.md.

Build

cd NotchBuddy && xcodegen && xcodebuild -scheme NotchBuddy -configuration Debug build

Windows and Linux: cd windows && npm install && npm run tauri dev

Rules

• Swift 6, SwiftUI + AppKit. No third-party dependencies unless truly unavoidable. The character is drawn in code (Canvas + TimelineView), no Rive/Lottie/images.
• Secrets live in the Keychain, never on disk or in git.
• No telemetry. Network calls only to services the user configured.
• Never block Claude Code: if the app doesn't answer, the hook exits immediately.
• Never overwrite ~/.claude/settings.json: dated backup, merge, show the diff, write only after the user confirms.
• Never send an email or approve a Claude Code or Codex permission without an explicit click.
• Performance: 0 % CPU when the island is hidden.
• Keep the bundle identifier fr.louisraille.NotchBuddy (Keychain items, preferences and permissions depend on it).
• Never restyle what already ships (pills, cards, Settings, chat…): existing views stay exactly as they are in main, which is the App Store build. Change the look of an existing view only when explicitly asked.
• Pill IDs are stable contract values (Keychain, UserDefaults, hook routing): never rename an existing pill ID.
• New views follow the existing app style. design/prototype/notch-buddy.html and design/captures/ are references for new work, not a reason to change existing views.
• Every release adds its CHANGELOG.md section, a row in the README Versions table, and commits the regenerated Info.plist with the new version.