DEV Community: Shingirayi Innocent Mandebvu

🔮 Nostradiffmus: Predict Your Next Bug Before It Manifests

Shingirayi Innocent Mandebvu — Sun, 15 Feb 2026 19:26:22 +0000

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 copilot and gh copilot commands

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

CIberus: A Three-Headed ASCII Guardian for Your CI Pipeline

Shingirayi Innocent Mandebvu — Sat, 14 Feb 2026 20:43:12 +0000

What I Built

CIberus is a zero-dependency, terminal-native DevOps companion that monitors your repository's health and reflects it as a living ASCII creature -- a three-headed Cerberus that evolves, emotes, and suffers based on real CI signals.

The idea is simple: dashboards get ignored, Slack alerts get muted, and broken builds become background noise. But a visibly suffering three-headed guardian in your terminal? That gets attention.

Health signals it tracks:

GitHub Actions run status and conclusion (via gh run list)
Green streak length from recent CI history
Flaky test heuristic (success/failure transition count)
Code coverage from coverage-summary.json or lcov.info
Documentation freshness (commits since README.md was last touched)

5 evolution stages that reflect overall repo health:

Score	Stage	Description
0-39	Pup	Single head, small, struggling
40-59	Sentinel	Two heads, lean, alert
60-74	Gatekeeper	Three heads, muscular, gate base
75-89	Infernal Guardian	Three fierce heads, horns, armor plating, braille flames
90-100	Ascended Cerberus	Three majestic heads, braille wings, aura, pedestal

5 moods (calm, alert, worried, angry, critical) change the creature's facial expression, aura effects, and coloring in real time.

4 theme modes:

Mythic -- detailed pixel-art using Unicode block elements (█▓▒░▀▄▛▜) and braille characters (⣿⣷⢰⢾⣦⣄) for fine detail, fur texture, and flame effects. No emoji -- pure terminal-safe characters.
Minimal -- clean ASCII (/\_/\), 5-8 lines.
Corporate -- box-drawing status panels. Intentionally bland.
Chaos -- procedurally corrupts the mythic art with deterministic braille noise injection, seeded PRNG so watch mode doesn't flicker.

The mythic art uses a template composition system instead of duplicating full art for every mood. Body templates contain {EYES}, {MOUTH}, {SNOUT}, {AURA}, and {FLAME} tokens that get swapped per mood, keeping the codebase clean while supporting 25 visual combinations (5 stages x 5 moods) from just 5 body templates.

Core Commands

ciberus init              # Initialize config
ciberus status            # Render current health
ciberus watch --interval 30  # Live monitoring loop
ciberus theme set chaos   # Switch visual theme
ciberus copilot run       # Non-interactive Copilot analysis
ciberus copilot chat      # Interactive Copilot session with context

Demo

Repository: github.com/shingy/CIberus

Mythic Theme -- Ascended Cerberus (calm)

               ✧
   ⣠⣴⣿⣿    ✧  ✧  ✧    ⣿⣿⣦⣄
  ⣸⣿⣿⣿  ┌───┐┌─────┐┌───┐  ⣿⣿⣿⣇
  ⣸⣿⣿  █▛ ◕‿◕ ▜█▛ ◕‿◕ ▜█▛ ◕‿◕ ▜█  ⣿⣿⣇
  ⣹⣿⣿  █  ᴖᴖ  █  ᴖᴖ  █  ᴖᴖ  █  ⣿⣿⣏
   ⣹⣿  █▄ ─  ▄█▄ ─  ▄█▄ ─  ▄█  ⣿⣏
    ⢹   ██▓══════════════▓██   ⣏
  ░░░░░ █▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█ ░░░░░
  ░░░░░ █▓▓▓▓████████▓▓▓▓█ ░░░░░
  ░░░░░ █▓▓█▒▒▒▒▒▒▒▒▒▒█▓▓█ ░░░░░
  ░░░░░ █▒█▒▒   ▒▒   ▒▒█▒█ ░░░░░
  ░░░░ ▄▄▄▄     ▄▄     ▄▄▄▄ ░░░░
  ░░ ════════════════════════ ░░
     ════════════════════════

