Heimdall 🛡️

Built for the GitHub Copilot CLI Challenge

"Static analysis shows you the problem. Heimdall converses until you've solved it."

A conversational code security assistant that showcases GitHub Copilot CLI's agentic capabilities through:

• 🤖 Interactive multi-turn dialogue (not just one-shot AI)
• 🔍 GitHub PR integration (authenticated, context-aware analysis)
• 📊 Deterministic signals (transparent risk scoring + evidence)
• 🎯 Adaptive intelligence (from junior devs to security experts)
• ✨ Polished terminal UI (gradient colors, animations, dramatic reveals)

🚀 What Makes This Special?

Heimdall isn't just analyzing your code — it's talking to you about it.

Traditional static analysis tools give you a report and leave. Heimdall uses GitHub Copilot CLI's agentic harness to become a conversational security expert that:

• 💬 Answers your questions about code changes in real-time
• 🔍 Analyzes GitHub PRs directly with full context
• 🤖 Adapts to your needs — from junior devs to security teams
• 🎯 Generates secure code fixes with AI-powered suggestions
• ✍️ Writes PR descriptions automatically from your changes

$ heimdall review --interactive

  _  _  ___  ___  __  __  ___    _    _     _
 | || || __||_ _||  \/  ||   \  /_\  | |   | |
 | __ || _|  | | | |\/| || |) |/ _ \ | |__ | |__
 |_||_||___||___||_|  |_||___//_/ \_\|____||____|
         🛡️  Your Code Security Guardian

╔══════════════════════════════════════════╗
║ HEIMDALL VERDICT                         ║
║ ⚠️  REVIEW CAREFULLY                      ║
║──────────────────────────────────────────║
║ Risk: ███████░░░ 7/10                    ║
║ Blast Radius: Medium                     ║
║ Confidence: 85%                          ║
╚══════════════════════════════════════════╝

🎯 Entering interactive mode...

You: What's the biggest risk here?
Copilot: The SQL query in db/queries.sql concatenates user input.
         This creates a SQL injection vulnerability. Here's a fix...

You: Show me how to write a test for that
Copilot: [provides actual test code]

You: What about the session changes?
Copilot: The session timeout was increased to 7 days. This increases...

Why this matters: Most tools stop at detection. Heimdall continues the conversation until you understand and can fix the issue.

✨ Complete Workflow: Detection → Fix → Ship

Heimdall is the only tool that takes you from problem detection to shipping the fix:

1️⃣ Detect Risks (Deterministic)

$ heimdall summary
# Shows risk score, heatmap, evidence receipts

2️⃣ Get AI Fix Suggestions (NEW! 🔥)

$ heimdall risks --fix

╔═══════════════════════════════════════╗
║  AI-Suggested Fixes                  ║
╚═══════════════════════════════════════╝

🔴 Risk: password keyword detected
──────────────────────────────────────────
**Quick Fix:** Use environment variables
**Secure Code:**
  const password = process.env.DB_PASSWORD;
  if (!password) throw new Error('Missing DB_PASSWORD');
**Why:** Prevents credentials from being committed to git
──────────────────────────────────────────

3️⃣ Generate PR Description (NEW! 🔥)

$ heimdall describe --ai --write

✔ Generating AI-powered PR description (3.2s)

╔════════════════════════════════════════════════╗
║  AI-Generated PR Description                 ║
╚════════════════════════════════════════════════╝

## Summary
Fixes security vulnerability where database credentials were
hardcoded. Moves sensitive values to environment variables.

## Changes
- Replaces hardcoded password with env var lookup
- Adds validation for required env vars
- Updates README with setup instructions

## Testing
1. Set DB_PASSWORD env var
2. Run connection test: npm run test:db
3. Verify error thrown when env var missing

✔ Saved to PR_DESCRIPTION.md
  Ready to paste into your GitHub PR!

4️⃣ Ask Questions (Interactive)

$ heimdall review --interactive
You: How do I test this securely?
Copilot: [Provides test strategy...]

This is the complete loop: Detect → Understand → Fix → Document → Ship

🎯 The Agentic Difference

Only Possible With Copilot CLI's Agentic Capabilities

| What Traditional Tools Do | What Heimdall Does (Powered by Copilot CLI) | |---------------------------|---------------------------------------------| | ❌ "Potential SQL injection found" | ✅ Explains the risk, shows the fix, writes the test | | ❌ Static report, no follow-up | ✅ Conversational — ask until you understand | | ❌ Generic warnings | ✅ Context-aware — knows your repo patterns | | ❌ Manual PR analysis | ✅ heimdall pr 123 — analyzes with full GitHub context | | ❌ One-size-fits-all output | ✅ Adapts to audience: junior, security, PM |

Core Innovation: Deterministic + Agentic

   Git Diff
      ↓
