All of them came from my Claude Code sessions: dev servers, tail -f watchers on task output files, small scripts. The sessions had ended and the processes kept running. There's an upstream issue about it, #62659, and a bot closed it as not planned.

So I wrote Sweepling, a Windows tray app that notices these leftovers and closes them once you confirm.

Why this is a Windows problem

On Linux an orphan is adopted by init or a subreaper, and a cleanup tool can end a whole process group in one call. cc-reaper does this well on macOS and Linux.

Windows does neither. When a parent exits, its children keep running and keep the dead parent's PID in their own process record. Windows also reuses PIDs, so a few minutes later that number can belong to something unrelated. Task Manager's tree only nests a process under a parent that's still alive, so an orphan shows up as one more top-level node.exe.

That gives the first rule: a process's parent is gone when its PID is missing, or when that PID now belongs to a process that started after the child.

Proc? ParentOf(Proc p) =>
    p.ParentPid != p.Pid
    && byPid.TryGetValue(p.ParentPid, out var parent)
    && parent.Started <= p.Started ? parent : null;

You can run the same check in PowerShell without installing anything:

$all = Get-CimInstance Win32_Process
$byId = @{}; $all | ForEach-Object { $byId[$_.ProcessId] = $_ }
$all | Where-Object { $p = $byId[$_.ParentProcessId]; -not $p -or $p.CreationDate -gt $_.CreationDate } |
  Where-Object Name -in 'node.exe', 'tail.exe', 'grep.exe', 'bash.exe', 'sh.exe' |
  Select-Object ProcessId, Name, CreationDate

It will also list orphans that have nothing to do with Claude Code. Telling those apart is the hard part.

Tying an orphan to a session

Plenty of programs start a helper and exit on purpose, so an orphan on its own isn't a leftover. Sweepling only offers a process it can tie to a Claude Code session, and it has three ways to do that, strongest first.

1. The family tree. Every few seconds Sweepling takes a snapshot of your processes and records which session each one descends from. Ancestry is only visible while the parents are alive, so it learns early and keeps what it learned after a parent exits.
2. CLAUDE_PID. Claude Code puts its own PID in its children's environment. Sweepling reads another process's environment from its PEB. That memory belongs to the other process, so every size and pointer in it is treated as untrusted and every read is bounded.
3. Command-line rules. Programs run from Git Bash are the awkward case: an MSYS2 process hands Windows only a handful of environment variables, and CLAUDE_PID isn't one of them. For those, a small rules file matches things like a grep --line-buffered from Git Bash's folder, or a command line that points into Claude Code's temp folder.

When Sweepling can't tell whether a session has ended, it treats the session as running. A wrong "running" only delays an offer. A wrong "ended" offers someone's live work.

Strays that share one dead parent and started within ten seconds of each other become a group, together with everything under them, and you close a group as one.

Is it still in use?

Belonging to an ended session still isn't enough. A group waits until its parent has been gone for a minute, and it's never offered when:

• anything in it has an established TCP connection, like a dev server a browser tab is still talking to;
• anything in it is a windowed app. Sweepling reads the subsystem field in the exe's PE header, and an exe it can't read counts as windowed;
• everything in it is on the protect list, which covers things like MSBuild nodes and the .NET build servers.

Sweepling never looks at CPU or memory use. A busy process is often a build someone is waiting for, and "kill whatever is using a lot of CPU" has ended background builds in other cleanup tools.

Asking first

Sweepling never closes anything you haven't confirmed, and there's no auto mode, setting or flag to change that. Leftovers of ended sessions start ticked. Strays of a session that's still running get their own section and are never ticked by default.

Right before closing a group it checks again. Nothing in the group may have gained a connection since you looked, and each PID must still belong to the process you were shown, compared by start time, because the PID you saw thirty seconds ago could be a new process by now. It closes parents first, so a supervisor can't restart a child it just lost. Each close goes into a local log with command lines masked, since command lines carry tokens and private paths.

Keeping it cheap

An app that cleans up leftovers shouldn't cost more than they do. Sweepling is .NET 10 and Avalonia 12, published with NativeAOT as a single process. Avalonia's GPU renderer held about 60 MB from launch whether a window was open or not, so Sweepling renders in software. In the tray it idles at about 17 MB of private bytes, and about 23 MB once its window has been opened. Its only network call is the update check against GitHub Releases, and there's no telemetry, because it can see every command line on the machine.

