svnscha - ai

🚀 New Release: mcp-windbg 1.3.0

2026-09-10T00:00:00+00:00

Version 1.3.0 of mcp-windbg separates the Claude Code integration into three plugins. If you've already installed mcp-windbg yourself, you can now add the debugging skills and crash-analysis agent to that connection.

Three Separate Plugins

The 1.2.0 release bundled the server, skills, and agent together. I split them so you can choose the parts you need:

Plugin	What it provides
`mcp-windbg-uvx`	The MCP server, launched with uvx, and default symbol settings
`mcp-windbg-skills`	Four debugging skills
`mcp-windbg-agents`	The `crash-analyst` agent

The uvx plugin now ships only the server configuration. Skills and agents are independent: install either, both, or neither.

Skills and Agents for Your Existing Server

If mcp-windbg is already registered in Claude Code, add the marketplace and install the workflows you want:

/plugin marketplace add svnscha/mcp-windbg
/plugin install mcp-windbg-skills@mcp-windbg
/plugin install mcp-windbg-agents@mcp-windbg

The skills cover the same four tasks:

analyze-dump for crash dump analysis.
debug-remote for live user-mode debugging.
kernel-debug for live kernel debugging.
windbg-doctor for checking the debugging setup.

They use your configured MCP connection, whether it runs a native executable, a Python installation, or an HTTP service. Setup diagnosis checks that server's actual launcher and host. It no longer assumes every installation needs uv.

For example:

/mcp-windbg-skills:analyze-dump C:\dumps\app.dmp

The agent is available as mcp-windbg-agents:crash-analyst. It investigates a dump and reports its likely cause, debugger evidence, and next steps. It uses the MCP tools directly and does not need the skills plugin.

If you want the plugin to start the server through uvx, install it as well:

/plugin install mcp-windbg-uvx@mcp-windbg

Windows and CDB/KD are still required on the debugging host. The server's built-in MCP prompts are available independently of these plugins.