┌──────────────────────────────────┐
│  1. DETERMINISTIC ANALYSIS       │  ← Always runs, no API calls
│     • Risk scoring (0-10)        │     Credible, transparent signals
│     • File heatmap               │
│     • Risk receipts (evidence)   │
│     • Test suggestions           │
└──────────────┬───────────────────┘
               ↓
┌──────────────────────────────────┐
│  2. AGENTIC ENHANCEMENT          │  ← Copilot CLI agentic harness
│     • Interactive Q&A            │     Conversational, adaptive
│     • Fix suggestions            │
│     • GitHub PR context          │
│     • Multi-turn dialogue        │
└──────────────────────────────────┘

The result: Credible risk signals that explain themselves, then stick around to answer your questions.

⚡ TL;DR for Challenge Judges

What is this? A conversational code security assistant that combines deterministic risk analysis with Copilot CLI's agentic capabilities.

What makes it special?

1. Deterministic signals first — Risk score, heatmap, evidence (transparent, trustworthy)
2. Then agentic conversation — Ask questions until you understand + can fix issues
3. GitHub-native — Analyzes actual PRs with full repository context
4. Adaptive — Same tool serves junior devs, security teams, and PMs

Key demo flow:

# 1. Analyze your changes
$ heimdall review --interactive

HEIMDALL VERDICT: ⚠️ REVIEW CAREFULLY
Risk: ███████░░░ 7/10
[Shows heatmap with evidence]

# 2. Conversation begins
You: What's the biggest risk?
Copilot: [Explains with repo context]

You: Show me a fix
Copilot: [Provides code]

You: Write a test
Copilot: [Generates test]

# 3. Or analyze GitHub PRs directly
$ heimdall pr 123 --interactive
[Full PR context + conversation]

Why this showcases Copilot CLI:

• ✅ Multi-turn dialogue with maintained context
• ✅ Repository-aware code generation
• ✅ GitHub integration (authenticated PR access)
• ✅ Agentic adaptation to user questions
• ✅ Couldn't exist without the agentic harness

Production value:

• Solves real developer pain (PR review anxiety)
• Deterministic base ensures reliability
• Graceful fallbacks (works without Copilot, better with it)
• 24 TypeScript files, proper architecture

🎬 Quick Demo

1. Interactive Security Review

$ heimdall review --interactive

HEIMDALL VERDICT: ⚠️ REVIEW CAREFULLY
Risk: ███████░░░ 7/10

REVIEW HEATMAP
auth/session.ts       ██████████  HIGH
db/queries.sql        ███████░░░  MED

You: Why is auth/session.ts flagged as high risk?
Copilot: It modifies token expiration logic. If this isn't validated
         correctly, attackers could extend their session indefinitely.

You: Show me how to fix it
Copilot: [provides secure implementation with explanation]

You: What test should I write?
Copilot: Test with an expired token and verify it's rejected...

2. GitHub PR Analysis

$ heimdall pr 847 --interactive

📦 Repository: your-org/payment-service
🔍 Analyzing PR #847: "Add payment retry logic"

HEIMDALL VERDICT: 🔴 HIGH RISK
Risk: █████████░ 9/10
Detected: Payment processing + retry logic + error handling

You: What happens if the payment succeeds but the retry still fires?
Copilot: Good catch! That's a double-charge risk. Here's how to add...

3. Audience-Adapted Output

# For junior developers
$ heimdall explain --audience junior
[Minimal jargon, educational context]

# For security teams
$ heimdall risks
[Security-focused analysis with threat detection]

# For product managers
$ heimdall explain --audience pm
[User impact, deployment considerations]

⚡ Copilot CLI Agentic Features

🤖 Multi-Turn Conversational Analysis

Powered by Copilot CLI's agentic capabilities, Heimdall maintains context across questions:

$ heimdall review --interactive

You: What's risky here?
Copilot: [explains auth changes]

You: How do I test that?
Copilot: [provides test code]

You: What about edge cases?
Copilot: [suggests specific scenarios]

The agentic harness enables:

• Context retention across questions
• Code-level fix suggestions
• Test generation on demand
• Adaptive explanations

🔗 Native GitHub Integration

Direct PR analysis using gh CLI + Copilot context:

$ heimdall pr 123

Heimdall fetches:

• PR metadata (title, author, state)
• Full diff with context
• Branch information
• Then analyzes with Copilot

Result: You're not analyzing a diff in isolation — you're analyzing a PR in your repository with full organizational context.

👥 Adaptive Personas

Same code, three perspectives:

| Persona | What Changes | |---------|--------------| | --audience junior | "This adds input validation to prevent SQL injection attacks (when malicious data tries to access the database)" | | --audience security | "Threat: SQL injection via unsanitized user input. Attack surface: POST /api/users endpoint. Mitigation: Parameterized queries" | | --audience pm | "This prevents a security issue where user-submitted data could expose sensitive information. No user-facing changes." |

