{
"markdown": "# Duck Duck Duck\n\n[](LICENSE)\n[](firmware/LICENSE)\n\n![\"Duck](\"docs/hero.jpg\")
\n\nA companion for Claude Code on Mac. It watches your coding sessions, scores every prompt and response, speaks opinionated reactions, and handles permissions by voice. Optionally connects to a [physical duck](https://duck-duck-duck.edges.ideo.com/) for hardware reactions.\n\n**[Learn more at duck-duck-duck.edges.ideo.com](https://duck-duck-duck.edges.ideo.com/)**\n\nπ [**Default intelligence is fully on-device and private**](#data--privacy) on M3+ Macs. M1/M2 users get the best experience with a cloud API key ([free options available](#evaluation)). No cloud audio regardless β your voice never leaves your machine.\n\n## Requirements\n\n- **macOS 26** (Tahoe) or later, **Apple Silicon** (M1 or later)\n- **Claude Code** or **Claude Desktop** β [get Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)\n\n> **On-device scoring is designed for M3+ Apple Silicon.** It works on M1/M2 but runs slowly (~30-60s per eval). For instant reactions on older hardware, add a cloud API key β see [Evaluation](#evaluation) below.\n\n## Install\n\n1. Download `DuckDuckDuck.dmg` from [GitHub Releases](https://github.com/ideo/Rubber-Duck/releases)\n2. Drag to Applications, launch\n3. Grant **Microphone** and **Speech Recognition** when prompted β all audio stays on-device\n4. Accept the **Terms of Use**\n5. The app walks you through installing Claude and the plugin\n6. Open a Claude Code session (CLI or Desktop) β the duck is watching\n\n\nBuild from source
\n\n```bash\ngit clone https://github.com/ideo/Rubber-Duck.git\ncd Rubber-Duck/widget\nmake run\n```\n\nThen use **Setup β Install Plugin** from the menu bar.\n\nRequires Xcode with Swift 6.2+ (macOS 26 SDK).\n\n \n\n## How It Works\n\n```\nYou βββΊ π¦ Hardware Duck βββΊ Duck Widget (SwiftUI) βββ Claude Code / Desktop\n mic + speaker eval engine (Foundation plugin hooks (prompt,\n servo + LED Models / Haiku / Gemini) response, permission)\n β² β\n β voice out (TTS)\n βββββββββββββββββββ servo + LED commands\n speaker audio\n\n (no Duck, Duck, Duck device? laptop mic + speakers work too)\n```\n\n1. **Hooks** fire on Claude Code events and POST to the widget's embedded server\n2. **Eval engine** scores text on-device via Apple Foundation Models (free, sub-second on M3+) β returns scores + a spoken reaction\n3. **Widget** animates the duck face, speaks the reaction, optionally drives hardware via USB serial\n4. **Voice permissions** β the duck summarizes what Claude wants to do and asks. Say \"yes\", \"always allow\", \"deny\". Foundation Models classifies ambiguous responses.\n5. **Voice commands** β say \"ducky [command]\" to inject text into Claude Code via tmux\n6. **Wildcard voice** β score-gated AI picks from 10 voices per reaction (normal, grave, cheerful, dramatic, whisper, etc.)\n\n## Modes\n\n| Mode | What it does | Mic |\n|------|-------------|-----|\n| **Companion** | Reacts to everything, voice permissions, wake word | On |\n| **Permissions Only** | Silent until a permission arrives | On |\n| **Companion (No Mic)** | Reacts and speaks, click-only permissions | Off |\n| **Relay** (Experimental) | Speak directly to Claude CLI via tmux | On |\n\n## Evaluation\n\nEach prompt and response is scored from -1.0 to +1.0:\n\n| Dimension | What it measures |\n|-----------|-----------------|\n| **creativity** | Novel/surprising vs boring/obvious |\n| **soundness** | Technically solid vs flawed |\n| **ambition** | Bold undertaking vs trivial tweak |\n| **elegance** | Clean/clear vs hacky/convoluted |\n| **risk** | Could break things vs safe |\n\nDefaults to Apple Foundation Models (on-device, free, **designed for M3+**). Switch to Claude Haiku or Gemini Flash from the menu bar for higher-quality scoring. See [Data & Privacy](#data--privacy) for details.\n\n\nM1/M2 Mac? Use a cloud API key for snappy reactions
\n\nOn-device scoring runs slowly on M1/M2 (~30-60 seconds per eval). For instant results:\n\n**Gemini Flash (free tier, no credit card):**\n1. Go to [aistudio.google.com](https://aistudio.google.com/apikey) and sign in with Google\n2. Click Get API Key β Create API Key\n3. Paste it into Preferences β Intelligence β Gemini\n\n**Claude Haiku (~$0.001 per eval):**\n1. Go to [console.anthropic.com](https://console.anthropic.com/settings/keys) and create an account\n2. Add a payment method (pay-as-you-go)\n3. Go to API Keys β Create Key\n4. Paste it into Preferences β Intelligence β Anthropic\n\n \n\n## Voice\n\n| What you say | What happens |\n|---|---|\n| \"ducky, refactor the auth module\" | Command sent to Claude Code |\n| \"yes\" / \"no\" (during permission) | Approves or denies |\n| \"always allow\" (during permission) | Applies the session-wide suggestion |\n| \"ducky, quit\" | Duck says goodbye |\n\n## Troubleshooting\n\n- **\"Claude Code not found\"** β [Install Claude Code](https://claude.com/download), then retry the plugin install.\n- **No mic permission dialog** β System Settings β Privacy & Security β Microphone β enable Duck Duck Duck.\n- **Duck not reacting** β Make sure the widget is running (duck in menu bar) and you have an active Claude session. Try `/reload-plugins`.\n- **Duck reacting slowly** β On M1/M2, on-device scoring takes 30-60s per eval. The duck IS working, just thinking. Switch to Gemini or Haiku in Preferences β Intelligence for instant reactions.\n- **Plugin not loading** β Start a new session. Hooks are cached at session start.\n- **Claude CLI asking for git / Xcode tools** β First-time CLI setup requires Xcode Command Line Tools. Install them when prompted, then run `sudo xcodebuild -license accept` in Terminal to accept the Apple license. Claude won't work until the license is accepted.\n\n## Data & Privacy\n\nBy default, Duck Duck Duck's intelligence is **fully contained to your machine**.\n\n| Component | Where it runs | Data sent externally |\n|-----------|--------------|---------------------|\n| **Apple Foundation Models** (default) | On-device | None. Private and free. Not used for training. |\n| **Voice (STT + TTS)** | On-device via Apple APIs | None. No audio leaves your machine. |\n| **Claude Haiku eval** (opt-in) | Anthropic API | Prompts/responses sent to Anthropic for scoring. |\n| **Gemini Flash eval** (opt-in) | Google API | Prompts/responses sent to Google for scoring. |\n\nIn Foundation Models mode (the default), the entire experience β eval scoring, voice recognition, text-to-speech, and the help system β runs privately on your machine at zero cost. [Apple does not use your interactions to train Foundation Models.](https://machinelearning.apple.com/research/introducing-apple-foundation-models)\n\n**M1/M2 note:** On-device scoring is designed for M3+ and runs slowly on older hardware. The app detects this and recommends switching to a cloud provider. If you do, your prompts and responses will be sent externally for scoring (see below). Voice and audio always stay on-device regardless.\n\n**Optional cloud eval:** If you switch to Haiku or Gemini, your prompts and responses are sent directly to the respective API for evaluation. You provide your own API key at your own discretion. Keys are stored locally in `~/Library/Application Support/DuckDuckDuck/` and are never shared. Costs are between you and the API provider. There is no intermediary server β the widget calls the APIs directly.\n\n## Project Structure\n\n```\nwidget/ SwiftUI macOS app β the duck's brain\nplugin/ Claude Code plugin β hooks that connect to the widget\nplugin-gemini/ Gemini CLI extension β experimental\nfirmware/ Arduino firmware for hardware duck (ESP32-S3, Teensy 4.0)\nscripts/ Shell scripts (tmux launcher, hook helpers)\nhardware/ CAD (SolidWorks, STEP) and EE (Eagle, Fusion 360) source files\nbambu/ Bambu Duck β sibling product, see \"Other ducks\" below\n```\n\n## Other ducks in the family\n\nTwo distinct products live in this repo. They share lineage (the squelchy\nchirp synth, the servo idle behaviors, the same opinionated rubber-duck\nvoice) but they're built around different hosts:\n\n| | **Claude Code Duck** (this README) | **Bambu Duck** ([`bambu/`](bambu/)) |\n|---|---|---|\n| **What it watches** | Your Claude Code session on a Mac | A Bambu 3D printer |\n| **Host required** | macOS 26 + Claude Code/Desktop | Nothing β runs standalone |\n| **Talks via** | Embedded HTTP+WS server on the Mac | ElevenAgents conversational AI |\n| **Hardware** | Optional Teensy/ESP32 connected over USB | ESP32-S3 with mic + speaker, WiFi onboard |\n| **Setup surface** | App + plugin install on your Mac | Captive portal: WiFi + Bambu login on phone |\n| **License/repo** | Same repo, MIT software / CERN-OHL-P-2.0 hardware | Same repo, same licenses |\n\nIf you're here for the **Mac/Claude Code duck**, keep reading.\n\nIf you're looking for **the 3D-printer companion that needs no computer**: head to [`bambu/`](bambu/) and start with [`bambu/README.md`](bambu/README.md), or skip straight to **[the in-browser flasher](https://ideo.github.io/Rubber-Duck/flash/)** if you already have a duck in hand.\n\n### Hardware (Optional)\n\nConnect the [IDEO Duck, Duck, Duck](https://duck-duck-duck.edges.ideo.com/) or build your own. The widget auto-detects boards via USB. All parts print without supports β pop off the bed and assemble.\n\n- [`hardware/README.md`](hardware/README.md) β enclosure CAD, 3D print settings, assembly instructions, PCB design\n- [`firmware/README.md`](firmware/README.md) β supported boards, wiring, flashing, serial protocol\n\n#### Button Controls\n\nThe duck has a single button with two modes:\n\n**Normal Mode** (default) β volume control:\n\n| Action | What happens |\n|--------|-------------|\n| **Press** | Announces current volume level |\n| **Press again within 15s** | Cycles to next level: Quack! (75%) β Normal (50%) β Indoor Voice (25%) β Whisper (5%) β Silent (0%) |\n| **Hold 2 seconds** | Enter Demo Mode |\n| **Hold 5 seconds** | Enter bootloader (for firmware updates) |\n\nSilent mode (0%) mutes all audio β the widget shows subtitles instead. Volume changes on the duck sync to the widget, and vice versa.\n\n**Demo Mode** β show off the duck's personality:\n\n| Action | What happens |\n|--------|-------------|\n| **Press** | Cycles through 6 emotion presets (Impressed β Excited β Skeptical β Nervous β Disgusted β Bored), each with a unique chirp and spoken quip |\n| **Hold 2 seconds** | Exit back to Normal Mode |\n| **Hold 5 seconds** | Enter bootloader |\n| **30s no button press** | Auto-exits to Normal Mode |\n\nOn boot, the duck plays a startup chirp and says \"I'm awake.\" When the widget connects, it says \"Connected.\"\n\n## Development\n\n```bash\ncd widget && make run # release build + launch\ncd widget && make sandbox # re-sign with App Sandbox entitlements\ncd widget && make debug # debug build in terminal\ncd widget && make dmg # notarized DMG for distribution\n```\n\nSee [`plugin/README.md`](plugin/README.md) for hook details and [`CLAUDE.md`](CLAUDE.md) for architecture notes.\n\n## License\n\nSoftware (widget, plugin, scripts) β [MIT License](LICENSE)\n\nHardware (firmware, PCB, enclosure) β [CERN Open Hardware Licence v2 β Permissive](firmware/LICENSE)\n\n## Limitation of Liability\n\nTHE ITEM AND THE SOFTWARE ARE PROVIDED AS-IS, AND IDEO MAKES NO WARRANTIES OF ANY KIND, WHETHER EXPRESS, IMPLIED, OR STATUTORY, INCLUDING ANY WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS, PRODUCT LIFE OR LONGEVITY, OR FITNESS FOR A PARTICULAR PURPOSE, ALL OF WHICH ARE EXPRESSLY DISCLAIMED. USE OF THE ITEM AND THE SOFTWARE IS AT YOUR OWN RISK.\n\nTO THE FULLEST EXTENT ALLOWED UNDER APPLICABLE LAW, IN NO EVENT SHALL IDEO BE LIABLE FOR ANY INCIDENTAL, CONSEQUENTIAL, SPECIAL, OR INDIRECT DAMAGES OF ANY KIND, INCLUDING WITHOUT LIMITATION THOSE RELATING TO LOSS OF USE, LOST PROFITS OR REVENUES, INTERRUPTION OF BUSINESS, AND/OR COST OF PROCUREMENT OF SUBSTITUTE GOODS, REGARDLESS OF (A) THE FORM OF ACTION, WHETHER IN CONTRACT, TORT OR OTHERWISE, (B) WHETHER OR NOT FORESEEABLE, AND (C) EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.Β IDEO'SΒ AGGREGATE LIABILITY FOR ANY DAMAGES OR LIABILITY CAUSED BY THE ITEM OR THE SOFTWARE SHALL NOT EXCEED $50 IN EACH CASE.\n",
"bytes": 12630,
"sha": "da2e98dab4c154ff00e9665fcd89ec0c918dba1180d5cc85a9932ef415014f55",
"repo_slug": "ideo/rubber-duck",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_ideo_rubber_duck_2f75d11a/readme"
}