Mythic Theme -- Pup (calm)

       ✧
      ┌─────┐
     █▀ ◕‿◕ ▀█
     █  ᴖᴖ  █
     █▄ ─  ▄█
      ███████
      █▒█  █▒█
      ▄▄    ▄▄

Infernal Guardian (angry) -- with braille flames

     ⢰⢾⣿⣷⣆     ⢰⢾⣿⣷⣆     ⢰⢾⣿⣷⣆
      ✧        ✧        ✧
     ┌────┐  ┌─────┐  ┌────┐
    █▛ ◉_◉ ▜█▛ ◉_◉ ▜█▛ ◉_◉ ▜█
    █  ᴖᴖ  █  ᴖᴖ  █  ᴖᴖ  █
    █▄ ⨷  ▄█▄ ⨷  ▄█▄ ⨷  ▄█
     ██▓══════════════▓██
       █▓▓▓▓▓▓▓▓▓▓▓▓▓▓█
       █▓▓▓▓██████▓▓▓▓█
       █▓▓█▒▒▒▒▒▒▒▒█▓▓█
       █▒█▒▒    ▒▒█▒▒█▒█
      ▄▄▄▄      ▄▄▄▄▄▄▄
    ═══════════════════════

Full status output

CIberus

  [creature art rendered in color]

  CIberus is calm. The gates are secure.

  Stage: Gatekeeper
  ████████████████░░░░ 78/100

  Signals
  CI:                completed/success
  Green streak:      5
  Flaky transitions: 1
  Coverage:          85%
  Docs freshness:    3 commits since README.md
  Branch:            main

  Wins:
    + Latest CI run passed
    + Coverage is 85%

My Experience with GitHub Copilot CLI

CIberus has first-class Copilot CLI integration baked into its command structure. The ciberus copilot subcommands bridge the gap between passive health monitoring and active remediation:

How the integration works

ciberus copilot check -- verifies the standalone copilot CLI is installed and authenticated. This validates the toolchain before attempting any AI-assisted workflows.
ciberus copilot prompt -- generates a context-rich remediation prompt from live repo metrics. It pulls the current branch, CI status, green streak, flaky transitions, coverage percentage, and docs freshness, then wraps them into a structured prompt asking for prioritized fixes and exact terminal commands.
ciberus copilot run -- sends that prompt directly to copilot CLI in non-interactive mode. CIberus builds the full argument list (-p <prompt> --stream off -s), handles auth errors gracefully, and prints the AI response. You can pass --model gpt-5 or --allow-all-tools flags through.
ciberus copilot chat -- opens an interactive Copilot session (copilot -i <prompt>) pre-seeded with the same repo context, so you can have a back-and-forth conversation about what to fix.

The workflow in practice

The typical loop is:

ciberus status           # See health at a glance
ciberus copilot run      # Get AI-powered fix suggestions
# ...apply fixes...
ciberus status           # Watch the creature evolve

This turns Copilot CLI from a general-purpose assistant into a DevOps-aware one. Instead of asking "what's wrong with my repo?" and providing context manually, CIberus collects the signals, formats the context, and hands it off. The creature's mood tells you when to ask for help; the Copilot integration tells you what to do about it.

Development experience

During the build itself, I used Copilot CLI to scaffold shell command wrappers, debug gh run list JSON parsing edge cases, and iterate on the scoring algorithm. The copilot CLI's ability to understand terminal context made it particularly useful for testing spawnSync argument patterns and validating ANSI escape sequences across different terminal emulators.

The project is zero-dependency (Node.js 18+ only, no npm packages) and all 20 tests pass with node --test.

How I Used GitHub Copilot CLI to Make Git 10x Less Scary

Shingirayi Innocent Mandebvu — Tue, 10 Feb 2026 16:50:51 +0000

What I Built

I built Hermes 🪽 — an AI-powered Git CLI that turns natural language into safe, explainable Git operations.

Honestly? I built this because I was tired of Git anxiety. You know that feeling when you're about to run git rebase or resolve a conflict and you're like... "please don't break everything"? Yeah, that feeling.