🎯 Evidence-Based Risk Scoring

Unlike AI black boxes, Heimdall shows its work:

RISK RECEIPTS
✓ Matched keyword: "password" in auth/utils.ts:47
✓ Matched pattern: SQL file modified (db/queries.sql)
✓ High-impact area: Authentication system
✓ Diff size: 247 lines (medium blast radius)

Confidence: HIGH (4 strong signals)

Deterministic + Transparent = You can trust the verdict.

📸 Screenshot-Worthy Output

$ heimdall wow

Ultra-compact mode for sharing:

• Verdict + top 5 heatmap in <10 lines
• Actually looks good on Twitter/Slack
• No paragraph soup

🧪 Actionable Test Suggestions

Not "test this" — exactly what to test:

| Detected Pattern | Suggested Test | |-----------------|----------------| | Auth changes | "Test authentication with expired/invalid tokens" | | SQL modifications | "Test with SQL injection payloads" | | Payment logic | "Test idempotency - same request twice should not double-charge" |

⚡ Fast + Safe

• 🔍 Read-only — Never modifies code or git history
• ⚡ Instant base analysis — Deterministic heuristics, no API wait
• 🛡️ Security-focused — Built for review, not code generation

🎯 The Before/After Story

Before Heimdall (Traditional Static Analysis)

$ some-linter analyze

Warning: Potential SQL injection in db/queries.sql
Warning: Sensitive data exposure in auth/utils.ts
Warning: Missing error handling

# Now what? 😕
# - Which is most critical?
# - How do I fix them?
# - What should I test?
# - Is this a real issue or false positive?

After Heimdall (Deterministic + Agentic)

$ heimdall review --interactive

HEIMDALL VERDICT: ⚠️ REVIEW CAREFULLY
Risk: ███████░░░ 7/10 (HIGH confidence - 4 strong signals)

HEATMAP                          RISK RECEIPTS
db/queries.sql    ██████████ HIGH  ✓ SQL file modified
                                   ✓ String concatenation detected
auth/utils.ts     ███████░░░ MED   ✓ Matched keyword: "password"

THE ONE TEST I'D DEMAND: Test SQL injection payloads

You: Show me the SQL injection issue
Copilot: [explains line 47 with context]

You: How do I fix it?
Copilot: [provides parameterized query code]

You: Write a test for that
Copilot: [generates test code]

# ✅ Concrete understanding
# ✅ Actual fix code
# ✅ Test code ready to paste
# ✅ Confidence to merge

The difference: Static analysis tells you there's a problem. Heimdall works with you until you've solved it.

🚀 Installation

Prerequisites: Copilot CLI Setup

Heimdall uses GitHub Copilot CLI for interactive analysis and AI-enhanced insights.

Install Copilot CLI (choose one method):

# Recommended: npm (all platforms)
npm install -g @github/copilot

# OR: Homebrew (macOS/Linux)
brew install copilot-cli

# OR: WinGet (Windows)
winget install GitHub.Copilot

# Verify installation
copilot --version
# OR
gh copilot --version

Optional: GitHub CLI (for heimdall pr command):

# 1. Install GitHub CLI
brew install gh  # or: https://cli.github.com/

# 2. Authenticate
gh auth login

Note: Heimdall uses copilot explain for code explanations and interactive Q&A. The tool works without Copilot (deterministic analysis only), but interactive mode and AI enhancement require it.

Install Heimdall

# Clone and install
git clone <repo-url> heimdall-cli
cd heimdall-cli
npm install

# Build and link globally
npm run build
npm link

# Verify installation
heimdall doctor  # Checks git, gh, and Copilot CLI setup

Usage

Quick Start (The Agentic Way)

# 1. Review your changes conversationally
heimdall review --interactive

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

# 3. Quick risk check
heimdall summary

# 4. AI-enhanced analysis
heimdall risks --ai

🌟 Signature Commands (Copilot CLI-Powered)

heimdall review --interactive

The conversation command — Analyze your changes, then ask questions until you understand.

$ heimdall review --interactive

[Shows deterministic analysis: verdict, heatmap, receipts]

🎯 Entering interactive mode...
You: [Ask anything about the changes]
Copilot: [Answers with context]

Commands: help | context | exit

When to use: When you need to understand risks deeply, get fix suggestions, or generate tests.

heimdall pr <number> [--interactive]

The GitHub integration command — Analyze actual PRs from your repository.

$ heimdall pr 847 --interactive

📦 Repository: your-org/payment-service
🔍 Fetching PR #847: "Add payment retry logic"

[Shows PR metadata + analysis]

🎯 Interactive mode enabled
You: What happens if the payment API is slow?
Copilot: [Analyzes retry logic in context]

When to use: Reviewing someone else's PR, onboarding to a PR, or deep security review.

