Skip to main content
This guide covers common issues you might encounter with Rubber Duck and how to resolve them.

​
Daemon Issues

​
Duck Commands Hanging

If duck commands hang or don’t respond:
1

Check daemon status

Run the diagnostic command:
duck doctor
This checks:
  • Daemon reachability
  • Pi binary installation
  • API key configuration
  • Socket connection
2

Restart the daemon

Kill and restart the daemon:
pkill -f duck-daemon
duck
The daemon will automatically restart when you run any duck command.
3

Check the daemon log

View the daemon log for errors:
cat ~/Library/Application\ Support/RubberDuck/duck-daemon.log
Look for error messages indicating what went wrong.

​
Daemon Not Responding

If the daemon won’t start or immediately crashes:
Check if the socket file exists but isn’t responding:
ls -l ~/Library/Application\ Support/RubberDuck/duck.sock
If present but daemon isn’t running:
rm ~/Library/Application\ Support/RubberDuck/duck.sock
pkill -f duck-daemon
duck
The PID file might be stale from a previous crash:
rm ~/Library/Application\ Support/RubberDuck/duck-daemon.pid
duck
If metadata.json is corrupted, rename it to reset:
mv ~/Library/Application\ Support/RubberDuck/metadata.json ~/Library/Application\ Support/RubberDuck/metadata.json.backup
duck
Warning: This will lose your session list. Sessions files are preserved in pi-sessions/.

​
Microphone Permissions

​
Voice Not Activating

If pressing Option+D doesn’t start recording:
1

Check microphone permission

Open Settings → Permissions and verify microphone access is granted.
2

Grant permission

If permission is denied:
  1. Click “Open Settings” next to Microphone
  2. Find Rubber Duck in the list
  3. Enable microphone access
  4. Restart Rubber Duck
3

Verify the hotkey

Settings → General → ActivateEnsure the hotkey is set (default: Option+D) and not conflicting with another app.
If the Rubber Duck menu bar icon disappears: Press Option+Shift+D to open Settings directly. This works even when the icon isn’t visible. To restore the icon:
  1. Quit Rubber Duck completely
  2. Check System Settings → Control Center → Menu Bar Only
  3. Relaunch Rubber Duck

​
Pi Binary Issues

​
Pi Not Found

If duck doctor shows “Pi not found”:
1

Install Pi globally

npm install -g @mariozechner/pi-coding-agent
2

Install Pi in the CLI directory

cd /path/to/rubber-duck/cli
npm install
3

Set the binary path manually

export RUBBER_DUCK_PI_BINARY="/custom/path/to/pi"
duck doctor

​
Pi Version Mismatch

If you see warnings about Pi version compatibility: 
npm install -g @mariozechner/pi-coding-agent@latest
Then restart the daemon: 
pkill -f duck-daemon
duck

​
API Key Issues

​
No API Key Configured

If duck doctor shows “No API keys found”:
1

For the Rubber Duck app (voice)

  1. Open Settings
  2. Enter your OpenAI API key
  3. Key is stored in macOS Keychain
2

For the duck CLI (text)

Set the environment variable:
export OPENAI_API_KEY="sk-..."
duck doctor
Add to your shell profile to persist:
echo 'export OPENAI_API_KEY="sk-..."' >> ~/.zshrc

​
API Key Not Saving

If the API key doesn’t persist in Settings:
macOS may be blocking Keychain access. Check Console.app for errors:
  1. Open Console.app
  2. Filter for “Rubber Duck”
  3. Look for Keychain-related errors
Try resetting Keychain permissions:
  1. Open Keychain Access app
  2. Search for “Rubber Duck”
  3. Delete any existing entries
  4. Re-enter API key in Settings

​
Session Issues

​
Sessions Not Appearing

If duck sessions shows no sessions but you’ve created some: 
# Check metadata file
cat ~/Library/Application\ Support/RubberDuck/metadata.json

# Check Pi session files exist
ls ~/Library/Application\ Support/RubberDuck/pi-sessions/
If metadata.json is empty or corrupted: 
pkill -f duck-daemon
rm ~/Library/Application\ Support/RubberDuck/metadata.json
duck
Sessions in pi-sessions/ are preserved and can be reattached.