Enterprise environments: Managed allowedMcpServers settings can cause Claude Code to silently skip plugin-bundled MCP servers (issue #32882). I recommend manual installation and registration plus the skills plugin, with the agents plugin if needed. The server must still be permitted by your organization's MCP policy.

Upgrading from the Bundled Plugin

Update the marketplace and server plugin:

/plugin marketplace update mcp-windbg
/plugin update mcp-windbg-uvx@mcp-windbg

Then install the skills and agents plugins using the commands above if you want to keep those workflows.

Skill commands now start with /mcp-windbg-skills: instead of /mcp-windbg:. For example, /mcp-windbg:analyze-dump becomes /mcp-windbg-skills:analyze-dump. References to the agent should use mcp-windbg-agents:crash-analyst. Restart Claude Code if the new components do not appear.

See the full v1.3.0 release notes and the plugin guide for installation, switching servers, and updating each plugin.

🚀 New Release: mcp-windbg 1.2.2

2026-09-05T00:00:00+00:00

Version 1.2.2 of mcp-windbg is out. This release fixes missing Unicode output on Windows systems that use a multibyte code page, including Chinese, Japanese, and Korean systems.

The bug was reported by a community member in issue #102. Thanks for taking the time to provide a clear report and help track it down.

The Problem

The du command, which displays a Unicode string, sometimes returned an empty result through mcp-windbg. Running the same command directly in CDB worked as expected. Other commands such as db and dw also worked against the same address.

The important detail was the reporter's Chinese Windows system locale.

What Caused It

mcp-windbg communicates with cdb.exe through a pipe. It sends a command and reads the debugger's response from that pipe.

On multibyte system code pages, such as Chinese 936, Japanese 932, Korean 949, or the "Use Unicode UTF-8" setting, CDB can truncate text while writing it to a pipe. The end of a line may be missing, including the closing quote and newline.

For du, this could remove the entire string. If the output was cut in the middle of a character, later commands could also time out because the session could no longer parse the incomplete output correctly.

This only affects redirected output, which is why the command still looks correct when run in a normal debugger window. There is no CDB option that fixes the pipe output; interactive mode, batch mode, and ANSI log files all show the same problem.

The Fix

CDB can write complete UTF-16 log files using .logopen /u, so mcp-windbg now uses one on affected systems. The pipe is still used to manage command timing, but the command output itself is read from the UTF-16 log.

This is not a special case for du. It also fixes Unicode text in module paths, !analyze output, string dumps, and other debugger commands. Systems with a single-byte code page continue to use the existing pipe-based output.

I tested the fix with real crash dumps, a live kernel target, and remote sessions using the 1252, 936, and 65001 code pages.

Getting Started

Upgrade with:

pip install -U mcp-windbg

If you use the Claude Code plugin, update the plugin to pick up the new version.

The project is available on GitHub. If you notice any other commands behaving differently on a non-English Windows system, please open an issue.

🚀 New Release: mcp-windbg 1.2.0

2026-08-27T00:00:00+00:00

Version 1.2.0 of mcp-windbg adds a Claude Code plugin. It packages the MCP server together with the instructions and workflows needed for common debugging tasks, so Claude Code can install and use it without a separate Python setup or a hand-written MCP configuration.

Installing the Plugin

Add the mcp-windbg marketplace and install the plugin from Claude Code:

/plugin marketplace add svnscha/mcp-windbg
/plugin install mcp-windbg-uvx@mcp-windbg

The plugin starts mcp-windbg with uvx, which downloads the pinned version from PyPI the first time it runs. You still need Windows, CDB, and uv, but you do not need to install the Python package yourself.

The existing pip install mcp-windbg setup remains available for other MCP clients and for anyone who prefers a manual configuration.

Skills for Common Debugging Tasks

The plugin includes four skills:

analyze-dump guides the analysis of a Windows crash dump.
debug-remote works with a live user-mode target through CDB.
kernel-debug handles live kernel debugging with KD.
windbg-doctor checks the local setup when CDB, KD, symbols, or the MCP server are not working as expected.

These skills only load when they are needed, which keeps the plugin's normal context use small. The underlying MCP tools are still available directly when you want to run a specific command or control a session yourself.

The Crash Analyst Agent

The plugin also includes a read-only crash-analyst agent. It can investigate a dump independently and return:

its likely cause
the debugger evidence supporting that conclusion
alternative causes it checked
practical next steps

The agent is kept away from mutating tools. It can inspect a debugging session, but it cannot resume a target or perform another action that would change its state.

Symbols by Default

Readable stack traces depend on symbols, and missing symbol configuration is a common source of poor results. The plugin now provides the Microsoft symbol server as the default value for _NT_SYMBOL_PATH.

If you already have _NT_SYMBOL_PATH configured, the plugin leaves it unchanged. Existing private symbol servers and custom cache paths therefore continue to work.

A Small 1.2.1 Follow-up

Version 1.2.1 followed later the same day. It reorganized the README installation guide by client and fixed a corrupted C:\dumps\app.dmp example that contained a hidden control character. There were no runtime changes, so it does not need a separate post.

Getting Started

Use the two plugin commands above for Claude Code, or upgrade the Python package for another MCP client:

pip install -U mcp-windbg

See the full release notes for v1.2.0 and v1.2.1. The source and plugin marketplace are available in the mcp-windbg repository.

🚀 New Release: mcp-windbg 1.1.0

2026-08-26T00:00:00+00:00

Version 1.1.0 of mcp-windbg is out. It's the first release since 1.0.0, which was broken on fresh installs for some time.

What Happened: 1.0.1

The dependency was mcp>=1.28.1 with no upper bound. When the MCP Python SDK shipped 2.0.0 - renaming McpError to MCPError and dropping the @server.list_tools() decorator - every fresh install broke at import:

ImportError: cannot import name 'McpError' from 'mcp.shared.exceptions'

Existing installs worked fine; only new ones broke. That's the worst kind of bug: invisible to anyone who could report it. 1.0.1 capped the requirement at <2.0.0. Thanks to @aphroteus for the fix and @arjunarjun07 for finding the cause.

If you're still on 1.0.0, run pip install --upgrade mcp-windbg. Any pip install "mcp<2" workaround can go.

Support for the 2.x SDK

A cap is a stopgap, not a fix. 1.1.0 runs on mcp>=2.0.0: handlers are passed straight to Server(...) instead of registered via decorators, and they return the SDK's result types (ListToolsResult, CallToolResult).

Nothing changes for clients - same tools, same schemas, stdio and streamable-http both work as before. Python support is unchanged (the 2.x SDK wants 3.10+, like this project already did).

Two changes so the next SDK release is boring instead of another five silent weeks:

All runtime dependencies are capped at the next major version. Without a ceiling, moving to 2.x would have left the same trap for 3.0.0. Since mcp-windbg is an application, not a library, upper bounds can't conflict with anything downstream - a breaking SDK release just becomes a failing CI run.
A weekly canary tests what users actually get. CI installed from uv.lock, so it only tested pinned versions, while real installs resolve whatever the ranges allow. The canary ignores the lock, installs the newest allowed versions, and runs the test suite every Monday. It's scheduled rather than tied to pull requests on purpose: an upstream break should page me, not block someone's unrelated PR.

`wait_for_break`

The one new tool. Resume a target with g, go do something else, then call wait_for_break to block until it stops again - breakpoint, bugcheck, or CTRL+BREAK. It returns everything the debugger printed along the way.

If the wait expires, the target keeps running. Waiting never halts your machine behind your back.

Fixing `g` Freezing the Target

This was bad and hid for a while, so let me be honest about it.

Go-class commands (g, gh, gn, gN, gc, gu) hand control back to the target, after which the debugger stops reading stdin. The server queued an .echo marker behind the g, which never got answered - so the command sat until timeout, and the timeout's CTRL+BREAK halted the target again. Ask the machine to run, get it frozen a minute later. The opposite of what you asked for.

Go-class commands are now sent bare and return immediately. Step commands (p, t, pa, ta, ...) are unaffected.

Fixing that exposed several related problems:

A command right after g breaks in cleanly. No manual send_ctrl_break, and the target's output isn't thrown away.
A break-in sent immediately after g no longer gets lost. Resuming used to return before the debugger read the g, leaving a window where a CTRL+BREAK hit the prompt instead of the target. Against a live KDNET target, a break sent with no gap was lost every single time. The resume is now confirmed consumed before reporting success.
Break-in checks before signaling. A CTRL+BREAK aimed at an already-stopped target would queue and re-halt it later. The session now probes for a prompt first and only signals if there's no answer, making speculative send_ctrl_break calls safe.
bp nt!X; g reports whether the breakpoint was set. A typo'd symbol now shows up as Couldn't resolve error instead of an endless wait.
One operation per session at a time. wait_for_break parks on a worker thread while the server keeps answering other requests; a second call on the same session is refused immediately. Closing a session also ends any wait parked on it.
Kernel sessions over named pipe or serial connect. kd announces those links with a different message than KDNET, and only the latter was matched - so sessions that were actually attached timed out.

Getting Started

Still one line:

pip install mcp-windbg

Release notes: v1.1.0 - Docs: svnscha.github.io/mcp-windbg - Source: github.com/svnscha/mcp-windbg

Summary

No headline features here. Just a dependency cap, a canary, one new tool, and a long list of places where the debugger and the server disagreed about who was talking. That's what a .1 release should be - especially after a 1.0.0 nobody could install.

If mcp-windbg has helped you, I'd love to hear about it. Open an issue, reach out, or star the repository. Thank you.

🚀 New Release: mcp-windbg 1.0.0

2026-07-16T00:00:00+00:00

I've just released version 1.0.0 of mcp-windbg. Yes, one-point-zero. The headline: your AI assistant can now debug the Windows kernel. The fine print: every tool has a new name, so bring your prompts. Both below.

Kernel Debugging

Three new tools, open_kd_session, run_kd_command, and close_kd_session, drive kd.exe against a live kernel target over the connections you would actually use:

KDNET (net:port=...,key=...)
Named pipes (com:pipe,port=\\.\pipe\...) - the classic VM setup
Serial - because sometimes it is 2003 in your lab and that is fine

Point your assistant at a VM, ask what that driver is up to, and let it run !process, !irql, lm, and friends while you have your coffee.

A kernel target is not a dump file: break in at the wrong moment and you have halted an entire machine. The tools are built around that reality:

Sessions arrive already stopped. open_kd_session waits for the connect banner and breaks in for you.
Closing resumes the target. close_kd_session sends g by default; pass resume: false only if you want the machine frozen on purpose.
--kd-path points the server at a specific kd.exe, the counterpart to --cdb-path.

There are also two new guided prompts to go with it: kernel-triage investigates a kernel target (including telling a real bugcheck apart from a plain break-in, and releasing the machine at the end), and remote-triage does the same for a live user-mode process.

Session IDs

The other big change: sessions are now first-class. Every open_* tool returns an opaque session ID (cdb-… or kd-…), and run_*, close_*, and send_ctrl_break address a session by that ID. No more implicit sessions, no more addressing by dump path: open first, then talk. Opening the same dump twice gives you two independent sessions.

The kind is enforced, too: pass a cdb ID to run_kd_command and you get an error naming the right tool. That matters more than it sounds when the caller is a model that occasionally guesses.

The Breaking Changes

The old names conflated the product (WinDbg) with the engines doing the work (cdb.exe for user mode, kd.exe for kernel). That distinction is now load-bearing, so everything got renamed:

0.x	1.0.0
`list_windbg_dumps`	`list_dumps`
`open_windbg_dump`	`open_cdb_dump`
`open_windbg_remote`	`open_cdb_remote`
`run_windbg_cmd`	`run_cdb_command` / `run_kd_command`
`close_windbg_dump`, `close_windbg_remote`	`close_cdb_session`

Also: send_ctrl_break takes a session_id, and the connection_type parameter is gone because the tool name now says which engine you mean. If you have prompts or agent instructions written against the 0.x names, they need updating - that is exactly why this is 1.0.0 and not 0.16.0. The docs are rewritten around the new flow, including a "Debug a kernel target" guide.

Smaller, But You Will Notice

Per-call timeouts: timeout_seconds on any open_* / run_* overrides that tool's default. Useful when that one !analyze -v against a 30 GB dump needs its time.
A slow command no longer wedges the session. On timeout the server breaks in with CTRL+BREAK and resynchronizes, so the session is usable for the next command instead of stranded.
Output goes to the right command. Every command waits on its own unique completion marker, so late output from a slow command can never be mistaken for the next one's result.
No more orphaned debuggers. cdb.exe launched via the Microsoft Store aliases spawns a child that a plain terminate left behind, still holding the target. Shutdown now kills the whole process tree.

Getting Started

Still a one-liner:

pip install mcp-windbg

Full release notes are on the v1.0.0 release page, and the project lives at github.com/svnscha/mcp-windbg. A star is always appreciated.

One-Point-Zero

Fourteen months ago this was a weekend experiment. Today it sits at 1.4k stars and debugs kernels. Calling it 1.0 is a promise more than a milestone: the names are stable now, and breaking changes from here on will be rare and loud.

Here is to stable.

If mcp-windbg has helped you, I would love to hear about it. Reach out, open an issue, or just star the repository. Thank you all.

🚀 New Release: mcp-windbg 0.15.0

2026-06-09T00:00:00+00:00

I've just released version 0.15.0 of mcp-windbg. It has been a while since the 0.12.2 post, and three releases have landed since then. Rather than a single feature, this is a round-up of everything that has shipped: a way to break into a running session, a hook to scrub sensitive data before it ever reaches the model, and a proper documentation site to tie it all together.

What's New

Break into a live session

If you have used a real debugger, you know the moment: the process is spinning, you want to know what it is doing right now, and you reach for CTRL+BREAK. That now works through the MCP interface too.

The new send_ctrl_break tool, contributed by @GeoYS, interrupts an active CDB/WinDbg session, for both dump and remote debugging workflows. So when you are driving a live target and it wanders off into a tight loop or a long wait, the model can break in, inspect the state, and carry on, the same way you would at the keyboard. This closes a real gap: before, a live session that was busy was a session you could only wait on.

Redact sensitive data before it leaves the machine

Crash dumps are full of things you might not want to hand to a model: file paths with usernames, machine names, environment variables, command lines, sometimes worse. The new --filter-script option lets you point the server at a trusted Python helper that can rewrite string-valued tool arguments and tool text output on the way through.

The important part is the boundary. Your script only sees the string values, not the full MCP protocol messages, so you can do focused PII redaction (mask a username, strip a token, normalize a path) without writing a protocol-aware proxy. If you run a centralized analysis service, this is the piece that lets you control what actually crosses the wire.

A real documentation site

The project has outgrown a README and a wiki. There is now a proper documentation site built with MkDocs Material and deployed to GitHub Pages. It covers getting started, the individual use cases, and a reference for the command-line options, the tools, and client configuration.

A few highlights worth calling out:

Use-case guides for the things people kept asking about: running the server over HTTP to debug from another machine, and scrubbing tool output to redact sensitive data.
The built-in dump-triage prompt is now documented, including its dump_path argument, so you can trigger a full structured triage without hand-writing the workflow.
Honest limitations are written down rather than discovered the hard way: the HTTP transport has no authentication, attach-by-PID is not supported, and sessions run concurrently.

Quieter, sturdier foundations

This release also includes several smaller changes that matter in daily use:

The stdio transport no longer crashes on a malformed input line. A single unparseable line used to tear down the whole process; now it is logged and the server keeps running.
The test suite was rebuilt as a declarative end-to-end harness. Every scenario runs against a really-hosted python -m mcp_windbg server driven by a real MCP client, with only the LLM faked. Coverage now sits above 90 percent, measured in the subprocess where tool dispatch actually runs.
Package metadata is complete, so pip show and the PyPI page now carry the author, project URLs, and proper classifiers.
Symbols resolve more often out of the box: the dump's own directory is now auto-included in the symbol search path, so PDBs sitting next to a dump are found without extra configuration.

Community Contributions

This stretch of releases leaned on the community, and two contributions stand out:

@GeoYS added the live break-in feature in #40, which became the send_ctrl_break tool above. It is the headline of the 0.13.0 release.
@SSyl made symbols just work in more cases by auto-including the dump directory in the symbol search path (#41).

This is exactly the kind of contribution that makes a tool better for everyone, not just the person who filed it. Thank you both.

Getting Started

Installation is unchanged and still a one-liner:

pip install mcp-windbg

The project is open source and available on GitHub at https://github.com/svnscha/mcp-windbg. If you find it useful, a star on the repository is always appreciated.

A Year and a Month In

It is hard to believe, but mcp-windbg is now a year and a month old. When I first wrote about it in May 2025, it was a weekend experiment to scratch my own itch: I was tired of typing the same WinDbg commands over and over, and I wanted to see whether a model could drive the debugger for me. I genuinely did not expect it to go anywhere.

It went somewhere. The repository now sits at 1.4k stars, the original article reached tens of thousands of readers in its first days, and the project has shown up in conversations, talks, and threads far beyond anything I planned. People have used it to triage real production crashes, wired it into team workflows, and sent screenshots of it cracking bugs that had been open for weeks. Every one of those still makes my day.

What has meant the most, though, is not the numbers. It is the people. Contributors who saw a gap and just fixed it. Folks who filed thoughtful issues, asked sharp questions, or pushed back when something did not work the way they needed. The many of you who reached out directly, by email, on LinkedIn, in DMs, to say the tool saved you an afternoon, or to suggest where it should go next. A project like this is only as good as the community around it, and this one has been generous well beyond what I could have hoped for.

So this is mostly a thank-you note. Thank you for the stars, the pull requests, the issues, the messages, and for trusting a small open-source tool with your hardest crashes. You are the reason it keeps getting better, and the reason I keep shipping.

Here is to the next year.

If mcp-windbg has helped you, I would love to hear about it. Reach out, open an issue, or just star the repository. Thank you all.

Meet Ralph: The AI Coding Agent That Just Keeps Going

2026-01-26T00:00:00+00:00

📺 Watch Ralph in Action: Ralph implementing its own features

🔗 Links: GitHub Repository

Shoutout to Matt Pocock whose viral tweet about "Ralph Wiggum" sparked this whole thing.

Why, You Ask?

Because AI coding assistants have a dirty little secret: they forget.

You start strong. "Refactor this auth module." The AI gets it. Code looks good. You're feeling productive.

Then 15 minutes later... it forgets what you discussed. It starts solving problems you never asked about. It rewrites code you specifically said to leave alone.

Sound familiar?

The Problem

Most AI coding tools are built for short bursts. Quick questions, small fixes, code snippets. Try to run them for hours on a bigger task? Good luck. Context degrades. Focus drifts. You spend more time course-correcting than coding.

I always wanted something different. An AI that could work autonomously on well-defined tasks. Start it before bed, wake up to working code. The missing piece? An agent that you can programmatically control.

Now, with the GitHub Copilot SDK and the Ralph loop, this has become too easy not to do.

So I built yet another Ralph.

What Is Ralph?

Ralph is a .NET CLI tool that treats AI as an autonomous agent, not a chat buddy. The key insight: structure breeds autonomy.

Here's how it works:

You describe what you want. Ralph asks clarifying questions, then generates a structured PRD with prioritized user stories.
Ralph executes autonomously. Picks up one story at a time, implements it, runs verification scripts to confirm it works, commits, moves on.
Repeat until done. You come back to find working, tested code.

The Secret Sauce: The PRD

At the heart of Ralph is a simple JSON file - the Product Requirements Document:

{
  "project": "my-app",
  "taskName": "add-auth",
  "userStories": [
    {
      "id": "US-001",
      "title": "Create login endpoint",
      "acceptanceCriteria": [
        "POST /api/auth/login accepts email and password",
        "Returns JWT token on success",
        "ralph_verify(Build) passes",
        "ralph_verify(Test) passes"
      ],
      "priority": 1,
      "passes": false
    }
  ]
}

Each story is small enough to complete in one go. Ralph picks the next one where passes: false, implements it, runs verification, and marks it complete. If the build fails, it sees the errors and fixes them. If tests fail, same thing.

The magic is in the ralph_verify() calls. These run actual C# verification scripts - compiled at runtime with Roslyn - that confirm the work is correct before moving on.

Verification Scripts

Traditional AI assistants produce code and hope for the best. Ralph takes a different approach: every story must pass verification before it's marked complete.

The ralph_verify() function in acceptance criteria tells Ralph which scripts to run. When Ralph sees ralph_verify(Build) passes, it executes the Build script and confirms it succeeds before moving on.

Ralph ships with Build and Test scripts out of the box. They're C# classes compiled at runtime with Roslyn:

using Ralph.Core.Abstractions;

namespace Ralph.Scripts;

[VerificationScript("Build", "Verifies solution compiles")]
public class Build : IVerificationScript
{
    public VerificationResult Execute()
    {
        // Spawn dotnet build, capture output, return pass/fail
    }
}

The key insight: Ralph loops until all verification scripts pass. If Build fails, Ralph sees the compiler errors and attempts to fix them. If Test fails, Ralph sees which tests failed and why. This self-correcting loop is what enables hours of autonomous work.

Why custom scripts instead of just telling the AI "run dotnet build"? Context efficiency. A successful build returns "Build succeeded" - not the entire compiler output. Only on failure does Ralph see the errors it needs to fix. This keeps the context window lean and focused on what matters.

Want custom verification? Drop a script in .ralph/scripts/:

[VerificationScript("Lint", "Runs dotnet format to check code style")]
public class Lint : IVerificationScript
{
    public VerificationResult Execute()
    {
        // Run dotnet format --verify-no-changes
        // Return pass/fail based on exit code
    }
}

Now you can use ralph_verify(Lint) passes in your acceptance criteria. Security scans, API tests, whatever you need.

Behind the Scenes

Every AI model has a context window-the amount of text it can "see" at once. Ralph works within these limits by keeping each story self-contained.

A story must fit entirely within a single context window:

The system prompt (Ralph's instructions)
The current story's details and acceptance criteria
Relevant source files Ralph needs to read
Space for Ralph to "think" and generate code

Practical guidance:

Story Size	Files Touched	Recommendation
Small	1-3 files	✅ Ideal
Medium	4-8 files	✅ Good
Large	9-15 files	⚠️ Consider splitting
Too Large	15+ files	❌ Split required

Ralph doesn't have persistent memory across stories. Each time it picks one up, it starts fresh. This isn't a bug-it's a feature that forces clean design. Each story is a complete, verifiable unit of work.

"Add user authentication" becomes:

Create User entity and migration
Implement password hashing service
Create login endpoint
Add JWT token generation
Implement authentication middleware
Create registration endpoint

Each story is small enough to complete in one iteration, yet together they deliver the full feature.

State Management

Ralph maintains state at two levels:

PRD state (persistent) - which stories exist, which have passed, notes from completed work. This file persists across sessions and gets committed to your repo.

Session state (ephemeral) - current working story, in-progress changes, retry attempts. Lives only for one execution.

If Ralph crashes mid-story, that story remains passes: false and will be retried on next run. Completed stories are never redone.

Getting Started

You'll need .NET 10 SDK and GitHub Copilot CLI installed and authenticated.

# Build and pack
dotnet build
dotnet pack src/Ralph/Ralph.csproj

# Install globally
dotnet tool install --global --add-source src/Ralph/nupkg Ralph

Then in your project:

# Option A: Plan and implement in one go
ralph

# Option B: Plan first, then implement separately
ralph plan    # Create the PRD interactively
ralph run     # Implement all stories from the PRD

That's it. Ralph asks "What would you like to accomplish?", creates a PRD from your description, and implements all stories. Go grab coffee.

Why This Works

Traditional AI assistants are designed for conversation. Ralph is designed for execution.

	Traditional AI	Ralph
Duration	Minutes	Hours
Context	Degrades over time	Fresh per story
Verification	You check manually	Scripts verify automatically
Human involvement	Constant supervision	Set and forget

The AI model is the same. The difference is the workflow architecture around it.

The Catch

Stories need to be small enough to fit in a context window. If a story requires understanding 50 files at once, it'll struggle. Keep them focused: 1-5 files per story, one concern each.

Also, this isn't magic. Ralph still needs good acceptance criteria. Vague requirements produce vague results. But that's true of any engineering work.

Summary

AI coding assistants are great at short bursts but fall apart on longer tasks. Ralph fixes that by giving AI what it needs: structure. A PRD breaks work into discrete stories. Verification scripts confirm each one works. The result? An agent that can run for hours without wandering off course.

The shift from "AI assistant" to "AI agent" isn't just semantic. It's the difference between babysitting and delegating.

Next Steps

Watch the demo - See Ralph implement its own features in the YouTube video
Clone the repo - github.com/svnscha/ralph
Try it on something small - Pick a well-defined feature, let Ralph work on it overnight, come back to commits

That moment when you return to working, tested code you didn't write line by line? That's when it clicks.

Ollama Now Speaks Messages API

2026-01-22T00:00:00+00:00

The News: Ollama Learns a New Language

Claude Code can now talk to your locally-hosted models without any extra adapters, proxies, or dark magic.

"Ollama v0.14.0 and later are now compatible with the Anthropic Messages API, making it possible to use tools like Claude Code with open-source models." — Ollama Blog

Cue the excitement: Finally! Unlimited coding on steroids! No more watching your token budget evaporate! 24/7 AI-assisted development without the API bill anxiety!

...right?

Why Test This, You Ask?

Naturally, I had to try this immediately. What better excuse to fire up the DGX Spark and see what these local models can really do?

If you're running a DGX Spark (or any beefy GPU setup), this means you can now fire up Claude Code and have it talk to whatever model you've got running locally. Zero cloud dependency. Zero API costs eating into your coffee budget. Just pure, local AI goodness.

But does it actually work? Let's find out.

Setting It Up

Which Model?

The official docs recommend a few options:

Cloud models (if you're into that sort of thing):

glm-4.7:cloud, minimax-m2.1:cloud, qwen3-coder:480b

Local models (the fun part):

qwen3-coder - Excellent for coding tasks
gpt-oss:20b - Strong general-purpose model
glm-4.7-flash - Deep reasoning, needs Ollama 0.14.3

I tested several of these locally - qwen3-coder is genuinely impressive for coding tasks, and glm-4.7-flash (just released with Ollama 0.14.3) surprised me with its deep reasoning approach. Cloud models? Kind of defeats the purpose of running local, doesn't it?

Bump Ollama's Context Window

The docs recommend at least 32k context. Use systemctl edit for a persistent override that survives updates:

sudo systemctl edit ollama.service

Add this in the editor that opens:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=32000"
Environment="OLLAMA_FLASH_ATTENTION=1"
Environment="OLLAMA_KV_CACHE_TYPE=f16"

Bonus performance tweaks:

OLLAMA_FLASH_ATTENTION=1 - Normal attention loads the entire context into memory at once. Flash Attention breaks it into chunks, processes them sequentially, and combines the results. Same output, way less memory.
OLLAMA_KV_CACHE_TYPE=f16 - Keeps the K/V cache at full precision (default). Use q8_0 to halve memory if you're tight on VRAM.

How much context can you actually fit? The VRAM Calculator is your friend. Play around with your model size, quantization, and available VRAM - it'll tell you the exact settings to max out each model.

Then restart:

sudo systemctl restart ollama.service

PowerShell Helper for Your Work Machine

This little function lives in my $PROFILE:

function Enter-ClaudeSpark {
   $env:ANTHROPIC_AUTH_TOKEN = "ollama"
   $env:ANTHROPIC_BASE_URL = "http://spark-1:8080"
   $env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1"
}

Now I just type Enter-ClaudeSpark and Claude Code magically routes everything to my DGX Spark. The ANTHROPIC_AUTH_TOKEN is set to ollama because Ollama doesn't actually need a real token - it just checks if the header exists. Clever.

My Test: Meeting Destruction Therapy

Public benchmarks do not always reflect how a model feels in everyday use. I care more about how well it follows my language and understands the task, so I made a small practical test of my own.

I needed something creative, visual, and complex enough to separate the wheat from the chaff. What better way than asking these models to build a Breakout-style game where you "reschedule" your weekly meetings by smashing them with a paddle?

The Prompt:

# Breakout-Style Calendar Game Prompt

## Objective
Build a **simple, modern Breakout-inspired browser game** where a bouncing ball clears **calendar-style blocks representing weekly meetings**, and a horizontal paddle is used to “reschedule” (break) them.

## Core Concept
- The playfield should resemble a **weekly calendar view** rather than a classic arcade board.
- Each block represents a **meeting/event** (rounded rectangles, subtle borders).
- The paddle metaphorically “reschedules” meetings by bouncing the ball upward.
- The ball “clears” meetings as they are hit.

## Visual & UX Direction (Very Important)
- **Look & feel inspired by modern calendar apps** such as **Google Calendar** or **Outlook Calendar**:
  - Soft neutral background (light or dark mode acceptable)
  - Rounded corners, subtle shadows, clean typography
  - Muted but intentional color palette (event colors feel like calendar categories)
  - Gentle grid or column structure reminiscent of a weekly view
- Avoid retro/arcade styling (no pixel fonts, neon colors, or harsh outlines).
- Animations should feel **smooth and calm**, not frantic:
  - Subtle easing on ball movement
  - Soft fade/scale effects when meetings are cleared
  - Light hover or focus states where appropriate

## Technical Requirements
- Use **only vanilla HTML, CSS, and JavaScript** (no frameworks or libraries).
- Single-page implementation.
- **Responsive and centered layout** that works on desktop and mobile.
- Canvas or DOM-based rendering is acceptable, but visuals should remain crisp.
- Code should be clean, readable, and well-commented.

## Gameplay Requirements
- Paddle controlled via mouse/touch (keyboard optional).
- Ball physics should feel smooth and predictable.
- Winning state when all meetings are cleared.
- Optional: subtle sound effects or score labeled as **“Meetings Cleared”**.

## Polish Encouraged
- Thoughtful spacing and alignment
- Calendar-like typography (system UI fonts preferred)
- Micro-interactions and transitions that reinforce the scheduling metaphor

## Implementation
- Create index.html, style.css and game.js.

When finished, suggest that the user can host and test the game locally using:

python -m http.server

I threw this at several models through Claude Code and timed the results:

Model	Time	Rating
Claude Opus 4.5	2m 30s	⭐⭐⭐⭐⭐
`qwen3-coder:30b`	1m 48s	⭐⭐⭐⭐
`gpt-oss:20b`	4m 24s	⭐⭐⭐
`glm-4.7-flash`	8m 45s	⭐⭐⭐
`nemotron-3-nano:30b`	2m 46s	⭐
`ministral-3:14b`	-	🚩
`rnj-1`	-	🚩

Claude Opus 4.5 (Reference)

Not self-hosted - this is the cloud-based frontline model, included for comparison. Understood the creative brief, nailed the game mechanics, produced clean and maintainable code. No surprises there.

Your browser does not support the video tag.

qwen3-coder:30b

Faster than expected, and it actually produced something playable. At 30B parameters, genuinely impressive.

Your browser does not support the video tag.

gpt-oss:20b

Your browser does not support the video tag.

For this one I went all out - maxed context window at 95k with full precision KV cache:

Environment="OLLAMA_CONTEXT_LENGTH=95232"
Environment="OLLAMA_FLASH_ATTENTION=1"
Environment="OLLAMA_KV_CACHE_TYPE=f16"

Solid result! The 20B variant delivered a working game with proper paddle controls. Not as polished as qwen3-coder, but definitely playable. A good middle-ground option if you want something from the GPT family.

glm-4.7-flash

"As the strongest model in the 30B class, GLM-4.7-Flash offers a new option for lightweight deployment that balances performance and efficiency." - Bold claims require testing. This one needs Ollama 0.14.3 (just released!).

Your browser does not support the video tag.

Why the 8+ minute runtime? GLM spends serious time in its thinking stage. Watch the Ollama output live and you'll see deep, methodical reasoning - no "what if" self-doubt loops, just clear and consistent problem-solving. The result shows: best physics of all the OSS models I tested. The ball movement felt smooth and responsive. The catch? It completely ignored the meeting-themed UI brief and went with a generic breakout style instead. So close, yet so far.

nemotron-3-nano:30b

It rendered something! Got the calendar theme, colorful meeting blocks, even a "Meetings Cleared" counter. But... where's the ball? Where's the paddle? Apparently Nemotron thought breakout meant "break out of implementing game mechanics." Nice UI though.

This one makes me a bit sad, honestly. NVIDIA has been releasing incredible AI stuff lately - the voice models alone are mind-blowing - but Nemotron-3-Nano just flopped here. Maybe it shines elsewhere, but for Claude Code workflows? Not ready.

ministral-3:14b

I really tried with this one. Multiple attempts, different prompts, fresh sessions. Every single time: Claude Code just... completed. Immediately. No files, no code, no output. It's like the model and Claude Code looked at each other and mutually agreed to do nothing. 🤷

rnj-1

"8B parameter open-weight, dense models trained from scratch by Essential AI, optimized for code and STEM with capabilities on par with SOTA open-weight models." - 130k downloads, fresh release, sounded promising. The VSCode + Cline demo on their blog looked great - but that was a Python game, not our HTML/JS breakout challenge.

Unfortunately, no results here. Another one that just didn't produce anything usable with Claude Code. At least the resource usage was... well, not surprising for an 8B model.

Summary

So, Ollama now speaks the Messages API, and Claude Code can talk to local models. I put it through a fun benchmark - building a calendar breakout game - and the results were clear: Opus still delivers the goods, but the OSS models are catching up fast.

For Claude Code agentic workflows, qwen3-coder is the clear winner in the OSS space - fast, capable, and actually follows instructions. glm-4.7-flash has potential but needs work on following prompts. gpt-oss:20b is a solid middle-ground option.

This actually reflects my broader model philosophy: ChatGPT-style models for basic tasks - rephrasing, docs, research. Anthropic for serious coding work. And now in the open-source world, qwen3-coder is genuinely fun to work with.

Is this going to replace Claude Opus for serious work? Not today. But for experimentation, learning, and those times when you want to see what the open-source world can do? This setup is fantastic.

Next Steps

Want to try this yourself?

Install Ollama ≥ 0.14: curl -L https://ollama.com/install.sh | sh
Pull your model of choice: ollama pull qwen3-coder:30b
Bump the context window to at least 32k
Add the PowerShell helper to your $PROFILE
Fire up Claude Code and start breaking some meetings... I mean, coding

And who knows - at the rate these models are improving, maybe in a few months I'll have to eat my words about frontline models being irreplaceable.

In the meantime, building a game that lets you destroy your weekly meetings with a bouncing ball might be the most satisfying thing I've prompted this month.

Happy hacking! 🎮

AI Agents in .NET: Beyond DevUI - LibreChat Integration

2026-01-04T00:00:00+00:00

Welcome back to the AI Agents in .NET series. In the introduction, I built a basic conversational agent. In Part 1, I added database persistence, embeddings, and semantic search capabilities.

Today I'm breaking free from the built-in DevUI. Time to escape the developer dungeon.

Don't get me wrong - DevUI is fantastic for development and debugging.

This post connects those agents to LibreChat through OpenAI-compatible endpoints.

The first version failed when a tool-calling agent was used through a downstream client. The solution was a reusable middleware pattern called ToolCallFilterAgent, which I explain below.

The Problem with DevUI

DevUI served me well. It let me test agents, inspect tool calls, and debug issues. But it has limitations:

Single-purpose: It's a development tool, not a production interface
No multi-user support: One conversation at a time
Limited customization: You get what you get

For real-world use, I need something more flexible. And rather than building my own chat UI (been there, done that in early 2025, don't want to repeat), let's leverage existing open-source solutions.

Why LibreChat?

I mentioned LibreChat in my DGX Spark post, and I really enjoy it. Like, really like it.

It's:

OpenAI API compatible: Speaks the same language as ChatGPT
Self-hosted: Your data stays yours (take that, cloud overlords)
Feature-rich: File uploads, conversations, presets, the whole shebang
Beautiful: Actually looks like something you'd want to use - not like a developer accidentally vomited JSON onto a webpage

The key insight? LibreChat doesn't care what's behind the API. It just needs something that speaks OpenAI's protocol. And guess what the Microsoft Agent Framework already supports?

The Plan

Here's what I'm building:

%%{init: {"theme": "dark"}}%%
flowchart LR
    LC[LibreChat] -->|OpenAI API| K[Knowledge API]
    K -->|Agent Framework| A[Agents]
    A --> KA[Knowledge]
    A --> KSA[KnowledgeSearch]
    A --> KTA[KnowledgeTitle]
    KSA -->|Vector Search| PG[(PostgreSQL)]

LibreChat talks to our Knowledge API using the standard OpenAI chat completions format. Our API routes requests to our agents based on the model parameter. From LibreChat's perspective, it's just another OpenAI-compatible endpoint with multiple models to choose from.

Removing DevUI, Embracing Swagger

First things first - I'm removing the DevUI dependency and redirecting to Swagger for API exploration. DevUI is great for debugging, but for an API-first approach, Swagger makes more sense. Plus, Swagger has that nice "I'm a real API" energy.

The home page now redirects to Swagger:

app.MapGet("/", () => Results.Redirect("/swagger"));

Clean and simple. The API is now focused on being a backend service. Goodbye, training wheels.

Exposing OpenAI-Compatible Endpoints

The Agent Framework provides a beautiful MapOpenAIChatCompletions method that exposes agents as OpenAI-compatible endpoints. Each agent gets its own endpoint path. It's almost too easy (foreshadowing...).

I collect agent builders during registration and map them after building the app:

// Collect agent builders for endpoint mapping
var agentBuilders = new List<IHostedAgentBuilder>();

builder.ConfigureKnowledgeDefaults((settings, logger) =>
{
    // ... OpenAI client setup ...

    // Register agents and collect builders for endpoint mapping
    builder.Services.AddSingleton<KnowledgeSearchAgent>();
    agentBuilders.Add(builder.AddAIAgent("Knowledge", (services, key) => 
        AgentFactory.CreateKnowledgeAgent(chatClient, services, key)));
    agentBuilders.Add(builder.AddAIAgent("KnowledgeSearch", (services, key) => 
        AgentFactory.CreateKnowledgeSearchAgent(chatClient, services, key)));
});

var app = builder.Build();

// ... middleware setup ...

// Map OpenAI chat completions endpoint for each registered agent
foreach (var agentBuilder in agentBuilders)
{
    app.MapOpenAIChatCompletions(agentBuilder);
}

Now each agent has its own endpoint:

/Knowledge/v1/chat/completions
/KnowledgeSearch/v1/chat/completions

Pretty slick, right?

Setting Up LibreChat

Before I go further, let me get LibreChat running so I can test this integration. If you don't have LibreChat running yet, here's the quick setup. (If you do, feel free to skip ahead and judge my configuration choices.)

Docker Compose

mkdir -p ~/librechat
cd ~/librechat
git clone https://github.com/danny-avila/LibreChat.git .
cp .env.example .env

The LibreChat Configuration

Create librechat.yaml and point LibreChat at the API:

version: 1.2.8
cache: true

endpoints:
  custom:
    - name: "Agent Framework"
      apiKey: "not-used-but-required"
      baseURL: "http://host.docker.internal:5000/v1"
      models:
        default: ["Knowledge", "KnowledgeSearch"]
        fetch: false

      titleConvo: false
      summarize: false
      forcePrompt: false
      modelDisplayLabel: "Agent Framework"
      iconURL: "https://svnscha.de/svnscha.webp"

Docker Compose Override

Create docker-compose.override.yml to mount the config:

services:
  api:
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml
    extra_hosts:
      - "host.docker.internal:host-gateway"

The extra_hosts line is crucial - it lets containers reach the host machine where the Knowledge API runs.

Fire It Up

docker compose up -d

Navigate to http://localhost:3080, create an account (it's local, don't worry), and you should see "Agent Framework" in the endpoint list.

But wait - if you select "Knowledge" and send a message, LibreChat hits /v1/chat/completions with "model": "Knowledge". My per-agent endpoints live at /Knowledge/v1/chat/completions instead. Houston, we have a routing problem.

The Model Routing Middleware

LibreChat (and most OpenAI clients) expect a single endpoint at /v1/chat/completions where the model parameter determines the underlying model but in this scenario it should determines routing:

{
  "model": "Knowledge",
  "messages": [{"role": "user", "content": "What's on your mind?"}]
}

I need middleware that reads the model from the request body and rewrites the path to the agent-specific endpoint. Nothing fancy, just some good old path mangling:

// Rewrite /v1/chat/completions to /{model}/v1/chat/completions based on request body
app.Use(async (context, next) =>
{
    var path = context.Request.Path.Value;
    if (path?.Equals("/v1/chat/completions", StringComparison.OrdinalIgnoreCase) == true)
    {
        context.Request.EnableBuffering();

        using var reader = new StreamReader(context.Request.Body, leaveOpen: true);
        var body = await reader.ReadToEndAsync();
        context.Request.Body.Position = 0;

        string? model = null;
        if (!string.IsNullOrEmpty(body))
        {
            try
            {
                var json = System.Text.Json.JsonDocument.Parse(body);
                if (json.RootElement.TryGetProperty("model", out var modelElement))
                {
                    model = modelElement.GetString();
                }
            }
            catch (System.Text.Json.JsonException)
            {
            }
        }

        if (string.IsNullOrWhiteSpace(model))
        {
            var logger = context.RequestServices.GetRequiredService<ILogger<Program>>();
            logger.LogWarning("Chat completions request missing required 'model' field");
            context.Response.StatusCode = StatusCodes.Status400BadRequest;
            context.Response.ContentType = "application/json";
            await context.Response.WriteAsJsonAsync(new { 
                error = new { 
                    message = "The 'model' field is required", 
                    type = "invalid_request_error", 
                    param = "model", 
                    code = "missing_required_parameter" 
                } 
            });
            return;
        }

        context.Request.Path = $"/{model}/v1/chat/completions";
    }
    await next();
});

The key points:

Enable buffering: I need to read the body to extract model, then reset it for the actual handler
Path rewriting: Transform /v1/chat/completions → /{model}/v1/chat/completions
Error handling: Return a proper OpenAI-style error if model is missing

Now when LibreChat sends a request, it gets routed to the right agent automatically. Back to LibreChat - select "Knowledge" from the dropdown, send a message, and... it works! Streaming responses, proper formatting, everything.

At this point, I thought I was done. Celebrated with a coffee. Time to test KnowledgeSearch...

The Tool Call Disaster (And How I Fixed It)

I switched to the KnowledgeSearch model in LibreChat, asked it to search for something, and... nothing. The request just hung. Then cancelled. No error message. No response. Just the cold, judgmental silence of broken software.

I dug through LibreChat's source code, traced the request flow, added logging everywhere. Console.WriteLine debugging like it's 2005.

Note: We should get to Observability very soon...

The Problem

My KnowledgeSearch agent uses tools - specifically the SearchConversationHistory function. When the agent executes a tool, the response stream includes FunctionCallContent and FunctionResultContent alongside the text. This is how the Agent Framework communicates "I'm calling a tool" and "here's what the tool returned."

LibreChat receives the stream and interprets the function call as something it should execute. That fails because the function exists in the backend rather than in LibreChat, so LibreChat cancels the request.

[Our Agent] → "I'll search for that" → FunctionCallContent{SearchConversationHistory}
[Our Agent] → [executes tool internally]
[Our Agent] → FunctionResultContent{results...}
[Our Agent] → "Based on the search, here's what I found..."
          ↓
[LibreChat] → Sees FunctionCallContent → "I need to call this function!"
[LibreChat] → Can't find function → Cancels request
          ↓
[User] → "Why isn't anything happening?" 😤

The frustrating part? You can't disable this behavior in LibreChat. It's doing the right thing for its use case - if it sends a function call to an upstream model, it expects to handle the response. But I'm the upstream model, and I've already handled my own tool calls. We're both right, and that's the most annoying kind of bug.

The Solution

Don't send tool call content downstream. Filter it out before it leaves the API. If LibreChat never sees the tool calls, it can't get confused by them. taps forehead

Meet ToolCallFilterAgent - a delegating agent that wraps any agent and strips FunctionCallContent and FunctionResultContent from responses. It's like a bouncer for your API responses:

/// <summary>
/// A delegating agent that filters out tool call content from responses.
/// This prevents downstream consumers from seeing FunctionCallContent and FunctionResultContent
/// that they cannot execute.
/// </summary>
public sealed class ToolCallFilterAgent : DelegatingAIAgent
{
    public ToolCallFilterAgent(AIAgent innerAgent) : base(innerAgent) { }

    public override async Task<AgentRunResponse> RunAsync(
        IEnumerable<ChatMessage> messages,
        AgentThread? thread,
        AgentRunOptions? options,
        CancellationToken cancellationToken)
    {
        var response = await InnerAgent.RunAsync(messages, thread, options, cancellationToken);
        response.Messages = FilterToolCalls(response.Messages);
        return response;
    }

    public override async IAsyncEnumerable<AgentRunResponseUpdate> RunStreamingAsync(
        IEnumerable<ChatMessage> messages,
        AgentThread? thread,
        AgentRunOptions? options,
        [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        await foreach (var update in InnerAgent.RunStreamingAsync(messages, thread, options, cancellationToken))
        {
            yield return FilterToolCalls(update);
        }
    }

    private static IList<ChatMessage> FilterToolCalls(IEnumerable<ChatMessage> messages) =>
        messages.Select(m => new ChatMessage(m.Role,
            m.Contents.Where(c => c is not FunctionCallContent && c is not FunctionResultContent).ToList()
        )).ToList();

    private static AgentRunResponseUpdate FilterToolCalls(AgentRunResponseUpdate update) =>
        new(update.Role, update.Contents
            .Where(c => c is not FunctionCallContent && c is not FunctionResultContent).ToList());
}

Now in the AgentFactory, I wrap KnowledgeSearchAgent:

public static AIAgent CreateKnowledgeSearchAgent(IChatClient chatClient, IServiceProvider services, string key)
{
    var searchAgent = services.GetRequiredService<KnowledgeSearchAgent>();

    var agent = chatClient.CreateAIAgent(new ChatClientAgentOptions
    {
        Id = key,
        Name = key,
        ChatOptions = new ChatOptions
        {
            ConversationId = "global",
            Instructions = KnowledgeSearchSystemPrompt,
            Tools = [AIFunctionFactory.Create(searchAgent.SearchConversationHistoryAsync, "SearchConversationHistory")],
            ToolMode = ChatToolMode.Auto
        }
    });

    // Wrap with filter to prevent downstream consumers from seeing tool calls they can't execute
    return new ToolCallFilterAgent(agent);
}

The agent still uses tools internally, but clients only see the final text response. Clean and transparent. What happens in the backend stays in the backend.

Back to LibreChat - KnowledgeSearch now works! The agent searches, finds results, and responds - all without LibreChat ever knowing tools were involved. It's like magic, except it's just careful filtering.

Title Generation with KnowledgeTitleAgent

LibreChat has a feature called titleConvo - it automatically generates titles for conversations using the AI. But my main agents have tools and complex system prompts that are overkill for simple title generation. It's like using a flamethrower to light a candle.

The solution: a dedicated title agent. It's intentionally simple - no tools, no embeddings, just a focused system prompt:

/// <summary>
/// Simple agent for generating conversation titles.
/// No tools, no embeddings - just a basic helpful assistant.
/// Designed for use with LibreChat's title generation feature.
/// </summary>
public static class KnowledgeTitleAgent
{
    private const string TitleSystemPrompt = @"You are a helpful assistant that generates concise, descriptive titles for conversations.
When given conversation content, create a brief title (3-7 words) that captures the main topic or purpose.
Be specific and informative. Avoid generic titles like 'Chat' or 'Conversation'.";

    public static ChatClientAgent Create(IChatClient chatClient, IServiceProvider services, string key)
    {
        return chatClient.CreateAIAgent(new ChatClientAgentOptions
        {
            Id = key,
            Name = key,
            ChatOptions = new ChatOptions
            {
                ConversationId = "global",
                Instructions = TitleSystemPrompt,
            }
        });
    }
}

agentBuilders.Add(builder.AddAIAgent("KnowledgeTitle", (services, key) => 
    AgentFactory.CreateKnowledgeTitleAgent(chatClient, services, key)));

Now update librechat.yaml to use the title agent:

version: 1.2.8
cache: true

endpoints:
  custom:
    - name: "Agent Framework"
      apiKey: "not-used-but-required"
      baseURL: "http://host.docker.internal:5000/v1"
      models:
        default: ["Knowledge", "KnowledgeSearch", "KnowledgeTitle"]
        fetch: false

      titleConvo: true
      titleModel: "KnowledgeTitle"
      summarize: false
      forcePrompt: false
      modelDisplayLabel: "Agent Framework"
      iconURL: "https://svnscha.de/svnscha.webp"

Now LibreChat uses KnowledgeTitle specifically for generating conversation titles, while Knowledge and KnowledgeSearch handle the actual conversations.

The Complete Program.cs

Here's what Program.cs looks like after all these changes:

using System.ClientModel;
using Knowledge.Services;
using Knowledge.Shared.Agents;
using Knowledge.Shared.Extensions;
using Microsoft.Agents.AI.Hosting;
using Microsoft.Extensions.AI;
using OpenAI;

var builder = WebApplication.CreateBuilder(args);

// Collect agent builders for endpoint mapping
var agentBuilders = new List<IHostedAgentBuilder>();

builder.ConfigureKnowledgeDefaults((settings, logger) =>
{
    if (string.IsNullOrWhiteSpace(settings.ApiKey))
    {
        logger.LogWarning("No API key configured. Set Knowledge:ApiKey in user secrets or environment.");
    }

    var options = new OpenAIClientOptions();
    if (!string.IsNullOrEmpty(settings.ApiEndpoint))
    {
        options.Endpoint = new Uri(settings.ApiEndpoint);
    }

    var client = new OpenAIClient(new ApiKeyCredential(settings.ApiKey), options);
    var chatClient = client.GetChatClient("gpt-4.1").AsIChatClient();

    // Configure embedding service
    var embeddingClient = client.GetEmbeddingClient("text-embedding-3-small").AsIEmbeddingGenerator();
    builder.Services.AddEmbeddingService(embeddingClient);

    // Register agents and collect builders for endpoint mapping
    builder.Services.AddSingleton<KnowledgeSearchAgent>();
    agentBuilders.Add(builder.AddAIAgent("Knowledge", (services, key) => 
        AgentFactory.CreateKnowledgeAgent(chatClient, services, key)));
    agentBuilders.Add(builder.AddAIAgent("KnowledgeSearch", (services, key) => 
        AgentFactory.CreateKnowledgeSearchAgent(chatClient, services, key)));
    agentBuilders.Add(builder.AddAIAgent("KnowledgeTitle", (services, key) => 
        AgentFactory.CreateKnowledgeTitleAgent(chatClient, services, key)));
});

// Register background service for embedding processing
builder.Services.AddHostedService<EmbeddingBackgroundService>();

builder.Services.AddOpenAIResponses();
builder.Services.AddOpenAIConversations();

var app = builder.Build();

// Rewrite /v1/chat/completions to /{model}/v1/chat/completions based on request body
app.Use(async (context, next) =>
{
    var path = context.Request.Path.Value;
    if (path?.Equals("/v1/chat/completions", StringComparison.OrdinalIgnoreCase) == true)
    {
        context.Request.EnableBuffering();

        using var reader = new StreamReader(context.Request.Body, leaveOpen: true);
        var body = await reader.ReadToEndAsync();
        context.Request.Body.Position = 0;

        string? model = null;
        if (!string.IsNullOrEmpty(body))
        {
            try
            {
                var json = System.Text.Json.JsonDocument.Parse(body);
                if (json.RootElement.TryGetProperty("model", out var modelElement))
                {
                    model = modelElement.GetString();
                }
            }
            catch (System.Text.Json.JsonException) { }
        }

        if (string.IsNullOrWhiteSpace(model))
        {
            var logger = context.RequestServices.GetRequiredService<ILogger<Program>>();
            logger.LogWarning("Chat completions request missing required 'model' field");
            context.Response.StatusCode = StatusCodes.Status400BadRequest;
            context.Response.ContentType = "application/json";
            await context.Response.WriteAsJsonAsync(new { 
                error = new { 
                    message = "The 'model' field is required", 
                    type = "invalid_request_error", 
                    param = "model", 
                    code = "missing_required_parameter" 
                } 
            });
            return;
        }

        context.Request.Path = $"/{model}/v1/chat/completions";
    }
    await next();
});

app.UseRouting();

app.ConfigureKnowledgePipeline();

// Map OpenAI chat completions endpoint for each registered agent
foreach (var agentBuilder in agentBuilders)
{
    app.MapOpenAIChatCompletions(agentBuilder);
}

app.MapGet("/", () => Results.Redirect("/swagger"));

app.LogStartupComplete();

app.Run();

That's it. No CORS configuration needed (LibreChat makes server-side requests). No custom request/response models. No manual streaming code. The framework does the heavy lifting - I just wire it up. Sometimes the best code is the code you don't have to write.

The key insights:

Each agent gets its own endpoint via MapOpenAIChatCompletions
Inline middleware handles routing from /v1/chat/completions based on model
ToolCallFilterAgent hides internal tool execution from downstream clients
KnowledgeTitleAgent handles title generation without tool complexity

LibreChat Test

Open LibreChat, select "Agent Framework" as the endpoint, choose a model from the dropdown (Knowledge, KnowledgeSearch, or KnowledgeTitle), and start chatting. You should see:

Streaming responses (that satisfying typing effect)
Tool calls working transparently (KnowledgeSearch uses tools, but you only see the results)
Automatic title generation (thanks to KnowledgeTitle)

Architecture Overview

Let me step back and look at what I've built (and maybe pat myself on the back a little):

%%{init: {"theme": "dark"}}%%
flowchart TB
    subgraph Clients
        LC[LibreChat]
        API[Direct API Calls]
    end

    subgraph "Knowledge API"
        MR[Model Router Middleware]
        E1["/Knowledge/v1/chat/completions"]
        E2["/KnowledgeSearch/v1/chat/completions"]
        E3["/KnowledgeTitle/v1/chat/completions"]
    end

    subgraph Agents
        KA[Knowledge Agent]
        KSA[KnowledgeSearch Agent]
        KTA[KnowledgeTitle Agent]
        TCF[ToolCallFilterAgent]
    end

    subgraph Storage
        PG[(PostgreSQL)]
    end

    LC -->|"/v1/chat/completions"| MR
    API --> MR
    MR -->|"model: Knowledge"| E1
    MR -->|"model: KnowledgeSearch"| E2
    MR -->|"model: KnowledgeTitle"| E3
    E1 --> KA
    E2 --> TCF
    TCF --> KSA
    E3 --> KTA
    KSA -->|Vector Search| PG

The flow is clean:

Request comes in to /v1/chat/completions with "model": "KnowledgeSearch"
Middleware rewrites path to /KnowledgeSearch/v1/chat/completions
Framework routes to the agent, which is wrapped in ToolCallFilterAgent
Agent executes tools internally, filter strips tool content from response
Client sees clean text output

Multiple clients, multiple agents, one simple routing pattern. It's almost... elegant?

Swagger is still available at /swagger for API exploration and testing.

Summary

I've taken the agents from a development-only DevUI to something that can serve real users through a proper chat interface. And I did it with surprisingly little code - plus one hard-won debugging lesson that I'm still a bit salty about.

The main points are:

MapOpenAIChatCompletions does the heavy lifting - one line per agent, full OpenAI compatibility
Each agent gets its own endpoint - clean separation, easy to test directly
Simple inline middleware handles routing - LibreChat sends to /v1/chat/completions, I rewrite to /{model}/v1/chat/completions
Tool-calling agents need filtering - the ToolCallFilterAgent pattern is essential when exposing agents to downstream clients that don't understand your internal tool calls.
Dedicated agents for specific tasks - KnowledgeTitleAgent for titles, KnowledgeSearch for search, Knowledge for general chat

Next Steps

I've got a solid foundation now - persistence, embeddings, semantic search, a proper UI, and automatic title generation. But there's more to explore:

Observability: OpenTelemetry, Jaeger, understanding what's happening at scale
Agent Loop: Exploring the magic behind automated AI Agents
Authentication: Proper API key validation for production deployments (because "meh, whatever" isn't a security strategy)

But first, I'm letting this settle. Play with LibreChat, see how your agents perform with real conversations, and notice what's missing. The best features come from actual use - not from staring at code and imagining what users might want.

See you in the next post. 🚀

The companion repository has been updated with the part/02-connect-librechat branch containing all the code from this post. Check it out on GitHub.

DGX Spark: Hello World

2025-12-31T00:00:00+00:00

What Better Way to End 2025?

So here's how I'm closing out the year: playing with an NVIDIA DGX Spark. Yes, that DGX Spark - the "personal AI supercomputer" that makes my wallet cry but my inner tech nerd do a happy dance.

I have already spent some time testing LibreChat and ComfyUI on it. The courses at stable-diffusion-art.com also helped me get started with image-generation workflows.

And what better way to ring in the new year than with 128GB of unified memory and a Blackwell GPU sitting on my desk? I mean, some people do fireworks. I do neural networks.

(Yes, I'm aware that's possibly the nerdiest New Year's joke ever.)

Let me walk you through my first-day adventures getting this beautiful beast up and running. Fair warning: there may have been moments of childlike excitement, some creative problem-solving (read: frantically searching for a USB-C keyboard), and an unhealthy amount of "let's try this and see what happens."

The Unboxing

There's something special about unboxing new hardware. But unboxing a DGX? That hits different.

The packaging screams premium - NVIDIA clearly understands that when you're dropping serious money on a personal AI supercomputer, presentation matters. Opening the box felt like a tech ritual. Inside, nestled in protective foam, sat this compact powerhouse that somehow packs a Blackwell GPU and 128GB of unified memory into a form factor that actually fits on a desk.

The unit itself is surprisingly compact. I expected something massive and loud, but NVIDIA engineered this thing to be almost civilized. Almost. We'll see how that holds up once I start pushing it with larger models. Everything was included - power cables, documentation, and that unmistakable feeling of "I'm about to have way too much fun with this."

Alright, enough admiring the hardware. Time to make it do things.

The Setup Experience

I went with the local installation method - straightforward enough. Well, mostly. Here's a fun discovery: do you own a keyboard with USB Type-C? No? Neither did I. Fortunately, a laptop docking station saved the day. Crisis averted.

Once the initial setup was complete, first things first - let's give this machine a proper identity:

sudo hostnamectl set-hostname spark-1
sudo reboot

Why spark-1? Because who knows if there'll be a spark-2 someday. Better to be prepared. Future me will thank present me for this foresight. Or curse me for the temptation.

Installing Ollama

After updating the system, I started with something familiar. Ollama has become my go-to for local LLM deployment - it's absurdly simple to set up:

curl -fsSL https://ollama.com/install.sh | sh

Now, I know what you're thinking - "But what about vLLM? What about llama.cpp? What about those fancy self-compiled versions optimized for Blackwell's SM120 architecture?"

Yes, I've seen those posts. Yes, I'll explore them. But that's a future adventure. For now, let's start with the classics and make sure everything actually works before we go down the optimization rabbit hole.

With Ollama ready, time to pull a model:

ollama pull gpt-oss:20b

Could I run the massive 120B parameter models? Absolutely - that's kind of the whole point of having this hardware. But let's walk before we run. Download a smaller model to verify everything works, then let the big ones download overnight while I sleep. Strategy.

Setting Up LibreChat

Running models from the CLI is fine for testing, but I wanted a web interface. I previously used Open WebUI for my self-hosted LLM setup; this time I chose LibreChat, an open-source chat UI that supports local models.

Docker was pre-installed on the DGX Spark (nice touch, NVIDIA). Though my user wasn't in the docker group - but I'll assume you can figure that one out.

mkdir -p ~/workspaces
cd ~/workspaces/
git clone https://github.com/danny-avila/LibreChat.git
cd LibreChat/
cp .env.example .env

After some experimentation, I settled on these configuration changes:

Environment Configuration

In .env, the key change:

ENDPOINTS=custom

Docker Compose Override

Create a docker-compose.override.yml for your custom settings, and a librechat.yaml for the LibreChat-specific configuration.

docker-compose.override.yml

services:
  api:
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml

librechat.yaml

---
version: 1.2.8
cache: true

endpoints:
  custom:
    - name: "Ollama"
      apiKey: "ollama"
      baseURL: "http://host.docker.internal:11434/v1/"
      models:
        default: [
          "gpt-oss:20b"
          ]
        fetch: true
      titleConvo: true
      titleModel: "current_model"
      summarize: false
      summaryModel: "current_model"
      forcePrompt: false
      modelDisplayLabel: "Ollama"

And that's... almost it.

The Reverse Proxy Dance

Here's where it gets slightly more involved. LibreChat enforces secure cookies by default - great for security, annoying when you're hitting F5 every five seconds during development and don't want to re-authenticate each time.

The solution? Set up a reverse proxy with HTTPS. I use Caddy in my home infrastructure because life's too short to manage SSL certificates manually.

chat.int.domain.tld {
    @lan remote_ip 172.16.29.0/24
    handle {
        reverse_proxy @lan http://172.16.2.123:3080
    }
    handle {
        templates
        respond "Access denied, {{.RemoteIP}}" 403
    }
}

This configuration does a few things:

Only allows access from my local network (the 172.16.29.0/24 range)
Proxies requests to the DGX Spark running LibreChat on port 3080
Returns a 403 for anyone trying to access from outside

It's not always open from outside but when it is (to refresh certificates) this is a great and easy way to deal with this.

I've also configured a custom DNS zone in my router to make chat.int.domain.tld resolve correctly, but that's infrastructure stuff for another post.

First Impressions

And just like that - we're live. Quick setup, everything working, ready to chat with local models running on actual Blackwell hardware. The response times are snappy, the interface is clean, and I can already tell this is going to be a fun playground.

Next Steps

Now that the basics are running, it's time to explore what this hardware can actually do. On my list:

Document Understanding: Feed it files and see how well it comprehends them
Voice integration: Testing spoken conversations with local models
Image generation with ComfyUI: Exploring image-generation workflows on the Blackwell GPU. The stable-diffusion-art.com courses have been a useful starting point.

These are just the fundamentals to get comfortable with the platform. But honestly? Between LibreChat's slick interface for chatting with local models and ComfyUI's node-based wizardry for image generation, I've already had more fun than should be legal.

It was a good way to end 2025: experimenting with new hardware and learning what it can do.

Here's to closing out the year with new adventures, and to many more in 2026! 🎉

I will share more results as I continue testing the DGX Spark.

AI Agents in .NET: Building Agentic RAG

2025-12-28T00:00:00+00:00

Welcome back. In the first post, we set up a basic conversational agent. It worked. It responded. It was... fine.

But let's be honest - an agent that can only chat is just a very expensive echo chamber. Today we're giving our agent actual knowledge. It will remember past conversations, search through its own message history, and - most importantly - decide when to use that knowledge.

This is going to be a long one. Grab coffee. Let's build the next piece of the puzzle.

What We're Building

By the end of this post, we'll have:

A PostgreSQL database for persisting messages and embeddings
A second agent (KnowledgeSearch) that searches conversation history
Tool calling so our main agent can invoke KnowledgeSearch when needed
Autonomous decision-making about when to retrieve information vs. just respond

That last point is the key difference between classic RAG and agentic RAG. We're not blindly stuffing context into every prompt. The agent chooses when retrieval helps.

A Quick Word on RAG

RAG - Retrieval-Augmented Generation - has been the go-to pattern for giving LLMs access to external knowledge. The classic approach:

User asks a question
System searches a knowledge base
Retrieved documents get stuffed into the prompt
LLM generates a response using that context

It works. But it's also... dumb? Every query triggers retrieval, whether needed or not. Ask "What's the capital of France?" and you're still embedding the question, searching vectors, retrieving documents. Wasteful.

Agentic RAG flips this. The agent has tools for retrieval and decides when to use them. Simple questions get simple answers. Complex questions trigger the agent to go digging. Much more elegant.

Heads up: There's a whole universe of RAG variations out there - hybrid RAG combining vector search with full-text search (FTS), reranking strategies, query expansion, and more. If you go down the rabbit hole, you'll find dozens of ways to improve retrieval quality. We're intentionally skipping all of that here to focus on the agentic part - how an agent decides when and how to retrieve. Once you grok that, feel free to explore the retrieval optimizations.

Enough theory. Let's write some code.

Database Foundation

Our agent needs a place to store things - messages, embeddings, knowledge. PostgreSQL with pgvector gives us a solid foundation.

The Schema

We're keeping it simple: messages for chat history, embeddings for semantic search.

%%{init: {
  "theme": "dark",
  "themeVariables": {
    "fontFamily": "Jetbrains Mono",
  },
  "themeCSS": [
    ".er.relationshipLine { stroke: #858585; }",
    ".er.relationshipLabel { fill: #bbbbbb; }",
    ".er.relationshipLabelBox { fill: transparent; }",
    ".er.entityBox { fill: #252526; stroke: #303031; }",
    "[id^=entity-messages] .er.entityBox { fill: #1e3a5f; stroke: #5abae0; }",
    "[id^=entity-embeddings] .er.entityBox { fill: #451a03; stroke: #f59e0b; }"
    ]
}}%%
erDiagram
    messages ||--o| embeddings : "has"
    messages {
        uuid id PK
        uuid conversation_id
        uuid embedding_id FK
        varchar role
        varchar author_name
        text content
        bigint sequence_number
        timestamp created_at
    }
    embeddings {
        uuid id PK
        varchar source_type
        uuid source_id
        text content
        vector vector_1536
        timestamp created_at
    }

A few notes:

conversation_id: Groups messages by conversation/session - indexed for fast retrieval
role: Maps to ChatRole.Value from Microsoft.Extensions.AI (user, assistant, system, tool)
sequence_number: Auto-assigned by a database trigger - ensures correct ordering
source_type: Polymorphic pattern - can reference Message or any future entity (e.g., DocumentChunk)
vector_1536: 1536-dimension embedding from OpenAI's text-embedding-3-small

The DbContext

Entity Framework Core handles the mapping. The key thing we need is pgvector support:

// KnowledgeDbContext.cs
modelBuilder.HasPostgresExtension("vector");

This single line enables the vector data type in PostgreSQL. Without it, EF Core won't know what to do with our embedding vectors.

For the Embedding entity, we tell EF Core the exact column type:

// KnowledgeDbContext.cs
entity.Property(e => e.Vector)
      .HasColumnType("vector(1536)");

The rest is standard EF Core configuration - indexes on ConversationId (our primary query pattern), composite index on ConversationId + SequenceNumber for ordered retrieval, and SourceType + SourceId on embeddings for fast lookups.

Don't skip the indexes. Without them, you're doing full table scans.

Wiring It Up

Database registration goes into our extension method. The important choice: AddDbContextFactory instead of AddDbContext.

// ServiceCollectionExtensions.cs
services.AddDbContextFactory<KnowledgeDbContext>(options =>
{
    options.UseNpgsql(connectionString, npgsqlOptions =>
    {
        npgsqlOptions.UseVector();  // Enable pgvector
    });
});

Why the factory? Our message store and agents live outside the normal HTTP request lifecycle. The factory pattern lets each operation spin up its own short-lived context.

Migration Time

EF Core migrations version our schema:

cd src/Knowledge

# Create the migration
dotnet ef migrations add InitialCreate --project ../Knowledge.Shared --output-dir Migrations

# Apply it
dotnet ef database update --project ../Knowledge.Shared

We also add a trigger migration for auto-incrementing sequence numbers:

// 20251224000001_AddCustomTriggers.cs
migrationBuilder.Sql("""
    CREATE OR REPLACE FUNCTION assign_message_sequence_number()
    RETURNS TRIGGER AS $$
    BEGIN
        SELECT COALESCE(MAX(sequence_number), 0) + 1
        INTO NEW.sequence_number
        FROM messages
        WHERE conversation_id = NEW.conversation_id;
        RETURN NEW;
    END;
    $$ LANGUAGE plpgsql;
    """);

migrationBuilder.Sql("""
    CREATE TRIGGER trg_messages_sequence_number
    BEFORE INSERT ON messages
    FOR EACH ROW
    WHEN (NEW.sequence_number = 0 OR NEW.sequence_number IS NULL)
    EXECUTE FUNCTION assign_message_sequence_number();
    """);

This assigns sequence numbers per conversation. The WHERE conversation_id = NEW.conversation_id ensures each conversation has its own sequence. For high-concurrency production use, consider using a proper sequence/identity instead of MAX().

The Conversation Workaround

Before we get to the message store, there's a wrinkle. The framework's DevUI doesn't pass AgentThread information to custom ChatMessageStore implementations. No thread ID means no way to group messages by conversation using the framework's intended abstractions.

We could give up on persistence entirely. Or we could be pragmatic.

The workaround is dead simple: generate a conversation ID once at startup.

// ConversationWorkaround.cs
public static class ConversationWorkaround
{
    public static Guid CurrentConversationId { get; } = Guid.NewGuid();
}

One GUID, initialized once when the application starts, shared for the lifetime of the process. Every message gets tagged with that ID. Restart the app? New ID, new conversation.

We add a corresponding ConversationId column to our Message entity - just a Guid property that gets persisted alongside the role, content, and sequence number.

The Message Store

With our workaround in place, the ChatMessageStore implementation becomes straightforward. The framework calls AddMessagesAsync after each exchange, and GetMessagesAsync when loading history.

The key insight: we use IDbContextFactory<KnowledgeDbContext> instead of injecting a DbContext directly. Why? The store lives outside the normal HTTP request lifecycle. The factory pattern lets each operation spin up its own short-lived context - no connection leaks, no stale entity tracking.

When adding messages, we tag each one with ConversationWorkaround.CurrentConversationId:

// KnowledgeChatMessageStore.cs
var message = new Message
{
    Id = Guid.TryParse(chatMessage.MessageId, out var id) ? id : Guid.NewGuid(),
    ConversationId = ConversationWorkaround.CurrentConversationId,
    Role = chatMessage.Role.Value,
    AuthorName = chatMessage.AuthorName,
    Content = chatMessage.Text ?? string.Empty,
    SequenceNumber = 0,  // Trigger auto-assigns
    CreatedAt = chatMessage.CreatedAt?.UtcDateTime ?? DateTime.UtcNow
};

When retrieving, we filter by that same ID:

// KnowledgeChatMessageStore.cs
var messages = await dbContext.Messages
    .Where(m => m.ConversationId == conversationId)
    .OrderBy(m => m.SequenceNumber)
    .ToListAsync(cancellationToken);

This keeps each app instance isolated. Messages from yesterday's debugging session don't pollute today's conversation.

Why This Workaround?

The ideal solution would use the framework's AgentThread abstraction - each thread gets its own conversation, the UI manages thread creation, everything Just Works™. But DevUI doesn't pass thread information to custom stores yet.

Good news: our ChatMessageStore does get called. Messages persist. The agent loads context on startup. The workaround gives us:

Per-instance conversations: Each app restart starts fresh
Persistent context: Within a session, the agent remembers everything
Future-proof schema: When DevUI supports threads, we swap ConversationWorkaround.CurrentConversationId for the real thread ID

We've opened issue #3000 to track proper thread support. For now, this gets the job done.

Embeddings

Before building the KnowledgeSearch agent, it helps to understand embeddings, which are the basis of semantic search. If you already know how they work, you can skip this section.

This section covers the theory, but we're not just hand-waving. As we go, we'll be building toward our second agent that can search through conversation history and return relevant context.

The Big Reveal

An embedding is just a list of numbers. That's it. That's the tweet.

%%{init: {"theme": "dark"}}%%
flowchart LR
    A["🐱 cat"] --> B["[0.021, -0.034, 0.089, 0.012, ..., -0.045]"]
    style A fill:#064e3b,stroke:#10b981,color:#fff
    style B fill:#252526,stroke:#303031,color:#bbbbbb

When you feed text into an embedding model, it spits out a vector - 1536 floating-point numbers for OpenAI's text-embedding-3-small. These numbers encode the meaning of the text. Not the letters, not the spelling - the actual semantic content.

The magic? Similar meanings produce similar numbers.

%%{init: {"theme": "dark"}}%%
flowchart LR
    A["🐱 cat"] --> V1["[0.021, -0.034, 0.089, ...]"]
    B["🐈 kitten"] --> V2["[0.019, -0.031, 0.092, ...]"]
    C["🗳️ democracy"] --> V3["[-0.067, 0.142, -0.023, ...]"]

    style A fill:#064e3b,stroke:#10b981,color:#fff
    style B fill:#064e3b,stroke:#10b981,color:#fff
    style C fill:#451a03,stroke:#f59e0b,color:#fff
    style V1 fill:#252526,stroke:#303031,color:#bbbbbb
    style V2 fill:#252526,stroke:#303031,color:#bbbbbb
    style V3 fill:#252526,stroke:#303031,color:#bbbbbb

See how "cat" and "kitten" have similar-ish numbers, while "democracy" is completely different? That's semantic similarity, encoded as math.

The "magic" demystified: This is the whole secret behind AI "understanding" - it's just numbers. There's no mystical intelligence, no consciousness pondering the nature of cats. Just insanely clever linear algebra operating in 1536-dimensional space. Once you see it, you can't unsee it. Beautiful, really.

Where Things Live in Vector Space

Imagine plotting these vectors in space. The real vectors have 1,536 dimensions, but a three-dimensional sketch is enough to show the idea of clusters and similarity scores.

%%{init: {
  "theme": "dark"
}}%%
flowchart LR
    subgraph Pets[" "]
        A[cat]
        B[kitten]
    end
    subgraph Civics[" "]
        D[democracy]
        E[parliament]
    end

    A ---|"0.94"| B
    A -.-|"0.31"| D
    D ---|"0.89"| E

    style A fill:#064e3b,stroke:#10b981,color:#fff
    style B fill:#064e3b,stroke:#10b981,color:#fff
    style D fill:#451a03,stroke:#f59e0b,color:#fff
    style E fill:#451a03,stroke:#f59e0b,color:#fff

Similar concepts cluster together. Words about pets huddle in one corner, political terms in another. In the real 1536-dimensional space, these relationships become incredibly nuanced - the model captures categories, analogies, context, even vibes. The scores on the edges are cosine similarities: higher numbers mean those meanings live closer together.

This is why semantic search works. Ask "how do I create an agent?" and the system finds documents about "instantiating agents" and "agent initialization" - different words, same neighborhood in vector space.

How "Close" Are Two Vectors?

We use cosine similarity - basically measuring the angle between two arrows in space.

Similarity = 1: Identical meaning (same direction)
Similarity = 0: Unrelated (perpendicular)
Similarity = -1: Opposite meaning (opposite direction)

You don't need to understand the math. Just know: higher number = more similar meaning. When we search our knowledge base, we're finding the vectors that point in roughly the same direction as the query.

%%{init: {"theme": "dark"}}%%
flowchart LR
    subgraph Query
        Q["How do I build an agent?"]
    end
    subgraph Results["Top Matches (by similarity)"]
        R1["0.94 - Creating your first agent"]
        R2["0.91 - Agent initialization guide"]
        R3["0.87 - Setting up agent tools"]
        R4["0.34 - PostgreSQL connection strings"]
    end
    Q --> R1
    Q --> R2
    Q --> R3
    Q -.-> R4

    style Q fill:#1e3a5f,stroke:#5abae0,color:#fff
    style R1 fill:#064e3b,stroke:#10b981,color:#fff
    style R2 fill:#064e3b,stroke:#10b981,color:#fff
    style R3 fill:#064e3b,stroke:#10b981,color:#fff
    style R4 fill:#451a03,stroke:#f59e0b,color:#fff

The PostgreSQL doc isn't wrong, it's just pointing in a completely different direction. Low similarity score, doesn't make the cut.

The Model We'll Use

OpenAI offers several embedding models:

Model	Dimensions	Use Case
`text-embedding-3-small`	1536	Most applications
`text-embedding-3-large`	3072	When you need more context
`text-embedding-ada-002`	1536	Legacy

We'll use text-embedding-3-small. It's cheap, fast, and good enough for most use cases. The larger model is more accurate but costs more - classic tradeoff. Start small, upgrade if you need to.

Now the question becomes: where do we store 1536 floating-point numbers per piece of text, and how do we search them efficiently?

pgvector Setup

PostgreSQL with pgvector gives us a proper vector database without leaving our existing stack. No separate Pinecone or Weaviate instance to manage.

Enabling the Extension

First, we need pgvector enabled in our database. Connect to PostgreSQL and run:

CREATE EXTENSION IF NOT EXISTS vector;

This installs the vector data type and operators. You only need to do this once per database. If you're using my dev container template, this is already handled in the database initialization scripts.

Verify it worked:

SELECT * FROM pg_extension WHERE extname = 'vector';
-- Should return one row showing the vector extension

The Embedding Entity

We want a generic approach - store embeddings for any content type (messages, documents, whatever). The key property:

// Embedding.cs
public Vector Vector { get; set; } = null!;  // pgvector's native type

We use pgvector's native Vector type instead of float[]. The Pgvector.EntityFrameworkCore package handles the mapping between C# and PostgreSQL.

The entity also tracks what was embedded via SourceType + SourceId - a poor man's polymorphic association. Not elegant, but flexible. We can add new source types (documents, code snippets) without schema changes.

We also store the original Content alongside the vector. Why? When we retrieve matches, we need the actual text to show. And if embeddings get stale, we can re-generate from the stored content.

EF Core Configuration

We already covered the key line in Section 1 - HasColumnType("vector(1536)"). The dimension must match your embedding model. OpenAI's text-embedding-3-small produces 1536 dimensions, so that's what we use.

Indexing for Speed

Without an index, similarity search scans every row - fine for 1,000 embeddings, catastrophic for 1,000,000. HNSW (Hierarchical Navigable Small World) gives us logarithmic search time.

We create the index via a migration (we include this in our AddCustomTriggers migration):

// 20251224000001_AddCustomTriggers.cs
migrationBuilder.Sql("""
    CREATE INDEX IF NOT EXISTS ix_embeddings_vector_cosine
    ON embeddings
    USING hnsw (vector vector_cosine_ops);
    """);

Breaking this down:

hnsw: The index algorithm - builds a graph structure for fast nearest neighbor search
vector_cosine_ops: Use cosine distance (1 - cosine similarity) as the metric
Creation time: ~1-2 seconds per 10,000 vectors on my laptop

The tradeoff: HNSW uses more memory and takes longer to build, but queries are dramatically faster. For a RAG system, this is always worth it.

Embedding Messages

Time to give our agent some actual knowledge. Instead of indexing external documentation, we're embedding our own conversation history - every message becomes searchable.

Why Messages?

We need something to embed, and chat messages are already there - no external datasets, no document ingestion pipelines, no extra setup. It's demo content that generates itself as you use the agent.

Important distinction: This is not the same as Microsoft.Agents.AI.Memory.ChatHistoryMemoryProvider, which provides memorable context during agent invocation (think: short-term working memory for the current conversation). What we're building is long-term semantic search over historical content. Different problems, different solutions.

The Chunking Problem (Or Not)

For large documents, chunking is essential - split into smaller pieces, embed each one. But messages are already bite-sized. A typical chat message is well under our embedding model's context limit.

We'll embed messages as-is. No chunking needed. If you later want to add document indexing (PDFs, markdown files, whatever), you'd apply chunking:

Fixed size: Every chunk is N tokens. Simple but might split mid-sentence.
Paragraph-based: Split on natural boundaries. Preserves context but uneven sizes.
Semantic: Use the LLM to identify logical sections. Expensive but smart.

For documents, fixed size with overlap (500 tokens, 50 token overlap) is the standard. But for messages, we skip this entirely.

The Embedding Service

We wrap IEmbeddingGenerator<string, Embedding<float>> from Microsoft.Extensions.AI in a simple service. The key conversion:

// EmbeddingService.cs
var result = await _embeddingGenerator.GenerateAsync(text, cancellationToken);
return new Vector(result.Vector.ToArray());

Text goes in, pgvector Vector comes out. The service handles the conversion from the AI library's float array to pgvector's native type. Nothing fancy - just a thin wrapper to keep the embedding generation consistent across the app.

Background Processing

We could embed messages synchronously when they're saved, but that blocks the chat response. Instead, a background service picks up unprocessed messages every 10 seconds.

The trick is using Message.EmbeddingId as both a foreign key and a processing flag:

// EmbeddingBackgroundService.cs
var pendingMessages = await dbContext.Messages
    .Where(m => m.EmbeddingId == null)  // Not yet embedded
    .Where(m => !string.IsNullOrEmpty(m.Content))
    .OrderBy(m => m.SequenceNumber)
    .Take(10)
    .ToListAsync(cancellationToken);

For each message, we generate the embedding and link it back. Once EmbeddingId is set, that message won't be picked up again.

No chunking, no complexity. Message goes in, vector comes out, gets stored. The SourceType = "Message" links back to the original - we'll use this when searching.

The KnowledgeSearch Agent

Once the embeddings are generated, the KnowledgeSearch agent can use them to search the conversation history by meaning.

Why an Agent Instead of a Simple Tool?

You could just wire up a tool function. But wrapping it in an agent brings benefits:

Clear separation: Search logic lives in its own class, testable in isolation
Dependency injection: Proper lifetime management for database contexts and services
Composability: Later, we can add more specialized agents (DocSearch, WebSearch, etc.)

This is the "agentic" part of agentic RAG - agents with tools, each specialized for their task.

The Implementation

The flow is straightforward: embed the query, search pgvector, format results.

First, we embed the search query using the same model that embedded our messages:

// KnowledgeSearchAgent.cs
var queryVector = await _embeddingService.EmbedAsync(query);

The vector search uses pgvector:

// KnowledgeSearchAgent.cs
var results = await dbContext.Embeddings
    .Where(e => e.SourceType == "Message")
    .Select(e => new
    {
        Embedding = e,
        Distance = e.Vector.CosineDistance(queryVector)
    })
    .Where(x => x.Distance <= (1 - DefaultMinScore))  // DefaultMinScore = 0.40
    .OrderBy(x => x.Distance)
    .Take(DefaultTopK)  // DefaultTopK = 10
    .ToListAsync();

A few notes:

CosineDistance() returns distance (0 = identical, 2 = opposite), not similarity. Lower is better.
Threshold of (1 - 0.40) means we want at least 40% similarity. Tweak DefaultMinScore based on your use case.
IDbContextFactory gives us a fresh context per search - the agent is a singleton, but each query gets its own connection.

Finally, we fetch the actual messages and format them with timestamps. The timestamps matter - they help the LLM understand recency.

The pgvector Query

EF Core translates this LINQ query to:

SELECT e.*, e.vector <=> @queryVector AS distance
FROM embeddings e
WHERE e.source_type = 'Message'
  AND e.vector <=> @queryVector <= 0.6  -- 1 - DefaultMinScore
ORDER BY e.vector <=> @queryVector
LIMIT 10;

The <=> operator is pgvector's cosine distance. Lower distance = better match. The HNSW index we created earlier makes this logarithmic instead of linear - critical at scale.

Wiring It Up

Now we connect everything in AgentFactory and Program.cs.

The Agent Factory

Wiring the tool is the key step. We use AIFunctionFactory.Create() to turn our instance method into something the agent can call:

// AgentFactory.cs
var searchAgent = services.GetRequiredService<KnowledgeSearchAgent>();

return chatClient.CreateAIAgent(new ChatClientAgentOptions
{
    Id = key,
    Name = key,
    ChatOptions = new ChatOptions
    {
        ConversationId = "global",
        Instructions = KnowledgeSearchSystemPrompt,
        Tools = [AIFunctionFactory.Create(searchAgent.SearchConversationHistoryAsync)],
        ToolMode = ChatToolMode.Auto
    }
});

The [Description] attributes on our method and parameters become the tool's schema - the LLM sees them and knows what the tool does and what arguments it needs.

ToolMode = ChatToolMode.Auto is important. It tells the model to decide when to use tools, rather than always using them or never using them.

The system prompt is equally crucial. We tell the LLM when to use the tool:

DECISION FRAMEWORK:
- For general knowledge (math, common facts): Answer directly without tools
- For recall questions ('did we discuss X?'): Use SearchConversationHistory
- When unsure if something was discussed: Search first rather than guessing

Without this guidance, models either never use tools or use them for everything. The prompt teaches restraint.

Registration in Program.cs

The key registration:

// Program.cs
builder.Services.AddSingleton<KnowledgeSearchAgent>();

Why singleton? The agent factory resolves from the root provider during startup. This is safe because KnowledgeSearchAgent only depends on singletons (IEmbeddingService, ILogger) and factories (IDbContextFactory) - no scoped services leaking through.

The rest follows the same pattern we established: AddAIAgent with factory delegates, AddHostedService for the background embedding processor.

Before and After

Let's see the difference:

Without RAG:

User: "What did we discuss about database indexes?" Agent: "I don't have memory of our past conversations..."

With KnowledgeSearch:

User: "What did we discuss about database indexes?" Agent: calls SearchConversationHistory("database indexes") Agent: "Based on our earlier conversation, we discussed adding indexes for ConversationId and the composite index for ordered retrieval..."

Night and day.

Summary

We've covered a lot of ground today, but we're still just scratching the surface.

We learned how to take abstract concepts like embeddings and store them in an actual database using pgvector. We saw how to consume that knowledge by building a specialized agent that can perform semantic searches over our own conversation history.

Along the way, we touched on the importance of database persistence, the nuances of tool calling with AIFunctionFactory, and how to manage agent lifetimes in a .NET application. We also explored chunking and more advanced RAG strategies like hybrid search and reranking - topics that are definitely worth exploring as you dive deeper into the world of AI.

The full code is on the part/01-agentic-rag branch. Clone it, run it, break it, and most importantly, make it your own.

Microsoft's official examples are also worth reading. The framework implements some features, including search, with higher-level abstractions such as TextSearchProvider. I used the lower-level approach here to make each step visible.

Here are some examples worth checking in the Microsoft Agent Framework repository:

Getting Started on GitHub

Agent_Step03_UsingFunctionTools/Program.cs
Agent_Step06_PersistedConversations/Program.cs
Agent_Step07_3rdPartyThreadStorage/Program.cs
Agent_Step12_AsFunctionTool/Program.cs
AgentWithRAG/*

Next Steps

We now have an agent that can remember and retrieve earlier conversations.

The next step is the Agent Loop. Instead of a single request and response, the agent can act, observe the result, and adjust its next step until the task is complete. This pattern is the basis for more autonomous coding assistants.

As these agents become more autonomous, we also need to know exactly what they're thinking. That's why we'll be diving into Observability and tracing so we can peek inside the "black box" and see every tool call, every reasoning step, and every decision the agent makes in real-time.

We're moving from "chatbots" to "collaborators." I'll see you in the next one as we start closing the loop. 🚀

AI Agents in .NET: Let's Build Something Smart

2025-12-21T00:00:00+00:00

Welcome to a new blog series about building AI agents in .NET.

Yes, you read that right - I just said .NET. Not Python. C#. Curly braces. Strong typing. With drums and trumpets.

Over the coming posts, we'll explore the Microsoft Agent Framework, build actual agentic systems, and - most importantly - have some fun doing it. This first post sets the stage: why I'm doing this, what we're building, and how to get started with the companion repository.

Here is how to get started.

Why, You Ask?

Honestly? I got a little restless. Every AI agent tutorial out there follows the same well-worn path:

"Build a weather agent!" - Revolutionary stuff. Though I hear windows also exist.
"Spam detection with AI!" - Gmail's been doing this since 2004.
"Customer service chatbot!" - Oh good, we definitely need more of those.

These examples are useful for learning the basics, but I wanted to build something closer to a real application.

This series is about building agents that are genuinely smart, genuinely fun, or ideally both. No boring examples. No wrapping API calls in agent clothing and calling it intelligent.

As for the language choice - I've always been a C-family person. Python is lovely for what it does, but give me curly braces and strong typing any day. When Microsoft released the Agent Framework for .NET? Yeah, that got me genuinely excited. First-class AI agents in C#. Native support, proper tooling, the whole package.

The Microsoft Agent Framework

So what exactly are we working with? The framework comes with everything you need to build proper agentic systems:

Native C# support (obviously)
A beautiful DevUI for testing and debugging your agents - still in preview and missing some Python-side features, but it gets the job done
Built-in patterns for common agentic scenarios (the fun stuff)
Integration with the broader .NET ecosystem (finally!)

And that's what this blog series is all about.

About DevUI

Speaking of DevUI - if you head over to Microsoft's documentation and switch to the C# tab, you're greeted with this gem:

"DevUI documentation for C# is coming soon. Please check back later or refer to the Python documentation for conceptual guidance."

Ah yes, the classic "refer to Python" move. You know, the language we specifically chose not to use for this series? The irony isn't lost on me. But hey, I'm not bitter - I'm just impressed they managed to ship a working DevUI before the documentation. That's actually kind of bold.

The DevUI is a useful web interface for chatting with agents and inspecting their behavior during development. It does not replace proper tracing with tools such as OpenTelemetry and Jaeger, but it works well for quick iteration and debugging. I will cover observability separately in a later post.

The Knowledge Repository

To support this series, I've created a companion repository called Knowledge. I briefly considered "AI-Stuff-I-Throw-Together-At-2AM" but that didn't seem like a good fit. So I thought about it - I'm deepening my own knowledge about AI as I create this series, and hopefully you'll gain some knowledge along the way too. Yeah, let's face it: Knowledge is simple. Sometimes simple works.

The repository is structured as a progressive learning path. Each branch builds on the previous one, taking you from zero to building sophisticated agentic systems. Here's what we're working with:

Branch	Topic	What You'll Learn	Codespace
`main`	Repository & Hello World Agent	Project setup, DevUI, your first conversational agent

More branches will be added as the series progresses. And honestly? That Codespaces button is kind of magical - click it, grab a coffee, and come back to a fully configured dev environment. No setup, no dependencies, just ready to go. I still find that ridiculously cool.

Star the repo if you want to follow along!

Development Environment

You've got two options here - pick whichever fits your workflow.

Dev Container Setup

First things first: reproducible development environments. The repository includes a .devcontainer configuration with:

.NET 10
PostgreSQL with pgvector for when we get into embeddings and semantic search
All the tooling pre-configured

Just open the repo in VS Code, click "Reopen in Container," and you're ready to go. The classic "works on my machine" problem? Solved.

You can also open it in a Codespace and work entirely in the browser without a local setup.

Classic

And for those of you rolling your eyes at all this container and cloud stuff - fair enough. Install the .NET 10 SDK, fire up VS Code or Visual Studio, clone the repo, and just go. Sometimes the old ways are the best ways. That said, you'll want to get PostgreSQL with pgvector set up sooner rather than later - we'll need it for embeddings and semantic search in upcoming posts.

What's on the Main Branch?

Let me walk you through what you'll find when you clone the repo. The main branch sets up everything you need to hit the ground running with AI agent development.

Project Structure

The solution is organized into two projects:

Knowledge - The main web application that hosts our agents and the DevUI
Knowledge.Shared - Shared configuration, extensions, and utilities

This separation keeps things clean as we add more complexity in future posts.

Configuration Done Right

One thing I'm particular about is handling configuration properly. In Knowledge.Shared, we have a KnowledgeSettings class that gives us strongly-typed access to our config values.

The important bits are these two properties:

public string ApiKey { get; set; } = string.Empty;

public string ApiEndpoint { get; set; } = string.Empty;

ApiKey is where your OpenAI (or compatible) API key goes. ApiEndpoint is optional - leave it empty and we'll hit OpenAI's default endpoint, or set it to point at Azure OpenAI, a local model, whatever you need.

Now, you definitely don't want to hardcode API keys in your source code. That's how keys end up on GitHub and suddenly you're funding a stranger's LLM experiments. Instead, we use .NET User Secrets:

cd src/Knowledge
dotnet user-secrets set "Knowledge:ApiKey" "your-api-key-here"

Your key stays on your machine, outside of source control. Sleep well at night.

Wiring Up the Agent

The following sections walk through Program.cs piece by piece.

First, the imports - nothing too surprising here:

using System.ClientModel;
using Knowledge.Shared.Extensions;
using Microsoft.Agents.AI.DevUI;
using Microsoft.Agents.AI.Hosting;
using Microsoft.Extensions.AI;
using OpenAI;

We're pulling in the Agent Framework (Microsoft.Agents.AI.*), Microsoft's AI abstractions (Microsoft.Extensions.AI), and the official OpenAI client. Standard .NET web app stuff otherwise.

Next, we create our builder and call into our configuration extension:

var builder = WebApplication.CreateBuilder(args);

builder.ConfigureKnowledgeDefaults((settings, logger) =>
{
    // ...
});

ConfigureKnowledgeDefaults is a helper method in our shared project. It handles loading appsettings.json, binding it to our KnowledgeSettings type, and then gives us a callback where we can access both the settings and a logger. This keeps Program.cs clean while still giving us full control.

Inside that callback, we set up OpenAI. First, a sanity check:

if (string.IsNullOrWhiteSpace(settings.ApiKey))
{
    logger.LogWarning("No API key configured. Set Knowledge:ApiKey in user secrets.");
}

Better to warn loudly than fail silently.

Then we create the OpenAI client options. If a custom endpoint is configured, we use it:

var options = new OpenAIClientOptions();

if (!string.IsNullOrEmpty(settings.ApiEndpoint))
{
    options.Endpoint = new Uri(settings.ApiEndpoint);
}

This is what lets you swap between OpenAI, Azure OpenAI, or even a local model running through something like Ollama with an OpenAI-compatible API.

Now we create the actual client and register it with dependency injection:

var client = new OpenAIClient(new ApiKeyCredential(settings.ApiKey), options);

builder.Services.AddChatClient(client.GetChatClient("gpt-4.1").AsIChatClient());

GetChatClient("gpt-4.1") gets us a chat client for that specific model. .AsIChatClient() wraps it in Microsoft's IChatClient abstraction, which is what the Agent Framework expects. Using this abstraction means we could swap out OpenAI for any other provider without changing our agent code.

And finally - the actual agent registration:

builder.AddAIAgent("Knowledge", "You are a helpful agent named Knowledge.");

That's it. One line. We give it a name and a system prompt, and the framework handles the rest. We'll make this more sophisticated in future posts, but for a "hello world" agent, this is all you need.

Finishing the Pipeline

After our configuration callback, we register a few more services:

builder.Services.AddOpenAIResponses();
builder.Services.AddOpenAIConversations();

These set up the Agent Framework's handlers for OpenAI's responses and conversations API patterns.

Then we build the app and configure the HTTP pipeline:

var app = builder.Build();

app.ConfigureKnowledgePipeline();

ConfigureKnowledgePipeline is another shared helper - it sets up logging, error handling, and other middleware that we'll want across all our experiments.

Finally, we map our endpoints:

app.MapOpenAIResponses();
app.MapOpenAIConversations();
app.MapDevUI();

app.MapGet("/", () => Results.Redirect("/devui/"));

app.Run();

MapOpenAIResponses() and MapOpenAIConversations() expose endpoints that follow OpenAI's API patterns. MapDevUI() enables the Agent Framework's built-in developer interface.

That last MapGet just redirects the root URL to the DevUI. Because when you're developing agents, that's where you want to be.

Running the Application

Once configured, getting started is simple:

dotnet run --project src/Knowledge

Navigate to http://localhost:5000/devui and you'll see the DevUI - a beautiful interface for interacting with your agents, inspecting their reasoning, and debugging when things inevitably go sideways.

Summary

We've covered a lot of ground in this introductory post. You now have:

A companion repository with a reproducible dev container setup
A working "hello world" agent using the Microsoft Agent Framework
Proper configuration with user secrets (no API keys in source control!)
The DevUI for testing and debugging your agents

The foundation is solid. Now comes the fun part.

Next Steps

We've got the foundation in place - a working agent, DevUI, proper configuration. But let's be real: a "hello world" agent isn't going to impress anyone, least of all ourselves.

Next, I will add tools so the agent can perform actions, explore multi-agent scenarios, and use PostgreSQL with pgvector for embeddings and semantic search. A later post will also add proper observability.

But first things first. Step by step.

If you're a .NET developer who's been watching the AI agent space from the sidelines, wondering when C# would get some love - welcome. If you're just someone who's bored of the same old tutorials and wants to see something different - also welcome.

Clone the repo, star it if you're feeling generous, and let's build something that's actually worth building.

See you in the next post. 🚀

🚀 New Release: mcp-windbg 0.12.2

2025-12-15T00:00:00+00:00

I've just released version 0.12.2 of mcp-windbg, bringing some significant enhancements that expand how and where you can perform crash dump analysis.

What's New

This release introduces two major features that address the flexibility and deployment needs many of you have been asking about.

First up is support for the Prompts API, which fundamentally changes how you can interact with crash dump analysis. Rather than being tied to a local setup, you can now trigger triage analysis from anywhere in your environment. The server can be deployed on any machine in your network, whether that's a dedicated analysis box, a build server, or even directly on a file server hosting your crash dumps. This means you can centralize your debugging infrastructure and access it from wherever you're working.

Second, this release adds streamable-http as an alternative transport backend. This gives you more options for how the server communicates, particularly useful in containerized or networked environments where different transport mechanisms might be preferable.

The combination of these features means you can now set up a centralized crash analysis service that developers across your team can leverage without needing to install WinDbg or configure everything locally. Want to analyze dumps directly on the file server where they're stored? Now you can.

Getting Started

If you want to try out the latest version, installation is straightforward:

pip install mcp-windbg

The project is open source and available on GitHub at https://github.com/svnscha/mcp-windbg. If you find it useful, a star on the repository is always appreciated.

A Real-World Example

No release post would be complete without putting the tool to work on an actual crash dump. Here's an example of the analysis in action:

Even Copilot needs a debugger sometimes.

The Passenger Seat Developer

2025-10-27T00:00:00+00:00

The Great Prototype Experiment

Here's what nobody tells you about AI-assisted rapid prototyping: After six months and nearly 100 projects, I had to face an uncomfortable truth.

Every prototype feels like success. But is it really?

Why, You Ask?

Picture this: Me, armed with Claude, spinning up project after project like I'm some kind of coding machine gun. A productivity suite here, a file manager there, throw in some web scrapers, automation tools, data processors - you name it, I've probably built a prototype of it in the past six months.

Nearly 100 projects. The dopamine hits were insane. Every idea that popped into my head, no matter how half-baked, could become a working prototype in hours instead of weeks. The velocity felt otherworldly.

The result took me too long to acknowledge: out of nearly 100 prototypes, only one reached production.

One. Literally. One.

That project? mcp-windbg. And guess what made it special? It's the only one where I spent those classic, grinding hours sitting there, actually understanding every line of code, debugging the edge cases, and wrestling with the gnarly implementation details.

The Dopamine Factory

Let me be real with you about what those early days felt like. I'd wake up with some random idea - "What if I built a tool that automatically organizes screenshots by content?" or "I need a better way to manage my development environments" - and by lunch, I'd have a working prototype.

Six months ago, I was writing about vibe coding like I'd discovered fire. The euphoria was real - watching AI refactor entire codebases, generate complex implementations, solve architectural problems in seconds. I was living in that perfect state where "the barrier between thinking and implementing just got so much thinner."

Me: Build me a screenshot organizer that uses OCR to categorize images
Claude: *Generates Python app with OCR integration, file management, GUI*
Me: This actually works perfectly!

The rush was incredible. Idea to implementation in hours. No tedious boilerplate. No debugging mysterious dependency issues. No wrestling with documentation. Just pure, frictionless creation.

I felt like a goddamn wizard. Every prototype that worked felt like validation that I'd cracked some secret code of productivity. Friends would ask what I was working on, and I'd rattle off a dozen projects like I was running a software factory.

That euphoric beginning? It was exactly six months ago. Time has a funny way of providing perspective.

The Reality Check: Why Nothing Shipped

After several months, my project folder had grown to nearly 100 directories, but I still had not shipped anything.

Why? Because prototypes aren't products.

Every time I'd come back to one of these AI-generated prototypes to actually finish it - to handle edge cases, add proper error handling, write tests, or make it production-ready - I'd hit the same wall: I had no clue how the thing actually worked.

The code looked familiar. The structure made sense at first glance. But when it came time to:

Debug why it crashed with certain file types
Add a feature that required understanding the data flow
Optimize performance bottlenecks
Handle edge cases the AI hadn't considered

I was lost. Completely, utterly lost.

The One That Made It: mcp-windbg

So why did mcp-windbg succeed when 99 others failed? It wasn't because I spent months on it - it was a small weekend project. But I approached it differently.

I started by vibe-coding with Claude, just like the other prototypes. Got the basic structure working, had it generating and parsing WinDBG commands. But then - and this is the crucial difference - I actually went back and reviewed what the AI had built. Debugged the edge cases myself. Traced through the subprocess communication to understand how it really worked.

When pytest failures popped up, I didn't just ask Claude to fix them. I sat there and figured out why they were failing. When the CDB interaction got weird with certain commands, I debugged it manually until I understood the communication protocol.

The result? A weekend project that actually solved a real problem in my daily work. Something I could confidently maintain, extend, and explain to others.

I owned the code because I'd taken the time to understand what Claude had built.

The Brutal Truth About AI-Generated Prototypes

Those 99 failed projects weren't failures because the code was bad. Most of them actually worked pretty well for their basic use cases. They failed because I'd delegated understanding to AI instead of using it as a tool to support my understanding.

Here is what was happening:

Week 1: "Holy shit, look at this amazing prototype!"
Week 2: "I should probably clean this up and ship it"
Week 3: "Hmm, there are some edge cases I need to handle"
Week 4: "Why is this crashing? Let me ask Claude to fix it"
Week 5: "The fix broke something else. This is getting messy"
Week 6: "Maybe I'll just start a new project instead..."

Sound familiar? This cycle repeated so consistently I could set my calendar by it.

The Sitting-There Hours: Why They Matter

You know those classic hours every developer has experienced? The ones where you're just sitting there, staring at code, trying to figure out why something isn't working the way you expect? Those moments when you're debugging line by line, tracing execution paths, and slowly building up a mental model of how everything fits together?

Those hours aren't wasted time. They're investment time.

When you skip those hours - when you let AI generate the solution and just accept it - you never build that intimate knowledge of your own system. You become a tourist in your own codebase.

With mcp-windbg, I didn't spend weeks wrestling with it - it was just a weekend project. But during that weekend, when I hit issues with subprocess communication or weird CDB behavior, I actually debugged them myself instead of immediately asking Claude for fixes. I took the time to understand why certain commands failed and how the debugging session management worked.

That weekend of actually understanding what I was building made the difference between prototype #99 and shipped product #1.

The False Productivity Trap

I felt productive while building those 99 prototypes. Each working demo felt like progress, and my GitHub activity supported that impression. It did not mean I was finishing useful products.

But productivity isn't about how much code you generate. It's about how much value you ship. And by that metric, I had a 1% success rate.

The problem was not AI itself, but how I used it. I treated it as a replacement for understanding instead of a debugger or knowledge base that could help me learn faster.

How I Use AI Now

I still use AI regularly, but now I treat it like any other development tool.

AI as a knowledge base: "How does subprocess communication work in Python?" "What are the edge cases for file parsing?" "Show me different approaches to error handling."
AI as a debugging partner: "Here's my stack trace, what could be causing this?" "This function isn't behaving as expected, help me trace through the logic."
AI for the boring repetitive stuff: Boilerplate code, test scaffolding, documentation generation, refactoring patterns I've done a million times.
AI as a code reviewer: "Does this implementation handle edge cases properly?" "Are there performance issues with this approach?"

The key difference: I use AI to accelerate my understanding, not replace it.

For anything I might ship, the rule is simple: If I can't explain how the core functionality works without looking at the code, I don't ship it. AI can help me get there faster, but it can't get there for me.

This isn't about being a purist or rejecting AI assistance - it's about maintaining professional competence and shipping software you can actually support.

What Success Actually Looks Like

After six months of this experiment, here's what I've learned about successful AI-assisted development:

Delegate the repetitive stuff: Boilerplate generation, test scaffolding, documentation, refactoring patterns you've done before.
Use it as a knowledge multiplier: Research APIs, explore different approaches, get explanations of complex concepts, debug tricky issues.
Keep the understanding: Architecture decisions, core business logic, data flow design, system integration points.
Invest in the sitting-there hours: For anything you plan to ship, spend the time to truly understand how it works.

AI is similar to a good debugger or profiler: it can make you more effective, but it does not replace understanding the system you are building.

The Uncomfortable Question

Here's the question that keeps me up at night: How many developers are building careers on AI-generated code they don't understand?

This is also a matter of professional responsibility. If you own a piece of code, you should be able to explain, modify, and debug it, especially when a production issue occurs and the AI assistant is unavailable.

I don't have a good answer to that question. I just know I don't want to be that kind of developer.

Summary

After six months and nearly 100 AI-assisted prototypes, only mcp-windbg shipped. The difference was that I used AI to speed up my learning instead of asking it to replace that learning.

Remember that uncomfortable truth from the beginning? Every prototype feels like success, but success is measured by shipping, not building. The dopamine hits from rapid prototyping are real, but they're not the same as the satisfaction of maintaining code you actually understand.

The lesson isn't to use less AI. The lesson is to use it better.

AI is like having a brilliant research assistant, debugger, and code reviewer all rolled into one. Use it to explore ideas faster, understand concepts deeper, and eliminate the boring repetitive work that burns you out. But don't delegate the understanding itself.

Next Steps

If this resonates with you, here's what I'd suggest doing right now:

Audit your current projects: Look at your recent work. Can you explain how the core functionality works without looking at the code? If not, spend some time diving into those systems.
Set a new rule: For anything you plan to ship, implement the "explain it without looking" test. If you can't walk someone through how it works from memory, you're not ready to ship.
Change how you prompt: Instead of "Build me X," try "Help me understand how to build X" or "What are the key concepts I need to know for X?"
Embrace the sitting-there hours: When you hit a bug or weird behavior, resist the urge to immediately ask AI for a fix. Spend 15-20 minutes trying to understand it yourself first.

Someone still needs to own the code. AI can help you move faster, but it cannot take that responsibility from you.

🚀 New Release: mcp-windbg 0.10.0

2025-10-11T00:00:00+00:00

mcp-windbg 0.10.0: Now Available on PyPI

Five months after the initial release of mcp-windbg, I'm releasing version 0.10.0 with significant improvements and simplified deployment.

mcp-windbg is now officially available on PyPI. Installation no longer requires cloning repositories or setting up development environments:

pip install mcp-windbg

This represents a significant simplification from the original setup process described in my first article.

Additionally, mcp-windbg is now listed on the official Model Context Protocol registry, which should improve discoverability and enable integrations with various MCP-compatible tools.

Release 0.10.0: Key Features and Improvements

Version 0.10.0 incorporates community feedback and focuses on improving usability across different experience levels with debugging tools.

New Features

Live Debugging Sessions

Added open_windbg_remote and close_windbg_remote functions
Support for connecting to live processes beyond crash dump analysis
Real-time debugging through conversational AI interface

Extended Dump File Support

Full compatibility with .mdmp and .hdmp formats
Microsoft Store WinDbg CDB compatibility
Improved automatic discovery of crash dump files

Development Infrastructure

Migrated to uv package manager for improved build performance
Significantly reduced development setup and build times
Streamlined dependency management

Community Contributions

@sooknarine contributed several key improvements that made this release possible:

#6: Find local dumps with other common extensions - Enhanced automatic discovery of crash dump files
#10: Add support for remote debugging - Implemented live debugging session support

These contributions demonstrate the value of community involvement in open source development.

Infrastructure Improvements

Several behind-the-scenes improvements enhance reliability and maintainability:

Continuous Integration: Automated testing across Python versions 3.10 through 3.14
Dependency Management: Automated security updates and dependency maintenance
Release Process: Streamlined deployment for faster delivery of updates

Documentation Updates

The documentation has been restructured for better usability:

AGENTS.md: Comprehensive debugging instructions specifically for AI assistants
Structured Templates: .github/prompts/dump-triage.prompt.md for consistent crash analysis (inspired by my prompt engineering article)
Repository Wiki: All documentation now lives in an easily searchable wiki
Simplified README: Focused on getting you started in minutes, not hours
This Changelog: So you know what's changing and why

Installation: From Tedious to Trivial

Remember the old installation process? Clone, setup virtual environment, install dependencies, configure paths... ugh.

Here's the new process:

# Install mcp-windbg
pip install mcp-windbg

# That's it. Seriously.

Then add this to your .vscode/mcp.json:

{
	"servers": {
		"mcp_windbg": {
			"type": "stdio",
			"command": "python",
			"args": [
				"-m",
				"mcp_windbg"
			],
			"env": {
				"_NT_SYMBOL_PATH": "SRV*C:\\Symbols*https://msdl.microsoft.com/download/symbols"
			}
		}
	}
}

The installation process is now considerably simplified compared to the previous manual setup requirements.

Next Steps

With 0.10.0 released, these are the next areas I plan to work on:

More AI integrations beyond VS Code
Enhanced live debugging capabilities
Performance optimizations for large dump files
Community-requested features (keep them coming!)

The development roadmap will continue to incorporate community feedback and feature requests.

Getting Started

To begin using mcp-windbg 0.10.0:

Install: pip install mcp-windbg
Configure: Add the MCP server to your VS Code configuration
Use: Load crash dumps and interact through natural language queries
Contribute: Report issues, suggest features, or contribute code improvements

Links:

Community Response and Impact

Since the initial release in May, the project has received significant community engagement. The original article generated over 40,000 page views within the first two days, along with thousands of LinkedIn impressions and direct messages from developers worldwide.

The feedback has been constructive and encouraging. Developers have shared how the tool helped reduce time spent on crash analysis, and several teams have integrated it into their debugging workflows. I've had opportunities to present this work both internally and externally, leading to valuable discussions about AI-assisted development tools.

The open source community response has been particularly gratifying. Contributors like @sooknarine have stepped in to add functionality that benefits all users. The GitHub repository has gained considerable attention, and the project's inclusion in the official MCP registry should further improve its discoverability.

Building something that genuinely helps other developers solve real problems has been rewarding beyond what I expected when I first started working on this as a way to improve my own debugging workflow.

Thanks to everyone who has contributed, shared feedback, or simply tried the tool. The community response has made this project much better than it would have been otherwise.

How to extend GitHub Copilot with prompt files

2025-09-10T00:00:00+00:00

Why, You Ask?

Remember when I went absolutely euphoric about vibe coding? Well, that honeymoon phase taught me one crucial lesson: context matters, and you really need to spend time writing good prompts.

At first, I was frantically scribbling prompts in my notes app like some kind of digital hoarder. Then I graduated to GitHub Copilot instruction files, adding rules like "when asked for review, do this and that." But constantly switching between apps and copy-pasting prompts? I'm tired of it.

GitHub Copilot's prompt files solve this by keeping reusable instructions in the repository.

Using `.prompt.md` Files

Prompt files turn your best prompts into reusable slash commands. VS Code gives you two flavors:

Workspace prompts (.github/prompts/): Travel with your repository, perfect for team-shared helpers
User prompts: Stored in your VS Code profile, available everywhere for personal tools

Both become accessible as /my-prompt directly in VS Code chat. Instead of hunting through notes for that brilliant review prompt, you just type /svnscha-blog-review and boom, there it is.

Note: Prompt files are currently in public preview and may change in future releases.

Real-World Example: Blog Review Prompt

Let me show you what this looks like in practice. I use project prefixes for workspace prompts and /my-... for personal ones.

For this blog, I created /svnscha-blog-review - a specialized prompt that understands my writing style:

---
mode: "agent"
description: "Review blog posts for svnscha.github.io with focus on style, grammar, and technical accuracy"
---

# Blog Post Review for svnscha.github.io

You are an expert editor reviewing a blog post for svnscha's technical blog.

Focus on:

## Writing Style & Tone

- Consider using "Why, You Ask?" openings when it makes sense for the topic (not mandatory for all posts)
- Keep the direct, slightly sarcastic but helpful voice
- Ensure smooth transitions between sections
- End posts with a short summary or practical next steps when they add value

## Technical Accuracy

- Verify code examples are correct and practical
- Check that technical explanations are clear and accurate
- Ensure all file paths and commands are properly formatted

## Grammar & Spelling

- Fix any grammatical errors or typos
- Improve sentence structure where needed
- Maintain consistency in technical terminology

## Content Structure

- Ensure headings flow logically
- Verify examples support the main points
- Suggest a brief summary or actionable next steps when appropriate
- Check that the conclusion ties back to the opening

Provide specific, actionable feedback that maintains the author's voice while improving clarity and correctness.

This becomes available as /svnscha-blog-review in VS Code, giving me instant access to a specialized editor that knows my style.

Smart Naming & Location Strategy

The naming convention is simple: project prefixes for workspace prompts, /my-... for personal ones. So /svnscha-blog-review is specific to this blog, while /my-commit works everywhere.

Choose your location based on scope:

Workspace prompts: Team-shared, project-specific helpers
User prompts: Personal tools that follow you across all projects

Dynamic Prompts with Variables

Make your prompts adapt to context with VS Code variables:

# Code Review Prompt

Review the following code in ${file}:

${selection}

Focus on:
- Security vulnerabilities in ${fileBasename}
- Performance implications 
- Code style consistency with ${workspaceFolderBasename} standards

The most useful variables include:

Workspace: ${workspaceFolder}, ${workspaceFolderBasename}
File context: ${file}, ${fileBasename}, ${fileDirname}
Selection: ${selection}, ${selectedText}

For the full list of available variables and advanced features, check out the VS Code prompt files documentation.

Setting Up Your Prompt Arsenal

Getting started is simple:

Workspace Prompts

Create .github/prompts/ in your repository
Add your .prompt.md files
Commit and push - your team now has access

User Prompts

Open Command Palette (Ctrl+Shift+P)
Run "Chat: New Prompt File"
Choose "User profile" for location
Author and save your prompt

Both methods make prompts available with /prompt-name in GitHub Copilot chat. Workspace prompts travel with your repository, while user prompts sync across devices with Settings Sync.

For examples and community contributions, check out the Awesome GitHub Copilot prompts collection.

Summary

Prompt files transform good prompting from an exclusive skill into a shared superpower. Your team gets expert-level guidance, your hotfix deployments get proper review, and your collective wisdom becomes instantly accessible with slash commands.

Next Steps

Start small - Convert your three most-used prompts to .prompt.md files
Choose scope wisely - Workspace prompts for teams, user prompts for personal tools
Use variables - Make prompts dynamic with ${selection}, ${file}, and ${input:variableName}
Follow naming conventions - Project prefixes for workspace, /my-... for user prompts
Explore the community - Check out Awesome GitHub Copilot prompts
Read the docs - VS Code prompt files documentation has the latest features

The main benefit is simple: useful instructions live with the project and can be reused without copying them into every chat.

AI Meets WinDBG: A Different Way to Analyze Crashes

2025-05-04T00:00:00+00:00

Old Meets New: Bringing Crash Analysis into 2025

Let's face it - while the rest of software development has evolved at warp speed, crash dump analysis feels like it's been preserved in digital amber for decades. We've got self-driving cars and pocket-sized supercomputers, yet here we are, still pecking away at command prompts like it's the dawn of the internet. Why is debugging the only area where we cling to tools that look like they belong in a computer history museum?

Picture this: You, a professional software engineer in 2025, hunched over a terminal, manually typing arcane commands like !analyze -v and .ecxr, squinting at hexadecimal memory addresses, and mentally translating stack traces. All while your friends in other industries are delegating their work to AI assistants that can write entire documents, create art, or automate complex workflows.

Something's wrong with this picture, right?

I wanted a simpler workflow: ask questions in plain language and let an AI assistant run the relevant debugger commands. This is more than a new interface for WinDBG; it changes how you interact with the debugger.

When Inspiration Strikes

During a debugging session at work, I had one of those lightning bolt moments. What if - and stick with me here - we could apply the same AI-assisted "vibe coding" approach to crash dump analysis?

Picture this: instead of manually slogging through memory dumps and command outputs, you simply ask, "Hey, why did this application crash?" and get an intelligent, contextual answer that actually helps you solve the problem.

The idea was too compelling not to pursue. So I built it.

See It In Action: AI-Powered Crash Analysis

Before diving into the technical details, let me show you what this looks like in practice. I have prepared a demo application to showcase two different use cases:

Video 1: Crash Analysis and Automated Bugfix

In this video, I show how Copilot can analyze a crash dump, identify the bug and auto-fix the issue.

Your browser does not support the video tag.

As you can see in the video, instead of manually running WinDBG commands and interpreting the cryptic output, I'm having a natural conversation with GitHub Copilot. The AI quickly identifies that the application crashed, explains which specific conditions led to the crash, and suggests a fix.

Video 2: Automated Crash Dump Analysis of multiple crash dump files

This video demonstrates a different capability: analyzing multiple crash dump files at once. It shows how the tool can quickly identify which dumps belong to your application and which don't.

Your browser does not support the video tag.

Worth noting, it takes just a few seconds until you get your first useful answer. I've played around with this for many hours and let me tell you one thing: You can really go deep. If you ask the right questions, the AI runs WinDBG/CDB commands that I haven't seen in all these years of debugging, and that is simply amazing.

How can this help the industry?

I believe this is one of the really good examples of how AI can boost productivity. Analyzing crash dumps is a very tedious task. It begins with quickly checking and identifying whether crashes are the same or different, and often requires very advanced knowledge when a crash is challenging - really challenging.

Copilot can help here tremendously; it knows how to:

Interpret assembly code (without you having to remember what EAX stands for)
Check memory contents (so you don't have to count hex bytes on your fingers)
Traverse structures with symbols (goodbye to manual pointer arithmetic!)
And so much more

This can help engineers, support teams, and QA staff work with crash dumps without memorizing every debugger command.

How did I build this?

If you've ever worked with WinDBG, you know the drill: cryptic commands, obscure syntax, and endless scrolling through memory addresses and stack traces that make your eyes glaze over. It's the kind of specialized knowledge that takes years to master and feels like speaking an alien language even when you do.

The trick here is connecting WinDBG with AI. To do that, you first need to programmatically control a debugging session, right? There are plenty of options on how to do this. I prefer to keep things simple, so I have chosen CDB, which is Microsoft's Console Debugger. It operates on standard input and output, and that's so much more fun to deal with than setting up COM APIs or similar approaches.

The second part is "connecting with AI." That's where Model Context Protocol Servers come into the game.

Understanding Model Context Protocol Servers

MCP is an open standard developed by Anthropic, released in November 2024. This protocol allows AI models to interact with external tools and data sources - think of it as giving AI assistants "hands" to work with other software. It defines a way for AI assistants to discover, access, and use tools through a consistent interface. In essence, it's what allows GitHub Copilot to "talk" to external programs like WinDBG.

An MCP server acts as the intermediary between the AI model and the tool. It:

Registers available tools with the client
Handles requests from AI models to use these tools
Executes the tool operations and returns results
Maintains context across interactions

Any tool can be made available to an AI model through an MCP server. I built one for WinDBG's CDB debugger.

Why MCP Instead of LanguageModelTool API?

The LanguageModelTool API might eventually be a better fit for this specific use-case. Creating a Visual Studio Extension that "just works" out of the box would potentially simplify the integration process significantly.

However, using MCP directly offers several notable advantages. It works with any AI model, not just limiting itself to Copilot. The server can be used outside VS Code, functioning with various other tools. New features can be easily added without necessitating changes to the core integration. Moreover, it remains platform-independent, avoiding lock-in to any single company's implementation.

The MCP-WinDBG Project

I've implemented a Model Context Protocol server that wraps WinDBG/CDB and exposes its capabilities to AI models within VS Code. Better yet, I've made it open source so everyone can experience this new workflow.

The project, mcp-windbg, connects VS Code and GitHub Copilot to WinDBG's analysis commands.

The actual "hard part" was implementing the CDB (Command-Line WinDBG) interaction layer. And by "hard", I mean vibe-coding with two coffees on a Saturday morning, where I spent more time being annoyed by pyTest failures than actual coding difficulties. The core implementation came together surprisingly quickly!

The rest is primarily wrapper code that implements the Model Context Protocol specifications. Now that I've established and defined the core WinDBG interaction logic, I'm considering refactoring the project to TypeScript. This would enable me to create both an MCP Server in TypeScript and a dedicated Visual Studio Extension, with both implementations leveraging the same underlying CDB interaction layer.

What Does This Mean In Practice?

Let me walk you through what this enables:

Natural language crash analysis: "Why is this application crashing with an access violation at this address?" (Instead of: "What the $%#@ is this heap corruption!?")
Contextual debugging: "Show me the stack trace for thread 5 and explain what each function is doing based on the symbols." (Instead of staring at call stacks like they're ancient hieroglyphics)
Root cause identification: "What's causing this null pointer dereference and where should I look in the code to fix it?" (Instead of playing detective with memory addresses)

Instead of typing obscure commands like !analyze -v followed by a series of manual investigations, you simply ask questions in plain language, and the AI interprets the crash data for you. It's like having a WinDBG expert whispering in your ear, except it doesn't get annoyed when you ask the same question five times.

How It Works

The MCP server connects GitHub Copilot to WinDBG:

It provides a set of tools that Copilot can use to interact with crash dumps
It translates natural language questions into appropriate WinDBG commands
It parses and interprets the often cryptic WinDBG output into more useful information
It maintains context throughout a debugging session, enabling follow-up questions to work naturally

The technical implementation uses Python to spawn and communicate with CDB (the command-line version of WinDBG), parses the output, and exposes the functionality through the Model Context Protocol to VS Code.

Getting Started With mcp-windbg

Ready to try it yourself? Here's how to get started:

First, make sure you have the Windows SDK installed with Debugging Tools for Windows
Clone the repository: git clone https://github.com/svnscha/mcp-windbg.git
Set up a Python virtual environment and install the package
Configure VS Code to use the MCP server

For complete details, check out the repository README.

Once configured, create a .vscode/mcp.json file in your project that points to the server:

{
    "servers": {
        "mcp_server_windbg": {
            "type": "stdio",
            "command": "python",
            "args": [
                "-m",
                "mcp_server_windbg"
            ],
            "env": {
                "_NT_SYMBOL_PATH": "SRV*C:\\Symbols*https://msdl.microsoft.com/download/symbols"
            }
        },
    }
}

You might need to update the command, depending on where and how you have installed the mcp_server_windbg to.

The Human Touch Still Matters

Just like with code refactoring, the AI assistance isn't perfect. The human element - your experience, intuition, and domain knowledge - remains crucial. Sometimes you'll need to guide the analysis, ask follow-up questions, or provide additional context.

The useful part is the combination: AI can process a large amount of debugger output quickly, while you provide the context needed to judge the result. It still needs supervision and can follow the wrong lead, so treat its findings as a starting point rather than a final answer.

Join The Experience

I'd love for you to try this out, contribute to the project, and share your experiences. If you're interested:

Star the GitHub repository
Try it on your own crash dumps
Report issues, suggest improvements, or contribute code
Share your success stories (or even failures - we learn from those too!)

The Magic Is In The Flow

Just like with my code refactoring experience, the real magic isn't about any single capability - it's about the flow. When debugging stops being a tedious chore and becomes a fluid conversation, something fundamentally changes in how you approach problem-solving.

Gone are the days of dreading crash analysis. Instead, each debugging session becomes an opportunity for collaboration with an AI partner that helps you understand what's happening at a deeper level.

Summary

Crash dump analysis has traditionally been one of the most technically demanding and least enjoyable parts of software development. It's like archaeology with a keyboard - painstakingly excavating through layers of memory and CPU state to unearth what went wrong. With AI assistance through tools like mcp-windbg, it becomes another area where we can experience that perfect "vibe state" of frictionless problem-solving.

If you're still manually typing WinDBG commands and squinting at memory dumps in 2025, you're not just missing out on productivity - you're missing out on a fundamentally more enjoyable way to work.

Try it. Debug it. Vibe it.

Vibe Coding is So Damn Real

2025-04-27T00:00:00+00:00

Why, You Ask?

Ever had that moment when your coding flow is so perfect it feels like you and your tools are in some kind of cosmic alignment? That's vibe coding. It's when the friction between thought and implementation practically disappears. And let me tell you, with GitHub Copilot and VS Code, this isn't just a fleeting sensation-it's a consistent reality.

I'm tired of writing about theoretical capabilities. Let me show you something concrete.

A Childhood Dream Come True

Let me share something personal: since I first started coding, I've had this recurring dream. A dream where I could simply talk to my computer, tell it what I want in plain language, and watch as it translates my intentions into working code. No syntax gymnastics. No hunting for semicolons. Just pure, frictionless creation.

"Hey computer, refactor this module to use dependency injection instead of globals."
"Computer, optimize this database query, it's running too slow."
"Add translation support to all user-facing strings in this module."

For decades, this remained firmly in the realm of science fiction-something for Star Trek episodes where they casually ask the computer to "reconfigure the deflector dish" and it just... happens.

DAMN, we're just there now. Not in some distant future, not as a tech demo, but as a practical, everyday reality in my development workflow.

Real-World Context: Nofidoc

A little context: In my free time, I've been pushing the boundaries of what's possible with AI-assisted coding-well beyond just casual experiments. While I also use these workflows at work, Nofidoc has become my personal playground for exploring how far I can take this technology. It's a space where I can try things that aren't always ready for the spotlight, but the results have been too compelling not to share (even if I'm keeping things a bit low-key for now).

The codebase uses Qt for the UI components, has a wizard-based document import flow, and handles various document formats with a focus on PDFs. It's exactly the kind of mid-sized C++ project where refactoring used to be tedious and error-prone.

The Perfect Pairing

VS Code with GitHub Copilot doesn't just assist your coding-it transforms it. No more wasting precious brain cycles on trivial tasks. No more tedious refactoring operations that make you question your career choices at 2 AM.

I recently needed to refactor the document import workflow to remove direct database dependencies in the wizard component. Why having that in the first place? Well, getting something proof-of-concept-ish is the answer. Anyways, this is a classic case of improving architecture by decoupling components, but it typically requires careful changes across multiple files and understanding the entire call hierarchy.

See The Entire Workflow In Action

I've recorded a full ~6-minute video showing the entire refactoring process from start to finish. You'll see me:

Prompt Copilot with my refactoring requirements
Watch the initial code changes being proposed
Hit compilation errors (because real-world code is messy!)
Provide additional guidance to Copilot
Get a complete, working solution

Your browser does not support the video tag.

What's remarkable here is not just that Copilot could make the changes, but how the entire interaction feels like working with a senior developer who deeply understands your codebase.

The Real Example: DocumentImportWizard Refactoring

Here's a snapshot of what happened in the video. I needed to update the DatabaseWidget class to use the new API of our DocumentImportWizard that we had refactored to remove direct database dependencies.

Copilot analyzed the code and came up with this solution:

// Before refactoring, direct database dependency:
void DatabaseWidget::onDocumentImportWizard()
{
    auto importWizard = new DocumentImportWizard(_database, this);
    importWizard->exec();
}

// After refactoring, using callback approach:
void DatabaseWidget::onDocumentImportWizard()
{
    auto importWizard = new DocumentImportWizard(this);
    importWizard->setGetDocumentTypesCallback([this]() {
        if (!_database)
            return QList<DocumentType>();
            
        auto docTypeService = _database->getDocumentTypeService();
        if (!docTypeService)
            return QList<DocumentType>();
            
        return docTypeService->getDocumentTypes();
    });
    importWizard->exec();
}

Copilot explained its reasoning:

"I've updated the onDocumentImportWizard() method in DatabaseWidget to use the new refactored API of our DocumentImportWizard class. The key changes were:

1. Removed passing the _database parameter directly to the DocumentImportWizard constructor 2. Added a call to setGetDocumentTypesCallback() with a lambda that:

Checks if _database is valid

Gets the document type service from the database

Returns the document types list from the service

Returns an empty list if any step fails

This completes the refactoring work by updating all the calling code to use the new API. The change maintains the same functionality but with a cleaner design that removes direct dependencies on the database pointer.

The implementation follows modern C++ practices by using a lambda to encapsulate the specific functionality needed (getting document types) while keeping the rest of the database access logic out of the wizard class. This makes the code more maintainable and easier to test."

This is exactly the kind of architectural improvement that typically takes deep understanding of both the codebase and software design principles. Yet Copilot produced it in seconds.

The Key Lesson: Human-AI Collaboration

My main takeaway is simple: AI tools work best when you bring your own domain knowledge.

Just before that, I was debugging a frustrating issue with field registration in that document import wizard. The fields weren't passing values between pages correctly. I asked Copilot to help fix the bug and it initially proposed an overly complex workaround that would have been a maintenance nightmare.

So I gave it a hint:

"I think there's an issue with the registerField calls for 'importSuccessCount' and 'importErrorCount'. The implementation doesn't specify the property name correctly."

And just like that, it had an "aha!" moment. It immediately identified the real issue:

// Before (buggy implementation):
registerField("importSuccessCount", this);

// After (Copilot's correct fix):
registerField("importSuccessCount", this, "importSuccessCount");

This simple fix resolved the entire issue. The fix works because it properly uses the Qt property system (third parameter) as the remaining code and pages expected, whereas Copilot's initial workaround was mega ugly - setting properties directly with setProperty() calls. With just a small hint about the actual problem, we were back on track. This perfectly illustrates why domain expertise remains critical - AI tools can suggest solutions, but knowing which ones make sense in your framework requires human judgment.

Sometimes AI tools need a gentle nudge in the right direction, and then they're off to the races again.

Not Always Perfect Magic

Let me be real with you - it's not all sunshine and rainbows. AI assistance sometimes misses the mark, and when it does, you need to steer it in the right direction. But I've found that:

The initial attempt is usually close
AI is exceptionally good at understanding feedback
With the right hints, it can quickly recover and find the optimal solution

The collaboration workflow is what makes all the difference. Instead of wrestling with a tool, it feels like having a junior developer who's eager to learn and quick to adapt.

What I Learned

This isn't just about saving time (though I saved HOURS). It's about changing how we think about coding. When you can express your intent in natural language and have it accurately translated into code changes, you're no longer programming computers-you're conversing with them.

The barrier between thinking and implementing just got so much thinner.

Getting This Setup Yourself

Want this superpower? Here's what you need:

VS Code
GitHub Copilot
A clear understanding of your codebase - To craft effective prompts

That's it! No complex configuration, no elaborate plugin chains.

Oh, which model? Right now I am using Claude 3.7 - it's so good.

Where This Is Going

You know that saying about technology and magic? This is it. We're witnessing the early days of a transformation in how software gets built. The tools are evolving to understand not just the syntax of our code, but the intent behind it.

Could I have written a complex bash script to do some of this refactoring? Maybe. Could I have used search-and-replace with regex? Probably. Would either approach have understood the semantic meaning of my code well enough to know which strings need translation? Absolutely not.

Summary

Vibe coding isn't just some feel-good developer term. It's that perfect state where you and your tools are in sync, where expressing your intent feels natural and immediate. With GitHub Copilot and VS Code, I'm experiencing this daily while building Nofidoc.

If you're still doing manual refactoring in 2025, you're not just missing out on productivity-you're missing out on the pure joy of frictionless development.

Try it. Feel it. Vibe code.

Exploring AI: Self Hosted LLM

2025-03-17T00:00:00+00:00

Why, You Ask?

So, I decided to self-host an LLM. Why? Every time you use an online AI model, you're handing over your data to some company. Whether it's casual conversations, coding snippets, or business-related queries, everything you type is potentially being logged, analyzed, or even used to train future models. No thanks.

Instead, I prefer to keep things local. Also, I have an RTX ADA 4000 with 20GB of memory sitting here, so why not put it to good use?

Ollama makes it easy to run LLMs locally. I combine it with Open WebUI for the user interface and Nginx for remote access.

Here is the setup.

Step 1: Install Ollama

Ollama makes deploying LLMs locally ridiculously simple. Here's how to install it:

curl -fsSL https://ollama.com/install.sh | sh

This will install Ollama and set up everything you need to start running models locally. Want to make sure it's working? Just run:

ollama run codellama:13b

If you see an interactive prompt, congrats - you've got a local LLM running!

Step 2: Install Open WebUI

Ollama is great, but a web interface makes it even better. That's where Open WebUI comes in. It gives you a sleek, chat-like interface to interact with your models.

To install Open WebUI manually without Docker, follow these steps:

1. Create a Virtual Environment

python3 -m venv ~/openwebui-venv
source ~/openwebui-venv/bin/activate

2. Install Open WebUI

pip install open-webui

3. Create a Systemd Service

To make sure Open WebUI runs on startup, create a systemd service file:

sudo nano /etc/systemd/system/openwebui.service

Paste the following content:

[Unit]
Description=Open WebUI Service
After=network.target

[Service]
User=$USER
Group=$USER
WorkingDirectory=/home/$USER/openwebui-venv
ExecStart=/home/$USER/openwebui-venv/bin/open-webui
Restart=always

[Install]
WantedBy=multi-user.target

Save and exit, then reload systemd and enable the service:

sudo systemctl daemon-reload
sudo systemctl enable openwebui.service
sudo systemctl start openwebui.service

Step 3: Reverse Proxy with Nginx

Now, let's make accessing our LLM easier by setting up an Nginx reverse proxy. This way, we can reach Open WebUI without exposing it directly.

Here's a basic Nginx config:

server {
    listen 443 ssl;
    server_name chat.example.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Reload Nginx with:

sudo systemctl restart nginx

Now, you can access your self-hosted LLM via https://chat.example.com. Fancy.

You Own Your Data Now

One of the biggest advantages of self-hosting an LLM? Your data stays with you.

No sending queries to an external API, no third-party tracking what you're asking, no potential leaks of sensitive information. It's all running on your hardware, fully under your control. Whether you're experimenting with code, processing confidential documents, or just having fun chatting with AI, everything stays local.

Model Sizes & Performance

Of course, different models come with different memory requirements. Here's what I'm running on my RTX ADA 4000 and how much VRAM they use:

NAME             ID              SIZE      PROCESSOR    UNTIL              
codellama:7b     8fdf8f752f6e    9.4 GB    100% GPU     2 minutes from now    
codellama:13b    9f438cb9cd58    15 GB     100% GPU     4 minutes from now    
gemma3:12b       6fd036cefda5    13 GB     100% GPU     4 minutes from now

This means I can comfortably run mid-sized models like codellama:13b while keeping things snappy.

Choosing the Right GPU

Picking the right GPU is all about balancing performance, VRAM, and cost - because, let's be honest, unless you're running an AI research lab, you're not dropping $30,000 on an H100.

Here's a quick breakdown of solid options:

NVIDIA RTX 3090 - Powerful, with 24 GB of VRAM, but it's last-gen. ($$)
NVIDIA RTX 4090 - Even more powerful, with 24 GB of VRAM and better efficiency. ($$$)
NVIDIA RTX 5090 - Even more and more powerful, with 24 GB of VRAM and better efficiency. ($$$$)
NVIDIA RTX 4000 ADA Generation - Less powerful, but 20 GB of VRAM, and a low-profile card. ($)

Now, why the ADA 4000? While the RTX 5090 is the fastest in raw compute power, VRAM is king for training AI models. The ADA 4000's 20 GB VRAM gives you enough room for Stable Diffusion training, larger batch sizes, and AI experiments, without hitting the limits of other consumer GPUs such as 3080 (10 GB).

Performance-wise, the 4090 and 5090 has more horsepower, but for training workloads where memory matters more than raw speed, the ADA 4000 is the more practical and cost-efficient choice. Plus, lower power consumption makes it a better long-term option if you're running AI workloads frequently. Also, the physical size - I mean it's a low profile card. Small, fits perfectly into any case.

For my needs, the RTX 4000 Ada offered a useful balance of VRAM, price, power use, and size.

Example

Asking codellama:13b

Prompt: implement fibonacci in python and also some unit tests using pytest

Your browser does not support the video tag.

Asking gemma3:12b

Prompt: implement fibonacci in python and also some unit tests using pytest

Your browser does not support the video tag.

Summary

With an RTX ADA 4000, Ollama, Open WebUI, and an Nginx reverse proxy, I now have an AI-powered assistant running entirely on my own hardware. No subscriptions, no cloud dependencies, just raw, local AI power. If you're serious about AI and privacy, setting this up is a no-brainer. Give it a try, and let your GPU do some work.

svnscha - ai

🚀 New Release: mcp-windbg 1.3.0

Three Separate Plugins

Skills and Agents for Your Existing Server

Upgrading from the Bundled Plugin

🚀 New Release: mcp-windbg 1.2.2

The Problem

What Caused It

The Fix

Getting Started

🚀 New Release: mcp-windbg 1.2.0

Installing the Plugin

Skills for Common Debugging Tasks

The Crash Analyst Agent

Symbols by Default

A Small 1.2.1 Follow-up

Getting Started

🚀 New Release: mcp-windbg 1.1.0

What Happened: 1.0.1

Support for the 2.x SDK

wait_for_break

Fixing g Freezing the Target

Getting Started

Summary

🚀 New Release: mcp-windbg 1.0.0

Kernel Debugging

Session IDs

The Breaking Changes

Smaller, But You Will Notice

Getting Started

One-Point-Zero

🚀 New Release: mcp-windbg 0.15.0

What's New

Break into a live session

Redact sensitive data before it leaves the machine

A real documentation site

Quieter, sturdier foundations

Community Contributions

Getting Started

A Year and a Month In

Meet Ralph: The AI Coding Agent That Just Keeps Going

Why, You Ask?

The Problem

What Is Ralph?

The Secret Sauce: The PRD

Verification Scripts

Behind the Scenes

State Management

Getting Started

Why This Works

The Catch

Summary

Next Steps

Ollama Now Speaks Messages API

The News: Ollama Learns a New Language

Why Test This, You Ask?

Setting It Up

Which Model?

Bump Ollama's Context Window

PowerShell Helper for Your Work Machine

My Test: Meeting Destruction Therapy

Claude Opus 4.5 (Reference)

qwen3-coder:30b

gpt-oss:20b

glm-4.7-flash

nemotron-3-nano:30b

ministral-3:14b

rnj-1

Summary

Next Steps

AI Agents in .NET: Beyond DevUI - LibreChat Integration

The Problem with DevUI

Why LibreChat?

The Plan

Removing DevUI, Embracing Swagger

Exposing OpenAI-Compatible Endpoints

Setting Up LibreChat

Docker Compose

The LibreChat Configuration

Docker Compose Override

`wait_for_break`

Fixing `g` Freezing the Target