📊 Standard Analysis Commands

# Quick risk summary (verdict + heatmap)
heimdall summary

# Deep analysis with all context
heimdall analyze

# Security-focused review
heimdall risks

# Human-readable explanation
heimdall explain

# With audience adaptation
heimdall explain --audience junior     # Educational, minimal jargon
heimdall explain --audience security   # Threat model focus
heimdall explain --audience pm         # User impact focus

🎨 Utility Commands

# Generate PR description markdown
heimdall describe > pr.md

# Ultra-compact screenshot mode
heimdall wow

# Check environment setup
heimdall doctor

🚀 AI Enhancement Flags

# Add Copilot insights to any analysis
heimdall summary --ai
heimdall risks --ai
heimdall analyze --ai

# One-shot enhancement (no interactive mode)
# Shows: Deterministic analysis + AI insights section

Interactive Mode (Copilot-Powered)

The review --interactive command starts a conversational session where you can ask Copilot CLI anything about your code changes:

heimdall review --interactive

Example questions:

• "What security concerns should I watch for?"
• "Explain the changes in auth/session.ts"
• "How can I fix the SQL injection risk?"
• "What tests should I add for this?"
• "Show me a secure implementation of this function"

Note: Responses typically take 20-30 seconds for complex queries with full diff context. This ensures thorough, context-aware analysis from Copilot CLI.

Type help for commands, exit to quit.

GitHub PR Integration

Analyze pull requests directly from GitHub using the gh CLI:

# Analyze a PR
heimdall pr 123

# With interactive Q&A
heimdall pr 123 --interactive

Requirements:

• GitHub CLI installed: brew install gh
• Authenticated: gh auth login
• Run from within a GitHub repository

### Heimdall+ (AI-Enhanced Mode)

When you add the `--ai` flag, Heimdall uses **GitHub Copilot CLI** to enhance analysis:

```bash
heimdall summary --ai

What changes:

• Deterministic analysis runs first (verdict, heatmap, receipts, test suggestion)
• Then adds AI-enhanced insights from Copilot CLI
• Clearly labeled as "Heimdall+ (Copilot-enhanced)"
• Shows attribution: "✨ Enhanced with GitHub Copilot CLI"

Requirements:

• Install Copilot CLI: npm install -g @github/copilot (or brew install copilot-cli)
• See installation instructions above for other methods

Graceful fallback: If Copilot isn't available, you'll see a message and get deterministic analysis only.

### Options

All analysis commands support custom git references:

```bash
heimdall summary --base origin/develop --head feature/new-auth

Output Modes

| Mode | Command | Best For | Output Length | Includes | |------|---------|----------|---------------|----------| | Standard | summary, analyze, risks | Pre-merge review | Full report | Verdict, heatmap, 4 sections, receipts, test | | Screenshot | wow | Social sharing | <10 lines | Verdict, top 5 heatmap, key signals | | PR Description | describe | GitHub PRs | Markdown | Formatted for copy-paste | | AI PR Description | describe --ai | AI-written PRs | Markdown | Summary, changes, testing, notes | | Fix Suggestions | risks --fix | Get secure code | Code examples | Risk + AI-suggested fixes | | AI-Enhanced | Add --ai to any | Deep analysis | Standard + AI section | All above + Copilot insights |

Command Reference

┌─────────────┬──────────────────────────────────────────────────┐
│ Command     │ What It Does                                     │
├─────────────┼──────────────────────────────────────────────────┤
│ summary     │ Quick 4-section risk report (default)            │
│ analyze     │ Deep analysis with full context                  │
│ explain     │ Human-readable explanation                       │
│ review      │ Interactive code review with Copilot CLI         │
│ pr <number> │ Analyze GitHub PR by number                      │
│ risks       │ Security-focused risk assessment                 │
│ describe    │ GitHub-ready PR description (markdown)           │
│ wow         │ Ultra-compact screenshot mode                    │
│ doctor      │ Check environment setup                          │
├─────────────┼──────────────────────────────────────────────────┤
│ Flags       │                                                  │
├─────────────┼──────────────────────────────────────────────────┤
│ --ai        │ Add Copilot CLI enhancement (Heimdall+)         │
│ --fix       │ Generate AI-powered fix suggestions (risks)     │
│ --write     │ Save output to file (describe)                  │
│ --interactive│ Start interactive Q&A session (review/pr)      │
│ --audience  │ junior / security / pm (for explain)            │
│ --base      │ Base git reference (default: origin/main)       │
│ --head      │ Head git reference (default: HEAD)              │
└─────────────┴──────────────────────────────────────────────────┘

🏗️ Architecture: Deterministic → Agentic Pipeline

┌─────────────────────────────────────────────────────────────────┐
│                    INPUT SOURCES                                │
├─────────────────────────────────────────────────────────────────┤
│  • Git Diff (local changes)                                     │
│  • GitHub PR (via gh CLI + auth)                                │
│  • Uncommitted changes (working directory)                      │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│          PHASE 1: DETERMINISTIC ANALYSIS (No API calls)         │
├─────────────────────────────────────────────────────────────────┤
│  ✓ Risk Scoring Engine    → 0-10 score + confidence level      │
│  ✓ File Heatmap           → Visual risk bars per file          │
│  ✓ Pattern Matching       → Keywords, file paths, size         │
│  ✓ Risk Receipts          → Transparent evidence trail         │
│  ✓ Test Suggestions       → ONE critical test for patterns     │
│                                                                 │
│  Result: Credible signals you can trust (same input = same     │
│          output, no AI hallucinations)                          │
└────────────────────────────┬────────────────────────────────────┘
                             ▼
                    ┌────────────────┐
                    │  Render Report │
                    └────────┬───────┘
                             │
            ┌────────────────┼────────────────┐
            ▼                ▼                ▼
     ┌──────────┐    ┌──────────┐    ┌──────────┐
     │ Standard │    │   wow    │    │ describe │
     │  Report  │    │(compact) │    │   (PR)   │
     └──────────┘    └──────────┘    └──────────┘
            │                │                │
            └────────────────┼────────────────┘
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│       PHASE 2: AGENTIC ENHANCEMENT (Copilot CLI Harness)       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  OPTION A: One-Shot Enhancement (--ai flag)             │  │
│  ├──────────────────────────────────────────────────────────┤  │
│  │  • Calls gh copilot explain <context>                   │  │
│  │  • Adds AI insights section to report                   │  │
│  │  • Clearly labeled: "Heimdall+ (Copilot-enhanced)"      │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  OPTION B: Interactive Mode (--interactive flag)        │  │
│  ├──────────────────────────────────────────────────────────┤  │
│  │  1. Shows deterministic report (gives you signals)      │  │
│  │  2. Enters readline REPL                                │  │
│  │  3. Each question → gh copilot explain with context     │  │
│  │  4. Maintains conversation state                        │  │
│  │  5. Continues until user types 'exit'                   │  │
│  │                                                          │  │
│  │  Example flow:                                          │  │
│  │  You: "Why is this risky?"                              │  │
│  │  Copilot: [explains with repo context]                  │  │
│  │  You: "Show me a fix"                                   │  │
│  │  Copilot: [generates code]                              │  │
│  │  You: "Write a test"                                    │  │
│  │  Copilot: [generates test code]                         │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│  Key Agentic Capabilities:                                     │
│  • Multi-turn dialogue with maintained context                 │
│  • Repository-aware code generation                            │
│  • Adaptive responses based on question complexity             │
│  • On-demand test/fix generation                               │
│  • Cross-file context understanding                            │
└─────────────────────────────────────────────────────────────────┘

Why This Architecture Wins

1. Deterministic First — Builds trust with transparent, reproducible signals
2. Agentic Second — Uses credible signals as conversation starters
3. Human-Guided — You control the exploration depth
4. Context-Preserved — Each question builds on previous answers
5. Repository-Aware — Copilot CLI understands your codebase patterns

Quick Decision Tree

Need to...
│
├─ Review a PR before merging?
│  └─→ heimdall summary
│
├─ Write a PR description?
│  └─→ heimdall describe > pr.md
│
├─ Share results on social media?
│  └─→ heimdall wow
│
├─ Explain to non-technical stakeholder?
│  └─→ heimdall explain --audience pm
│
├─ Deep security analysis?
│  ├─→ heimdall risks
│  └─→ Add --ai for AI-enhanced threat analysis
│
├─ Ask questions about changes?
│  └─→ heimdall review --interactive
│
├─ Review a GitHub PR?
│  ├─→ heimdall pr 123
│  └─→ Add --interactive for Q&A
│
├─ Onboard junior developer?
│  └─→ heimdall explain --audience junior
│
└─ Check if tool is working?
   └─→ heimdall doctor

How It Works

1. Git Diff Extraction — Uses simple-git to fetch unified diffs
   • Committed changes: Compares branches (e.g., origin/main..HEAD)
   • Uncommitted changes: Automatically includes working directory and staged changes
   • Smart fallback: If no committed diff, analyzes uncommitted changes
2. Risk Scoring — Deterministic heuristics assign weighted scores:
   • Critical keywords: password, secret, token, api_key (weight: 2)
   • High-risk patterns: auth, session, database, sql (weight: 1.5)
   • File paths: auth/session files, SQL/shell scripts get higher scores
   • Diff size: Large changesets increase risk and blast radius
3. Heatmap Generation — Per-file risk analysis with visual bars
4. Risk Receipts — Transparent evidence of what triggered each flag
5. Test Suggestion — Recommends ONE critical test based on patterns
6. Report Rendering — Beautiful terminal output with chalk + boxen
7. AI Enhancement (Optional) — With --ai flag:
   • Calls GitHub Copilot CLI for deeper insights
   • Adds explanation of changes and intent
   • Provides security-focused analysis
   • Clearly labeled and attributed

Deterministic by default — All base analysis is keyword-based heuristics (no AI required).

AI optional — Add --ai for Copilot-enhanced insights when you need deeper analysis.

Always transparent — AI sections are clearly labeled as "Heimdall+ (Copilot-enhanced)" with attribution.

💡 Why Heimdall Exists

The Problem

Code review is terrifying:

• Is this auth change safe?
• What if I miss a SQL injection?
• What should I even test?
• How do I explain this to my manager?

Traditional tools don't help:

• Static analyzers: Wall of warnings, no context
• AI summarizers: Vague platitudes, no receipts
• Copilot alone: Need to know what to ask

The Solution: Deterministic Signals + Agentic Conversation

Heimdall gives you specific signals:

Risk: ███████░░░ 7/10 (HIGH confidence)
Matched keyword: "password" in auth/utils.ts:47

Then lets you explore:

You: What's wrong with line 47?
Copilot: [explains the issue]
You: How do I fix it?
Copilot: [provides code]
You: Write a test
Copilot: [generates test]

The result: You understand the risk AND know how to fix it.

Who Benefits

| Role | Pain Point | How Heimdall Helps | |------|-----------|-------------------| | Junior Dev | "I don't know what's risky" | Verdict + heatmap show exactly where to focus | | Senior Dev | "I need to review 10 PRs today" | Quick triage with heimdall summary, deep dive with --interactive | | Security Team | "Did anyone check for SQL injection?" | heimdall risks + receipts prove it was checked | | Team Lead | "How do I explain this to PM?" | heimdall explain --audience pm translates to user impact | | Open Source Maintainer | "Reviewing PRs from strangers" | heimdall pr 123 --interactive analyzes + lets you ask about intent |

🏆 Why This Wins the Copilot CLI Challenge

The Core Innovation: Credible Signals + Agentic Conversation

Most tools are either:

• Deterministic but dumb (grep for "password", show warning)
• AI-powered but opaque (black box says "risky", trust us)

Heimdall bridges both worlds:

STEP 1: DETERMINISTIC ANALYSIS (Always runs, no API)
├─ Risk scoring with evidence
├─ File heatmap with visual bars
├─ Transparent receipts
└─ Specific test suggestions

        ↓ [Base report gives you something to talk about]

STEP 2: AGENTIC ENHANCEMENT (Copilot CLI harness)
├─ You: "Why is this risky?"
├─ Copilot: [Explains with context]
├─ You: "Show me the fix"
├─ Copilot: [Provides code]
└─ Continues until you're satisfied

What's Only Possible With Copilot CLI's Agentic Harness

1. Multi-Turn Contextual Dialogue

You: What's the risk in auth/session.ts?
Copilot: Token expiration changes could allow session extension attacks

You: How severe is that?
Copilot: Critical if the tokens are used for admin access. Let me check
         the user roles... [analyzes codebase] This affects admin sessions.

You: Give me a fix
Copilot: [provides actual code with explanation]

You: And a test for that
Copilot: [writes test code]

Without the agentic harness: You'd get one static response and be done.

With Heimdall + Copilot CLI: The conversation continues until you understand and can act.

2. GitHub-Native PR Analysis

$ heimdall pr 847

What Heimdall does:

1. Uses gh CLI to fetch PR #847 with authentication
2. Gets full context: title, author, description, diff, branch names
3. Analyzes the diff with deterministic signals
4. Provides interactive session in the context of that specific PR

Why Copilot CLI matters here:

• Authenticated GitHub access
• Repository-aware analysis
• Understands organizational patterns
• Can reference other files in the repo

3. Adaptive, Context-Aware Responses

Heimdall uses Copilot CLI's repository understanding:

You: Is this pattern safe?
Copilot: In your codebase, I see you use JWT tokens in auth/jwt.ts.
         The pattern here is consistent with that approach, but you're
         missing the expiration check you use elsewhere.

The agentic harness enables:

• Cross-file context awareness
• Pattern recognition across your codebase
• Organizational best practice understanding
• Adaptive explanations based on skill level

Technical Deep Dive: How We Use the Agentic Harness

Not just calling gh copilot explain once — we're leveraging the full agentic capabilities:

// Interactive REPL with maintained context
export async function startInteractiveSession(context: InteractiveContext) {
  // Creates readline interface for multi-turn dialogue
  const rl = readline.createInterface({ ... });

  rl.on('line', async (input: string) => {
    // Each question includes:
    // 1. Original diff context
    // 2. Previous analysis
    // 3. Current question
    // Copilot CLI's agentic harness maintains state
    const answer = await askCopilot(question, context);
  });
}