What a week of using it found

I've run it every day since it worked. On its busiest day it found 22 groups on my machine: 9 task output watchers, 9 of their grep filters, a Next.js dev server, two Angular dev servers and a shell script. I closed all of them. One was an Angular dev server I had completely forgotten about. The number I watch most is how many it offered that were still in use, and so far that's zero.

Try it

You need Windows 10 or 11 on x64. Download sweepling-setup-win-x64.exe from the latest release. It installs for your user only, needs no admin rights, is signed, and keeps itself up to date. It sits in the tray as a straw brush. When the brush shows a count, click it, untick anything you still want, and press Close. To see what it would offer without closing anything, run Sweepling.exe --scan > scan.json.

For now it covers the Claude Code CLI only. On macOS or Linux, use cc-reaper, which does much more. If you already know which port is stuck, npx kill-port 3001 is faster than any tray app.

The code is Apache-2.0 on GitHub. The most useful issue you could open describes a leftover Sweepling missed, or one it offered while you were still using it.

This is part 2 of 3. Part 1 covered reading the rules out of Shin Megami Tensei III Nocturne HD Remaster and rebuilding the minigame as puzzle-boy. This one covers what I did with the unplayed stages, how that broke the port's one promise, and how splitting it into three repos fixed it.

The stages nobody played

Part 1 said 21 of the 50 files are played. The code does list a 21st, file 00, for "levels 2 and 3", but every video and guide ends after stage 20, so I count 00 as unused.

None of the 30 is junk. Every start and goal is on floor, no goal is walled off, and a few are tutorial-sized, at 3 or 4 pushes. They include all seven multi-character stages and the six files damaged by the line-ending conversion.

The multi-character ones are where it gets strange. In the original, control passes to the next Jack only when one reaches the goal. Nothing else switches, so the first Jack has to get home alone, using only its own pushes. A search ran out of positions on six of the seven. File 05 shows why: one push can only be made from a dead-end alcove that the block itself seals off, so somebody has to wait in that alcove while another character brings the block over.

They look like stages designed for a switch the shipped code doesn't have. That's my guess, not something the code says.

A switch key and a search

So the port got a switch key, C. It passes control to the next visible character, in the same order a goal arrival does. Its label on the controls bar, "Switch Character", is the game's own guide text. With it, four of the six stuck stages have solutions, and file 47 needs all four Jacks and 10 switches.

Then a search went through all 30 files. It made every move on the port's real Board, built from the real file, so no solution could lean on a rule the port doesn't have. Breadth-first search found the fewest pushes, and A* took over when the space got big. A faster second pass had its rules checked against the real Board on 4.7 million single steps before I trusted it, and every solution was replayed input by input on a fresh board before anything shipped.

A stage only counts as unwinnable when the search runs out of positions. The seven unsettled ones hit the search budget, which proves nothing either way. Of the 23 solutions, 19 are proved shortest.

The 23 shipped in v0.2.0 as stages 21 to 43, easiest first, with PageUp and PageDown to skip around.

It worked. It also meant the "faithful port" now had a key, a controls-bar label and 23 stages the original never had.

Three repos, one rule each

A preservation port shouldn't contain things the original lacks. But the bonus stages and the switch were good, and I didn't want to throw them away. So I stopped asking one repo to do both jobs:

Both games pin the engine as a git submodule at a fixed commit. An engine change lands there first, then each game bumps its pin on purpose. There's no package feed and no floating main, so an engine change reaches a game only when that game asks for it.

Board.Switch stayed in the engine, since Community uses it. The port just never calls it.

Proving nothing changed

The split itself was mostly moving files. The work was proving the port was still the port.

Before touching anything, I tagged the last commit pre-split-baseline: a clean build and 164 passing tests. Then:

• The rules moved with their tests. 86 of the 164 tests went to the engine with the rules, unchanged but for their namespace.
• The stage list is pinned. A test checks that the port plays exactly the 20 documented files, each once, with none of the 23 bonus files, and that it loads only those 20 from a bundle holding all 50.
• The switch can't come back by accident. A test scans the game's compiled metadata for any call to Board.Switch. A scan for an absence proves nothing on its own, so the same scanner must also find Board.Step, which the game does call.

Later, Community needed the original's look too (that's part 3), so the board renderer, Jack's model, the camera, the move timing, the sound and the bundle reading moved from the port into the engine. The rule for that move was verbatim. Each moved file was diffed against the last commit before the move: 12 files and 1,889 lines, of which 34 changed. Every change was a namespace, an internal that became public because a game now uses it, or a citation that now names the port's roadmap. No statement, constant or expression changed, so the port can't play or look any different. The HUD, menus and text renderer followed the same way: 1,081 lines, 19 changed.

Community Edition had to play without Nocturne

If you own Nocturne, you import it once, and Community Edition plays every stage in the original's look and sound: its board, its Jack-o'-Lantern, its camera, its music. Your copy's stages come along too, as two more campaigns: the original 20 and the 23 bonus stages.

How it got that look is part 3. It also had to work for everyone without a copy. The port needs one, and if Community did too, it would just be the port with extras. So its first rule, written into its roadmap, is that an unpacked release starts on a machine with no Nocturne, no Steam, no .NET, no network and no dev checkout, and reaches a playable stage. It never opens on a missing-assets screen.

Without a copy, the Default theme takes over: Pixel Jack, a pumpkin in a witch's hat, with art and sound drawn and synthesized in code. The builds are self-contained, so there's nothing to install first. Here are the same two screens each way:

It also needed stages of its own. Community ships 20 new ones in a pack called First Steps, made by designer agents with a breadth-first solver and curated into a difficulty curve: a walk, a first push, holes, long blocks, swivels and a switch tutorial. They take from 7 inputs to 161, and every one has a recorded solution that the tests replay to a clear.

The editor builds on the stage-authoring API that came with the engine, which reports problems with coordinates, so a broken stage says where it's broken:

Keeping Nocturne's layouts out

An editor and level packs raise an obvious question: what stops someone from converting one of Nocturne's 50 stages to JSON, mirroring it, and sharing it as their own?

Fingerprints. LayoutFingerprint hashes a stage's cropped grid in its smallest rotation or mirror, so turning, flipping or shifting a layout doesn't change it. Each of the 50 Nocturne stages gets two, with and without the goal and starts, and only those 100 SHA-256 hashes are in the repo, generated outside it from a local install. Community's tests fail if a bundled stage matches one, the pack importer refuses a matching stage, and without the list beside the game nothing is imported or exported at all.

The bonus stages live on in Community the way the port works: imported from your own install, on request. They never ship.

What the reviews caught

Every milestone ended with adversarial reviewers who tried to break it. Some favourites:

• Linux crashed at startup when the GL driver had no multisampling.
• Turning on fullscreen caused a stack overflow through a resize handler.
• A save file with a duplicate JSON key crashed startup.
• A 115-byte fake bundle header made the classic import allocate until it ran out of memory.

Where it ended up

Both games shipped on October 15. puzzle-boy v0.3.0 plays the original's 20 stages on the shared engine, and nothing else. Community Edition v0.1.0 runs on Windows, Linux and macOS, Apple Silicon and Intel. Its release job only publishes once every platform's smoke test passes; on macOS and Linux that means a real window opened, drew the title and stage 1, and took a step.

Then I changed my mind about how Community should look. That's part 3.

pbGame.pushCheck      pushing a block
pbGame.roundCheck     turning a swivel block
pbGame.hallCheck      falling into a hole (yes, "hall")
pb_H                  the old pb.h header, now a C# namespace
pbEdit                the developers' level editor, still in the build

That's Puzzle Boy, a minigame deep inside Nocturne. You guide Jack-o'-Lantern through a maze by pushing blocks, turning swivel blocks and filling holes, while the Manikin Kid taunts you. It's Atlus's old Game Boy puzzler (Kwirk in the West), redone in 3D. I wanted it as a game of its own that runs anywhere, so I rebuilt it: puzzle-boy.

This is part 1 of 3. It covers the first two days: reading the rules out of the game, the line I drew around its copy protection, and how the rules became tests before they became code. Part 2 is about the stages the original never plays, and how one repo became three.

The rules I started with

Before writing any code, I wrote down what the project would never do, in the repo's AGENTS.md, so every agent session starts with it:

• No Atlus data in the repo. No stages, text, audio, textures, models, metadata dumps or decompiler output. The game reads all of it from your own install at startup.
• No decompiled code in the source. Every rule found in the game becomes a test on a handmade stage first, and the code is written from the test.
• No circumvention. More on that below.

I built it with Claude Code doing the reverse engineering through REA and Ghidra, and me deciding.

The metadata talks first

The HD Remaster is a Unity 2019 game compiled with IL2CPP: C# turned into a 383 MB native GameAssembly.dll. IL2CPP keeps every class, method and field name in a separate file, global-metadata.dat, and Nocturne's isn't encrypted.

So before decompiling anything, a small parser read 5,378 type definitions. The Puzzle Boy classes were all there, with the names from the list above. pbGame alone has 74 fields and 60 methods. Nearby were sdfChipFreeDelayed, dds3PrimFrameRect, and mcSave for the PS2 memory card. The remaster is the 2003 C code, converted to C# and kept nearly as it was. The help text still documents the developers' edit mode, translated into eight languages, and the debug menu has a "PUZZLE BOY GAME" entry next to "MODEL VIEWER".

Six files broken by a line ending

The stages are 50 files in a Unity bundle called pazzleboy (Atlus's typo). Each is 828 bytes: a character count, four start positions, a goal, then a 20×20 grid of 16-bit cells. 0x2000 is a wall, 0x0800 a hole, 0x60nn part of block group nn, and swivels have their own pair of types.

Six files were a few bytes longer. In one of them, the character starts at y = 2573 on a 20-row grid.

Each of the six had exactly as many 0D 0A byte pairs as extra bytes. Somewhere in Atlus's pipeline, a line-ending conversion treated these binary files as text and turned every 0A byte into the Windows 0D 0A. Undo it, and every file is 828 bytes again and makes sense. The broken one starts its character at (17, 10).

The code later explained why nobody ever noticed: the original never loads those six files. The port repairs them anyway, and its .gitattributes marks stage files as binary, so the same thing can't happen to me.

The line around Denuvo

GameAssembly.dll is protected by Denuvo Anti-Tamper. I wasn't going to dump the running game's memory, de-obfuscate anything or patch it. What made the project possible at all was one check: all 225 Puzzle Boy methods live in the unprotected .text section, along with 13,002 of the game's 13,028 methods. The protected code is a separate 316 MB section.

So the rule is short: read only unprotected code, statically. If a question leads into protected code, answer it by playing the real game instead.

The usual tools didn't make it easy. REA couldn't open Unity bundles and had no IL2CPP support. Il2CppDumper couldn't find IL2CPP's registration tables, because the protector had renamed the sections that hold them. Found by hand, the tables turned out to use the v24.3 layout while the metadata claimed v24.2, and the dumper crashed on that too. So a script of about 100 lines followed each method's token to its address and wrote 13,028 names into a seed file for Ghidra.

Ghidra versus a 32 GB laptop

Then Ghidra had to analyze 383 MB of native code. The first run died about 12 minutes in, when the agent's session ended and took its background job with it. The second was launched outside Claude Code's process tree. After 52 minutes, Java held 11.4 GB and the machine had 0.1 GB of RAM free. I stopped it.

The overnight run spent 6.5 hours looping through the protected section without finishing. Denuvo's code is virtualized, so there's nothing readable there anyway; Ghidra was just wading through it.

So I made a local analysis copy of the DLL with the protected sections emptied. .text stayed byte-identical, and every address still lined up with the seed file. Nothing was defeated and nothing ran: it just removed the protected code from what Ghidra looked at. The analysis finished in 41 minutes.

One beat I like: the agent then tried to commit that trimming script to the public repo, and Claude Code's own safety check refused. A public script that strips sections from a Denuvo-protected binary reads as anti-DRM tooling, whatever it's for. I agreed. The script and the copy stayed on my machine, and the explanation went here instead.

Reading the rules, with an adversary

The research ran as one batch: seven agents each read one area of the decompiled code (pushing, swivels, the turn loop, stages, loading, undo, presentation), and for each one, a second agent re-checked every claim against the pseudocode and tried to prove it wrong. Then a critic looked for what was missing.

The findings went into the public ROADMAP.md as plain-language rules, each with a short evidence ID, and never as pseudocode. A few surprises:

• Only 21 of the 50 stage files are ever played. Level 1 is 20 stages in a fixed order. The six damaged files are among the unused ones.
• There's no move counter. The only number on screen is the stage counter.
• Undo keeps 30 steps and only records pushes and turns. Undoing throws away any walking since the last push.
• The original has a real bug: its character-collision check swaps x and y. It never matters, because every played stage has exactly one character.

Rules as tests

Every rule then became a test on a stage drawn as text. Columns are x and rows are y, and a helper turns the drawing into real 828-byte stage bytes, so every test also goes through the parser:

#2##
1a..
#o##
#G##

# is a wall, . floor, o a hole, G the goal, digits are characters and lowercase letters are block groups. The expected result is just another drawing.

To check the tests had teeth, I broke the engine on purpose nine ways: reverse the swivel's turning sense, skip the fall into a hole, drop the sweep check, set the undo limit to 31, and so on. Every mutation failed at least one test. Reversing the swivel sense failed 22.

2,756 inputs, and the board was upside down

Tests prove the code matches what I read. They don't prove I read it right. For that I needed the real game's solutions.

AppMedia publishes the full input list for every stage of the HD version. Parsed into left, right, up and down and replayed in the port, they cleared all 20 stages: 2,756 inputs, each stage clearing exactly on its last one, with none refused.

Except at first, they didn't. Stage 1's solution only worked under one of the eight possible ways to map screen directions onto the grid, and it wasn't the port's. Gameplay video showed why: the original draws +y going up the screen. The port drew it down, so every stage was a mirror image and swivels seemed to turn the wrong way. The rules were right; only the picture was flipped. After a one-line fix, the same mapping cleared all 20.

Measuring the clock from video

The original runs one tick per rendered frame, so its speed depends on your frame rate. A 144 Hz monitor plays it faster. The code can't tell you what "normal" is.

Gameplay video can. In 60 fps footage, every move lasts a multiple of 8 frames, and stage 1's five-cell walk lasts exactly 40. That's 4 ticks a step at 30 ticks a second, which is what the port runs. Even the extra tick after a swivel turn shows up as a 2-frame pause.

Making it look like the real thing

The rest of the first two days went into the original's look, all read from the player's install at startup: the board textures (DXT1, decoded on the CPU), the backdrop, Jack-o'-Lantern's skinned model and idle animation, the sound effects and music (FMOD banks with Vorbis inside), the HUD, the □ menu and the Manikin Kid's lines.

The game ships no font file. Its text exists only as TextMeshPro distance-field atlases, so the port runs TextMeshPro's shader math on the CPU to draw it.

Before polishing, a review compared the port's timing against the research and the footage and found 12 real differences. The overhead view turns in 12 ticks, not 9. The camera orbits a point a quarter cell below Jack. The next stage loads 35 ticks after the winning input. And the original reads no input at all while a move plays, so a key pressed then is lost, not queued.

Keeping it honest

"No Atlus data in the repo" is a rule an agent can break by accident, so CI checks it. A script inspects every tracked file by its first bytes for Unity bundles, FMOD sound banks, IL2CPP metadata and Atlus flow scripts. It also rejects stage files outside the tests and Ghidra's generated names in the source.

A check for an absence proves nothing until you see it fail, so it has a positive control that plants each kind in a scratch repo and expects a failure. I also opened a throwaway pull request with a 4-byte stage file in it. CI failed exactly where it should, and the PR was closed unmerged.

Two mistakes worth admitting. To take screenshots of other stages, the agent once sent keystrokes to the game, while Windows was keeping focus on whatever window I had open. And the first frame-capture tool played the game's music on my speakers. Both tools now run the game with no real input and no sound.

Where it ended up

v0.1.0 shipped about 24 hours after the first question. It has Windows, Linux and macOS builds, all 20 stages, and the original's look, timing, sound, HUD, dialogue and menu, read from your own copy. You need Shin Megami Tensei III Nocturne HD Remaster to play it, and the repository holds none of it.

Then I looked at the 30 stage files the original never plays, and found that six of them can't be won as shipped. That's part 2.

if (SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO) != 0) {  // SDL3 returns true on success
    SDL_Log("SDL_Init failed: %s", SDL_GetError());
    return 1;                                          // so this runs on every launch
}

In SDL2, SDL_Init returned 0 on success. In SDL3 it returns true. The line looks the same, the compiler is happy, and the game quits every time it starts.

SDL3 is full of changes like that. An audio stream now opens paused, so the game is silent. Textures filter linearly by default, so pixel art comes out blurry. A texture with an alpha channel now blends, so an emulator's screen can go invisible. SDL's rename scripts handle most of a port and the compiler catches most of the rest, but neither one catches code that still compiles and now means something else. Coding agents make exactly these mistakes, because most of the SDL code they learned from is SDL2.

So I built sdl3-porter, a Claude Code plugin that ports C and C++ from SDL2 to SDL3 and catches those changes. This post is less about the plugin than about the question I kept asking while building it: how do I know it works?

What counts as a trap

I gave myself a strict definition. A trap is a change that compiles against SDL3 with warnings as errors (-Wall -Wextra -Werror on GCC and Clang, /W4 /WX on MSVC) and then breaks at runtime. If any compiler warns about it, the compiler already catches it, and it goes in a reference file instead.

A trap also doesn't count until it's proven. Each one has three small C programs:

• the SDL2 original, which must pass against SDL 2.32;
• the naive port, the code an agent would write, which must compile cleanly and then fail;
• the fixed port, which must pass.

CI builds all three and runs them headless on Windows, Linux and macOS, against SDL 3.4.18 and the oldest supported 3.2.0. Headless means no display, no sound card and no gamepad: the offscreen video driver, dummy audio, SDL's virtual joystick and the software renderer.

The naive port is the important one. It's the positive control. If it ever stops failing, the trap is no longer proven, and CI goes red. It also has to fail for the right reason: it must print one line that starts with the trap's id, like bool-returns: SDL_Init reported failure, so a setup error can't pass for the trap.

That rule threw out a lot of good ideas. Nintendo face buttons, rumble, exclusive fullscreen and high DPI all change in SDL3, but none of them can be proven without real hardware. They became 12 sections of guidance that the agent checks by reading the code. The 17 traps are only the changes I could make fail on demand.

Proving things headless had its own traps. The vsync fixture can't time frames, because SDL2's software renderer reports vsync as on and never actually waits. It checks the renderer's state instead.

Measuring it

A trap card tells the agent what to look for. That doesn't mean the agent finds it. For that I used evals: run Claude Code on an SDL2 program, let it port the code, then check the result.

Two rules made the scores worth believing.

Don't port the fixture. The fixture's SDL2 original checks the exact behavior the trap is about, which points straight at the answer. Each eval ports a separate sample instead: a plausible little SDL2 program with a neutral name and no self-checks. One more case ports a whole game, where the agent has to find the traps itself.

Every grader has to be able to fail. Most graders are a regular expression over the ported files that checks one trap fixed or one porting step done. A test runs every trap grader against a port made only with SDL's rename scripts, and fails if any of them passes it. A grader that can't fail measures nothing.

Each case runs five times with the skill and five times without it, on Sonnet 5 and Haiku 4.5. I also wrote down the rules for messy results before I had any. An infrastructure error gets one traced rerun, and a second error counts as measured. Hitting the turn limit is a real result. No threshold ever gets lowered. When a new Claude Code release shipped in the middle of a batch, I pinned the version and reran the cases that had mixed versions, so one table never mixes two versions.

What the numbers say

Without the skill, Sonnet 5 already gets 10 of the 17 traps right every time. On the other 7 it scores between 0.00 and 0.47. With the skill it scores 1.00 on all of them.

The skill doesn't help much with what the model already knows. It helps with silent default changes, where the SDL2 code looks perfectly fine: textures that now blend, textures that now filter, audio that SDL2 started by itself and SDL3 doesn't. Sonnet scores 0.00 on all three of those without the skill.

Finding is harder than fixing. In an early run, text-input-off scored 1.00 without the skill as a small standalone sample. In the whole game, the same model missed it in 3 runs out of 3. One trap in a small file is easy to spot. One trap in a game is easy to miss.

The smaller model gains more. On the whole game, Haiku 4.5 went from 0.39 without the skill to 0.92 with it. It isn't perfect, though. It scores 0.40 on window-mode-null, where it keeps the old call behind a NULL check and calls that a fix, and 0.80 on logical-scale-separate. I shipped 1.0 with both listed as known gaps instead of running the evals until they looked better.

Without the skill, scores also move between runs. linear-by-default scored 0.33 in one run and 0.00 in the next. Five runs per case is a small sample, so I read the table as "reliably fixed" versus "sometimes missed", not as exact percentages.

The agent that searched the whole disk

The first smoke run took 785 seconds with the skill and 43 without. The skill was making the agent much slower.

