This is a submission for the GitHub Copilot CLI Challenge
What I Built
Nostradiffmus is a developer tool that reads your git diffs and predicts what could go wrong—before you push. It combines pattern recognition with AI-powered analysis from GitHub Copilot CLI to identify likely bug categories, then delivers both a dramatically styled "prophecy" and actionable technical advice.
Think of it as a pre-mortem for your code changes: playful enough to be fun, smart enough to catch real risks.
The Problem It Solves
As developers, we often:
- Move fast and miss subtle regressions
- Refactor async logic without adjusting error paths
- Modify state without rethinking side effects
- Introduce edge cases when changing validation
- Delete tests and forget what they were protecting
Nostradiffmus acts as an early warning system—not replacing tests or static analysis, but adding a layer of intelligent pattern recognition that learns what kinds of changes historically lead to bugs.
How It Works
# Install globally
npm install -g nostradiffmus
# Analyze your staged changes
nostradiffmus --staged
# Get JSON output for CI integration
nostradiffmus --staged --json
# Try different tones
nostradiffmus --tone sarcastic
Example Output:
🔮 Consulting the sacred diff scrolls...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
THE PROPHECY OF DOOM
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Hark! I peer into the abyss of your commit,
And lo, darkness stirs within...
⚡ A race condition sleeps in asynchronous shadows,
Waiting for the precise moment to awaken.
⚡ Promises made but not kept—error paths abandoned,
Like a bridge half-built over turbulent waters.
⚠ Likely Bug Category: Async Race Conditions
🧠 Advice: Review promise chains and shared state updates.
📊 Confidence: 82%
Key Features
🎭 Five Tone Variations:
- Tragic: Shakespearean warnings
- Cryptic: Mysterious oracle prophecies
- Sarcastic: Witty developer humor
- Biblical: Ancient prophecy style
- Clinical: Dry technical analysis
🔍 Bug Categories Detected:
- Async Race Conditions
- State Drift
- Null/Undefined Access
- Validation Edge Cases
- Off-By-One Errors
- Incomplete Refactors
- Test Coverage Gaps
- Configuration Regressions
⚙️ Advanced Features:
- Git hook support (pre-commit, pre-push)
- JSON output for CI/CD integration
- Large diff handling with smart truncation
- Configurable thresholds via environment variables
- Debug mode for troubleshooting
🧪 Quality:
- 23 passing unit tests
- TypeScript with strict mode
- CI/CD via GitHub Actions
- Comprehensive documentation
Demo
🔗 Links
- npm Package: https://www.npmjs.com/package/nostradiffmus
- GitHub Repository: https://github.com/simandebvu/nostradiffmus
- Live Examples: See examples/ directory
📸 Screenshots
Tragic Tone Analysis:
JSON Output for CI:
{
"predictedBugCategory": "AsyncStateRace",
"confidence": 0.82,
"signals": [
"New async function introduced",
"Shared mutable state detected",
"Error handling removed or modified"
],
"advice": "Review promise chains and shared state updates...",
"metadata": {
"diffSizeChars": 2847,
"diffSizeKB": 2.8,
"wasTruncatedForCopilot": false,
"filesChanged": 3
}
}
Different Tones Showcase:
See complete examples in the examples directory:
- Tragic, Cryptic, Sarcastic, Biblical, Clinical tones
- All 8 bug category predictions
- Real-world diff scenarios
🎬 Quick Demo
# Install
npm install -g nostradiffmus
# Make some changes
echo "const x = await fetchData()" >> app.js
# Stage them
git add app.js
# Get your prophecy
nostradiffmus --staged --tone cryptic
My Experience with GitHub Copilot CLI
GitHub Copilot CLI transformed how I built Nostradiffmus. Here's how it impacted my development:
🤖 AI-Enhanced Diff Analysis
The core feature of Nostradiffmus is using GitHub Copilot CLI to analyze diffs and provide context-aware bug predictions. I integrated it in src/integrations/copilot.ts:
// Copilot CLI interprets the diff semantically
const prompt = [
"Analyze this git diff and provide a concise bug-risk advisory in 1-2 sentences:",
truncatedDiff
].join("\n\n");
const result = spawnSync("gh", ["copilot", "--", "-p", prompt, ...flags]);
What this enables:
- Natural language understanding of code intent
- Context-aware risk assessment beyond pattern matching
- Semantic analysis of architectural changes
- Suggestions that consider the broader codebase impact
💡 Development Workflow Impact
1. Rapid Prototyping
Copilot CLI helped me quickly explore different approaches:
- Testing various prompt strategies for diff analysis
- Experimenting with different output formats
- Validating edge case handling
2. Error Handling Strategy
I learned to build robust fallbacks. Copilot CLI might not always be available (auth issues, timeouts, network problems), so I implemented:
// Graceful fallback to heuristics
if (!success) {
debugLog("copilot failed; falling back to heuristics");
return { enrichment: undefined };
}
3. Smart Truncation
Large diffs can timeout Copilot. I added intelligent truncation:
- Defaults to 4KB for Copilot analysis
- Preserves file headers and critical context
- Metadata tracks whether truncation occurred
- Configurable via
NOSTRADIFFMUS_COPILOT_CHARS
🎯 Key Learnings
1. Timeouts Matter
Copilot CLI calls can be slow on large diffs. I implemented:
- Configurable timeout (default 35 seconds)
- Multiple retry strategies
- Fallback to both
copilotandgh copilotcommands
2. Both Standalone and gh Wrapper
I discovered users might have different Copilot setups:
const hasStandaloneCopilot = hasCommand("copilot", ["--help"]);
const hasGhCopilot = hasCommand("gh", ["copilot", "--help"]);
// Try both methods
if (hasStandaloneCopilot) {
attempts.push(runPrompt("copilot", promptArgs));
}
if (hasGhCopilot) {
attempts.push(runPrompt("gh", ["copilot", "--", ...promptArgs]));
}
3. Environment Variables for Control
Users should control AI features:
# Disable Copilot if needed
NOSTRADIFFMUS_USE_COPILOT=0 nostradiffmus --staged
# Adjust timeout
NOSTRADIFFMUS_COPILOT_TIMEOUT_MS=60000 nostradiffmus --staged
🚀 Impact on Quality
GitHub Copilot CLI elevated Nostradiffmus from "pattern matcher" to "intelligent advisor":
- Before Copilot: Basic regex patterns detecting keywords
- With Copilot: Context-aware analysis understanding code semantics
Real Example:
Without Copilot:
Signal detected: async keyword added
Category: AsyncStateRace
With Copilot:
Detected async state modification without synchronization.
The new promise chain accesses shared state that may be
modified by concurrent operations. Consider adding locks
or ensuring atomic updates.
🎨 Creative Use Case
Nostradiffmus combines AI analysis with creative output. Copilot's semantic understanding feeds into five different "tone" generators—proving that AI tooling can be both useful and fun.
📚 What I Learned
- AI as a Layer, Not a Crutch: Always have fallbacks
- Prompt Engineering Matters: Small prompt tweaks = big output differences
- Performance is Critical: Timeouts, retries, and truncation are essential
- User Control: Let users disable AI features if needed
- Debug Visibility: Debug mode showing Copilot attempts was invaluable
🔮 Future with Copilot
I'm excited to expand Copilot integration:
- Historical analysis: "This pattern failed before in commit abc123"
- Team learning: Aggregate predictions across a codebase
- PR comment bot: Automatic prophecies on GitHub PRs
- Accuracy tracking: Did the prediction come true?
Why This Matters
Developer tools shouldn't just be functional—they should be delightful. Nostradiffmus proves you can build something that:
- Solves a real problem (catching bugs early)
- Uses AI thoughtfully (Copilot enrichment with fallbacks)
- Makes developers smile (dramatic prophecies)
- Integrates seamlessly (git hooks, CI/CD, JSON output)
It's the kind of tool I wanted to exist, so I built it. And GitHub Copilot CLI made it smarter than I could have built alone.
Try It Yourself
npm install -g nostradiffmus
nostradiffmus --staged --tone tragic
I'd love to hear what prophecies you receive! 🔮
Repository: https://github.com/simandebvu/nostradiffmus
npm Package: https://www.npmjs.com/package/nostradiffmus
License: MIT
Built with ❤️ and 🔮 by Shingirayi Mandebvu and Seshan Pillay
Top comments (0)