Git is incredibly powerful, but it's also unforgiving. Even experienced devs regularly mess up rebases, panic during conflicts, or forget what state their repo is in. I wanted something that could stand beside me and say "here's what's happening, here's what's safe, and here's why."

But here's where it gets interesting: I didn't just want another Git wrapper. I wanted something that actually learns from your project, tracks how much time it saves you, and proves its value with data. Because let's be real — if a tool can't show me it's making me more productive, why use it?

Key features:

🧠 Intent-first commands — "sync my branch" instead of memorizing flags
📊 Built-in analytics — See exactly how much time you're saving
🛡️ Safety by default — Shows you commands before running them
🔄 Workflow shortcuts — Turn 50+ commands into 5 per day
🎯 Context-aware — Learns your project's patterns and conventions

Demo

Live on npm: https://www.npmjs.com/package/hermes-git
GitHub: https://github.com/simandebvu/hermes-cli

Installation

npm install -g hermes-git

Real-World Examples

Starting a new feature:

 $ hermes start "oauth2 authentication"
🚀 Starting new task...
📍 Base branch: main
🌿 New branch: feature/oauth2-authentication
💭 Creating branch from clean state ensures no unexpected commits. Safe to proceed.

    $ git checkout main
    $ git pull
    $ git checkout -b feature/oauth2-authentication

✅ Successfully created and switched to feature/oauth2-authentication

Understanding a conflict:

$ hermes conflict explain

🔍 Analyzing conflicts...
⚔️  Conflicts detected:
    • src/auth/login.ts

🔍 Analysis:
  Main branch refactored authentication to use async/await
  patterns, while your feature branch added comprehensive
  error handling with try-catch blocks.

Both changes are valuable:
  - Main: Modern async patterns improve code readability
  - Your branch: Error handling prevents crashes

Recommended strategy: Merge both approaches
  1. Keep the async/await structure from main
  2. Integrate your error handling improvements
  3. Test the combined implementation

Checking your productivity:

$ hermes stats

╔══════════════════════════════════════════════════════╗
║  Hermes Efficiency Report - Last 30 Days           ║
╚══════════════════════════════════════════════════════╝
⏱️  Time Saved:        12.4 hours
🚀  Commands Run:      123 (85% reduction)
📈  Efficiency Gain:   +34% compared to raw Git

Top Time Savers:
1. workflow      ████████████ 45x
2. start         ████████     32x
3. sync          ██████       24x

💡 Weekly projection: ~2.9 hours saved
💡 Monthly projection: ~12.4 hours saved

Quick Walkthrough

Here's what a typical workflow looks like:

Morning sync: hermes workflow daily-sync # Fetch all, show status, suggest actions
Start new work: hermes start "user profile refactor" # Smart branch creation
Save progress: hermes wip -m "checkpoint" # Decides commit vs stash
Sync with main: hermes sync # Evaluates rebase vs merge
Ready for PR: hermes workflow pr-ready # Fetch, rebase, force-with-lease push

Each command explains why it's doing what it's doing. No surprises, no hidden magic.

My Experience with GitHub Copilot CLI

This project fundamentally depends on GitHub Copilot CLI — it's not just a feature, it's the reasoning engine behind every decision Hermes makes.

The Integration Journey

When I started, I thought: "Okay, I'll use Copilot CLI to generate some commands." But I quickly realized it could do so much more.

Here's what I learned:

The new Copilot CLI is a game-changer

Context is everything
Instead of just asking "what Git command should I run?", I learned to give Copilot CLI rich context:

```typescript
   const prompt = `
    Repository State:
    - Branch: feature/auth
    - Status: 5 files changed, 2 conflicts
    - Behind main: 12 commits
    - Working directory: dirty

   User wants to: "sync my branch without losing work"

   Evaluate whether rebase or merge is safer given:
       - Branch has unpushed commits
       - Conflicts detected
       - Working directory not clean

   Provide step-by-step commands with safety explanations;