​
Session Stuck “Running”

If a session shows as “running” but isn’t responding: 
# Abort the session
duck abort session-name

# Or restart the daemon
pkill -f duck-daemon
duck

​
Can’t Switch Sessions

If duck use session-name fails:
1

Verify the session exists

duck sessions --all
2

Use the full session ID

Instead of the name, try the full session ID:
duck use abc123def456
3

Check for session name conflicts

If multiple sessions have similar names, use a more specific prefix or the full ID.

​
Performance Issues

​
Slow Response Times

If the agent is responding slowly:
Higher thinking levels increase latency:
echo $RUBBER_DUCK_PI_THINKING
Default is off for speed. If set to high or xhigh, responses will be slower.To disable extended thinking:
unset RUBBER_DUCK_PI_THINKING
pkill -f duck-daemon
duck
Larger models may be slower but more capable:
duck doctor
Look at the pi_model line to see which model is in use.To use a faster model:
export RUBBER_DUCK_PI_MODEL="gpt-4o-mini"
pkill -f duck-daemon
duck

​
High CPU Usage

If Rubber Duck is using excessive CPU:
1

Check running sessions

duck sessions --all
Look for unexpectedly running sessions.
2

Abort background sessions

duck abort session-name
3

Restart the daemon

pkill -f duck-daemon
duck

​
Network Issues

​
Connection to OpenAI Failed

If you see network errors:
1

Verify internet connection

curl -I https://api.openai.com
2

Check API key validity

Verify your key is active at platform.openai.com/api-keys
3

Check for proxy settings

If behind a corporate proxy, set:
export HTTPS_PROXY="http://proxy.example.com:8080"

​
CLI Installation Issues

​
duck Command Not Found

If duck isn’t in your PATH:
1

Check installation location

The CLI binary should be at:
ls /usr/local/bin/duck
Or if symlink failed:
ls ~/.local/bin/duck
2

Add to PATH

If in ~/.local/bin, add to your shell profile:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
3

Reinstall via Settings

Open Rubber Duck Settings → CLI Tools → Download/Reinstall

​
CLI Version Mismatch

If the app and CLI versions don’t match:
  1. Open Settings → CLI Tools
  2. Click “Update” if available
  3. Or click “Reinstall” to force download
The CLI version should match the app version.

​
Voice Output Issues

​
No Voice Output

If the agent responds in the terminal but doesn’t speak:
1

Check system volume

Ensure macOS volume isn’t muted.
2

Check voice session

Voice only plays for the active voice session (marked with ✓ in duck sessions).
duck sessions
duck use session-name
3

Check Rubber Duck app is running

pgrep -x "Rubber Duck"
If not running, launch from Applications.

​
Voice Cuts Off Mid-Sentence

If voice output stops unexpectedly:
  • Check if “Auto-abort on barge-in” is enabled
  • Ensure you’re not triggering the microphone inadvertently
  • Check for background noise that might activate VAD

​
Getting More Help

​
Collecting Diagnostic Information

1

Run duck doctor

duck doctor
Save the output.
2

Check the daemon log

cat ~/Library/Application\ Support/RubberDuck/duck-daemon.log
3

Check the app log

In Settings, click “Show Logs” to view the Rubber Duck app log.
4

List sessions

duck sessions --all --json

​
Reporting Issues

File issues at github.com/mblode/rubber-duck/issues Include:
  • Output of duck doctor
  • Relevant log excerpts (review for sensitive data first)
  • macOS version
  • Steps to reproduce

​
Clean Reinstall

For a complete reset:
This will delete all sessions and configuration. Export any important sessions first.
# Stop everything
pkill -f duck-daemon
pkill -x "Rubber Duck"

# Remove all data
rm -rf ~/Library/Application\ Support/RubberDuck/
rm /usr/local/bin/duck

# Reinstall
brew reinstall --cask rubber-duck
Launch Rubber Duck and set up your API key again.

Build docs developers (and LLMs) love

Get started for freeTalk to us