AI-KD — AI-Augmented Kernel Debugger

Automates Windows kernel crash dump triage using Claude (Anthropic) as an agentic reasoning engine. Works in two modes: inside WinDbg via pykd, or offline via the CLI — no GUI required.

Project Status

Current phase: Phase 1 Complete — Single-model agentic implementation complete and validated. CLI and WinDbg extension modes both live-tested against real crash dumps.

Milestone	Status
Concept	Complete
Architecture & Design	Complete
Phase 1 — Single-model agentic loop (Claude Sonnet)	Complete
Phase 1 — CLI mode (`cdb.exe` + Claude)	Complete — `DRIVER_IRQL_NOT_LESS_OR_EQUAL` validated (2026-04-18)
Phase 1 — WinDbg extension (pykd + Claude)	Complete — `DRIVER_OVERRAN_STACK_BUFFER` validated (2026-04-18)
Phase 1 — Automated tests (unit + integration + live API + E2E)	Complete — 88 passed, 9 E2E passing
Phase 2 — Hybrid multi-model approach	Planned
Phase 2 — Production hardening	Not Started

Phase 2 direction: Hybrid multi-model architecture — lightweight triage model for initial classification, specialist model for deep disassembly and root-cause reasoning.

Modes

Mode 1 — CLI (offline, no WinDbg GUI)

Point AI-KD at a .DMP file. It opens a single cdb.exe session — symbols load once, then Claude runs as many commands as needed at full speed:

python -m ai_kd_extension analyze samples/MEMORY.DMP

[*] Dump   : samples/MEMORY.DMP
[*] cdb.exe: C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\cdb.exe
[*] Model  : claude-sonnet-4-6
[*] Max iterations: 25
[*] Opening cdb.exe session (symbols load once here)...

[AI-KD] Running: !analyze -v
[AI-KD] Reason:  Initial triage — get bugcheck code and faulting IP

[AI-KD] Running: k 30
[AI-KD] Reason:  Walk the call stack to identify the faulting frame

[AI-KD] Running: u myfault+0x12f0 L20
[AI-KD] Reason:  Disassemble faulting offset to identify the paged access

[AI-KD] Root-cause analysis:
============================================================
Root cause: myfault.sys allocates from PagedPool then raises IRQL to
DISPATCH_LEVEL before dereferencing the pointer in an unbounded loop.
Any non-resident page causes the 0xD1 bugcheck.

Remediation: use NonPagedPoolNx, or complete all paged-memory operations
before raising IRQL. Wrap IRQL elevation in an RAII scope guard.
============================================================

Mode 2 — WinDbg extension (live session, uses pykd)

.load C:\Users\<username>\AppData\Local\Dbg\EngineExtensions\pykd.pyd
!py C:\path\to\run_aikd.py

Note: .load pykd (without full path) fails in WinDbg Preview due to UWP sandboxing. Always use the full path to pykd.pyd. See setup instructions below.

Claude runs the same agentic loop, issuing commands via pykd against the currently loaded crash dump — no CLI required.

Screenshots

CLI Mode (offline, PowerShell)

AI-KD running from the command line against a .DMP file via cdb.exe:

Root-cause analysis output:

Remediation recommendations:

WinDbg Extension Live Session

AI-KD running inside WinDbg — agentic tool calls in progress

Claude's final analysis rendered in the WinDbg command window

Remediation recommendations output

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                   Two Executor Paths                            │
│                                                                 │
│  CLI mode                      WinDbg extension mode           │
│  ─────────────────────         ────────────────────────        │
│  __main__.py (argparse)        main.py (WinDbg entry point)    │
│       │                              │                         │
│       ▼                              ▼                         │
│  analyze_dump.py               start_assistant()               │
│       │                              │                         │
│       ▼                              ▼                         │
│  dump_executor.py              probe.py                        │
│  CdbSession (persistent        pykd.dbgCommand()               │
│  cdb.exe — symbols load once)                                  │
│       │                              │                         │
│       └──────────────┬───────────────┘                         │
│                      ▼                                         │
│              agent.py  ←──── sanitiser.py                      │
│              (Claude API + tool-calling loop)                  │
│                      │                                         │
│                      ▼                                         │
│              AnalysisResult { final_text, tool_call_log }      │
└─────────────────────────────────────────────────────────────────┘
                       │  HTTPS/TLS
                       ▼
              ┌─────────────────┐
              │  Anthropic API  │
              │  claude-sonnet  │
              └─────────────────┘

Core components:

File	Role
`agent.py`	Claude API client + programmable tool-calling loop
`sanitiser.py`	Strips kernel addresses before sending output to Claude
`probe.py`	WinDbg executor — wraps `pykd.dbgCommand()`
`dump_executor.py`	Offline executor — `CdbSession` (persistent) + `make_dump_executor` (single-shot)
`main.py`	WinDbg extension entry point
`analyze_dump.py`	CLI orchestrator — opens one `CdbSession` for the whole analysis
`__main__.py`	CLI router (`python -m ai_kd_extension analyze ...`)

No crash dump content is pre-loaded. Claude drives all information gathering via tool calls.

Requirements

CLI mode (offline)

Windows 10/11 x64
Python 3.9+
Windows Debugger Tools (cdb.exe) — installed with the Windows SDK or WinDbg Preview
- Auto-detected from C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\
- Or set AIKD_CDB_PATH to the exact path
Anthropic API key — set ANTHROPIC_API_KEY or create Claude-Key.txt in the project root

WinDbg extension mode

All of the above, plus:

WinDbg Preview (Microsoft Store or winget install Microsoft.WinDbg)
Python 3.9 x64 — pykd wheels on PyPI are only published for specific Python versions; 3.9 is confirmed working
pykd 0.3.x — available at https://pypi.org/project/pykd/#files; download the cp39 .whl and install manually