Key integration points:

• src/core/copilot/interactive.ts — Multi-turn dialogue engine
• src/core/github/pr.ts — GitHub PR fetching with auth
• src/core/copilot/enhancer.ts — Context-aware enhancement
• Context passing between turns for coherent conversation

What Heimdall Demonstrates

✅ Agentic conversation — Multi-turn dialogue with maintained context ✅ GitHub integration — Native PR analysis with authentication ✅ Adaptive output — Changes based on audience and questions ✅ Code generation — Provides fixes and tests on demand ✅ Repository awareness — Understands your codebase patterns ✅ Human-in-the-loop — Deterministic signals guide agentic exploration

This isn't just "tool with AI features" — it's agentic code review companion that couldn't exist without Copilot CLI's harness.

🏆 Feature Comparison: What You Can Only Do With Heimdall

┌───────────────────────────┬──────────────┬────────────────┬──────────────┬───────────────┐
│ Capability                │ Static       │ AI PR          │ Copilot      │ Heimdall      │
│                           │ Analyzers    │ Summarizers    │ CLI Alone    │ (This Tool)   │
├───────────────────────────┼──────────────┼────────────────┼──────────────┼───────────────┤
│ Multi-turn conversation   │      ❌      │       ❌       │      ✅      │      ✅       │
│ GitHub PR integration     │      ❌      │      ⚠️        │      ⚠️      │      ✅       │
│ Repository-aware context  │      ❌      │       ❌       │      ✅      │      ✅       │
│ Code-level fix suggestions│      ❌      │       ❌       │      ✅      │      ✅       │
│ AI-generated PR descriptions│   ❌      │       ❌       │      ❌      │      ✅       │
│ Risk scoring (0-10)       │      ⚠️      │       ❌       │      ❌      │      ✅       │
│ Visual file heatmap       │      ❌      │       ❌       │      ❌      │      ✅       │
│ Evidence/receipts         │      ⚠️      │       ❌       │      ❌      │      ✅       │
│ Test generation           │      ❌      │       ❌       │      ✅      │      ✅       │
│ Confidence scoring        │      ❌      │       ❌       │      ❌      │      ✅       │
│ Deterministic base        │      ✅      │       ❌       │      ❌      │      ✅       │
│ Transparent (shows work)  │      ⚠️      │       ❌       │      ⚠️      │      ✅       │
│ Audience adaptation       │      ❌      │       ❌       │      ❌      │      ✅       │
│ Screenshot-worthy output  │      ❌      │       ❌       │      ❌      │      ✅       │
└───────────────────────────┴──────────────┴────────────────┴──────────────┴───────────────┘

Legend: ✅ Yes  ❌ No  ⚠️ Partial/Limited

What Makes Heimdall Unique

| Other Tools Say | Heimdall Does | |----------------|---------------| | "Potential SQL injection" | Shows exact line + evidence, then converses: "Here's the fix + test" | | "This looks risky" (vague) | Risk: ███████░░░ 7/10 (specific score + confidence + receipts) | | One-shot analysis, done | Starts conversation: "What would you like to know?" | | Analyzes diff in isolation | Fetches PR #123 from GitHub with full repo context | | Same output for everyone | Adapts to audience: junior, security, PM | | Black box AI | Deterministic signals first, then AI enhancement | | Wall of text | Visual heatmap + risk bars (actually screenshot-worthy) |

The Copilot CLI Advantage

Heimdall demonstrates Copilot CLI's agentic capabilities that aren't available in other tools:

✅ Stateful conversation — Context maintained across multiple questions ✅ Repository intelligence — Understands your codebase patterns ✅ GitHub integration — Authenticated PR access with full metadata ✅ Adaptive responses — Changes explanation depth based on questions ✅ On-demand code generation — Fixes and tests when you ask ✅ Human-guided exploration — Deterministic signals guide agentic dialogue

This is what "agentic" means: Not just AI that answers questions, but AI that works with you to solve problems.

🎯 Addressing the GitHub Copilot CLI Challenge

Challenge Goals We Address

1. "Showcase the agentic capabilities of GitHub Copilot CLI"

✅ Multi-turn conversational analysis — Not just one-shot Q&A, but dialogue that continues until you understand ✅ Context-aware responses — Copilot understands your repository, not just the diff ✅ Adaptive behavior — Changes explanation depth based on your questions ✅ On-demand generation — Provides fixes and tests when asked, not upfront

2. "Build something that couldn't exist without Copilot CLI"

✅ Interactive security review — Static analysis + conversation = new capability ✅ GitHub-native PR analysis — Authenticated PR fetching + agentic analysis ✅ Repository intelligence — Cross-file context awareness from Copilot's codebase understanding

3. "Demonstrate practical value"

