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

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

1. 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)

2. 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();
      });
   

3. 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

1. 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.

2. 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

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:

1. Deterministic signals → Build trust with transparent evidence
2. 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

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)