A traced rerun showed why. The agent spent 87 seconds on one command: find /, looking for SDL_video.h so it could check its port against the SDL3 headers. I added a line to the skill telling it not to search for headers. In the first full eval run, one run hit the 1,200-second timeout anyway. A traced rerun showed the agent running find / -xdev -iname SDL3.h for 120 seconds, even though the skill had told it not to.

The fix was to stop asking for the behavior and remove the reason for it. The skill now ships with the 66 SDL3 headers it needs, 2.3 MB of them. The slowest run dropped from 1,200 seconds to 342.

Then it happened again. After dogfooding, I added a step telling the agent to build the port where it could. Three runs took 746, 808 and 1,130 seconds. This time the agent was searching the disk for an installed SDL3, its library or its CMake files, to decide whether it could build. My rule only covered headers, so this search wasn't against it.

The rule that finally held was about the action, not the target: don't run find or locate outside the project, and ask the build instead, with pkg-config --exists sdl3 or by configuring the project. In the same nine runs, the agent searched outside the project zero times, and the slowest run took 202 seconds.

A rule against one target invites a search for the next one. A rule about the action covers the next target too.

Facts in the output beat rules in the docs

For 1.0, I added a script, find_traps.py, that runs every trap's search over the project in one command. Writing it found a bug of its own: seven searches never matched pointer access such as ev->gbutton.button, so they had silently skipped some real code.

The script also prints facts next to its hits. When it sees an old SDL2 hint name, it prints "removed in SDL3" beside it. Before that, Haiku left the dead hint in the whole game in 5 runs out of 5. In a check after the change, it left it in 1.

Rules in the docs did worse. One trap card says in plain words that a NULL check is not a fix. Haiku read that card and then called a NULL check "no change needed". The traces also showed why small models miss things: Haiku reads files with a line limit, 80 to 150 lines at a time, so a trap card near the bottom of a long reference file sometimes doesn't get read at all.

Against the maintainers

Evals use programs I wrote. To test against real code, I ported open-source projects starting from the commit just before their maintainers did their own SDL3 port, then compared the two ports.

An early comparison found a trap I didn't have. A Game Boy emulator's maintainer had fixed a texture that SDL3 now blends by default, which made the whole screen invisible. The agent's port had missed it. It became blend-by-default, the trap Sonnet scores 0.00 on without the skill.

The larger ports:

Both had misses. In scrcpy, the agent's own search found the text input code, and then it never turned text input on. Both agents ran every search at once and skimmed past hits. Now the skill asks for a verdict on every section that has hits. Woof!'s menu turned up a mouse-mapping bug in letterboxed windows, which became the 17th trap, logical-scale-separate. The maintainers' own port has the same bug.

The agent also beat the maintainers twice. scrcpy's own port sent a loop index in gamepad events where SDL3 expects a joystick ID, and the agent's port sent the ID. Woof!'s port kept the __MACOSX__ macro, which SDL3 no longer defines, so some macOS-only code silently stopped building. The agent had renamed it to SDL_PLATFORM_MACOS. I reported that one as woof#2952. A contributor opened a fix within hours, and I checked the fix's macOS build without a Mac, by comparing strings in the binaries.

Every dogfood report also overcounted. One listed 6 traps where there was 1. Later, the port I recorded for the README flagged blend-by-default on a sprite whose pixels were all opaque, because the card's wording allowed it. The agent follows what the card says, not what I meant, so the cards got stricter.

How it was built

I built sdl3-porter with Claude Code itself. The repository's AGENTS.md holds the rules from this post: no trap without a naive port that fails, cite SDL's migration guide for every trap, never lower a threshold, and test every check that looks for an absence against a case where it should fail. Most of what's above is what happened when those rules met the evidence.

Try it

In Claude Code:

/plugin marketplace add hazeliscoding/sdl3-porter
/plugin install sdl3-porter@sdl3-porter

Then open an SDL2 project and ask Claude Code to port it to SDL3. Commit first, because the port is meant to be reviewed as a diff. The README has the full eval table and the known gaps, and ROADMAP.md records every decision, with its date.

This blog lives directly inside my Angular app, using Markdown files that get turned into routes at build time.

What I’m optimizing for

• Owning my content
• Keeping it simple
• Great performance and SEO

Thanks for reading — more posts coming soon.