pykd Python version constraint: pykd wheels are compiled against a specific CPython ABI. pip install pykd will fail with "no matching distribution" if your Python version has no published wheel. Check https://pypi.org/project/pykd/#files, find a wheel matching your Python version (e.g. cp39), download it, and install with python.exe -m pip install pykd-x.x.x-cp39-none-win_amd64.whl.

Cost note: A typical crash dump analysis costs roughly $0.01–$0.05 depending on dump complexity and number of tool iterations.

Installation

# Full install — WinDbg (via winget) + Python deps
.\install.ps1

# Dev/test only — no WinDbg needed, all tests run with mocks
.\install.ps1 -DevOnly

Usage

CLI — offline dump analysis

# Basic
python -m ai_kd_extension analyze samples/MEMORY.DMP

# More iterations for complex dumps
python -m ai_kd_extension analyze C:\dumps\crash.dmp --max-iterations 30

# Print each command + output size as it runs
python -m ai_kd_extension analyze samples/MEMORY.DMP --verbose

# Override cdb.exe path
python -m ai_kd_extension analyze samples/MEMORY.DMP --cdb "C:\DbgTools\cdb.exe"

python -m ai_kd_extension analyze --help

positional arguments:
  DUMP                Path to the .DMP file

options:
  --max-iterations N  Maximum WinDbg tool calls Claude may make (default: 25)
  --cdb PATH          Path to cdb.exe (auto-detected if omitted)
  --timeout SECS      Per-command cdb.exe timeout in seconds (default: 180)
  --verbose, -v       Print each command and output size as it runs

WinDbg extension

One-time setup

# 1. Install Python 3.9 x64 (to C:\Python39)
#    Download from: https://www.python.org/downloads/release/python-3913/

# 2. Download pykd wheel for cp39 from https://pypi.org/project/pykd/#files
#    e.g. pykd-0.3.4.15-cp39-none-win_amd64.whl

# 3. Install pykd into Python 3.9
C:\Python39\python.exe -m pip install pykd-0.3.4.15-cp39-none-win_amd64.whl

# 4. Install anthropic SDK into Python 3.9
C:\Python39\python.exe -m pip install anthropic

# 5. Copy pykd + python39.dll into WinDbg's user extension folder
New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\Dbg\EngineExtensions"
Copy-Item "C:\Python39\lib\site-packages\pykd\pykd.pyd" "$env:LOCALAPPDATA\Dbg\EngineExtensions\"
Copy-Item "C:\Python39\python39.dll" "$env:LOCALAPPDATA\Dbg\EngineExtensions\"

Running

Open WinDbg Preview and load a crash dump, then in the command window:

# Load pykd by full path (WinDbg Preview sandboxing requires this)
.load C:\Users\<username>\AppData\Local\Dbg\EngineExtensions\pykd.pyd

# Run AI-KD
!py C:\Code\ai-projects\ai-kd\run_aikd.py

Where run_aikd.py contains:

import sys, os
sys.path.insert(0, r"C:\Code\ai-projects\ai-kd")

key_path = r"C:\Code\ai-projects\ai-kd\Claude-Key.txt"
if not os.environ.get("ANTHROPIC_API_KEY"):
    with open(key_path, encoding="utf-8") as f:
        for line in f:
            line = line.strip()
            if line and not line.startswith("#"):
                for token in line.split():
                    if token.startswith("sk-ant-"):
                        os.environ["ANTHROPIC_API_KEY"] = token

from ai_kd_extension.main import start_assistant
start_assistant(max_iterations=20)

Verifying pykd works

# In WinDbg interactive Python console:
!py

>>> import pykd
>>> print(pykd.__version__)
>>> from ai_kd_extension.probe import execute_command
>>> print(execute_command("!analyze -v")[:300])
>>> exit()

Testing

No WinDbg required for unit/integration tests — pykd is fully mocked.

# Unit + integration tests (no API key, no WinDbg)
pytest -v

# Live API tests — real Anthropic calls, executor mocked
pytest tests/test_agent_live.py -m live -v

# E2E dump tests — real cdb.exe + real Claude API + real .DMP file
pytest tests/test_e2e_dump.py -m e2e_windbg -v -s

# Skip all live/E2E tests
pytest -m "not live and not e2e_windbg"

Status

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
.github/workflows		.github/workflows
Misc		Misc
TODO		TODO
ai_kd_extension		ai_kd_extension
docs		docs
samples		samples
tests		tests
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
install.ps1		install.ps1
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements-runtime.txt		requirements-runtime.txt
requirements.txt		requirements.txt

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

AI-KD — AI-Augmented Kernel Debugger

Project Status

Modes

Mode 1 — CLI (offline, no WinDbg GUI)

Mode 2 — WinDbg extension (live session, uses pykd)

Screenshots

CLI Mode (offline, PowerShell)

WinDbg Extension Live Session

Architecture

Requirements

CLI mode (offline)

WinDbg extension mode

Installation

Usage

CLI — offline dump analysis

WinDbg extension

One-time setup

Running

Verifying pykd works

Testing

Status

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

AI-KD — AI-Augmented Kernel Debugger

Project Status

Modes

Mode 1 — CLI (offline, no WinDbg GUI)

Mode 2 — WinDbg extension (live session, uses pykd)

Screenshots

CLI Mode (offline, PowerShell)

WinDbg Extension Live Session

Architecture

Requirements

CLI mode (offline)

WinDbg extension mode

Installation

Usage

CLI — offline dump analysis

WinDbg extension

One-time setup

Running

Verifying pykd works

Testing

Status

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages