Duck 🦆

An AI pair programmer that hooks into your git commit workflow to write drafts, ask clarifying questions when your code changes are ambiguous, and act as a complete guardian for your Git workflow.

Why Duck? (Solving Git's Everyday Frustrations)

The common thread across almost every well-known Git complaint isn't that Git is powerful — it's that Git gives you zero visual state awareness and lets you run destructive commands with no safety net.

duck wraps around your normal Git workflow to intercept these dangerous, blind spots:

1. The Detached HEAD Trap

The Frustration: Checking out a commit silently puts you in detached HEAD. If you commit here, your work can be lost forever. The Solution: duck goto <ref> explicitly warns you about detached HEAD and offers to create a branch first.

2. Destructive History Rewriting

The Frustration: git push --force and git reset --hard permanently wipe commits with no built-in undo. The Solution: duck force-push and duck reset automatically create a lightweight recovery tag before executing the destructive operation, ensuring you always have an undo button.

3. Fetch vs. Pull Confusion

The Frustration: Developers often can't tell what pull is about to do to their local commits before it happens. The Solution: duck fetch gives you a plain-English readout of incoming commits (read-only), and duck pull explicitly states what strategy it will use before merging.

4. Overwhelming Merge Conflicts

The Frustration: Merge conflicts dump all conflicting files at once, filled with raw <<<<<<< markers and no explanation. The Solution: duck resolve walks you through one conflict at a time, using AI to explain why the two branches diverged in plain English.

Installation

npm install -g duck-ai-cli

Setup

Set up a Groq API key (used for fast, free AI inference):

export DUCK_GROQ_API_KEY="your-api-key"

Or use Ollama locally if you prefer offline generation.

Basic Usage

Run duck manually before committing:

git add .
duck commit

Or hook it into your git flow automatically:

duck install-hook

Full Documentation

Duck is a complete guardian for your Git workflow, preventing bad state and explaining the unexplainable. To see the full suite of 21+ commands—and see beautiful visual previews of exactly how they lessen developer frustration—check out our Full Documentation.

Configuration

You can configure Duck by creating a .duckrc file in your home directory or project directory:

{
  "provider": "groq",
  "model": "llama3-8b-8192",
  "style": "auto",
  "duckPersonality": "sarcastic"
}