```

The AI gives much better guidance when it knows the full picture.

I built Hermes on this new architecture:

const response = await execAsync('copilot -p "${prompt}" --model claude-sonnet-4.5 --allow-all-tools --silent');

JSON responses need love

Copilot CLI sometimes wraps JSON in markdown code blocks:

  { "commands": [...] }

I wrote a helper to strip these automatically:

 function stripMarkdownCodeBlock(text: string): string {
    const match = text.match(/```

(?:json)?\s*([\s\S]*?)\s*

```/);
    return match ? match[1].trim() : text.trim();
  }

Small detail, but crucial for reliability.

Safety first, always

I configured Copilot CLI with --allow-all-tools for automation, but Hermes always shows commands before executing:

 displayStep(command);  // Show user what's about to run
  await executeGitCommand(command);  // Then execute

This way, Copilot can reason about tools and operations, but users stay in control.

What Surprised Me

The quality of explanations is incredible. When you ask Copilot CLI to explain why a conflict happened, it doesn't just say "files changed in both branches" — it gives you context:

"Main refactored authentication to async/await, while your branch added error handling. Both changes are valid.
Here's how to merge them..."

That level of understanding is what makes Hermes actually useful instead of just another Git wrapper.

It's fast. Really fast. 2-5 seconds to analyze a complex repo state and generate a plan. Fast enough that itdoesn't break your flow.

It learns patterns. When you use Hermes with your project's config, Copilot CLI picks up on your naming conventions, workflow preferences, and starts giving better suggestions over time.

The "Aha!" Moment

The moment I knew this worked was when I was deep in a messy merge conflict, ran hermes conflict explain, and the AI said:

"This conflict happened because you renamed a function while someone else refactored its logic. Both changes are
improvements. Keep the new name and the refactored logic."

I thought: "Holy crap, that's exactly what a senior dev would tell a junior in a code review." That's when I realized we're not building tools anymore — we're building mentors.

Challenges & Solutions

Challenge 1: Copilot CLI isn't always in PATH
Solution: Use full path (~/.local/bin/copilot) or check multiple locations

Challenge 2: Response format inconsistency
Solution: Always parse with fallbacks. If JSON fails, show the raw text to the user

Challenge 3: Rate limits and tokens
Solution: Used conservative prompts, cache repo state, batch operations

What I'd Tell Other Builders

Don't just wrap commands — Use Copilot CLI to reason about state and make decisions
Show your work — Let users see what the AI suggested and why
Trust but verify — Copilot CLI is smart, but parse responses defensively
Context > cleverness — A simple prompt with good context beats a clever prompt with no context
Make it fast — Use --silent mode and stream output when possible

The Impact

Since publishing Hermes:

Time saved: Users report 10-15 hours/month saved vs raw Git
Confidence boost: Devs try advanced Git features they avoided before
Learning tool: New developers learn Git concepts through explanations
Team alignment: Shared config means everyone follows the same patterns

The GitHub Copilot CLI isn't just powering Hermes — it's making Git accessible to everyone, from juniors to seniors.

Try It Yourself

  npm install -g hermes-git
  cd your-git-repo
  hermes init
  hermes plan "sync my branch safely"

Would love feedback, issues, or contributions: https://github.com/simandebvu/hermes-cli

Let's make Git less scary, together. 🪽

Heimdall 🛡️: The All-Seeing Code Guardian That Actually Fixes Your Problems

Shingirayi Innocent Mandebvu — Mon, 09 Feb 2026 15:12:13 +0000

Why "Heimdall"?

In Norse mythology, Heimdall is the all-seeing, all-hearing guardian who stands watch at the Bifrost—the rainbow bridge connecting the mortal realm to Asgard. His job?

To warn of danger before it arrives.

Just like the mythological guardian:

👁️ All-seeing — Analyzes every line of your code changes
🔊 All-hearing — Listens to your questions and concerns
⚡ Warns early — Detects security risks before they reach production
🛡️ Protects the bridge — Guards the path from development to deployment

Unlike the god who only warns, this Heimdall actually helps you fix the problems. All thanks to a new god in tech - copilot.

Heimdall ❤️ Copilot

Demo

https://youtu.be/_OmFY-ruVBs

What I Built

Heimdall is a conversational code security assistant that combines transparent risk analysis with GitHub Copilot CLI's agentic AI. It's the only tool that takes you from problem detection to shipping the fix:

# Install in seconds
npm install -g heimdall-security-cli
# The complete workflow
heimdall summary              # 1. Detect risks
heimdall risks --fix          # 2. Generate secure code
heimdall describe --ai        # 3. Write PR description
heimdall review --interactive # 4. Answer your questions

What makes it unique:

🔍 Detects security risks with transparent, deterministic scoring (no black-box AI)
🛡️ Generates secure code fixes using Copilot CLI (not just warnings!)
✍️ Writes PR descriptions automatically from your changes
💬 Answers your questions in real-time through multi-turn conversation
📊 Shows its work with evidence receipts (trust, then enhance)

The key insight: Most tools tell you what's broken. Heimdall tells you how to fix it—then writes your PR for you.

🚀 Why This Showcases Copilot CLI's Agentic Capabilities

Heimdall demonstrates three core agentic capabilities that wouldn't be possible without Copilot CLI:

Stateful Multi-Turn Conversation

Traditional tools give one-shot analysis. Heimdall uses Copilot CLI's conversation harness to maintain context across multiple questions:

  You: What's the risk?
  Copilot: SQL injection in line 42...

  You: Show me the fix
  Copilot: [Provides secure implementation]

  You: Write a test
  Copilot: [Generates test code]

  You: What if someone tries to bypass this?
  Copilot: [Explains attack vectors and additional protections]

Each response builds on previous context—true agentic behavior.

Code Generation (Not Just Analysis)

Heimdall doesn't just detect problems—it generates solutions:

Fix suggestions:heimdall risks --fix → Writes secure code
PR descriptions: heimdall describe --ai → Writes complete markdown
Test generation: Interactive mode → Creates test code on-demand
Documentation: Explains the "why" behind every suggestion

This generative capability transforms Heimdall from a "checker" into a "collaborator."

Repository-Aware Intelligence

Copilot CLI understands your codebase patterns:

Knows your project structure and conventions
Recognizes patterns across your files
Provides context-specific insights (not generic warnings)
Adapts suggestions to your tech stack

When it says "This doesn't follow your auth pattern," it actually knows your auth pattern.

Graceful Degradation (Hybrid Architecture)

Heimdall works without Copilot CLI (deterministic analysis only), but becomes powerful with it:

Without Copilot: "Password detected on line 47"
With Copilot: "Password detected on line 47"
+ secure code fix
+ explanation
+ test suggestion
+ answers to your questions

This "trust then enhance" approach is more credible than pure AI tools.

🏗️ How I Built It

Architecture: Deterministic → Agentic Pipeline

Heimdall's unique approach combines two philosophies:

Phase 1: Deterministic Base (Transparent & Trustworthy)
// src/core/analysis/

Risk scoring based on keyword patterns, file types, change complexity
Visual heatmap showing which files are riskiest
Evidence "receipts" showing exactly why something was flagged
No black-box AI—you see the reasoning

Phase 2: Agentic Layer (Powered by Copilot CLI)
// src/core/copilot/

Uses standalone copilot CLI for code generation
Maintains session context across questions
Adapts responses to user's level (junior/security/PM)
Generates actionable code, not just suggestions

Tech Stack

Language: TypeScript (strict mode)
CLI Framework: Commander.js
Git Operations: simple-git
AI Integration: GitHub Copilot CLI (2026 standalone version)
Testing: Vitest (29 passing tests)
Terminal UI: Chalk, gradient-string, ora, boxen, figlet

Key Implementation Decisions

Three-Tier Copilot Detection
The 2026 Copilot CLI changed from a gh extension to a standalone tool, so I added flexible detection (checked in this order):

Standalone copilot command (2026+)
Wrapper gh copilot
Legacy gh extension (backwards compatibility)

Readline Async Handling
Interactive mode needed careful async control to avoid overlapping prompts:

   rl.on("line", async (input) => {
     rl.pause(); // Stop processing new input
     const answer = await askCopilot(question);
     console.log(answer);
     rl.resume(); // Resume after response
     rl.prompt();
   });

Risk Receipts

     ✓ Matched keyword: "password" (auth.ts:47)
     ✓ SQL modification (queries.sql:89)
     ✓ Token change (session.ts:34)
     → Score: 7/10 (3 signals, high confidence)

Users trust what they can verify.

💪 Challenges I Overcame

Making AI Trustworthy
- Pure AI tools have a trust problem. Users don’t know why something is flagged. My solution was to flip the order: Deterministic signals first, AI second
  1. Show concrete evidence (keywords, patterns, file changes)
  2. Calculate a transparent risk score
  3. Display the receipts
  4. Then offer AI enhancement This “show your work first” approach builds credibility before asking users to trust AI suggestions.
Professional Polish Under a Tight Deadline
- With only 5 days until deadline, I focused on high-impact visual improvements:
  - ASCII banner with gradients (2 hours)
  - Dramatic verdict box (1 hour)
  - Animated spinners with intentional timing (1 hour)
  - Gradient color transitions (1 hour)

🎨 What Makes Heimdall Unique

The Only Tool That Completes The Loop

	Traditional Static Analysis	AI-Only Tools	Heimdall
Finding	“Potential SQL injection”	“AI says risky”	Evidence + context
Signal	❌	❌	✅
Understanding	Static report, done	One-shot summary	Multi-turn dialogue
Signal	❌	❌	✅
Fixes	None provided	Generic advice	Repo-aware secure code
Signal	❌	❌	✅
PR Workflow	Manual PR writing	No integration	Auto-generated PRs
Signal	❌	❌	✅
Follow-up	No follow-up	Can’t ask questions	Interactive Q&A
Signal	❌	❌	✅

Deterministic + Agentic = Trust + Power

Most tools are either:

Deterministic but limited (grep for "password", show warning)
AI-powered but opaque (black box says "risky", no explanation)

Heimdall combines both:

Deterministic signals → Build trust with transparent evidence
Agentic AI → Provide power with code generation & conversation

This hybrid approach is more credible than either alone.

Try It Yourself


  # Install Heimdall
  npm install -g heimdall-security-cli

  # Install Copilot CLI (required for AI features)
  npm install -g @github/copilot

  # Verify everything works
  heimdall doctor

  That's it. No cloning repos, no building, no complex setup.

  Quick Start

  # In any git repository with changes:

  # 1. Analyze risks
  heimdall summary

  # 2. Get AI fix suggestions
  heimdall risks --fix

  # 3. Generate PR description
  heimdall describe --ai --write

  # 4. Ask questions interactively
  heimdall review --interactive

  # 5. Analyze a GitHub PR
  heimdall pr 123 --interactive

Commands Reference

Command	Purpose	Use case
`summary`	Risk overview	Pre-commit
`risks --fix`	Findings + fixes	Post-scan
`describe --ai`	PR text	PR creation
`review --interactive`	Q&A	Code understanding
`pr <number>`	PR analysis	Reviews
`explain --audience <type>`	Audience-specific output	Stakeholders
`doctor`	Environment check	Debugging

Final Thoughts

Building Heimdall taught me that agentic AI isn't about replacing human judgment—it's about augmenting the workflow. The deterministic base gives you confidence to trust the tool, and the Copilot CLI layer helps you act on that confidence faster.

The mythological Heimdall warned of danger.
This Heimdall warns, explains, fixes, and ships.

If you're tired of security tools that just list problems without helping you solve them, give Heimdall a try. It's designed to take you from "Oh no, what's wrong?" to "Fixed, tested, documented, and shipped."

This is what agentic AI looks like in practice.

Acknowledgments

Built for the GitHub Copilot CLI Challenge 2026. Thanks to:

GitHub for Copilot CLI and this amazing challenge
The DEV community for inspiration and feedback
GitCoach, Linux Compass, Git Cluster RAG for setting the bar high
Every developer who's felt PR review anxiety (this is for you)