WhyCode

Understand every commit. Not just what changed — but why.

You just joined a team. You pull the repo. You run git log. You see:

a3f2c1d  fix: handle edge case
7b2e4f1  refactor: cleanup
9c1d3a2  temp: wip

What edge case? What cleanup? What WIP?

WhyCode reads your git diff and explains it — in plain language, structured as WHAT / WHY / RISK / IMPACT.

No more staring at diffs wondering what the original author was thinking.

Quick Demo

# Set your API key (one-time)
export DEEPSEEK_API_KEY=sk-xxx

# Analyze any commit — no install needed
npx why-code

🧠 WhyCode v0.3.0
──────────────────────────────

📋  Commit: a3f2c1d
📄  Files: 3 changed (+47 / -12 lines)

⚙️  WHAT
   Added null-check for expired subscription objects before
   processing payment. Removed deprecated retry logic.

💡  WHY
   Users with lapsed subscriptions were hitting a TypeError when
   the system tried to charge a null reference. This was causing
   500 errors in production.

⚠️  RISK
   Low — defensive check, no logic change to happy path

📦  IMPACT
   Affects payment processing module. Safe to deploy.

📊  CONFIDENCE
   85%

💰  Model: deepseek-chat | Tokens: 1200+180 | Cost: ~$0.0002

──────────────────────────────
✓  saved to .whycode/latest.md
✓  archived to .whycode/history/

Install

# One-time use — no install needed
npx why-code

# Global install
npm install -g why-code
whycode

API Keys

WhyCode requires an AI API key for analysis. Set one via environment variable:

export DEEPSEEK_API_KEY=sk-xxx   # Recommended — fast & cheap
# or
export OPENAI_API_KEY=sk-xxx     # GPT-4o mini

No API key? Use --mock for basic rule-based analysis:

npx why-code --mock

CLI Options

npx why-code                          Analyze last commit (HEAD~1 → HEAD)
npx why-code --staged                 Analyze staged changes
npx why-code --working                 Analyze unstaged working directory changes
npx why-code --commit abc123          Analyze a specific commit
npx why-code --last 5                 Analyze last 5 commits
npx why-code --range abc..def         Analyze diff between two commits
npx why-code --from main --to feature Analyze diff between branches
npx why-code --mock                   Rule-based analysis (no API key needed)
npx why-code --markdown               Output full Markdown report
npx why-code --help                   Show help
npx why-code --version                Show version

| Option | Short | Description | |---|---|---| | --staged | | Analyze staged (cached) changes | | --working | | Analyze unstaged working directory changes | | --commit <hash> | -c | Analyze a specific commit | | --last <n> | -n | Analyze last N commits | | --range <a..b> | -r | Analyze diff between two refs | | --from <ref> | | Start ref for range (use with --to) | | --to <ref> | | End ref for range (use with --from) | | --mock | | Use rule-based analysis without AI | | --markdown | -m | Output Markdown report to stdout | | --help | -h | Show help | | --version | -v | Show version |

Use Cases

Code review: Instead of reading 2,000 lines of diff, get a structured summary.

Onboarding: Understand a new codebase in minutes by running whycode on recent commits.

PR review: Use --range main..feature-branch to understand an entire pull request at once.

Debugging: When production breaks, check .whycode/history/ to see exactly what changed and why.

Team communication: Share .whycode/latest.md as a commit summary for your team.

How It Works

git diff → AI analysis → Structured report
                │
                ├── Terminal output (WHAT/WHY/RISK/IMPACT/CONFIDENCE)
                ├── .whycode/latest.md
                └── .whycode/history/YYYY-MM-DDTH...

Large diff handling: WhyCode uses a 3-tier strategy:

1. Full diff — if under 100KB, send everything
2. Smart truncation — keep the most-changed files, summarize the rest
3. File-level summary — for very large diffs (300KB+), send only file names and stats

Tech Stack

| Layer | Choice | Why | |---|---|---| | Runtime | Node.js 18+ (ESM) | Native fetch, top-level await | | Git | child_process | Zero dependencies | | AI | DeepSeek / OpenAI API | BYO key, no vendor lock-in | | Storage | Local fs | No database needed | | Dependencies | Zero | Installs in 1 second |

License

MIT