✅ Solves real pain: Understanding code risks is hard; Heimdall makes it conversational ✅ Clear use cases: PR review, security audit, onboarding, documentation ✅ Production-ready: Deterministic base ensures reliable signals

Technical Innovation

Not just calling gh copilot explain once — we've built:

1. Interactive REPL (src/core/copilot/interactive.ts)

   • Maintains conversation context across questions
   • Passes diff + analysis + previous exchanges to each Copilot call
   • Enables multi-turn dialogue that builds understanding

2. GitHub Integration (src/core/github/pr.ts)

   • Uses gh CLI for authenticated PR fetching
   • Provides full PR context (metadata + diff) to Copilot
   • Enables repository-aware analysis

3. Hybrid Analysis (src/core/render/report.ts + src/core/copilot/enhancer.ts)

   • Deterministic signals guide agentic exploration
   • Risk scores/heatmaps give you specific questions to ask
   • AI enhancement adds depth without replacing transparency

What Judges Will See

Video Demo Flow:

1. heimdall review --interactive on a PR with auth changes
2. Deterministic analysis shows HIGH RISK verdict + SQL file in heatmap
3. Enter interactive mode: "What's the SQL injection risk?"
4. Copilot explains the exact line with context
5. Ask: "Show me a fix"
6. Copilot provides parameterized query code
7. Ask: "Write a test for that"
8. Copilot generates test code
9. Then: heimdall pr 123 --interactive to show GitHub integration

Key Differentiators:

• ✅ Solves real developer pain (PR review anxiety)
• ✅ Agentic conversation, not static output
• ✅ Shows work (transparent signals) + explains work (AI dialogue)
• ✅ Production-quality tool, not a toy demo

📚 Use Cases

For Individual Developers

Before opening a PR:

$ heimdall review --interactive
[Get risk assessment + ask questions about your changes]

Reviewing someone else's PR:

$ heimdall pr 847 --interactive
You: What's the impact if this fails in production?
Copilot: [Explains blast radius with repo context]

For Security Teams

Quick triage:

$ heimdall risks
[Security-focused analysis with threat detection and attack surface mapping]

Deep investigation:

$ heimdall review --interactive
You: What attack vectors does this introduce?
You: How would an attacker exploit this?
You: What's the fix that doesn't break backward compatibility?

For Team Leads

PR review guidance:

$ heimdall summary
[Quick verdict + heatmap → focus review time efficiently]

Onboarding junior developers:

$ heimdall explain --audience junior
[Educational explanations with minimal jargon]

Communicating to stakeholders:

$ heimdall explain --audience pm
[User impact focus, deployment considerations]

🛠️ Technical Stack

• TypeScript — Type-safe CLI development
• Commander.js — CLI framework with subcommands
• Simple-git — Git operations (diff extraction, uncommitted changes)
• Execa — Process execution for gh CLI calls
• Chalk + Boxen — Beautiful terminal output
• Node.js Readline — Interactive REPL for conversations
• GitHub CLI (gh) — Authenticated GitHub API access
• Copilot CLI Extension — Agentic analysis harness

Architecture Highlights:

• ESM modules (NodeNext)
• Strict TypeScript (no any)
• Graceful fallbacks (works without Copilot, better with it)
• Read-only operations (safe by design)

🚀 Roadmap

Current (v0.1.0):

• ✅ Deterministic risk analysis
• ✅ Interactive conversational mode
• ✅ GitHub PR integration
• ✅ Audience personas

Future Ideas:

• 🔮 Multi-PR comparison (heimdall compare 123 456)
• 🔮 Risk trend analysis over time
• 🔮 Custom risk keyword configuration
• 🔮 Team-specific risk profiles
• 🔮 CI/CD integration (GitHub Actions)
• 🔮 Slack/Discord bot integration

📖 Contributing

Heimdall is built for the GitHub Copilot CLI Challenge. Contributions welcome!

Principles:

• 🔒 Read-only operations only (never modify code/git)
• 📊 Deterministic base analysis (trustworthy signals)
• 🤖 Clear AI attribution (transparent about what's AI-generated)
• 🎯 Show confidence, not certainty (honest risk assessment)
• 💬 Agentic, not just AI (conversation > one-shot generation)

Development:

npm run dev -- review --interactive  # Test in dev mode
npm run build                        # Build for production
npm test                             # Run tests (if added)

📄 License

MIT — Built with ❤️ for the GitHub Copilot CLI Challenge

🙏 Acknowledgments

• GitHub Copilot CLI team — For creating the agentic harness that makes this possible
• The security community — For inspiration on what risk analysis should look like
• Every developer — Who's stared at a diff wondering "is this safe to merge?"

Heimdall: Stop guessing. Start conversing.

Built to showcase what's possible when you combine credible signals with agentic intelligence.

Install • Quick Start • Challenge Context