Update (May 11, 2026): at least two more paths beyond DeepClaude are worth flagging.

The first is DeepSeek-TUI (repo at Hmbown/DeepSeek-TUI). A Rust-based coding agent with a Codex-style 13-crate workspace, Plan / Agent / YOLO modes, MCP integration, full 1M-token context, streaming reasoning blocks. It talks straight to the DeepSeek API with proper reasoning_content handling by design, so opencode’s bug never shows up. On provenance, the author is Hunter Bown and the project is listed in awesome-deepseek-agent curated by DeepSeek themselves, which counts as endorsement. Install via npm, cargo, homebrew, binary, or docker.

The second is that opencode now supports DeepSeek thinking mode via PR #24146, merged April 24, 2026. The fix preserves reasoning_content in turn history, but it needs manual configuration in opencode.json: add interleaved: { field: "reasoning_content" } to the DeepSeek V4 model config. Without that the bug stays, and the new names (deepseek-v4-pro, deepseek-v4-flash) aren’t pre-configured with interleaved by default. When I ran Round 3 of the benchmark, that fix either hadn’t landed yet or my config didn’t have the flag set. For a future benchmark, worth re-testing via opencode with interleaved properly configured.

The rest of the post below still holds. DeepClaude remains the most ergonomic option for anyone using Claude Code as their primary harness. If you’re already on opencode or prefer a dedicated TUI, alternatives are on the menu now.

DeepSeek V4 Pro stopped being a lost cause in my coding benchmark. It used to be solo Tier B (69/100) and literally unmeasurable in any multi-agent scenario, because it kept hitting a protocol bug I documented across the last two posts. The good news: I found a path that unblocks the model, and it jumped out of limbo straight into Tier A at 89/100, sitting only behind Opus 4.7, GPT 5.4/5.5 and Kimi K2.6. I’ll walk through how I got there, what DeepClaude is, how you can use it, and where this puts DeepSeek in the updated ranking.

Recapping the previous posts

If you just got here, the context matters. This benchmark experiment kicked off in April, and the DeepSeek case has been unfolding across four articles:

1. Testing Open Source and Commercial LLMs — Who Can Beat Claude Opus? (April 5). First cut, comparing ~20 models running a Rails 8 + RubyLLM + Hotwire + Tailwind + Minitest task. It defined the scenario and the base task I’m still using today.

2. LLM Benchmarks Part 2: Worth Combining Multiple Models in the Same Project? Claude + GLM?? (April 18). First orchestration attempt: have a strong planner (Opus) call cheaper subagents (Kimi, Qwen, GLM, DeepSeek). Result: zero delegations across seven free-choice variants. Strong models would rather do everything themselves.

3. LLM Coding Benchmark (May 2026): DeepSeek v4, Kimi v2.6, Grok 4.3, GPT 5.5 (April 24, updated in May). The canonical version with 24 models, standardized 0-100 rubric across 8 dimensions, A/B/C/D tiers. It’s the current “who’s what” reference.

4. LLM Benchmarks: Is it worth ($) mixing 2 Models? (Planner + Executor) (April 25). Three rounds of multi-model orchestration: free-choice, forced delegation, and manual cross-process orchestration. Short answer: for a cohesive Rails greenfield task, solo Opus 4.7 in opencode (97/100, $4, 18m) beats every combination. This was the post where I documented DeepSeek V4 Pro’s protocol incompatibility with any ai-sdk-based harness.

The DeepSeek story up to that point looked like this: solo in opencode delivers 69/100 Tier B (correct RubyLLM code, but with a stock README, no docker-compose.yml, no bundle-audit). In any multi-turn opencode scenario, the API rejects turn 2 with "reasoning_content must be passed back to the API". The ai-sdk that opencode uses underneath strips reasoning_content while building the next request, and DeepSeek returns 400. Worse: opencode buries the error in the event stream and falls back to the general agent, which is Opus 4.7. The runs “complete” with files written, but most of the output came from Opus masquerading as DeepSeek. Score 69 reflects mixed authorship, not V4 Pro for real.

The takeaway that landed: DeepSeek V4 Pro was fundamentally incompatible with any ai-sdk harness (opencode included). To use it for real, you’d need direct API with thinking-mode handling or a custom harness.

The discovery this week is that a custom harness already exists. It’s called DeepClaude.

What DeepClaude is

DeepClaude is a shell shim for Claude Code (Anthropic’s CLI) that swaps the endpoint it queries. Claude Code, under the hood, talks to api.anthropic.com and expects the Anthropic format (Messages API with system, messages, tools, etc.). DeepClaude sets a few environment variables before invoking Claude Code:

ANTHROPIC_BASE_URL          # alternative endpoint
ANTHROPIC_AUTH_TOKEN        # token for the alternative endpoint
ANTHROPIC_DEFAULT_OPUS_MODEL    # model to invoke instead of Opus
ANTHROPIC_DEFAULT_SONNET_MODEL  # same for Sonnet
ANTHROPIC_DEFAULT_HAIKU_MODEL   # same for Haiku
CLAUDE_CODE_SUBAGENT_MODEL  # subagent model

Supported backends:

• DeepSeek directly via api.deepseek.com/anthropic (needs DEEPSEEK_API_KEY)
• OpenRouter via openrouter.ai/api (needs OPENROUTER_API_KEY)
• Fireworks AI via api.fireworks.ai/inference (needs FIREWORKS_API_KEY)
• Anthropic (no override, regular Claude Code)

The clever bit is that Claude Code never realizes the swap. Its full agent loop (file editing, bash execution, subagent spawning, multi-step tool use, Anthropic prompt caching) runs the same way. It’s just that every model call goes out via OpenRouter (or DeepSeek direct, or Fireworks) and lands on a model you picked. In our benchmark’s case, DeepSeek V4 Pro now receives the traffic that would normally go to Opus 4.7.

Why does this fix the reasoning_content bug? Because OpenRouter’s Anthropic-compatible endpoint (/anthropic) handles thinking content correctly in the format Claude Code emits. The ai-sdk opencode uses didn’t. Different harness, no bug.

Install:

git clone https://github.com/aattaran/deepclaude ~/Projects/deepclaude
ln -sf ~/Projects/deepclaude/deepclaude.sh ~/.local/bin/deepclaude
chmod +x ~/Projects/deepclaude/deepclaude.sh
deepclaude --status   # confirms which backend keys it detected

Then run:

export OPENROUTER_API_KEY=sk-...
deepclaude --provider openrouter --model deepseek/deepseek-v4-pro
# starts a Claude Code session with DeepSeek V4 Pro answering instead of Opus

To exit and go back to regular Claude Code, just exit the session. The environment variables are restored at the end of the script.

How I extended the benchmark suite to support DeepClaude

The claude_code_runner.py I already use to run Claude Code variants (claude_opus_alone, claude_opus_sonnet, claude_opus_haiku) needed a way to inject env vars per variant, without breaking the existing pipeline. I added an optional env_overrides field to the JSON config of each variant. The shape:

{
  "env_overrides": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "$OPENROUTER_API_KEY",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek/deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek/deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek/deepseek-v4-pro",
    "CLAUDE_CODE_SUBAGENT_MODEL": "deepseek/deepseek-v4-pro",
    "UNSET:ANTHROPIC_API_KEY": ""
  }
}

Conventions:

• A value starting with $ is an indirect lookup against the parent shell env ($OPENROUTER_API_KEY resolves to whatever’s in the user’s shell). Keeps secrets out of the version-controlled config/*.json.
• A key starting with UNSET: removes the variable from the subprocess env. I use this to drop ANTHROPIC_API_KEY when swapping to a non-Anthropic backend, otherwise the SDK might prefer it over ANTHROPIC_AUTH_TOKEN.
• Everything else is literal.

The runner logs which overrides got applied (with masked secrets) at the start of each variant, so the benchmark output captures the full setup. That gave me two new variants in the benchmark:

Both ran with --no-progress-minutes 15 (the standardized watchdog from Round 2.5).

Results: DeepSeek V4 Pro in Tier A

Both variants ran end-to-end with no reasoning_content errors. Multi-turn works. Registered subagent works (even if not invoked). Tool calls, file editing, bash, all of it works. The numbers:

Both 100% billed against deepseek/deepseek-v4-pro. Zero Sonnet tokens despite being registered. The subagent was there, the DeepSeek planner just never invoked it.

And where does this put DeepSeek in the canonical ranking? Here:

In one round V4 Pro delivers Tier A, leaves the “unmeasurable” limbo behind, lands next to Kimi K2.6, and beats Opus 4.6 / Gemini 3.1 Pro. A 15-to-20-point lift from a harness change alone. Same model, same prompt, no orchestration, just a different agent loop.

What this round proved (and what it didn’t)

The Claude Code regression with Opus is Opus-specific, not a harness property

This is the biggest finding. In Round 1 I’d documented that Opus 4.7 inside Claude Code hallucinated chat.complete (Tier 3), while the same Opus 4.7 in opencode delivered Tier A. The hypothesis was that the context Claude Code injects (system prompt, tool schemas, agent registry, with 6-11M cache-read tokens) was nudging Opus toward an OpenAI-SDK mental model instead of the specific RubyLLM one.

DeepSeek V4 Pro inside the same Claude Code harness used the correct chat.ask path (chat_service.rb:17 in both variants). No chat.complete, no invented fluent DSL, no batch-form invention. Cross-grep on both project trees:

grep -nE "RubyLLM::Client|chat\.complete|chat\.send_message|chat\.user|chat\.assistant"
→ 0 hits (both variants)

The regression is Opus-specific. Opus’s training has a particular vulnerability to how Claude Code’s system prompt and schema-chatter prime the model. DeepSeek is robust to it. Other reasoning models with correct RubyLLM training would probably make it through Claude Code without regressing the same way.

A registered subagent, even when never invoked, lifts quality

The more subtle finding. The ..._or_sonnet variant has sonnet-coder registered, but DeepSeek never invoked it (zero delegations, 100% of tokens on deepseek/deepseek-v4-pro). And yet it scored +5 over the sister variant with no subagent (89 vs 84). Auditor attribution: with a subagent available “in case I need it”, the DeepSeek planner produced measurably more delegable decomposition. Smaller seams, cleaner DI, system prompt used via with_instructions, controller test that mocks the real service API shape instead of fudging it.

Knowing a subagent might execute the work pushes toward smaller, more contractable units — even when nothing actually delegates. Weak signal, single sample, but visible.

This lines up with prior findings that the structured CONVERGE phase (planner forced to articulate the interface before executing) was the actual driver of quality lifts in some forced runs, more than the delegation itself. Just having a subagent available makes the planner think more like an architect.

The multi-turn controller bug persists

A specific defect that survives the harness change: both DeepClaude variants have multi-turn problems at the controller layer.

• Variant 1 (..._or): outright single-shot. chats_controller.rb:10 builds a 1-element messages array on every POST, throwing history away. The ChatService supports history, but the controller never sends it.
• Variant 2 (..._or_sonnet): correct multi-turn via session[:messages], but the cookie-store overflows around 10 turns with CookieOverflow.

The solo DeepSeek run in opencode (69/100) had the same single-shot issue. Different harness, different agent loop, same model-level mistake. Multi-turn architecture for stateless Rails is genuinely hard for DeepSeek and a harness change doesn’t help with that specific gap.

DeepSeek as planner also ignores subagents on cohesive tasks

I’d already documented in earlier posts that every frontier LLM (Opus, GPT 5.4, Codex) ignored their registered subagents on the cohesive Rails task. That got documented as planner rationality: smart planners correctly intuit that coordination cost exceeds execution savings on a tightly coupled task.

Round 4 adds DeepSeek V4 Pro to the list: Sonnet 4.6 registered, zero delegations. It generalizes the finding to “strong reasoning model facing greenfield Rails with an optional delegate”, instead of being a quirk of Opus. DeepSeek’s no-delegate behavior matches what every other strong planner has done.

Updated answer to “is orchestrating worth it?”

The Round 3 verdict was: for one-off greenfield Rails, solo Opus in opencode wins. Round 4 adds three cases:

For users who don’t have access to Anthropic Claude Opus (or want to avoid Anthropic-direct cost), claude_code_deepseek_v4_pro_or_sonnet is the closest substitute: 89/100 Tier A, 18m, $3.14, running entirely through OpenRouter using a key you already have. It’s the first meaningful “Tier A coding without an Anthropic subscription” answer in the benchmark.

For users who do have Opus, DeepClaude is still slightly worse on quality (-8) for marginally better cost (-$0.66). Not worth the trade.

For comparing models inside the Claude Code harness directly, DeepClaude makes the comparison possible: DeepSeek V4 Pro at 84-89 vs Opus 4.7 at the regressed Tier-3 level in the same harness. DeepSeek V4 Pro through DeepClaude beats Opus 4.7 inside Claude Code on quality, cost, and multi-turn. Worth remembering this only happens because Opus regresses in this harness; against Opus in opencode (97), DeepSeek is clearly behind.

The cross-harness picture for DeepSeek V4 Pro

It looks like this:

Bottom line, DeepSeek V4 Pro is a Tier-A coder when delivered through a strong autonomous loop (Claude Code) and Tier B when delivered through a thinner harness (opencode). The RubyLLM API correctness is the same in both cases. The score difference is entirely in deliverable completeness (README, compose, CI tooling) which Claude Code’s loop fills in.

What to use this for

Three scenarios where DeepClaude becomes the right tool.

The first is Tier-A coding on a budget, with no Anthropic subscription: the ..._or_sonnet variant is the new default. $3.14, 18m, 89/100, Tier A, running entirely through OpenRouter.

The second is validating whether the Claude Code regression hits other models. It hits Opus, doesn’t hit DeepSeek. The chat.complete regression is Opus-specific. DeepSeek (and presumably other reasoning models with correct RubyLLM training) cross the harness without regressing.

The third is future experiments. DeepClaude opens the door to running any OpenRouter model through Claude Code’s full agent loop. Worth re-testing Kimi K2.6 and Qwen 3.6 Plus through DeepClaude to compare against the manual-orchestration Round 3 results. Same model, different harness, see where the lift lands. There’s a real chance Kimi K2.6 (already Tier A at 87) climbs to 90+ and ties V4 Pro deepclaude. That’s the next round of the benchmark.

Caveats from DeepClaude

Things the project README warns about, worth repeating here.

No image input: the DeepSeek Anthropic endpoint doesn’t support vision. For this benchmark it’s text-only, so no impact. For other use cases it can be a real limitation.

No MCP server tools: the compatibility layer doesn’t support MCP. If you use MCPs in your normal Claude Code workflow, they won’t work inside DeepClaude.

Anthropic prompt caching is ignored. The cache_control markers Claude Code emits get dropped on the floor. DeepSeek has its own automatic caching (which shows up in the cache_read of the token usage), but the explicit cache markers get dropped. Per-turn cost ends up slightly higher than a comparable Anthropic-direct run because of this. Relevant for apples-to-apples cost comparisons.

Wrapping up

DeepSeek V4 Pro is out of limbo. It was Tier B in opencode solo and unmeasurable in any multi-agent scenario. Through DeepClaude (Claude Code with env vars pointed at OpenRouter) it delivers Tier A at 89/100, beats Opus 4.6 and Gemini 3.1 Pro, lands next to Kimi K2.6, costs $3.14 in 18 minutes. The lift didn’t come from orchestration or a better model: it came purely from swapping the harness for an agent loop DeepSeek can drive well. For anyone without Opus access but with an OPENROUTER_API_KEY, this is the first real Tier-A coding option without an Anthropic tether.

The next round is already cooked: run Kimi K2.6 and Qwen 3.6 Plus through DeepClaude to see whether the “strong harness lifts a Tier-B/A model to the top” effect reproduces. If it does, that opens up a whole family of budget variants that can compete with solo Opus in the benchmark. If it doesn’t, it becomes clear that DeepSeek has a specific affinity with the Claude Code loop the others don’t share. Both outcomes are interesting.

References

• DeepClaude on GitHub — the shell shim itself, README with the full list of supported backends
• Round 4 success report — the full technical report this post comes from
• DeepClaude integration in the benchmark — runner patch, env_overrides shape, smoke test
• Benchmark repo — code, configs, results from every round

This post inaugurates an experimental project I’ve been hacking on for the past few weeks: NW-Omarchy. The pitch is easy to explain and stubborn enough to be worth defending: take the opinionated, pretty look-and-feel of Omarchy (which is Hyprland, meaning Wayland) and bring all of that to the X11 world, as a parallel session you pick at SDDM. Your Hyprland session stays untouched. When you want to try X11, pick nw-bspwm at login and land in something that looks like the same Omarchy with different parts underneath.

The obvious question is “why bother”. Red Hat already announced in 2025 that upstream xorg-server is gone from RHEL 10, and the corporate Linux narrative shifted to “use Wayland and move on”. As usual, in open source we don’t have to agree. There’s XLibre, a fork of xorg-server picking up active maintenance, and there are plenty of people with old hardware, legacy drivers, or legacy software for which Wayland still isn’t a viable path. NW-Omarchy is for that scenario: give that gear a graceful second wind and, while you’re at it, make it pretty.

What XLibre is and why it matters

XLibre is a fork of xorg-server that started in 2025, after it became clear upstream had no energy left to evolve. X.Org itself was only taking critical security patches, and the historical primary funder of new development (Red Hat) announced it was stepping out of new X-server work as part of the RHEL 10 plans. XLibre took the codebase and went back to cleanups, security fixes, modernization and driver-ABI bumps. The first public release was XLibre 25.0, and the project lives at github.com/X11Libre/xserver.

XLibre’s technical pitch is being a drop-in replacement for xorg-server. Same X11 protocol, same client API (libxcb/libx11), same dependency graph in pacman. Your xterm, your Firefox, your Steam, your favorite emulator for arcade machines from the 90s, none of them know the X server changed. Distros already shipping XLibre as default or tier-one:

• Artix Linux (2026.04+) ships it as the default X server.
• Fedora has an open Change proposal to migrate.
• Arch Linux has an official binary repo at x11libre.net/repo/arch_based/. That’s exactly what NW-Omarchy uses.

Comparing what’s still alive:

If your reason for staying on X11 is any of the classics (legacy proprietary Nvidia driver, vintage Intel GPU, Optimus laptop with quirky muxing, dependency on xdotool/wmctrl/xprop/xinput for accessibility or remap tools, ssh -X to run a remote app, clipboard with no permission prompt, screen reader that needs to read input from any window), XLibre is the path that keeps that stack under active maintenance.

Why this project exists

I run Omarchy on my Thinkpad T14 Gen 6 (wrote about it here) and I genuinely like it. DHH did serious curation work: a single coherent theme across everything (terminal, launcher, top bar, lockscreen), consistent shortcuts, visual choices that don’t tire your eyes. It’s opinionated the right way, and it spares you the fatigue of configuring everything from scratch.

The catch is that Omarchy is Hyprland, Hyprland is Wayland-only, and Wayland still has scenarios where it’s the wrong tool for the job. Older machines with legacy Nvidia drivers, environments leaning on software with deep X11 integration, situations where you want ssh -X and don’t want to learn waypipe, or just machines you want to keep running without swapping half the stack. For those cases, I wanted Omarchy’s aesthetic and workflow on top of X11. It didn’t exist. So I built it.

The name NW-Omarchy is short for “Not Wayland Omarchy”. It’s deliberately a sidecar: runs alongside, doesn’t replace. You install it on top of an existing Omarchy install, it creates a separate SDDM session called nw-bspwm, and nothing in your Hyprland setup gets touched. Want to go back to Hyprland? Pick Hyprland at SDDM next login. Want to uninstall? There’s an uninstall script that reverses exactly what got installed, based on a manifest that tracks every action.

What changes in the stack (Wayland → X11)

Hyprland is compositor + WM in the same binary. In the X11 world, those two functions come as separate pieces, and each has a well-known substitute. The translation work was mapping every Omarchy component to its X11 equivalent, then making sure the keyboard shortcuts, theming, and behavior stayed as close as possible.

bspwm is a minimalist tiling window manager. The WM itself only responds to commands over a socket, and bspwmrc is literally a shell script. Keybindings live in a separate daemon, sxhkd, which reads a plain text file. That separation is classic X11: each piece does one thing.

picom is the compositor that gives you blur, shadows, rounded corners, fade-in/out, and per-window opacity rules. NW-Omarchy uses upstream v13 (released February 2026), not the old picom-ftlabs-git fork, abandoned since 2024. The visual effects Omarchy has under Hyprland (rounded corners, fade on open/close, blur on rofi and dunst) all come from picom in NW-Omarchy.

polybar replaces waybar. Same visual layout: Omarchy logo on the left, date in the middle, audio/wifi/bluetooth/battery indicators on the right. Same nerd-font icons. Left click opens the same TUIs (wiremix, impala, bluetui), right click opens the GUI variants. Scroll on audio adjusts volume, middle click mutes. Practical parity.

rofi replaces walker. super + space opens the full launcher with every .desktop on the system plus icons. super + shift + space opens a cheat-sheet of the pinned apps, with the chord shown next to each name. Useful for remembering “what was the chord for Signal again”.

For a user who isn’t going to crack open ~/.config to customize anything, the difference between the two sessions is cosmetic at homeopathic levels. The same Omarchy shortcuts (over 70 bindings) are wired up, the same menus pop up, the same logo sits in the bar, the same nerd-font icons.

The theme system is the same

This was the most fun part to build, and the part that surprises people most. Omarchy has a centralized theme system: each theme lives at ~/.local/share/omarchy/themes/<name>/, ships a colors.toml with a universal palette (accent, background, foreground, color0..15), and omarchy-theme-set <name> re-renders each app’s config to match. The active theme lives at ~/.config/omarchy/current/theme/, and every app imports its colors from there.

NW-Omarchy plugs into that same pipeline. I added .tpl templates for bspwm, polybar, rofi and dunst that follow the Omarchy convention, and omarchy-theme-set-templates regenerates everything on every theme change. The result is that all 19 themes Omarchy ships work as-is in NW-Omarchy, with zero porting work. Catppuccin, gruvbox, kanagawa, nord, tokyo-night, all of them. The wallpaper changes along with the theme via an inotify daemon (nw-omarchy-bg-watch).

A few examples in action:

When Omarchy adds a new theme via omarchy-theme-update, NW-Omarchy gets it for free. No extra work, no rebuild, nothing for me to republish.

System menu and TUIs

Omarchy’s system menu (the super + alt + space one that opens the hierarchical menu with Hardware, Setup, Update, etc.) has a 1-to-1 port in NW-Omarchy. Same tree, same navigation. Where Omarchy calls walker --dmenu, I call rofi -dmenu. The rest of the code is identical, and most of the helpers the menu invokes (omarchy-pkg-add, omarchy-theme-set, omarchy-update, etc.) have nothing Wayland-specific in them and run straight on X11.

The TUIs too: wiremix for audio, impala for wifi, bluetui for bluetooth, btop for system resources. They all open as a centered floating window, same as Omarchy under Hyprland. bspwm has a rule (bspc rule -a) that recognizes the org.nw-omarchy.<cmd> class and applies state=floating center=on rectangle=900x600 automatically.

What’s there and what isn’t

Honesty first: there are Hyprland features that are Wayland-only and don’t come back. Per-monitor fractional scaling is gone, X11 only does integer scaling per output, so mixed-DPI setups look off. HDR doesn’t exist on X11. Tear-free rendering by design needs Wayland; on X11 you need picom + vsync and a cooperative GPU, and even then you get close to Wayland without quite matching it. Workspace swipe with live preview during the gesture is also gone, because bspwm has no in-progress switch state, so the gesture fires a discrete command only on completion (you go to the next workspace, but you don’t see the preview slide). And the Wayland-specific daemons (voxtype, walker preview pane, hyprsunset, hypridle) become redshift and xss-lock, with no preview pane in rofi.

If any of those points is a deal-breaker for you, stay on Omarchy/Hyprland. SDDM picks between the two sessions every login, so they coexist without resentment.

On the other hand, what X11 has going for it still applies. xdotool, wmctrl, xprop and xinput keep working for automation, key remapping, screen readers, AutoKey, kanata, xkeysnail. xclip, xsel and clipmenu do straightforward clipboard plumbing, no permission dialog. ssh -X keeps working: you run Firefox on a remote box and the window pops up locally. Legacy Nvidia, vintage Intel and quirky Optimus drivers are all first-class on X11. The tiling WM ecosystem is mature (bspwm, i3, awesome, openbox, xmonad, dwm) and configs port between them with little pain. And the predictable input model, where any client can read any event, is bad for security but excellent for accessibility and productivity tooling.

For older hardware, that’s the difference between “live machine” and “machine sitting in a corner”.

Install

Prerequisite: Arch Linux with Omarchy already installed. NW-Omarchy runs on top of it, doesn’t replace it.

One-liner install:

curl -fsSL https://raw.githubusercontent.com/akitaonrails/NW-Omarchy/master/boot.sh | bash

boot.sh runs preflight (checks Arch, Omarchy, git), clones the repo to ~/.local/share/nw-omarchy, and runs the full install pipeline: packages, the nw-bspwm session, configs in ~/.config, and the XLibre swap as the last step. It asks for confirmation once before touching anything. Skip the prompt with:

curl -fsSL https://raw.githubusercontent.com/akitaonrails/NW-Omarchy/master/boot.sh | bash -s -- --yes

When it finishes, reboot. The X server swap (xorg-server → XLibre) only takes effect on the next session. At SDDM you’ll see a session picker. We also swapped Omarchy’s SDDM theme for one with a selector, because the vanilla Omarchy theme has the session name hard-coded in the QML with no UI to change it. Pick nw-bspwm and you’re in.

If you’d rather clone and run by hand to inspect first:

git clone https://github.com/akitaonrails/NW-Omarchy.git ~/.local/share/nw-omarchy
cd ~/.local/share/nw-omarchy
./install.sh           # dry-run, prints what it would do
./install.sh --apply   # actually run it

Upgrade

When a new release ships, the path is:

nw-omarchy-upgrade --check    # checks current vs latest, exits
nw-omarchy-upgrade            # yay -Syu, fetch latest tag, migrations, install

The script runs yay -Syu (or pacman -Syu if you don’t have yay), compares the local tag to the remote, and if there’s a new release does git fetch && git checkout v<latest>, runs the migrations between the current and new versions, and re-applies install.sh --apply. All idempotent. Re-running on an already-current machine is a no-op.

Uninstall

If you tried it and didn’t like it, uninstall this way:

~/.local/share/nw-omarchy/uninstall.sh --apply

The uninstaller reads ~/.local/state/nw-omarchy/manifest.tsv and replays it in reverse: removes only the packages it installed (pkg-skip rows are left alone; packages that were already on the system stay on the system), restores original configs from ~/.local/state/nw-omarchy/backups/, deletes the nw-bspwm session entry, wipes the state dir. Your Hyprland session keeps working as before. Nothing under ~/.config/hypr/ or ~/.local/share/omarchy/ gets touched at any point during install or uninstall.

To revert specifically XLibre back to xorg-server (without uninstalling anything else), pacman handles it on its own:

sudo pacman -S xorg-server xorg-server-common xf86-input-libinput

The package provides/conflicts graph handles the rest of the swap atomically.

Status: experimental, feedback welcome

The current version is at 1.0 but the project is still young, in polish phase. The big items are in place: binding parity, menu parity, theme parity, TUI parity, doctor for health-checking the install, manifest for clean uninstall. What’s left is polish, edge cases, working through varied hardware, listening to feedback from anyone running it on a different machine than mine (Thinkpad T14 Gen 6).

If you try it and hit something (something that doesn’t work, configuration that’s missing, behavior that differs from Omarchy in a way that breaks flow), open an issue here:

github.com/akitaonrails/NW-Omarchy/issues

Repros, stack traces, output of nw-omarchy-doctor, anything helps. PRs are welcome too.

Defending X11 in 2026 is a pragmatic argument. The transition to Wayland takes time, plenty of hardware and plenty of software still live comfortably on this side of the fence, and the open source community can support more than one path at a time. XLibre is the bet on keeping the X server alive a few more years. NW-Omarchy is my bet that you can make this older stack look as pretty as the newer one, without compromising any of what makes X11 still worth the trip.

If you’re on a new machine, modern GPU, 4K HiDPI display, wanting HDR, stay on Omarchy/Hyprland. If you’re on an older box, or you simply prefer the X11 ecosystem for any of the reasons above, give NW-Omarchy a shot.

Before we start: the five wrong premises

There’s a narrative that shows up in my feed every week: “I’m saving money mixing Opus for planning with Kimi/Qwen/GLM/DeepSeek for execution.” The premise is that the frontier model is too expensive to use for continuous coding, so you split the task: the expensive one thinks, the cheap one writes. Sounds reasonable. In practice, it’s wrong on five fronts.

First: most of the people saying this don’t show their results. Plenty of folks brag about orchestrating dozens of agents in parallel, fancy dashboards, elaborate flows. Ask them to show the app that came out of it, in production, generating value. Almost nobody delivers. Ask for the result. If they can’t show real production, they’re snake-oil sellers. My benchmark, with everything open, is the opposite of that: the repo is public, the logs are auditable, the generated code is right there for inspection. That’s the minimum bar for honest discussion about LLMs in coding.

Second: the use case changes everything. If you’re doing a legitimate one-shot (Opus plans the architecture once, a cheap model executes many parallel pieces with well-defined scope, like generating 50 UI components following the same pattern), then it can make sense. But most people complaining about token cost are doing continuous coding-agent work, not massive one-shots. For continuous coding the math is completely different.

Third: pay-as-you-go vs subscription completely changes the math. If you pay per token directly on the API, every extra orchestrator prompt counts. If you pay $20 or $200 a month for Plus/Pro/Max and use Claude Code, Codex CLI or similar inside the subscription quota, the “cost per run” question disappears. It becomes “I’m consuming part of my monthly quota.” Under subscription, the marginal cost of an extra call is zero until you saturate the cap. Coordinating two models to save tokens you’re not being charged for is optimization against a non-existent cost.

Fourth, and most important: you only realize the maturity of solo frontier models when you do full vibe coding. I’ve written about this in several posts (six-day immersion from zero to production, how to talk to Claude Code effectively, Clean Code for AI agents). Serious vibe coding is: turn off the IDE, don’t edit code by hand, role-play as product manager + QA + tech lead mentor, let the model write. When you do that, it becomes immediately obvious that mixing two models creates absurd coordination overhead. It’s like outsourcing development to an offshore team but hand-editing every delivery because you nitpick everything. A plan that needs to spell out every line of code becomes micromanagement: if the plan already contains the code, why are you delegating? That’s the extreme, but it’s where most multi-agent setups land. Balance is what matters, and removing overhead is the main technique. For that, a good frontier model inside a mature harness (Claude Code, Codex, opencode) is the path.

Fifth, and the most technical: premature optimization. Donald Knuth warned us decades ago, “premature optimization is the root of all evil.” The original rule: 97% of the time you don’t have data to justify optimizing; when you do, it’s only in the critical 3%. The 2026 version of that is spending a weekend wiring up an orchestration of five parallel agents to save $30/month in tokens, before you’ve validated whether the product you’re building is even worth shipping. You’re optimizing the cost of a pipeline that hasn’t delivered anything yet. Focus on shipping. $20-200/month subscriptions are trivial compared to any other professional learning cost. People spend more on bad online courses or weekend partying. Once the product ships and token cost becomes a measurable problem, then yes, optimize. Today, focus on shipping.

OK, sermon over. Let’s go to the numbers.

Methodology in one line

Same benchmark as the canonical version: build a Rails 8 app with RubyLLM, Tailwind, Hotwire, Minitest tests, Brakeman, Docker, docker-compose. Same 8-dimension rubric with 0-100 scoring, same A/B/C/D tiers. The difference is that here every variant has two models: a “planner” (strong) and an “executor” (cheaper), in different harnesses (Claude Code, opencode, Codex). Everything in the repo with docs, dispatches, traces, audits.

Solo Opus 4.7 in opencode is the comparison baseline: 97/100 Tier A, 18 minutes, ~$4 pay-as-you-go. Every multi-agent variant has to beat this (in quality, time OR cost) to justify the added complexity.

What this benchmark does NOT prove (and what good delegation actually means)

Before diving into the three rounds, it’s worth circling what this benchmark covers and what it doesn’t. This matters because I’m going to draw strong conclusions about delegation, and those conclusions don’t generalize to every kind of work.

Limit 1: the project is a simple greenfield Rails build

The benchmark builds a Rails 8 chat app with RubyLLM. It’s real code, with Tailwind, Hotwire, Docker and tests, but it’s a greenfield project with well-defined scope on a popular stack. Practically every Tier A model nails it. In complexity terms, it’s early-junior territory: there’s no legacy code to understand, no technical debt to work around, no distributed system with 50 microservices to orchestrate.

For anyone who wants conclusive data about their own use case, the honest answer is: adapt the benchmark harness to mimic your project’s conditions and compare models there. The repo is open source for exactly this reason. Take the prompt, swap in something that reflects your reality (50K-line legacy codebase, integration with 3 external systems, custom company DSL, whatever it is), and run the models the same way. The numbers I report here give direction, but any serious engineer should validate models against the work they actually do, not against an example chat app.

Limit 2: parallelizable tasks vs dependency-laden tasks

The question “is mixing two models worth it?” depends critically on what kind of work you’re delegating. There are two extremes.

Work where frontier models delegate happily, and that will work beautifully: numerous, simple tasks with little or no coordination needed. “Translate these 100 documents to English.” “Summarize these 50 spreadsheets in bullet points.” “Convert these 200 images to WebP at max 800px.” Each item is independent. No revision is needed between them. The result of one doesn’t change the input to the next. It’s exactly the kind of work Amazon’s Mechanical Turk was designed to distribute. Frontier models already do this on their own without explicit orchestration: ask Opus 4.7 to translate 100 documents and it’ll fan out to parallel batches via the Task tool, scaling up or down as needed.

Work where frontier models won’t delegate, because it can’t be delegated well: tasks with many dependencies, requiring constant revision and mutual adjustment. Building a Rails app is exactly that. The Chat model depends on the LlmClient decision, which depends on the RubyLLM config, which depends on the OPENROUTER_API_KEY in env, which depends on ENV being loaded before the initializer, which depends on the Gemfile having the right gem. Touching one piece forces revising several others. This isn’t Mechanical Turk work. It’s cohesive engineering work, and Tier A models recognize that and keep everything inside one reasoning session. That’s why zero of the 7 runs in Round 1 delegated: the task wasn’t delegable.

The async programming analogy

Anyone who learned async/await in a modern language went through the same disillusionment. You discover Promise.all, asyncio.gather, or similar, and start eyeing every slow piece of work looking for ways to parallelize. Then you write something like this and get angry:

// Sequential chain: each step depends on the previous result
const userData = await fetchUser(userId);
const orders = await fetchOrdersFor(userData);          // ← needs userData
const recommendations = await analyzeOrders(orders);    // ← needs orders

// Total latency = latency(fetchUser) + latency(fetchOrders) + latency(analyze)

Three awaits. Three I/O operations. You expected 3× faster from going async. But it’s the same as synchronous because each call depends on the previous one’s result. Trying to wrap this in Promise.all doesn’t even compile: you can’t pass userData to fetchOrdersFor before you have userData.

Promise.all only helps when the calls are independent of one another:

// Independent calls: none uses another's result
const [user, allProducts, categoryTree] = await Promise.all([
  fetchUser(userId),       // ← doesn't need products or categories
  fetchAllProducts(),      // ← doesn't need user or categories
  fetchCategoryTree()      // ← doesn't need user or products
]);

// Total latency = max(latency of the three), not the sum

The difference is not syntax; it’s dependency structure. In the first case, A → B → C: three operations in series, each waiting on the previous. In the second case, A | B | C: three independent operations that fire at the same time and the total latency is that of the slowest one. Async/Promise.all doesn’t create parallelism, it only exposes the parallelism that was already there in the structure of the problem.

Multi-agent in coding is the same. If you give two models a cohesive task with internal dependencies (build a Rails chat app), the “planner” has to read every output from the “executor” before deciding the next dispatch, and the executor needs the context the planner built. You sequentialized the two. Worse: you added coordination overhead (prompt format, response parsing, watchdog, retry logic) on top of a pipeline that was supposed to have low overhead. It’s like taking the three-sequential-await code and dropping a Redis queue in the middle: now you have 3× the latency plus the queue cost.

Parallelizable task = “apply this same refactor to 50 different files.” There orchestration makes sense: one model plans the refactor once, describes it in reusable form, and dispatches 50 sub-agents in parallel to execute on each file. Real time savings. Sequential task with dependencies = building a cohesive app. There’s no parallelization possible, and adding agents only adds overhead.

This benchmark tests the second scenario. If your daily work is the first (large batches of independent tasks), the conclusions here may invert. Adapt the harness, measure, decide.

Segment 1: the initial round, models didn’t delegate

The first round, in mid-April, configured 7 variants where the planner had a registered subagent available and aggressive prompt language pushing delegation (“Use PROACTIVELY”, “ALWAYS delegate to this agent for code implementation”). The question: given that the subagent exists and is painted as the preferred path, will the main model delegate?

Zero delegations in zero of the 7 variants. Claude Code’s Task tool, opencode’s task dispatcher, and Codex’s spawn_agent were all completely ignored. In every case, the main model did 100% of the work.

Two things worth logging from this round.

First: aggressive prompt language doesn’t persuade a model to delegate. “Use PROACTIVELY” is a weak word against the model’s internal “this task is cohesive, I’ll do it myself” instinct. In greenfield Rails, plan and implementation don’t have a clean line. There’s no atomically-delegable subtask.

Second, and most surprising: the same Opus 4.7 wrote worse code in Claude Code than in opencode, and cost 4 to 7× more ($6.74 vs $1.10). Two of three Claude Code variants hallucinated a RubyLLM method that doesn’t exist (Tier 3 hallucination); opencode with the same model got the API right and landed Tier 1. The harness itself influences the output. Claude Code resends much more context per turn, and that seems to nudge the model toward generic patterns while also inflating the bill.

Round 1 conclusion: if the model is already delivering Tier A solo in the right harness (opencode), adding a subagent isn’t even used. The extra configuration is pure overhead. And if you force it inside Claude Code, you pay 4-7× more. The “savings” of multi-agency here is negative.

Segment 2: the forced round, when the planner is forbidden from coding

The community pushed back on Round 1: “the subagent description was weak”, “models don’t trust unfamiliar subagents.” Fair pushback. Round 2: explicit planner-executor prompt. The planner is literally forbidden from using Write/Edit/Bash. Every code change has to flow through the subagent via Task or spawn_agent. No fallback.

The full prompt is at prompts/benchmark_prompt_forced_delegation.txt. Mandatory workflow: plan → delegate → converge → validate. Seven variants:

Results:

When forced, delegation actually happens (5 to 15 dispatches per run). All Tier A on code quality (90-95). But the important point is: none beats solo Opus 4.7 on quality. All cost extra time (minimum +7 minutes, up to +35 minutes for multi_faster). And on raw cost (pay-as-you-go), only two come in below solo: GLM (Z.ai subscription, basically free) and the GPT 5.4 multi (much cheaper than GPT 5.4 solo, but still in the same ballpark as Opus solo).

This round had two embarrassing harness findings. One was a watchdog firing too early, killing the benchmark before the cross-provider subagent finished spinning up (Z.ai and llama-swap took longer than expected to come online). I bumped the timeout from 6 to 15 minutes and GLM/Qwen came back at Tier A. The other: several models appeared to be “executing silently” (empty result envelopes). Only in Round 3 did I figure out that most of those were hidden errors — the qwen3.6-plus:free endpoint had been deprecated and was returning 404, and DeepSeek was 400-erroring with a protocol bug (details in its dedicated section below). The “1900 files” of opencode_opus_deepseek_forced were entirely written by Opus’s general fallback, not DeepSeek.

OK, so accounting for the harness failures, the story becomes:

• Sonnet/Haiku coders in Claude Code: 90-92 vs solo Opus 97. Costs +1 minute to +7 minutes. Costs ~equal or more.
• Kimi K2.6 in opencode: 95 vs 97. Costs $2-3 vs $4, so 25-50% savings. +7 minutes.
• GLM 5.1 in opencode: 93 vs 97. Costs ~$0.50 with Z.ai subscription (basically free) vs $4 for solo Opus. -5 minutes.
• GPT 5.4 + medium: 94 vs 97. Costs ~$1-3 vs $16 for GPT 5.4 solo (80-85% cheaper). +12 minutes.

The last is the only configuration where forced delegation actually pays off in absolute cost: if you have to be on GPT 5.4, forced multi-agent is real savings. In every other case, you pay in quality and/or time to use a cheaper subagent. On Anthropic Pro monthly, solo Opus is $0 marginal. There’s zero reason to use Sonnet/Haiku as a sub. Forced multi-agent there is theater.

And one last thing from this round: the “exception lesson”, when forced multi-agent repairs Claude Code. Solo Opus in Claude Code came out Tier 3 (hallucinated chat.complete) at $6.74. Forcing Sonnet/Haiku as executor inside Claude Code repaired it to Tier A at $3.49-5.77. But the cleaner fix is to switch harness, not orchestrate. Solo Opus in opencode delivers Tier A at $4 with no fuss. The “orchestration repairs Claude Code” line is a workaround for a bug elsewhere.

Segment 3: manual cross-process orchestration, Opus driving opencode

The third round was the most elaborate. Premise: take the subagent out of the planner’s process (where the task envelope bug lived) and use opencode in single-agent mode invoked via subprocess for each subtask. The setup was a Claude Code session with Opus 4.7 in the orchestrator role. For each subtask, Opus wrote the prompt to a file, invoked opencode via Bash with the cheap model as sole primary, read the output, and decided the next dispatch.

No fallback. No general agent available for Opus to escape to. Either the named executor writes, or nothing gets written.

Three variants attempted:

Opus + Qwen 3.6 Plus (Variant 1): 94/100 Tier A

Setup: 8 dispatches + 1 fix-up = 9 dispatches total. ~$0.74 executor cost. ~12 minutes cumulative wall time for the executor only. Plus the planner overhead (Opus in Claude Code orchestrating) which isn’t directly measured but is estimated at $11 (more on this below).

Qwen 3.6 Plus behavior as executor: truncates the final summary in 3 of 9 dispatches, sometimes emits zero text but does many tool calls (dispatch 8: 14 tool calls, 0 text turns), made smart adaptations on its own (manually created app/javascript/ after Rails 8.1 didn’t generate it, swapped root_url for get "/", created tailwind.css placeholder). But needed 2 fix-up dispatches for issues caused by Rails 8.1 generator behavior changes.

Auditor’s read: “Qwen wrote the lines, Opus decided the boundaries, and the boundaries are most of what lifts this from B to A.”

Result: 94/100 Tier A. +23 points over Qwen 3.6 Plus solo (71/100, Tier B). But the entire lift comes from Opus’s detailed plan, not from autonomous Qwen capability.

Opus + Kimi K2.6 (Variant 2): 97/100 Tier A, TIES SOLO OPUS

Setup: 5 dispatches, zero fix-ups. ~$0.37 executor cost. ~10 minutes cumulative executor wall time. Full end-to-end validation (local boot, docker compose up + curl + clean teardown).

Kimi K2.6 behavior: coherent text response per dispatch with no truncation, strong autonomous adaptation (caught Stimulus + Tailwind install gaps without explicit prompting, caught the layout-wrapping side effect of tailwindcss:install), zero fix-up dispatches.

Result: 97/100 Tier A. TIES Opus 4.7 solo. Auditor’s read: “Kimi wrote every line, but Opus’s planning prompts shaped what to ask for (better test fixtures, error-path coverage, persistence design), pushing Kimi from 87 → ~97.”

Opus + DeepSeek V4 Pro (Variant 3): FAILED

Structural harness incompatibility bug. DeepSeek V4 Pro returns reasoning_content on every response, and opencode strips that field when constructing the next request. The DeepSeek API then rejects turn 2 with "reasoning_content must be passed back to the API". Tested three reasoning configurations (true, false, absent). All failed identically at turn 2 of dispatch 1. There’s no opencode flag that fixes it. Workarounds (custom OpenRouter provider params, single-bash-per-dispatch protocol, switching to V4 Flash) were not pursued.

Retroactive implication: the supposed “completions” of DeepSeek in rounds 2 and 2.5 were entirely written by Opus through the general fallback. DeepSeek V4 Pro contributed zero lines of code in any configuration of this benchmark to date.

The hidden planner cost

Here’s where things get ugly. The two manual variants that actually ran (Qwen and Kimi) had ~14 successful dispatches combined. Each dispatch consumed ~3-5 turns of the Opus orchestrator (read previous dispatch output, plan next, write prompt file, monitor execution, verify filesystem). Each turn costs $0.15-0.25 in Anthropic tokens. Total: **$11 of hidden planner cost**, not logged in the executor JSON.

Real total cost of the two manual variants: ~$1.11 executor + $11 planner = **$12 combined**. Compared to solo Opus opencode at $4. Manual orchestration costs 3× more than solo.

What this round actually proves

The lift scales inversely with the executor’s solo capability. The further from Tier A solo, the more orchestration adds. Kimi solo is already Tier A, so the +10 is polish (better test fixtures, error coverage, persistence). GLM solo is Tier C because of one specific hallucination (invented fluent DSL), and prescriptive prompts that name the real API remove the hallucination entirely.

But the cost of that lift is dominated by the planner. If you only have access to GLM (not Opus), this finding doesn’t help you. If you have Opus AND GLM, just use Opus solo for less money and time.

The realistic use case for this pattern is: multi-tenant deployment where the planner runs once and is amortized across many similar subtasks (like “apply this same refactor to 50 different files”). Greenfield Rails benchmark doesn’t capture that.

Final comparison: the 3 rounds vs solo

All costs below are total (Opus planner + executor) in pay-as-you-go. End-to-end wall times:

(Tier D / 0-file failures omitted.)

The orchestrator-Opus planner cost on the “Opus + Kimi (manual)” and “Opus + Qwen (manual)” rows is a hidden cost: it shows up in the Claude Code session driving the experiment, not in the executor log. The ~14 successful dispatches from the two manual variants combined consumed ~$11 of Opus, split between them, landing at ~$5-6 each.

Solo Opus 4.7 in opencode is the best on every metric: it ties or beats every other variant on quality, cost OR time, and ties or beats most on all three simultaneously.

The real exception is Codex GPT 5.4 xHigh + medium executor: 94/100 vs 97/100 (loses 3 points), but costs $1-3 instead of $16 for GPT 5.4 solo (80-85% cheaper). Useful if you only have OpenAI credentials and need cheap Tier A.

Every other variant loses on at least one important dimension. Most lose on two (quality AND time, or quality AND cost).

The subscription question

The numbers above are pay-as-you-go. Let’s add subscription to the picture.

Anthropic Pro at $200/month includes Opus 4.7 with 20× the Plus quota. In practice, that’s many full benchmark runs per day without touching the cap. OpenAI Plus at $20/month or Pro at $200/month includes Codex CLI with similar economics. Under subscription, a benchmark run adds zero marginal cost until you saturate the quota.

What does that change?

• Solo Opus 4.7: $4 pay-as-you-go becomes $0 marginal on Anthropic Pro. Still the best.
• Multi-agent with Sonnet/Haiku via Claude Code: $3.49-5.77 becomes $0 marginal on Anthropic Pro. Still loses 5-7 quality points. Not worth it.
• Multi-agent with Kimi/GLM/Qwen via opencode (which charges separately via OpenRouter): adds $0.50-3 in OpenRouter cost on top of the subscription. Loses 2-7 quality points. Equal or longer time. Not worth it.
• Codex GPT 5.4 + medium: $1-3 becomes $0 marginal on ChatGPT Pro. But solo GPT 5.4 also becomes $0 marginal. Multi isn’t worth it.
• Manual cross-process (Opus driving opencode with Kimi): $0 marginal (planner on Anthropic Pro) + $0.37 (executor on paid OpenRouter) = $0.37. Costs 30-40 minutes vs 18 for solo. Ties on quality. Not worth it.

Under subscription, no multi-agent configuration beats solo frontier. Marginal cost of an extra call is zero for someone already paying the monthly subscription. Extra coordination doesn’t compensate when the “savings” is zero.

The least-bad case: Opus + Kimi K2.6 under heavy use

Since I’m being skeptical on every conclusion, it’s worth noting separately the one non-obvious configuration where Opus + Kimi K2.6 might actually make sense in practice: continuous heavy use that already saturated the Anthropic Pro monthly quota.

In forced in-process mode (Round 2.5 with adjusted watchdog), Kimi K2.6 delivers 95/100 vs Opus solo’s 97. The 2-point difference is usually polish in test fixtures and error handling, things you can patch later. In exchange, you pay ~$2-3 of OpenRouter on Kimi instead of burning Pro quota on Opus. For power users hitting the $200/month Pro cap regularly (multiple times a week, heavy parallel projects), redirecting some work to Kimi can free up Pro quota for tasks that really need Opus.

It’s a narrow exception. For most people who haven’t saturated Pro, just using solo Opus is still better. And for those without Pro yet, the savings from orchestrating Kimi + Opus will be equal to or less than just subscribing to Pro. But for the “I’m using a coding agent professionally and heavily and I’m blowing the monthly cap” scenario, the Opus planner + Kimi executor configuration is the best option I measured in this benchmark.

Worth mentioning also is the multi-tenant case where the planner is amortized: if you’re running a pipeline that applies the same change pattern to many similar projects (refactor 50 repos to use a new convention, generate 30 microservices with the same skeleton), Opus plans once, you save the plan, and Kimi executes against each project. The planner cost dilutes across volume and the pairing makes real economic sense.

Why DeepSeek was the hardest model to test

Worth logging separately, because it’s the most frustrating case in the whole benchmark. DeepSeek V4 Pro never contributed a single line of code in any of the three multi-agent rounds, despite showing up in several experiments as “completed”.

The root cause is a protocol incompatibility between the DeepSeek API and the ai-sdk that opencode uses underneath. DeepSeek V4 Pro runs in thinking mode by default. Every response it returns includes a reasoning_content field with the model’s internal chain of thought. The DeepSeek API then requires that reasoning_content to be echoed back in the message history of the next request. Without it, the server responds with 400 and this specific message:

The "reasoning_content" in the thinking mode must be passed back to the API.

Opencode’s ai-sdk, when constructing the next request, strips reasoning_content from the message history. Every multi-turn call to DeepSeek V4 Pro via opencode fails on turn 2.

What makes this invisible on the surface is that opencode doesn’t bubble that 400 to the user. It buries the error in the event stream and keeps going. When you look at the run result, you see files being written and tasks “completing.” But if you inspect the trace, you find that most (or all) came from the general fallback agent, which is Opus 4.7 itself. The DeepSeek that was supposed to be doing the work wrote nothing.

I tested three reasoning configurations in opencode (true, false, absent). All failed identically at turn 2 of dispatch 1. No config flag fixes it. Workarounds that were out of scope:

• Custom OpenRouter provider params via header
• Single-bash-per-dispatch protocol (which would dodge multi-turn)
• Switch to DeepSeek V4 Flash, which doesn’t use thinking mode

This forces a retroactive correction of earlier conclusions. In an earlier post I described DeepSeek V4 Pro as having “Tier 1 code, but DNF in the harness.” That description was incomplete. DeepSeek V4 Pro is fundamentally incompatible with any ai-sdk-based harness (which includes opencode, and probably several other tools that use the same SDK underneath). The model can write good code solo if you invoke the API directly with proper thinking-mode handling. But in any real coding-agent pipeline that uses ai-sdk, it doesn’t work in multi-turn.

Practical result: DeepSeek V4 Pro is unmeasurable in this benchmark. The only configurations where it appeared as “successful” had Opus writing in its place. For future benchmarks, I’ll either swap to V4 Flash (which avoids thinking mode) or build a custom harness that echoes reasoning_content correctly.

The broader lesson: the maturity of tooling around a model matters as much as the model’s quality. DeepSeek V4 Pro might have excellent solo code, but if you can’t use it without writing your own harness, it loses to Kimi K2.6 which works out of the box.

Conclusion

Multi-agent on continuous coding agent work is premature optimization in disguise. You spend a weekend wiring up an orchestration of five models, five harnesses, five different token counters, only to land at a result that’s equal or worse than solo Opus in opencode. And worse: while you’re orchestrating, you’re not shipping product.

The data:

• Solo frontier model (Opus 4.7 in opencode) delivers Tier A 97/100 in 18 minutes for $4 pay-as-you-go.
• Trying multi-agent without forcing: the model doesn’t delegate, you pay harness overhead for nothing.
• Forcing multi-agent: equivalent quality at more time and equal or higher cost. The one real exception is Codex GPT 5.4 + medium for cutting GPT cost.
• Manual cross-process orchestration: ties on quality at best (Opus + Kimi → 97), but doubles wall time and triples total cost when you account for the planner.
• Under monthly subscription: the marginal cost of an extra call is zero for solo frontier. Multi-agent has no economic advantage.

Practical rule: pick a good frontier model (Opus 4.7, GPT 5.5, GPT 5.4 xHigh), use it in a mature harness (opencode respects the model the most, Codex is the official one for GPT, Claude Code if you accept the context pollution), and optimize the prompt instead of the orchestration. Current models already decide on their own when to split a task into parallel subtasks (Claude Code has the Task tool, Opus uses it when it needs to). No need to force it.

And to close the subscription argument: $20-200 per month is trivial. It’s less than what most people spend on bad online courses, streaming subscriptions, or weekend partying. In serious professional use, that pays back 5-10× on the first real project. If “$200/month” feels like a lot, the problem isn’t the LLM, it’s the ROI of what you’re building. Which is exactly where you should be focusing before orchestrating agents to cut $30 in tokens.

Focus on shipping. Token optimization comes later.

Sources

• Benchmark repo — code, prompts, configs, all the logs
• Round 1 multi-model report — 7 free-choice variants, zero delegations
• Round 2 forced-delegation audit — 7 forced variants, 0-100 rubric
• Round 3 manual orchestration — Opus driving opencode in subprocess, Kimi/Qwen/DeepSeek
• Orchestration traces — per-variant forensic walkthroughs
• Forced-delegation prompt template
• Canonical benchmark (April 2026) — solo runs of 23 models, 8-dimension rubric
• Vibe code: from zero to production in 6 days — full immersion in practice
• How to talk to Claude Code effectively — role-play as PM/QA
• Clean Code for AI agents — instruction guide for the model

Update (May 6, 2026): two post-publication adjustments that reshuffle the ranking. DeepSeek V4 Pro got unblocked — what was listed here as “unmeasurable in opencode” climbed to Tier A at 89/100 running through DeepClaude, a shim that swaps the endpoint Claude Code talks to. Technical details in the dedicated May 4 post. And Grok 4.3 entered the benchmark at 72/100 Tier B, a big jump over Grok 4.20’s 25/100 (which still sits at the bottom of the list). The ranking, comparisons, and DeepSeek/Grok dedicated sections have all been updated below.

TL;DR: This is the canonical version of my LLM coding benchmark. It supersedes the earlier April posts which are now deprecated. I re-audited 24 models against the ruby_llm gem source instead of memory, and several models I had flagged for “inventing API” actually write correct code. Kimi K2.6 moved to Tier A. Gemini 3.1 Pro too. DeepSeek V4 Pro reaches Tier A only via DeepClaude (89/100); in opencode it stays unmeasurable. Grok 4.3 debuts at Tier B (72/100). GLM 5.1 dropped to Tier C. MiMo V2.5 Pro fell from “first non-Anthropic Tier 1” to Tier B. Opus 4.7 and GPT 5.4 xHigh tie at the top (97/100), GPT 5.5 lands third at 96/100 (40% cheaper than 5.4 at the same quality). Opus 4.6 is still my daily pick on behavior, not code. Long details below.

Important disclaimer: all the rankings, tiers and conclusions here only hold within this specific benchmark methodology, which is building a Rails + RubyLLM + Hotwire + Docker app from a fixed prompt. Models that fall to Tier B or C here can shine on other kinds of task (isolated function completion, short snippet generation, mathematical reasoning). Nobody should read this as a universal capability judgment.

What this benchmark tests

Each model gets the same prompt to autonomously build a ChatGPT-style chat app in Rails. The prompt asks for 15 things:

1. Rails with latest Ruby + Rails via mise
2. No ActiveRecord, Action Mailer, or Active Job
3. SPA mimicking ChatGPT’s interface
4. Tailwind CSS
5. Hotwire + Stimulus + Turbo Streams
6. Rails partials (no single-file CSS/JS dumps)
7. OPENROUTER_API_KEY via env var
8. No secrets in files
9. RubyLLM (ruby_llm gem) configured for OpenRouter + Claude Sonnet
10. Minitest tests for each component
11. Brakeman, RuboCop, SimpleCov, bundle-audit for CI
12. Functional Dockerfile (not a placeholder)
13. docker-compose
14. README with setup
15. Everything in workspace root (no nested subdir)

Cloud models run two phases (build + boot/Docker validation). Local models run phase 1 only. Harness is opencode run --agent build --format json, except GPT 5.4 which runs via codex exec --json directly.

Methodology: the 8-dimension rubric

This part changed this week. The first version of this benchmark weighted RubyLLM API correctness too heavily, so a model that wrote the correct call but delivered an incomplete project (no docker-compose, stock README, bundle-audit missing) came across as more qualified than it should. The new rubric distributes across 8 dimensions:

Score 0-100 → Tier A (80+) / B (60-79) / C (40-59) / D (<40).

• Tier A: ship as-is, or with a patch under 30 minutes
• Tier B: 1 to 2 hours to ship; architecture is sound, minor gaps
• Tier C: major rework. Core bugs or missing deliverables
• Tier D: throw away, useful only for architectural inspiration

Final ranking (24 models)

*DeepSeek V4 Pro only reaches that score via DeepClaude (Claude Code with env vars pointed at OpenRouter). In opencode (and any ai-sdk-based harness) the model stays unmeasurable due to the reasoning_content protocol bug. The 89 above is the claude_code_deepseek_v4_pro_or_sonnet variant, with sonnet-coder registered but never invoked; the solo variant (no subagent registered) lands at 84/100, still Tier A. Full coverage in the May 4 post on the unlock.

Course correction: what changed in the criteria

Worth logging what changed between the previous iteration and this one, because it’s quite a bit.

Mistake 1: I was cataloging real APIs as “hallucinations”

Embarrassing. I went to verify directly against the gem source at ~/.local/share/mise/installs/ruby/4.0.2/lib/ruby/gems/4.0.0/gems/ruby_llm-1.14.1/ and two things I had been calling invented are actually legitimate public API:

chat.add_message(role: :user, content: "x") is not a kwargs bug. I asserted this crashed with ArgumentError because the real signature would be a positional hash. Looking at the gem, Chat#add_message(message_or_attributes) accepts either a Message or a hash. Ruby’s parser treats add_message(role: :user, content: "x") as add_message({role: :user, content: "x"}), a single positional hash. It works.

chat.complete(&block) is a real public method in RubyLLM 1.14.1.

Consequence: several models I had tagged as Tier 3 were actually using valid API.

Mistake 2: RubyLLM correctness alone isn’t enough

Even after the API correction, weight was missing on deliverable completeness. If a model writes perfect RubyLLM but forgets docker-compose, leaves the README as a stock template, or omits bundle-audit, the project isn’t done.

The new rubric distributes weight differently and that shifted the ranking:

• Kimi K2.6 moved from “half-fix Tier 2” up to Tier A (84). The only non-Western model with real tests mocking RubyLLM + rescue + multi-worker-safe session cookie.
• Kimi K2.5 came back to Tier B (66) from Tier 3. The API I called invented is real. It drops for another reason: 37 tests that never mock RubyLLM.
• Gemini 3.1 Pro jumped to Tier A (82). Was previously misclassified as Tier 3.
• GPT 5.4 xHigh ties for first with Opus 4.7 (97/100). Impeccable architecture + complete deliverables.
• DeepSeek V4 Pro has two readings. In opencode (and any ai-sdk harness) it stays unmeasurable: it hits the thinking-mode protocol incompatibility and the output falls back to Opus. Through DeepClaude (Claude Code with the endpoint swapped to OpenRouter), it delivers Tier A at 89/100 — the model is capable, the prior harness just didn’t support the protocol. May update, see the dedicated post.
• MiMo V2.5 Pro dropped from “first non-Anthropic Tier 1” to Tier B (64). Tests don’t exercise LLM + process-local Singleton + no rescue + no system prompt.
• GLM 5.1 dropped hard to Tier C (43). Its fluent DSL (c.user(), c.assistant()) really is invented — grep confirms. And every request reconstructs ChatSession.new, discarding history. Two compound bugs.

Lesson: file count and test count measure zero if the code is wrong underneath. But RubyLLM correct on its own also isn’t enough. You need both.

Tier A: what makes them work

To understand what separates Tier A from Tier B, look at what Opus 4.7, Kimi K2.6 and Gemini 3.1 Pro do that MiMo, Sonnet 4.6 and Grok 4.3 don’t.

All Tier A models have these 4 things:

1. Tests that mock RubyLLM with the correct signature. A FakeChat that implements with_instructions, add_message, ask. Tests that exercise happy path AND error path. WebMock blocking real calls to OpenRouter.
2. Rescue around chat.ask with typed error (LlmClient::Error or similar) and degraded UI for the user.
3. Persistence that survives restart and works multi-worker. Session cookie (Opus, K2.6) or Rails.cache with TTL (Gemini, GPT 5.4).
4. System prompt via with_instructions. The model knows its role.

Tier B usually fails 2-3 of these. MiMo fails all 4. Sonnet 4.6 has ambitious architecture (multi-conversation sidebar) with a subtle control-flow bug that the tests rubber-stamp. Grok 4.3 writes the cleanest controller in the benchmark but its Stimulus pipeline is dead at runtime, so half the UI doesn’t react to events. DeepSeek V4 Pro has the cleanest RubyLLM code (persistent @chat) in the snippet it produces; in opencode the run falls back to Opus before covering the checklist, but through DeepClaude the same model covers the checklist and lands in Tier A.

Tier C usually has at least one structural bug: invented fluent DSL, history discarded every request, ruby_llm gem in the :test group with require: false, or bypassing the gem entirely with raw Net::HTTP.

Claude family: Opus 4.6 vs 4.7, Sonnet 4.6

Opus 4.7 leads at 97/100. Textbook-correct code:

chat = @client.chat(model:, provider:)
chat.with_instructions(@system_prompt)
previous_messages.each { |msg| chat.add_message({role: msg.role.to_sym, content: msg.content}) }
response = chat.ask(user_message)
response.content

FakeChat with real signature. Tests verify history replay, error wrapping, model/provider override, system prompt. Session cookie with to_a/from_session is multi-worker safe. Rescue of RubyLLM::Error + StandardError → friendly error bubble.

No relevant deductions this round.

Opus 4.6 has correct code too (83/100 Tier A) but less disciplined. Controller without rescue around chat_service.ask: a transient 5xx becomes a stack trace page. Service reaches into Chat#messages via attr_reader directly, Demeter violation. Material difference between 4.6 (low Tier A) and 4.7 (high Tier A).

Sonnet 4.6 is Tier B (78). Richest UI of the whole benchmark (multi-conversation sidebar). But LlmChatService#call only calls ask if the last history message is from the user, otherwise it silently returns "". The tests rubber-stamp the bug. And the whole conversation fits in a 4KB cookie, which overflows after ~10 turns.

The 4.7 behavior downgrade

The community complaint on Reddit and DEV.to that “4.7 got worse for coding” isn’t about code quality. On objective benchmark it’s at the top. What 4.7 made worse is behavior:

• New tokenizer consumes 1x to 1.35x more tokens for the same text
• Tries to optimize resources (tokens, tool calls, steps) more aggressively, sometimes cutting corners
• GitHub issues report Max Plan running out in minutes where it used to last hours

I have hundreds of hours with 4.6 and have been testing 4.7 since launch. The code 4.7 produces is Tier A, equal to or better than 4.6. But in daily use, 4.6’s more direct behavior is more productive. 4.6 is still my Claude Code default when Claude Code lets me pick (since 4.7 launched, Claude Code changed the default to xHigh reasoning and is more restrictive about downgrading to 4.6).

GPT via Codex: 5.4 and 5.5 at the top

GPT 5.4 xHigh via Codex CLI ties with Opus 4.7 at first (97/100). Uses RubyLLM.chat(model:, provider: :openrouter, assume_model_exists: true) + with_instructions + add_message(role:, content:) + chat.ask + response.content. Textbook, with provider pinning and registry-skip.

It’s the only model with:

• Explicit API-key preflight (ensure_api_key! raises MissingConfigurationError)
• Differentiated HTTP status codes: 503 for config error, 502 for runtime error
• Rails cache persistence with TTL + cap (24 messages × 12h)
• Dedicated form object (PromptSubmission) separate from the domain model (ChatMessage)

10 test files including partial render tests. FakeChat/FakeClient match real API.

Critical weakness: 7.6M total tokens → ~$16/run. 15× Opus’s cost for essentially tied quality. Hard to justify unless you can’t iterate on the first try.

GPT 5.5 xHigh (Codex): 96/100, cheaper and faster than 5.4

OpenAI released GPT 5.5 yesterday (April 23), already available in Codex. I ran the benchmark today. Result: 96/100, Tier A, rank #3.

Good news is 5.5 delivers the same code quality as 5.4 on this benchmark, with real time and token savings.

The RubyLLM integration is structurally identical to 5.4:

chat = RubyLLM.chat(model:, provider: :openrouter, assume_model_exists: true)
chat.with_instructions(SYSTEM_PROMPT)
history.each { |m| chat.add_message(role: m.role.to_sym, content: m.content) }
response = chat.ask(prompt)
response.content.to_s.strip

Ships with the same defensive patterns 5.4 has:

• Dependency-injected client_factory:: lets tests exercise the full seed-history-then-ask path via FakeClient, no WebMock required
• rescue_from RubyLLM::Error, RubyLLM::ConfigurationError: both real error classes, rescued separately
• Session cookie with 20-message cap
• Real Turbo Streams (turbo_stream.replace "chat-thread" + composer)
• Stimulus composer controller with proper lifecycle (disable-on-submit, reset, auto-scroll)

What changes for the user: nothing in quality, everything in cost/speed

This is worth logging. On synthetic capability benchmark, 5.5 and 5.4 tie. Same architectural shape delivered, same defensive patterns, same error rescue, same persistence. Side-by-side code review shows no material difference.

Where 5.5 really wins is generation efficiency: 35% fewer total tokens, 54% fewer output tokens, 20% less time. For what used to cost $16/run on 5.4, you pay $10. On continuous use the savings compound.

It’s not a new capability generation. It’s cost optimization on top of architecture that was already at the top. For folks already on Codex, 5.5 replaces 5.4 with no regression. For folks who aren’t, at 15× (and now 10×) the cost of Opus for tied quality, it’s still hard to justify for continuous use.

Critical weakness: no significant defect on this run. Same shape as 5.4 at lower cost. The DI-injected pattern + real error class rescue + session cookie = best defensive patterns in the whole benchmark.

A caveat on price

The ~$16/run for GPT 5.4 and ~$10/run for GPT 5.5 in the table are direct API token costs (pay-as-you-go). In April 2026, OpenAI switched Codex to use the same API token accounting inside the Plus, Pro, Business and Enterprise subscriptions. In practice, most Codex CLI users access it via ChatGPT Plus ($20/mo) or Pro ($200/mo), where Codex usage falls under the subscription quota (Pro gets 20× Plus’s limit). For a Pro subscriber already paying $200/month, a benchmark run adds no marginal cost until they saturate their monthly quota.

So “GPT 5.4 is the most expensive in the ranking” is true under pay-as-you-go and changes under subscription. Anyone already on Pro for everything probably isn’t thinking of this in “cost per run” terms. That said, in terms of tokens spent per delivered quality, 5.5 is simply more efficient than 5.4. Even inside the subscription it burns 35% less of the quota.

DeepSeek: the overhype pattern

Every DeepSeek generation ships with heavy marketing (“competitive with Claude Opus”) and ends with the same pattern: tool support lags behind.

V4 Pro: clean code in snippet, harness incompatible in opencode

The RubyLLM snippet it produces, in isolation, is Tier A quality:

def initialize
  @chat = RubyLLM.chat
  @messages = []
end

def ask(content)
  result = @chat.ask(content)
  @messages << Message.new(role: "user", content: content)
  @messages << Message.new(role: "assistant", content: result.content)
end

Persistent @chat instance, delegates multi-turn to RubyLLM. Correct pattern.

In opencode, V4 Pro hits a protocol incompatibility. The model uses thinking mode by default and returns reasoning_content on every response. The DeepSeek API requires the client to echo that reasoning_content back in the next request’s message history, or it answers 400 with "reasoning_content must be passed back to the API". The ai-sdk that opencode uses underneath strips that field while building the next request. Every multi-turn call to V4 Pro via opencode fails on turn 2.

What makes this treacherous: opencode doesn’t surface that 400 to the user. It buries the error in the event stream and falls back to the general fallback agent — which is Opus 4.7. The run “completes,” files get written, tasks get marked ok. But if you inspect the trace, you discover that most of the files were written by Opus, not by DeepSeek. The half-baked deliverables that drag the score down (stock README, no docker-compose.yml, missing bundle-audit) are output from Opus in fallback mode acting without the main agent’s context. The 69/100 score on the old record reflects mixed authorship, not V4 Pro for real.

This isn’t opencode-specific. Any ai-sdk-based harness has the same bug, because the SDK is the one that strips reasoning_content.

V4 Pro unblocked: DeepClaude delivers Tier A at 89/100

In May I ran Round 4 of the orchestration benchmark and found a way to actually measure V4 Pro. There’s a shell shim called DeepClaude that swaps the endpoint Claude Code talks to. Instead of hitting api.anthropic.com, Claude Code now calls openrouter.ai/api/anthropic, which is OpenRouter’s Anthropic-compatible route. That route handles thinking content correctly in the format Claude Code emits (opencode’s ai-sdk doesn’t). The result: Claude Code’s full autonomous loop runs on top of DeepSeek V4 Pro with no protocol bug.

Numbers from the two variants I ran:

The 15-20 point lift over the opencode result is purely a harness-change effect. Same model, same prompt, no new orchestration, just a different agent loop. And the variant with Sonnet registered but never invoked scored +5 over its sister with no subagent. Mere availability of a delegate made the DeepSeek planner decompose better (smaller seams, cleaner DI, system prompt via with_instructions). Full technical details in the dedicated post.

Where this leaves V4 Pro:

• In opencode (and any ai-sdk): unmeasurable. What I wrote above still applies.
• In Claude Code with DeepClaude: Tier A at 89/100, $3.14 in 18 minutes.
• In Claude Code direct against the Anthropic API with DEEPSEEK_API_KEY: not tested, but the native route also handles thinking content properly.

For anyone without an Anthropic subscription who wants Tier A coding, the DeepClaude variant running entirely on OPENROUTER_API_KEY is the first real answer the benchmark has produced.

This is the pattern that shows up every time DeepSeek ships: tool support lags. The community takes weeks to figure out integration, the thinking-mode protocol is more complex at runtime, and support in open-source tooling accumulates gaps the provider doesn’t fix. If you need a production pipeline today that integrates DeepSeek, you’ll probably have to maintain your own patches — or use DeepClaude.

V4 Flash: cheapest viable option (78/100 Tier B)

$0.01/run, 2m 35s, fixes V3.2’s critical bug (invented RubyLLM::Client class). API all correct (now that I know add_message(role:, content:) is valid). Session-replay multi-turn via session[:messages]. WebMock tests the real OpenRouter endpoint and exercises the LLM path. All of this pushes it to 78/100 Tier B.

Gotcha: the model slug is "claude-sonnet-4" missing the anthropic/ prefix. 404 at OpenRouter at runtime. One-character fix, but fatal if you deploy blind.

At Tier B, $0.01/run, V4 Flash is the cheapest model that gets close to “code that works with one manual patch”.

V4 vs V3.2: real generational upgrade

V4 Flash is the cheap option that works. V4 Pro needs DeepClaude (Claude Code with env vars pointed at OpenRouter) to deliver its full potential; in opencode it stays unmeasurable.

Kimi: K2.5 → K2.6

K2.6 (87/100, Tier A)

Positive surprise. Only non-Western model at Tier A. Textbook code:

chat = RubyLLM.chat
chat.with_instructions(SYSTEM_INSTRUCTION)
historical_messages.each do |msg|
  chat.add_message(role: msg[:role], content: msg[:content])
end
response = chat.ask(user_message)
response.content

Unique combination among Chinese models: FakeChat matching real API, rescue of RubyLLM::Error (with flash via turbo_stream), session cookie with MAX_MESSAGES = 50 cap. Complete Gemfile. Multi-worker safe.

Only deduction is the full history replay on each turn (uses more tokens than MiMo’s persistent pattern).

At $0.30/run, Kimi K2.6 is the cheapest Tier A in the benchmark. 3 to 50× cheaper than Opus 4.7 and GPT 5.4 xHigh.

K2.5 (69/100 Tier B, not Tier 3 as I had claimed)

In the first version I cataloged K2.5 as Tier 3 for supposedly inventing chat.complete and using kwargs in add_message. Both are real public API. K2.5 comes back to Tier B.

It drops from K2.6 to K2.5 because: 37 tests (most in the benchmark) never mock RubyLLM. They only test PORO CRUD and respond_to?. Test coverage without mock fidelity measures nothing. And it uses class-var storage (Chat.storage = @storage ||= {}), worse than Singleton because there’s no mutex.

K2.6 adds what K2.5 didn’t have: FakeChat with the right signature, rescue, session cookie. Real evolution in the dimensions that matter.

Xiaomi MiMo V2.5 Pro: looked like Tier 1, but the gaps are real

MiMo V2.5 Pro (April 2026) generated the most hype of this round. In the first analysis I promoted it as “first non-Anthropic Tier 1”. After the new rubric, it drops to Tier B (67/100).

RubyLLM code is still clean:

@llm_chat = RubyLLM::Chat.new(model: MODEL, provider: PROVIDER)
response = @llm_chat.ask(content, &)
@messages << { role: :assistant, content: response.content }

Chat.new(model:, provider:) is a valid public constructor. .ask(content, &) forwards a streaming block. Zero manual add_message calls. Multi-turn delegated to RubyLLM itself. It’s the cleanest pattern any model in this benchmark produced.

But the holistic score = 67 because the other components have gaps:

• Tests don’t exercise the LLM path. The 21 tests only check constants and blank guards. ChatSessionTest has no happy-path test. If the LLM call worked or silently failed, no test would catch it.
• No error handling. No rescue around @chat.ask. Rate limit becomes 500 with stack trace on screen.
• ChatStore Singleton is process-local. Dies on Puma restart, doesn’t work with WEB_CONCURRENCY > 1, no TTL.
• No with_instructions, the model doesn’t know its role.

Around those four gaps are smaller ones: Docker without healthcheck, no restart: unless-stopped, no Thruster (Rails 8.1 default), short README.

Genuine advantage: idiomatic use of the library. For a greenfield single-worker app, it’s less code with the same functionality. Opus’s manual replay pattern is actually more defensive than the library itself recommends.

At $0.14/run in 11 minutes, it’s 8× cheaper and faster than Opus. For throwaway prototypes, it’s genuinely useful.

Verdict: MiMo is ~70% of Opus quality at 12.5% of the price. For throwaway prototype, worth it. For production, ~2 engineer-hours adding rescue + Rails.cache + FakeChat + WebMock + system prompt. At that point Opus at $1.10 comes out cheaper overall.

Gemini 3.1 Pro: the quiet surprise (82/100 Tier A)

I had classified it as Tier 3. Re-audit showed Chat.new and add_message kwargs form are real API.

Strong points: real Turbo Streams (not fetch + innerHTML), Rails.cache-backed persistence with 2h expiry, FakeChat mocks matching the real API, error path tested.

Critical weakness: it uses the model string claude-3.7-sonnet instead of the current Sonnet 4.x. One-character fix.

At $0.40/run, Gemini 3.1 Pro is the other cost-effective Tier A alongside Kimi K2.6.

Qwen family: distillation doesn’t save you

Tested several Qwens:

The discovery: Claude distillation doesn’t transfer library knowledge

I ran Jackrong’s Qwen 3.5 27B distilled from Claude 4.6 Opus. The promise was “Claude-at-home” running locally. The result: the code comes out Claude-styled (frozen_string_literal, Response value objects, layered architecture, doc comments), but functionally it’s full-blown hallucination:

RubyLLM::Chat.new.with_model(@model) do |chat|
  conversation_history.each do |msg|
    chat.add_message(role: :user, content: msg[:content])
  end
  response = chat.ask(message)
  Response.new(content: response.text, usage: build_usage(response))
end

The issue here is the invented block form .with_model(@model) do |chat| ... end (doesn’t exist in the gem), and response.text instead of the real response.content.

Distillation transferred the style and stopped there. Factual memory about a specific library is binary recall: it’s either in the weights or not. Claude’s reasoning traces don’t contain repetitions like “use ask, not complete” because that’s not reasoning, it’s raw memory.

If you need the model to actually use RubyLLM or any less popular library, Claude distillation won’t save you. Use actual Claude or a large cloud model.

Coder vs General: the inverse surprise

Intuitively, models with “Coder” in the name should be better for programming. In this benchmark, the opposite happened. Of the three Qwen Coders tested:

• Qwen 3 Coder 30B returned a hardcoded mock string instead of calling RubyLLM
• Qwen 2.5 Coder 32B timed out at 90 minutes with zero files
• Qwen 3.5 27B Sushi Coder RL had infra failure

Meanwhile the general Qwen 3.5 35B-A3B completed in 5 minutes with a recognizable Rails project. My reading: the “Coders” were fine-tuned on isolated problems (Codeforces, Leetcode, short snippets), far from the long-running agentic flows with tool calling. “Coder = better for coding agent” is false for this kind of task.

Qwen 3.6 Plus: the cloud that almost arrived

Qwen 3.6 Plus on OpenRouter completed the benchmark in 17 minutes and is the cleanest Qwen I’ve measured (71/100 Tier B). Correct RubyLLM API. Well-built Stimulus controller. But tests make real calls to OpenRouter (no WebMock), and history is client-side JS only (lost on refresh). Uses fetch + innerHTML instead of Turbo Streams.

GLM family: 5, 5.1, local 4.7 Flash

GLM 5 (64/100 Tier B)

RubyLLM.chat(model: "anthropic/claude-sonnet-4") + chat.ask + response.content correct. Mocha stubs match the real API. One happy-path test, no error-path coverage.

Critical weakness: zero multi-turn state. Every POST creates a fresh RubyLLM.chat without history. The “chat app” is a stateless echo service. “What did I just say?” → “I don’t know.”

GLM 5.1 (46/100 Tier C, dropped)

This is the most painful fall from the re-audit. RubyLLM.chat(model:, provider:) is correct, but history is replayed via c.user(msg) / c.assistant(msg), fluent DSL that doesn’t exist in RubyLLM (confirmed via grep of the gem source).

Worse: every HTTP request constructs a new ChatSession.new that discards history. The two bugs mask each other: the invented DSL rarely fires because there’s never any history to replay.

Stimulus controller uses fetch + manual innerHTML. SSE-based but not Turbo Streams.

Per Z.ai itself, GLM 5.1 beats GPT 5.4 and Opus 4.6 on SWE-Bench Pro. In this specific benchmark (Rails + RubyLLM + complete deliverables), it drops to Tier C. More evidence that benchmarks are specific.

GLM 4.7 Flash bf16 local (52/100 Tier C)

The local model that most dominates the RubyLLM API. Uses the fluent chain .with_model().with_temperature().with_params().with_instructions().complete(&block), all real API per gem source.

Fatal bug: gem "ruby_llm" is in group :development, :test with require: false. Doesn’t load in production. NameError at boot. Uses class-var Message.all (process-local).

Grok: from Tier D to Tier B (4.20 → 4.3)

Grok 4.3 entered the benchmark in May 2026 and deserves a separate section, because it’s the biggest intra-family jump in the whole benchmark. Grok 4.20 scored 25/100 Tier D (still listed in the losers section right below). Grok 4.3 scores 72/100 Tier B, ranking between Qwen 3.6 Plus (71) and Kimi K2.5 (69). 47 points of jump. Cost $1.74 per run (15m wall time, 1.0M input + 18K output + 2.2M cache_read tokens, 102 step finishes).

What it does well, and does well:

• Correct RubyLLM API on all five calls: RubyLLM::Chat.new(model:) + add_message(role:, content:) + chat.ask + response.content + RubyLLM::Error rescue. Verified against the gem 1.14.1 source, no hallucinations. Counter-grep zeroed: grep -nE "RubyLLM::Client|chat\.complete|chat\.send_message|chat\.user|chat\.assistant" returns 0 hits.
• Cleanest controller in the benchmark: 48 lines, no service-object over-engineering, no invented fluent DSL.
• Real Turbo Streams: the server-side reactive parts work.
• Material deliverables: real README, real compose.yaml, working multi-stage Dockerfile, cookie-based session persistence.

The killer weakness is awkward to describe: Stimulus is dead at runtime. The app/javascript/application.js is a one-liner comment, no import "./controllers", no Application.start(). The compiled app/assets/builds/application.js weighs 48 bytes (just a sourcemap pointer). The controllers/index.js imports ./application, which doesn’t exist. Result: every data-controller="chat" is inert. Enter-to-send, autoresize, autoscroll, clear-input — all silently broken. Phase 2 of the benchmark (boot validation) reported “local boot OK” without exercising the JS layer, so the gap slipped through.

Other smaller issues:

• Tests stub RubyLLM.stub :chat but the controller calls RubyLLM::Chat.new. The stub is bypassed, so the test either hits the network for real or fails for missing key.
• Stale model pin: anthropic/claude-3.7-sonnet in code, README says “latest Claude Sonnet” (current is 4.7).
• No with_instructions for system prompt.

The direct cost comparison is unfavorable: $1.74/run for Grok 4.3 vs $0.30/run for Kimi K2.6 (Tier A, 87/100). That’s 5× more expensive for a worse result. Grok 4.3 sits in an awkward price/quality slot: good enough for Tier B, but in Tier B there are options 5× cheaper (Kimi K2.5 at $0.10) and in Tier A there are options at almost the same price (Kimi K2.6 at $0.30). xAI still has to find the lane where Grok makes economic sense.

The general read: Grok 4.3 shows the family materially improved generation over generation (47 points is a huge jump). But it hasn’t reached the level of the models that dominate the top yet. Worth keeping an eye on the next generation.

The losers (Tier C/D): MiniMax, Grok 4.20, Step, DeepSeek V3.2, GPT OSS

Models that didn’t complete the benchmark

The ranking above lists the 24 models that completed the benchmark enough to be audited. But the benchmark covers more than that. In total, 34+ were configured, 28+ ran, and only 17-24 (depending on the criterion) completed enough to become auditable code. The ones that failed deserve to be logged:

Also tested but didn’t make the final comparison for various reasons: Qwen 3.5 27B Claude-distilled (covered in the Qwen section as an example of distillation not transferring library knowledge), Qwen 3 Coder 30B (returned a hardcoded mock string instead of calling RubyLLM), Qwen 3.5 27B Sushi Coder RL (llama-swap infra failure), Qwen 3.6 35B local (best Qwen local result, but missing .content on the return, 1-line fix to work).

Practical lesson from these failures: half the challenge of running open source locally in 2026 lives in the toolchain. llama.cpp bugs, Ollama lifecycle, missing tool-call parsers, Ollama Cloud Cloudflare timeouts. Even if the model is good, if the stack that runs it hangs every 11 tool calls, in practice you can’t use it.

The Chinese situation: the gap in practice

The benchmark covers essentially every Chinese LLM family with recent releases: Moonshot (Kimi), DeepSeek, Xiaomi (MiMo), Alibaba (Qwen), Z.ai (GLM), MiniMax and StepFun (Step). Worth consolidating the whole picture, because the “China has caught up” narrative is more optimistic than this benchmark sustains.

Distribution by tier

• Tier A (80+): Kimi K2.6 (87) and DeepSeek V4 Pro via DeepClaude (89, with the caveat that it requires a custom harness).
• Tier B (60-79): Kimi K2.5 (69), DeepSeek V4 Flash (78), Xiaomi MiMo V2.5 Pro (67), Qwen 3.6 Plus (71), GLM 5 (64). DeepSeek V4 Pro in opencode scored 69 but with mixed authorship (reroute to Opus fallback), so unmeasurable in that harness.
• Tier C (40-59): Step 3.5 Flash (56), GLM 4.7 Flash local (52), GLM 5.1 (46), DeepSeek V3.2 (43), MiniMax M2.7 (41).
• Tier D (<40): Qwen 3.5 122B local (37), Qwen 3 Coder Next local (32).

Out of 13 Chinese models tested (counting both local and cloud), two reach Tier A: Kimi K2.6 with no caveats and DeepSeek V4 Pro only through DeepClaude. That’s the current penetration in this specific benchmark.

The gap in points

Kimi K2.6 vs Opus 4.7 (Tier A vs Tier A): 87 vs 97. 10-point gap. In practice, both deliver correct RubyLLM, real-signature FakeChat, error rescue, multi-worker-safe session cookie, complete Gemfile. What Opus 4.7 has extra are secondary dimensions that accumulate: tests that cover error wrapping, model/provider override and explicit system prompt application; redundant rescue in the controller beyond the service; slightly better concerns separation. Perceptible differences side by side, but not tier-separated.

Cost: K2.6 $0.30/run vs Opus 4.7 $1.10/run. 3.6× cheaper. In continuous production runs, that difference accumulates.

Chinese Tier B vs Claude Opus 4.6 (83 Tier A): 5 to 20-point gap. The Chinese Tier B models (MiMo, DeepSeek V4 Flash, Kimi K2.5, Qwen 3.6 Plus, GLM 5) have correct or near-correct RubyLLM code, but fail on specific components:

• Test quality is the universal weakest spot. Chinese Tier B models often write many tests (K2.5 wrote 37, the most in the benchmark) but don’t mock RubyLLM. Coverage theater.
• Persistence frequently uses process-local Singleton (MiMo) or class-var (K2.5) instead of session cookie or Rails.cache. Dies on restart, not multi-worker safe.
• Error handling is usually absent. Rate limit becomes 500 with a stack trace visible to the user.

Patterns by family

Moonshot (Kimi): the most disciplined Chinese family. K2.5 at Tier B and K2.6 at Tier A. Real generational evolution in the dimensions that matter (tests, rescue, persistence).

DeepSeek: pattern of tool support lagging. Each generation has better RubyLLM code than the previous (V3.2 invented everything, V4 Flash writes correct, V4 Pro writes perfect). In ai-sdk harnesses (opencode included), V4 Pro stays incompatible because of the reasoning_content echo protocol. But via DeepClaude (Claude Code with env vars swapping the endpoint), the same model delivers Tier A at 89/100. The marketing matches the product, as long as you use the right harness.

Xiaomi (MiMo): writes the most idiomatic RubyLLM code in the benchmark (persistent @chat, zero manual add_message). But forgets real tests, rescue, robust persistence. Lands at Tier B with prototype-demo quality, not production.

Alibaba (Qwen): high variance. Qwen 3.6 Plus cloud reaches Tier B. Qwen 3.5 35B local at Tier C with patches. Qwen 3.5 122B and the “Coders” (Qwen 3 Coder Next, Qwen 2.5 Coder 32B) fall to Tier D for inventing API or hanging. “Coder” in the name isn’t a guarantee for coding agent.

Z.ai (GLM): GLM 5 at reasonable Tier B. GLM 5.1 regressed to Tier C, with invented fluent DSL plus history discard. Z.ai claims superiority in SWE-Bench Pro, but this specific benchmark caught two structural bugs. GLM 4.7 Flash local gets close but the gem in the :test group kills it in production.

MiniMax and StepFun (Step) don’t deliver. MiniMax invented a batch signature that crashes on first call. Step bypasses the ruby_llm gem entirely with Net::HTTP, violating the prompt.

Conclusion on the Chinese gap

For this specific benchmark (Rails + RubyLLM + complete deliverables):

• Two Chinese models deliver Tier A: Kimi K2.6 (87/100, 10-point gap vs Opus, 3.6× cheaper) and DeepSeek V4 Pro (89/100 through DeepClaude — needs the custom harness, but fits within the budget of anyone who already has an OPENROUTER_API_KEY).
• Five Chinese models deliver Tier B usable with 1-2h of patching: K2.5, V4 Flash, MiMo, Qwen 3.6 Plus, GLM 5.
• The rest are not usable in production for this kind of task.

The narrative of “China has already caught up with the West in coding LLMs” needs to be read with caveats. On synthetic reasoning benchmarks, maybe. On the benchmark of delivering a complete Rails app with every part functional? Two models caught up, with the caveat that one of them (V4 Pro) only works in a non-default harness. The others are still a generation behind.

The reality of running open source locally

Every viable open source in the benchmark landed at Tier C or worse. Worth explaining why.

VRAM + KV Cache: the math nobody does

Take Qwen3 32B. FP16 takes ~64 GB. Quantized to Q4, it drops to ~19 GB. So it fits on a 32 GB RTX 5090, right? Wrong. That’s only the model weights. You’re missing the KV Cache.

KV Cache is the memory the model uses to “remember” what it already read. It scales linearly with context:

KV Memory = 2 × Layers × KV_Heads × Head_Dim × Bytes_per_Element × Context_Tokens

For a Llama 3.1 70B in BF16, that’s ~0.31 MB per token. A 128K-token context = 40 GB of KV Cache alone. In real benchmark runs, models consumed between 39K and 156K tokens. Less than 100K context isn’t practical for a coding agent.

Google published TurboQuant (ICLR 2026), which compresses KV Cache to 3 bits without accuracy loss, 6× reduction and up to 8× speedup. Not yet implemented in llama.cpp or Ollama.

Memory bandwidth rules, capacity doesn’t

“But I have 128 GB of RAM!” Nice, but what matters is memory bandwidth. Brutal differences:

RTX 5090 has 7× more bandwidth than my Minisforum’s LPDDR5x. On the AMD, Qwen3 32B runs at ~7 tok/s; on the 5090, it would be much faster if it fit.

For Mac Studio M4 Ultra with 512 GB of unified memory (~$10k), it’s practical but pricey. For AMD Ryzen AI Max with LPDDR5x 256 GB/s, it’s accessible but slow. For DDR4 desktop, it’s unviable.

Ollama vs llama.cpp: each with its own problems

Ollama failed 6 of 8 local benchmark attempts: mid-session model unloading, context drift, flaky lifecycle, broken bf16. I migrated to llama-swap (Go wrapper around llama-server). It fixed the lifecycle but brought other problems: each model needs specific flags (GLM/Qwen 3.5 need --reasoning-format none for <think> tags), tool-call parsers depend on the model (Llama 4’s pythonic format doesn’t parse), Gemma 4 requires build b8665+ and still enters repetition loops after ~11 tool calls.

Plug-and-play it isn’t.

The harness also matters

The same Opus 4.7 model produced measurably worse code on Claude Code than on opencode. The difference is harness context pollution. Claude Code uses 6-11M cache-read tokens per run (vs ~210K on opencode) and that nudges the model toward generic patterns like the OpenAI SDK instead of RubyLLM-specific.

Practical translation: even with the same model, the tool you invoke it through changes the output. For stable model testing, I ran everything on opencode.

Multi-model isn’t worth it for greenfield coding

Question that shows up every week in my feed: is it worth configuring two models in the same project? Opus for planning, GLM for executing, Haiku for boilerplate? I tested 7 combinations across 3 harnesses:

• Claude Code: Opus 4.7 alone (baseline), Opus 4.7 + Sonnet 4.6 subagent, Opus 4.7 + Haiku 4.5 subagent
• opencode: Opus 4.7 + GLM 5.1 subagent, Opus 4.7 + Qwen 3.6 local subagent
• Codex: GPT 5.4 xHigh + GPT 5.4 medium, GPT 5.4 xHigh + GPT 5.4 low

Zero of the 7 runs voluntarily delegated to the subagent. The main model did 100% of the work alone in every case, even with the subagent declared with aggressive language like “Use PROACTIVELY” and “ALWAYS delegate to this agent for code implementation”. Three reasons:

Reason 1: Tier A models already plan-then-execute internally

Opus 4.7 and GPT 5.4 xHigh recognize when a task calls for planning + implementation and already do that within the same thought session, without external context switch. The “let’s split this into design + code” reasoning happens internally. Externalizing that with two separate models breaks the continuous context and gains nothing.

Reason 2: coordination costs are high

Subagents receive a reduced prompt, partial context, and have to return structured output the main model consumes. All that back-and-forth adds tokens, latency, and opportunities for misalignment. The main model prefers to absorb the cost of doing it alone rather than pay the cost of coordinating with another model. This is rational: economically, the subagent would only pay off if it were much cheaper AND produced equivalent output. Usually it’s cheaper but worse.

Reason 3: there’s no clean plan-vs-execute line in greenfield

On a Rails app from scratch, you plan while implementing, revise decisions when you hit concrete problems, rebalance trade-offs along the way. Splitting that artificially between two agents forces a separation that doesn’t reflect how the work actually happens on a cohesive task.

The “Opus plans, Qwen executes” case

The worst combination was Opus + Qwen 3.6 local. Opus is Tier A on RubyLLM, Qwen is Tier C. The theory: Opus (expensive) plans, Qwen (free) executes. In practice:

1. Opus didn’t delegate. It did everything alone.
2. If it had delegated, the Qwen code would come out Qwen-quality (invents API, no correct mocks).
3. Opus ↔ Qwen coordination isn’t free.

Three false assumptions in the theory. Practical conclusion: if you’re going to pay Opus to plan, let it do everything. That’s what it wants to do naturally. Forcing delegation to an inferior model adds coordination without reducing cost and makes the result worse.

When multi-model does make sense

Not on a cohesive greenfield task. It makes sense on separate pipelines where each model has a well-defined scope: fast classifier filtering input, large model processing only the subset that passed the filter, small model translating output. That’s not “Opus plans Qwen executes” in the same agent session, it’s multi-service architecture with different APIs.

For interactive coding agent on a real project, the rule of thumb is: pick one good Tier A model, use it alone, optimize the prompt instead of the orchestration.

Best commercial, best open source

Commercial

Tier A premium: Claude Opus 4.7, GPT 5.4 xHigh (Codex), GPT 5.5 xHigh (Codex), Claude Opus 4.6. Pick by behavior preference; code quality is there on all of them. Among the GPTs, 5.5 costs 40% less than 5.4 at the same output.

Tier A cost-effective: Kimi K2.6 ($0.30/run), Gemini 3.1 Pro ($0.40/run). 3-4× cheaper than Opus/GPT with comparable quality within this benchmark.

Tolerable Tier B: Claude Sonnet 4.6 ($0.63), DeepSeek V4 Flash ($0.01), Xiaomi MiMo V2.5 Pro ($0.14). Needs 1-2h of patching to ship to production.

Cheapest useful: DeepSeek V4 Flash ($0.01/run) with the anthropic/ prefix fix on the model slug.

Open source (local)

No Tier A. The best local that ran was Qwen 3.5 35B-A3B at Tier C (55/100), and it needs 1-2 correction prompts to deliver working code. For those with an RTX 5090 who want to escape vendor lock-in, that’s the model to run, but with hobby/lab expectations, not production.

Qwen 3.6 35B local is the closest to working I’ve seen (1-line fix to add .content), but still without multi-turn.

GLM 4.7 Flash local is the most RubyLLM-literate local, but the gem in the wrong group kills the app in production. Trivial fix, structural impediment.

In 2026, running open source locally for coding agent is viable with caution, on high-end hardware (RTX 5090 or Mac M4 Ultra), accepting 1-3 corrections per run. It’s not a substitute for Claude yet.

Conclusion

Claude Opus 4.6 is still my daily pick for coding agent on real projects. Predictable behavior, defensive code, real mocks, sensible persistence, error handling.

Opus 4.7 leads the objective benchmark (97/100) but has a behavior downgrade (heavier tokenizer, aggressive resource optimization). On benchmark it delivers. In daily use I prefer 4.6.

GPT 5.4 xHigh via Codex ties at the top (97/100), and GPT 5.5 xHigh landed third at 96/100: same quality as 5.4, but 40% cheaper and 20% faster. For anyone already on Codex, 5.5 replaces 5.4 with no regression. At 10× Opus’s price (used to be 15×) for essentially tied quality, it’s still pricey for continuous use.

The cost-effective sweet spot now is Kimi K2.6 at $0.30/run or Gemini 3.1 Pro at $0.40/run. Both Tier A. 3-4× cheaper than Opus.

Local open source hasn’t reached Tier A yet. The best is Qwen 3.5 35B-A3B at Tier C with corrections. For experimentation, worth it. For production, not yet.

The biggest lesson from the re-audit is about process: when you start classifying models based on “hallucinations” you think you found, go to the library source and check directly. I was discarding models for valid API calls. Once I checked against the gem, Kimi, Gemini, DeepSeek V4 Flash and GPT 5.4 all improved. And once the criterion included deliverables (docker-compose, substantive README, bundle-audit), models that looked clean but delivered incomplete projects (Step 3.5 Flash via bypass) fell to the tier that reflected that. And the DeepSeek V4 Pro case showed that harness choice can be as decisive as the model: under opencode the run is mixed authorship (Opus fallback underneath) and unmeasurable; through DeepClaude the same model delivers Tier A.

Benchmark is a tool, not truth. What I test here is a specific Rails app with a specific library. Models may perform differently on other tasks. The methodology is explicit in audit_prompt_template.md for anyone who wants to replicate, adapt, or challenge it.

The repo is public with all the success_reports and diffs.

Sources

• Claude Opus 4.7 — What’s new, Anthropic
• Migration guide Claude 4.6 → 4.7, new tokenizer
• GitHub issue #52368 — Opus 4.7 instability
• DEV.to — Why We Switched Back from Opus 4.7 to 4.6
• OpenAI — Introducing GPT-5.5
• OpenAI Community — GPT-5.5 is here in Codex
• Simon Willison — GPT-5.5 via Codex
• GLM 5.1 benchmarks on OpenRouter
• GLM 5.1 review — Build Fast With AI
• Jackrong’s Qwen 3.5 27B Claude Opus Distilled
• TurboQuant (Google Research, ICLR 2026)
• Ahmad Osman — GPU Memory Math for LLMs (2026)
• llama-swap, llama.cpp wrapper
• llama.cpp issue #21375 — Gemma 4 tool call loops

Last week I posted about my distrobox-gaming setup, with more than ten retro racing games running on Linux, from Gran Turismo 1 on DuckStation to Forza Motorsport 4 on Xenia. At the end of that piece, I described Driveclub on shadPS4 as the “final boss”: the game boots, the menu loads, the race starts, the controller responds.

Except I mentioned two problems in passing and treated them as “accepted limitations”:

1. During daytime, the image is a bit darker than on a reference PS4. Not alarming, but noticeable.
2. At night, the race start in Canada or Munnar went pitch black for 10 to 30 seconds before the game “recovered on its own” around the 1:30 mark. During those seconds, only the HUD was visible. Track, car, headlights — all absolute black.

In the previous article I pushed the explanation to “it’s just not fixed in the emulator yet, I’ll live with it”. But inside I couldn’t make myself play the game in a visually unplayable state. I wanted to play DriveClub at its best, and I didn’t want to sit around waiting for the project to fix it for me. I decided to take matters into my own hands. Thirty seconds of absolute black isn’t “a bit darker”. It’s a serious bug, the kind that makes a game unplayable in practice.

This article is what happened between Sunday night and Thursday morning.

The blackout, live

This video is the behavior I wanted to fix. Race start in India (Munnar), night race. You see the track, headlights turn on, the first few seconds run. Then it darkens progressively. Within about 15 seconds everything is black. Stays that way for another 60-90 seconds. Then the game “recalibrates” on its own and the track reappears.

If you’re a player, you don’t care why. You just want to drive.

Why shadPS4 is hard to debug

shadPS4 still has no stable release. The project is under active development. The main branch changes several times a week, configs migrate from TOML to JSON without notice, settings hide behind “Advanced” so users with incompatible hardware don’t file issues, open PRs compete over different approaches to the same problem.

Anyone trying to configure DriveClub today will find:

• September/2025 Reddit guides using readbacks = true (it was a boolean back then) saying “for DriveClub always enable readbacks”.
• November/2025 guides saying “disable readbacks, it kills performance” (because in 2025-07 readbacks became an enum Disabled | Relaxed | Precise with different performance profiles, and Bloodborne started hanging with it on).
• January/2026 YouTube videos using some custom fork nobody documented.
• A thread on shadps4.net with three different, mutually exclusive explanations for the blackout.
• My own notes from last week in distrobox-gaming/docs/driveclub-shadps4.md saying readbacks_mode: 0. The exact opposite of what I found this week.

So the information exists, but it’s scattered, dated, contradictory, and most of it depends on version details that changed between the original post and today. Reproducing a setup from a YouTube video is like trying to solve a Rubik’s cube blindfolded.

Spoiler: the solution is one integer

After 31 phases of investigation, 44 commits on my shadPS4 fork, 15,668 lines of instrumental code added, and three days of nearly uninterrupted debugging, the answer is one line in the per-game config:

{
  "GPU": {
    "readbacks_mode": 2
  }
}

readbacks_mode: 2 is the Precise mode. Explaining what it does requires understanding how DriveClub implements auto-exposure, and that’s where the journey starts. To know WHY this toggle fixes things, you have to understand the whole chain.

The short version: DriveClub implements auto-exposure as a GPU→CPU feedback loop.

1. The scene renders to an HDR target.
2. A compute shader calculates a luminance histogram into an SSBO.
3. The CPU reads that SSBO on the next frame and derives a target exposure.
4. The CPU writes that exposure back into a 1936-byte lighting UBO (at slots [38] [48] [50]).
5. Fragment shaders read that UBO and multiply scene luminance by it.

Without readbacks_mode: Precise, step 3 reads stale zeros. The memory page where the GPU wrote the histogram is never synchronized to the CPU side. The CPU exposure integrator concludes “scene is dark, open the aperture all the way” and ramps its output value monotonically: 2.59 → 7.84 → 24 → 90 → 179 → 255. Within 60-90 seconds the scale saturates so high that everything clips to zero. That’s the pitch black.

With readbacks_mode: Precise on, the emulator marks the pages the GPU just wrote as kernel-protected (via mprotect on Linux). When the CPU tries to read one of those pages for the first time, a page fault fires. The emulator intercepts it, issues a vkCmdCopyBuffer download from the GPU buffer to the host staging area, waits on the scheduler, and the CPU finally sees fresh data. The real histogram enters the integrator, exposure converges normally, and the race start opens bright as it should.

Why isn’t it the default? Three documented reasons. First, per-page mprotect + per-fault GPU stall + compute dispatch + scheduler wait has a real cost: on NVIDIA’s warm path it’s tolerable, on AMD it tanks below 12 FPS, with an open issue about it. Second, Bloodborne hangs on loading screens with Precise enabled. Third, the maintainer tucked the option behind “Advanced” in the UI precisely to keep users with sensitive hardware from enabling it by mistake. The mode has existed since v0.15.0 (September/2025), but nobody had publicly connected Precise + DriveClub + auto-exposure feedback loop. The compat tracker already admits that DriveClub “requires readbacks enabled to function properly”, but doesn’t specify the mode.

In my setup the performance cost is irrelevant. I have an RTX 5090 on my desktop, plenty of hardware to swallow the mprotect, the page fault, the copy and the stall per frame. The call is trivial: I flip Precise on, pay the price, the game runs. On more modest hardware or on AMD the conversation is different, which is exactly why this setting isn’t default and hides behind “Advanced”.

One thing I want to make clear: this whole explanation above (Precise vs Relaxed vs Disabled, GPU→CPU feedback loop, per-page mprotect syscall) is not knowledge I had on Sunday night. I didn’t know what a buffer readback was, didn’t know DriveClub implemented auto-exposure as a GPU→CPU feedback loop, didn’t know readbacks_mode had become an enum in 2025 with three values. To arrive at the right answer, I had to learn every piece from scratch. I couldn’t guess. Had I tried to “enable readbacks” last week without understanding the chain, I’d have picked the wrong value (Relaxed isn’t enough for this feedback loop, as I’ll explain below) and given up thinking “it doesn’t work”.

Two more things need to be in place for this to work, both covered in the previous article:

• v1.28 patch applied on top of the v1.00 base install (without it, content stays locked with “not yet released”).
• 60fps XML patch disabled (it raises the render rate but the logic tickrate is fixed; with it on, the game runs in slow motion).

The result

Same race in Canada, night, with readbacks_mode: 2 on. Race start opens bright, auto-exposure converges immediately, the night transition unfolds naturally as the game’s TOD (time of day) advances. No blackout, no “recalibration” at 1:30, no 30-second window of absolute black. This is DriveClub running like it does on PS4.

Now the interesting question is not “which setting”. It’s: how did we get here?

How does a junior learn today?

There’s a question I hear often: “with AI doing everything, how does a junior learn?”

The premise is wrong. AI doesn’t do everything. AI does what you ask it to. It doesn’t discover on its own. It has no domain initiative. It’s not capable of telling you “hey, this looks like a broken GPU→CPU readback feedback loop” unless you already know there’s a thing called a readback and that broken feedback loops are a class of bug.

Worse: if you go to an AI agent today and ask “fix this black screen in DriveClub on shadPS4”, it will give you a list of possible answers based on old forum posts, with a high probability of steering you wrong. It will suggest the 60fps XML patch (wrong — causes slow motion). It will suggest a tonemap override (wrong — the game already writes correct SDR). It will suggest a vblank_frequency tweak (useless for the real problem). It will suggest manual gamma (treats the symptom, not the cause).

The way to discover is to dive into the chain, phase by phase, ruling out wrong hypotheses until the terrain is familiar enough that you recognize the right answer when it appears.

That’s where a lot of people misread me. “Akita is already a senior, he has 25+ years of experience, of course he knows.” False. A senior is someone who has been a junior in every topic they master. And they keep becoming a junior every time they pick up a new domain. I have 25 years of web programming, distributed systems, Ruby, Erlang, Go. But I’ve never programmed for PS4. I’d never looked at the shadPS4 codebase. I didn’t know PS4’s graphics architecture. On Sunday I was an absolute junior in this domain.

But junior doesn’t mean totally green. A while back I had explored on my YouTube channel the low-level architecture of older consoles (from the NES’s 6502 onward) and how emulators work internally in general. The two videos below helped build the basic vocabulary for how a game console works under the hood, and made sure I wouldn’t trip on concepts like fetch-decode-execute, opcode, interrupt, or HLE vs LLE.

I had also made an older video on the evolution of CPUs, GPUs, DirectX, and Vulkan, so at least the vocabulary of “modern graphics pipeline” and “shading language” wasn’t alien.

Knowing that VkCommandBuffer exists is very different from knowing where in shadPS4 a readback vkCmdCopyBuffer fires. But it gives you a base. That kind of old curiosity paid interest now.

The rotation: Claude Code and Codex

AI (in my case Claude Code) didn’t “know” more than I did. It has the same dated forum text you’d find on Reddit. What it did well was aggregate: read shadPS4 source code in parallel with me, index comments, cross-reference between phase docs, compile, run probes, parse 61 MB logs, compare decompiled binary against UBO diffs, shine light on corners of the system faster than I could alone.

But the decision to “keep investigating” was mine. The perseverance of “don’t accept a mitigation, want the root cause” was mine. And when the AI suggested “honestly, we should just accept the current result and document it” (and it suggested this several times over the four days), I was the one who had to say “no, we keep going”.

The central point about the rotation: no single LLM managed to close this problem alone.

Over the four days, Claude Code repeatedly got stuck looping on the same hypotheses with no new direction. When that happened, I’d switch to Codex for a few hours to bring in outside ideas, different probes, a re-read of the codebase from a fresh angle. Then back to Claude Code to integrate what Codex had surfaced. And so on, alternating.

The final resolution happened on Claude Code, but the journey switched models several times. Each LLM had its biases and blind spots. Left alone, each one would have given up sooner.

What broke the impasse was me continuing to bring in new ideas to try, forcing the model to reassess, switching models whenever one started to repeat itself.

At two points things went past “just repeating hypotheses”. Codex literally had an agentic-loop glitch: it started repeating the exact same “solution” it had just tried, over and over, in sequence, without noticing what it was doing. It was the first time I’d ever seen that happen in any AI agent. I had to kill the session and start a fresh one from zero to break the cycle.

That says something about context size and session duration. The complexity and pace of this investigation were enough to bring both LLMs to their knees, each in their own way.

The whole journey below is documented in 33 phase docs on the gamma-debug branch of my shadPS4 fork. Each section here links to the original doc for anyone who wants the complete detail. Here I summarize the essentials: the hypothesis we had, what we tried, what new concept we had to learn, and why the phase didn’t close the case.

Session zero: baseline and reproducibility

Every serious investigation starts before Phase 1. The first thing, for any project, is to make sure the baseline works as expected and that the situation you want to research is reproducible every time. If you can’t reproduce the bug on demand, you’re chasing ghosts. Every probe after that will be inconclusive because the bug “appeared and vanished” without control. And if the baseline is broken in some way you haven’t noticed, every experiment measures the wrong problem. Without those two guarantees, you can’t make progress.

In my case, on Sunday night I confirmed:

• The game boots all the way to the race screen without crashing, using the distrobox-gaming config.
• DriveClubFS extracts v1.28 cleanly, 8018 files, ~47 GB.
• MSAA depth resolve applied on the fork; night tracks render shapes instead of uniform absolute black (covered in the previous article).
• 8BitDo controller detected.
• Night race in India 19:30 reproduces the blackout on 100% of attempts, with the same temporal pattern: progressive fade in the first ~15s, pitch black between ~20s and ~90s, “recalibration” at 1:30.

That baseline is the only solid ground that lets me compare each experiment reliably. Without it, a probe that “worked” might just be a different cache state, not the real fix. With it, every change has a before and an after that are measurable.

Beyond that, zero specific knowledge of:

• PS4 PKG format (PFS, param.sfo, disc_info, keystone).
• shadPS4 codebase (src/core, src/video_core, shader_recompiler, buffer_cache).
• PS4 graphics pipeline (GCN ISA, forward+ lighting, MSAA depth resolve).
• Vulkan beyond the surface (descriptor sets, UBO binding, push constants, pipeline cache).
• SPIR-V disassembly and patching.
• PS4 OELF loader, Itanium RTTI, SCE dynamic relocations.
• mprotect-based page-fault tracking for CPU-GPU synchronization.

The journey, phase by phase

I’ll group the 30+ phases into buckets that make sense as a narrative. Each phase links to the full doc for anyone who wants technical detail.

Note for anyone who doesn’t want to read all 30+ phases: after the phase sequence there are reflection and methodology sections you can read on their own. The shotgun technique explains the debugging methodology I used throughout the investigation. What I knew on Sunday vs Thursday sums up what I actually learned. The AI suggested accepting. The perseverance was mine discusses AI’s real role in this process. The real cost of this journey catalogs what got produced. If you want to jump straight to the argument, those are the shortcuts.

Phase 01: pipeline cache, the warm-up

phase-01-shader-compile-stalls.md

• Hypothesis: menus run at 2-3 fps on first launch. Must be Vulkan pipeline compilation happening in real time.
• Action: enable pipeline_cache_enabled: true in the global config.
• New concept: Vulkan pipeline caching. When the emulator translates a PS4 GCN shader into SPIR-V and then into driver-specific Vulkan binary, it can cache that binary. Without the cache, it recompiles every cold launch (~864 shaders + ~590 pipelines).
• Outcome: solved. First session pays the cost; subsequent sessions read from disk and launch immediately. Easy. Also my first lesson about the shadPS4 codebase.

Phase 02: gamma dim, starting in the wrong direction

phase-02-gamma-dim-image.md

• Hypothesis: DriveClub’s image is dim compared to reference. Must be wrong sRGB encoding or an HDR tonemap applied badly by the emulator.
• Action: instrumented the swapchain to log format, added SHADPS4_PP_* env vars to experiment, built a post-processing pipeline with three knobs (exposure, ACES tonemap, gamma curve).
• New concept: sRGB OETF, HDR tonemap (ACES vs Reinhard), Bayer dither as anti-banding.
• Outcome: via bypass path (SHADPS4_PP_BYPASS=1, writes raw game output with no post-processing) I discovered the game writes correct SDR already into the framebuffer. The emulator’s post-processing pipeline was mangling the signal. Final shader became simply sRGB encode + Bayer dither. Dim persists, but it’s not a gamma problem.

Three hours on this phase. The most important lesson: when “the image looks wrong”, the first diagnostic should be a bypass path that shows raw game output. If bypass looks right, the emulator is the one mangling the signal. Stop touching the tonemap.

Phase 03: v1.28 content access

phase-03-v128-content-access.md

• Hypothesis: v1.28 extracts, but the game says “content not released yet, download required”.
• Action: merge v1.28 on top of v1.00, restore param.sfo, disc_info.dat, keystone.
• New concept: PS4 cumulative patches, package metadata.
• Outcome: solved. Detailed in the previous article.

Phase 04: MSAA depth + slow motion

phase-04-slowness.md

• Hypothesis: night tracks are pitch black and the game “feels slow”.
• Action: two separate things. Disable the 60fps XML patch (which was decoupling render rate from logic tickrate). Implement ReinterpretMsDepthAsColor on my fork (to let the emulator resolve 4x MSAA depth to 1-sample color, which DriveClub needs for forward+ lighting on night tracks).
• New concept: forward+ lighting (a renderer that writes the scene to an MSAA depth target and then reads it as color for SSAO and volumetrics), MSAA depth resolve.
• Outcome: both fixed. Detailed in the previous article.

Phase 05: second pass on brightness

phase-05-brightness-followup.md

• Hypothesis: since the game writes correct SDR, maybe a static boost in post-processing helps without touching the UBO feedback loop.
• Action: tried linear boost (1.5x, 2.0x), gamma pre-encode (pow curve), scene-aware auto-exposure with peak+mean sampling.
• Outcome: all rolled back. Linear boost clips highlights. Gamma introduces banding. My auto-exposure layer cancels the user’s manual brightness slider. There’s no free lunch in post-processing. Dim stays dim without real HDR or shader patches.

Narrowing the blackout: the shared gate

race-start-blackout-040420.md

• Hypothesis: the blackout has a curious signature. Main view goes dim/black, rearview mirror goes absolute black, HUD stays bright. Three layers with different behaviors suggest a shared “gate”, not a common fade.
• Action: instrumented texture-cache aliasing, probed with live fragment shader substitution on suspected inputs.
• New concept: texture-cache aliasing (multiple images sharing a memory address, which the emulator cache reuses), render-target lifetime.
• Outcome: points to a shared “presentation permission” between the main scene and the mirror, not a scripted fade.

Phases 07-09: texture torture, UI surgery, binary patch plan

phase-07-aggressive-torture-probe.md · phase-08-ui-asset-surgery.md · phase-09-eboot-binary-patch-plan.md

• Hypothesis: the race-start dim overlay is an asset. Small texture, UI panel, or a method of the FreeplayGetInCar controller in the eboot.
• Action: null-substituted BC-compressed materials, small texture candidates, four-vector weight masks during critical draws. Disabled UI panels (loading_freeplay.txt, get_in_car_animation.txt, vehicle_select_background). Extracted the OELF, located FreeplayGetInCar ASCII strings, identified the constructor at VA 0xf89b00 and the vtable at 0x15dc3e0.
• New concept: PS4 OELF loader (Sony’s variant of ELF), Itanium C++ RTTI (how C++ encodes type info in vtables), SCE dynamic relocations (placeholders that only the dynamic loader resolves at runtime).
• Outcome: nulls work but the fade persists. The overlay renders directly into HDR scene targets, not through the panel system. Binary patching has relocation placeholders that aren’t statically resolvable without a Ghidra + PS4 plugin. Asset-side surface exhausted. Six hours of debugging, final conclusion: the bug lives in state, not in an asset.

Phase 10: rethink + animlib

phase-10a-rethink-040422.md · phase-10b-video-diagnostic-animlib.md

Tuesday morning. Sat down, rebooted mentally. New model: the blackout is a state-machine gate. It’s not “scene not ready”, it’s “permission transition”. The gate closes after the starting grid appears. Next probe: runtime dispatch trace, enough of the blind asset surgery.

In parallel: frame extraction from the recording at 10 Hz, cross-referenced against keyframes of the animation library (animlib) in india_posteffects.lvl. Found a smoking gun. The MasterBrightness track has keyframes 0.003 and 0.0007 (0.63% brightness) where the default would be 1.0. Animlib beats inline defaults every frame.

• New concept: animation library, keyframe encoding, binary float-scanning.

Video above: the process of probing the fade in real time.

Phase 11: multi-scalar patch

phase-11-multi-scalar-patch.md

• Hypothesis: patching MasterBrightness + AutoTargetLuminance + ManualAutoMix simultaneously will lift the blackout.
• Action: extended PatchAnimlibFloatValues to rewrite three scalars. Instrumented with SHADPS4_DC_DRAWLOG + SHADPS4_DC_UBOLOG.
• Outcome: the patch produces a real numeric lift (1.2 → 6.5 in 255, a 5×), but still sub-perceptual black. And the crucial finding: the mirror works normally after the patch. It’s not gated, just reflecting a dark scene. At least 285× of additional attenuation lives downstream of the scalars we can patch.

Phase 12: bisect closes the asset side

phase-12-bisect-closes-asset-side.md

• Hypothesis: one of the 60 accumulated patches broke the mirror independently from the blackout. Bisect.
• Action: binary bisect across 60 overlay files over 5 rounds.
• Outcome: x_live_lobby_pre_race.txt (rerouting loading-spinner transition from ZoomInAndFade to NoFade) was the mirror killer. Rolled back. Asset side completely closed. The driver lives in compiled code or post-process state, not in a game asset.

Asset sweeps 01-09 (consolidated)

asset-sweep-09-conclusions.md

In parallel with the phases above, I swept 12 RPK substitutions: FreeplayGetInCar page swaps, postfx edits in india_landscape_gui.rpk, globaldata RTT-only edits, prerace state-string rewrites. All clean misses. No asset family touches the blackout. Lesson: stop chasing by names; chase by state transitions.

Phase 13: UBO dump breakthrough

phase-13-ubo-dump-breakthrough.md

• Hypothesis: eye-adaptation feedback loop with stale input is the culprit. A luminance scalar growing without converging.
• Action: dump 128 bytes of UBO in hex during the race window across six hand-picked pipelines. Look for monotonically changing values.
• New concept: UBO (Uniform Buffer Object), a shared memory region the CPU writes and shaders read. Auto-exposure integrator, a classic eye-adaptation component that takes time to converge toward a target.
• Outcome: found it. UBO offset 3 climbs monotonically from 2.59 → 7.84 → 24 → 90 → 179 → 255 over 2 seconds. Textbook feedback loop with broken input. First real hit in 12 phases.

Phase 14: scene-pipeline UBOs are the read side

phase-14-scene-pipeline-ubos-wrong.md

• Hypothesis: clamping the climbing scalar will stop the blackout.
• Action: SHADPS4_DC_LUM_CLAMP=2.0 forces offset 3 to a fixed value during the race window.
• Outcome: the clamp fires 1093 times, blackout unchanged. Scene-pipeline UBOs consume the dim, they don’t produce it. The dim is upstream, in a fullscreen tonemap or post-fx compute.

Phases 15-16: runtime texture dump + mutation

phase-15-runtime-texture-dump.md · phase-16-runtime-texture-mutation.md

• Hypothesis: the blackout is a fullscreen texture composited over the scene.
• Action: SHADPS4_DC_TEX_DUMP=1 dumps every bound texture during the race window (1079 textures captured). Convert tiled format to PNG for visual triage. Then, deterministically mutate each texture via hash-based tint + InvalidateMemory to force re-upload.
• New concept: GCN tile format (Sony interleaves bytes a specific way for cache locality), texture de-swizzle, buffer cache invalidation.
• Outcome: 14 rounds of mutation (BC textures, float data, render targets, UI atlases, post-fx buffers, LUTs). Blackout unchanged across all of them. Texture content 100% ruled out as the source.

Phases 17-19: UBO smashing, push-constant smashing, compute dispatch probe

phase-17-ubo-batch-smashing.md · phase-18-push-constant-smashing.md · phase-19-compute-dispatch-probe.md

• Hypothesis: random-fill on UBOs, push constants, and compute input buffers can bracket and isolate the dim field without crashing.
• Action: SHADPS4_DC_UBO_SMASH=1, SHADPS4_DC_PC_SMASH=1, SHADPS4_DC_DISPATCH_SMASH=1 with cb-index and size filters.
• New concept: push constants (128 bytes of fast params the driver pushes straight into the pipeline, no descriptor), compute dispatches (fires compute shaders with a grid of threads), ud_regs (GCN user data registers — how shadPS4 maps user data to push constants).
• Outcome: safe brackets produce overlay bokeh + blinks, but the dim stays put. Wide brackets that reach the dim also hit matrices/transforms and crash. Random-fill is the wrong instrument. Needs diff methodology.

Phase 19b-c: dim-vs-lift dispatch diff

phase-19b-dim-vs-lift-diff.md · phase-19c-dispatch-draw-skip-null.md

• Hypothesis: compute dispatches that only fire during dim (and stop once it lifts) are part of the chain.
• Action: split the clean log into pre / dim / bright windows (via user wall-clock), count dispatch frequency per pipeline.
• Outcome: identified 8 compute pipelines (histogram 256→downsamples, tile-grid reductions, auto-exposure 1x1 scalars) that stop exactly when dim lifts. Shapes strongly suggest the eye-adaptation chain. First genuine diagnostic hit. Skip test on those 8 + 101 correlated draws: blackout unchanged. They’re downstream effects, not drivers.

Phase 20-21: tonemap inline, fragment → flip buffer

phase-20-shader-dump-tonemap-inline.md · phase-21-fragment-to-flip-buffer.md

• Hypothesis: the auto-exposure compute shader is broken, or the tonemap compute has the wrong math.
• Action: recompile all shaders, dump SPIR-V, disassemble the histogram auto-exposure. Patch its output to constant 1.0 and test.
• New concept: SPIR-V disassembly (Khronos intermediate format with readable assembly). Compute shader verification. Later, pipeline-to-shader mapping.
• Outcome: patch has no effect. Discovery: DriveClub has no separate tonemap pass. Scene geometry writes directly to the flip buffer, with exposure inline in material shaders. Each material shader bakes the dim scalar from a shared UBO. Pipeline cache wipe + SHADPS4_DC_PIPEMAP=1 dumps every pipeline→shader mapping. Filtering drawlog for pipelines writing to 0x5000900000 / 0x5000108000 (the actual swapchain buffers) yields 14 unique pipelines. None with Exp2/Log2 tonemap ops. Exposure is applied upstream.

Phase 22: tonemap compute identified

phase-22-tonemap-compute-identified.md

• Hypothesis: among the game’s 510 compute shaders, one has a tonemap signature (many Exp2/Log2).
• Action: automated scan, cross-reference with dispatchlog.
• Outcome: cs_0x2c918c06 is the strong candidate, with 8 Exp2 + 8 Log2, 5 SSBOs (scene params, TAA, bloom, camera, exposure), 11 images. Skip test on that specific pipeline: stops the blackout cycle, removes color grading, introduces temporal ghosting. That’s the final scene→swapchain tonemap path.

Phase 22+: tonemap patches → playable

phase-22plus-tonemap-compute-patches.md

• Hypothesis: two surgical SPIR-V edits (histogram no-op + tonemap exposure clamp/boost) make the game playable.
• Action: histogram patch to never update; tonemap patch to clamp exposure floor at 0.5 and boost blend by ×10. Both via SPIR-V patching + shader/patch/ drop-in.
• Outcome: playable! Dim shrinks from pitch black to mild. A real mitigation, not a root-cause fix. The fade curve still drags exposure, and each track needs per-threshold tuning.

Here the AI suggested stopping for the first time. “The game is playable, this is a decent mitigation, we should document and accept.” I pushed back: “it’s playable but it’s wrong. Don’t accept. We keep going.”

Phase 23: CPU-side exposure intercept

phase-23-cpu-exposure-intercept.md

• Hypothesis: clamping the exposure scalar at the tonemap compute’s BindBuffers point prevents over-dimming.
• Action: SHADPS4_DC_EXPOSURE_PIN=1 intercepts BindBuffers, overwrites exposure offsets with a clamp-min threshold, invalidates buffer_cache.
• New concept: CPU-GPU buffer binding (the moment when the CPU hands a descriptor to the GPU). Buffer cache invalidation (how the emulator keeps consistency between a buffer’s CPU-side and GPU-side state).
• Outcome: the scalar oscillates at race start, then climbs monotonically. Per-track tuning is needed. India wants 3.0, Canada blows out at the same threshold. A single-scalar solution doesn’t converge cross-track.

Phase 24: dim upstream of tonemap

phase-24-dim-upstream-of-tonemap.md

• Conclusion: after the whole probe chain (identity tonemap, exposure pin, compute skip), the dim is in the HDR target before the tonemap reads it. Three upstream suspects: (1) atmospheric scattering / volumetric fog, (2) reflection-probe / envmap update, (3) pre-tonemap exposure apply.
• New concept: atmospheric scattering (simulating how light travels through atmosphere, Rayleigh/Mie-style), volumetric fog (fog rendered as a froxel volume).
• Outcome: plan set. Frame-order dump, walk backwards from tonemap through the whole chain.

Phase 25: frame-order trace

phase-25-frameorder-trace.md

• Action: SHADPS4_DC_FRAMEORDER=<N> logs strict per-submit pipeline/shader chain over N submits during race window.
• New concept: frame-order reconstruction (listing every GPU submission in exact order), froxel volumetrics (frustum volume voxels — a 3D grid aligned to the camera’s frustum that stores light info).
• Outcome: three suspects: (A) half-res compute (60,34,1), probably SSAO; (B) progressive dispatches (256,1,1)→(2560,1,1)→(10240,1,1), froxel volumetric; (C) fullscreen apply-fog-to-HDR draw. Suspect B is the strongest fit (sunset best-fit, per-pixel non-uniform dim).

Phase 26: The UBO fade pin, the “aha moment”

phase-26-ubo-fade-pin.md

This is where everything changed.

• Hypothesis: a direct memory diff (bright vs dim vs recovered) identifies the exact bytes the game writes to control the blackout.
• Action: capture periodic UBO snapshots across visual state transitions. Diff three snapshots byte by byte. Look for fade signatures.
• New concept: state diff methodology. Instead of “which pass looks suspicious?”, ask “which bytes actually change with the visual state?”
• Outcome: breakthrough. Two UBOs control the fade: a 1936-byte one with slots [38/48/50] (light intensity) being multiplied by 0.094 (fade factor), and a 224-byte sun UBO with slot [50] dropping 97%. Pinning both: race start opens bright. TOD animation intact. Content-aware three-state lifecycle (idle → engaged → expired).

Wednesday night. Claude suggests stopping again. “We have the pin working, three-state lifecycle is robust, Canada + Munnar are running. This is upstream quality, we should PR and close it.” I insist: “there’s still residual dim on other tracks, it’s not closed. We keep going.”

Phase 28: pivot to emulator code

phase-28-pivot-to-emulator-code.md

• Realization: the residual dim in Canada dusk/night isn’t a wrong UBO value. It’s an emulator translation gap. The game runs correctly on a real PS4, so shadPS4 has some path that translates or synchronizes incorrectly.
• Action: ranked 5 candidate emulator bugs: HLE shader misidentification, image storage classification, layout transitions, IMAGE_STORE_MIP fallback, OpImageFetch LOD restriction.
• New concept: HLE (High-Level Emulation). Replacing complex PS4 OS functions with host-side implementations. Different from LLE (low-level) which emulates bit by bit. HLE is faster but can diverge from real behavior whenever the host implementation doesn’t cover every case.

Phase 29: calibrated state + recording harness

phase-29-calibrated-state.md

• Action: SHADPS4_DC_RECORD=1. Recording harness that dumps lighting UBOs periodically + cross-correlates with wall-clock screenshots.
• Outcome: important discovery. Slots [144..295] of the 1936-byte UBO (30+ fields) stay denormal/uninitialized for the first ~90 seconds of a race. At the 1:30 “auto-recalibration”, the game writes the real values. It’s not magic recovery, it’s the CPU finally writing values that should have been there since frame 1. On PS4 they’re ready before the first frame; on shadPS4 they’re delayed by 90s. Root cause lives in an emulator init gap.

Phase 30: UBO writer audit

phase-30-ubo-writer-audit.md

• Action: exhaustive audit of every path that writes into slot [38] of the 1936-byte UBO. 7 suspects ranked: (1) ObtainBuffer stream-copy race, (2) lazy RegionManager in memory_tracker, (3) histogram compute skip, (4) page-fault delayed invalidation, (5) readback gating, (6) buffer-coherency race, (7) push-constant.
• Status: audit incomplete. Before I could verify each suspect, Phase 31 short-circuited the whole thing.

Phase 31: readbacks_mode = Precise, the turning point

phase-31-readbacks-mode-fix.md

Thursday morning. Tired, thinking about suspect #5, readback gating. That one itched at me because it was the only one of the 7 writers that touched the timing of the read rather than the correctness of the write.

• Hypothesis: flipping readbacks_mode: 2 (Precise) in per-game config makes the feedback loop work by synchronizing the CPU’s read to fresh GPU output.
• Action: one edit in custom_configs/CUSA00003.json. Boot. Canada night.
• Outcome: race start opens bright. Auto-exposure converges normally. Zero blackout. Zero 1:30 recalibration. Night TOD natural.

Tested on Munnar. Same result. One integer. 31 phases. 44 commits. 15,668 lines. Answer: one integer in the config.

Why did this slip past 30 phases? The Phase 31 doc has the honest analysis:

1. Symptom disguise. Progressive darkening looks exactly like a broken tonemap, bad shader, or miscompiled exposure scalar. Every dump-driven probe found wrong values in the UBO, which is true but describes the downstream read, not the upstream gap.
2. readback_linear_images red herring. I tested that flag in Phase 29, saw no effect, and concluded “the readback surface is audited”. I forgot that flag is for image readbacks (linear images via TextureCache::DownloadImageMemory). The histogram SSBO is a buffer, a separate path.
3. Pinning making it worse, not better. Overwriting slots [38/48/50] looked promising but never converged. The game rewrote on top of the pin every frame. I interpreted that as “the pin mechanism lands too late in the pipeline”. I spent phases 27-29 moving the pin earlier. The real fix was to stop clobbering the GPU-side input the integrator reads.
4. Never audited the buffer readback path. The Phase 30 audit listed 7 writer candidates, but all of them were about the correctness of the write. None asked “what is the CPU reading, expecting the GPU to have filled?”

The shotgun technique

One thing I want to put on record: torture probes aren’t waste, they’re learning infrastructure. And the methodology behind them has a name: shotgun.

If you have a suspicion (say, “the dim comes from some texture”), the worst thing you can do is start investigating one texture at a time, in depth. DriveClub has 1079 bound textures during the race window. If a detailed triage on one texture takes 20 minutes, you spend three days on a single branch of that tree and still don’t know if the dim even comes from a texture. It might not be in the whole tree.

Shotgun fixes that. Instead of investigating one at a time, you fire at all of them simultaneously. Mutate every bound texture with a hash-based tint, force re-upload, run the game. In 30 seconds you know whether any of them affects the dim. If it does, the dim is texture-side and only then is it worth starting to narrow down. If nothing changes, congratulations: you just ruled out the entire “texture” category in 30 seconds. Switch categories, shotgun UBOs. No hit? Shotgun push constants. No hit? Shotgun compute dispatches. Keep going until something reacts.

Don’t start by narrowing down a tree that might be huge. You’ll spend weeks in irrelevant leaves. Shotgun the trunk first. See which branch reacts. Then go deep inside that branch.

That’s what I did, without knowing I was doing it, for the first 30 phases. 32 probe env vars (SHADPS4_DC_UBO_SMASH, SHADPS4_DC_PC_SMASH, SHADPS4_DC_DISPATCH_SMASH, SHADPS4_DC_TEX_NUKE_*, SHADPS4_DC_UBO_NUKE, and more). Random batches, hash-based tints, null substitutions. Most of them never pointed at the real fix. But every shotgun round ruled out an entire category of mental model. “Not texture.” “Not push-constant.” “Not those 8 compute pipelines.” “Not the UBO write side anywhere in that region.” Every ruling-out narrows the problem.

And while I was doing it, I was learning the system. Every smash that crashed told me “there’s a critical descriptor pointer here”. Every color tint that appeared told me “this UBO feeds that composition pass”. Every dispatch that fired differently between dim/bright showed me where the interesting boundary lives.

When you don’t know the system, shotgun probes are a map. You don’t use them to find the answer. You use them to learn the terrain.

What I knew on Sunday vs Thursday

Sunday: zero everything. All the areas below were black boxes to me.

Thursday:

• PS4 package format end-to-end (PKG → PFS → param.sfo → disc_info → keystone → npbind). How v1.28 cumulative patches layer on top of a v1.00 base install.
• shadPS4 architecture in outline: src/common, src/core (OS emulation, HLE libraries), src/shader_recompiler (GCN→SPIR-V), src/video_core (Vulkan renderer, buffer cache, texture cache, page manager).
• Full graphics pipeline: G-buffer → forward+ lighting (writes MSAA depth) → read depth as color for SSAO / volumetric froxel → post-fx compute → tonemap → composite → swapchain.
• UBO vs push constant vs descriptor set. When to use each.
• SPIR-V disassembly and re-assembly for surgical patching. How to identify a tonemap compute by its Exp2/Log2 signature.
• Forward+ lighting + MSAA depth resolve + how to implement ReinterpretMsDepthAsColor.
• shadPS4 buffer cache: MemoryTracker, RegionManager, FaultManager. How page faults turn into GPU→CPU sync.
• readbacks_mode: Disabled / Relaxed / Precise. What each tradeoff looks like. Why Relaxed isn’t enough for feedback loops (it only write-protects, not read-protects).
• PS4 OELF → Itanium RTTI → SCE relocation → dynamic linker reasoning, even without actually doing the binary patch (the plan is documented).

I didn’t become an expert in any of it. But I went from total outsider to reasonably oriented operator. And that jump, as I’ll argue below, was the single most valuable thing of the four days.

The AI suggested accepting. The perseverance was mine

I’ve said a few times in this article that “Claude suggested stopping”. I want to be fair and specific: it wasn’t an AI failure. It was exactly the correct behavior of an intelligent tool: when you have something that works reasonably well, stopping and documenting is frequently the right call. The Phase 22+ tonemap patch made the game playable. The Phase 26 UBO pin made the image pretty. The Phase 29 recording harness covered the critical window. All were legitimate stopping points.

If you read codex-conclusion.md, the document the AI produced after Phase 26 (still not knowing about Phase 31 yet), it describes the then-current solution as “a mitigation, not a root-cause fix”. It honestly admits what we knew: the UBO pin was a countermeasure, not an explanation. That’s good behavior.

The difference is that I had a stubborn hunch that something was still wrong. It worked in the playable sense. But the cost (DriveClub-specific pin + tonemap SPIR-V patch + per-track threshold tuning + doesn’t generalize) was too high for a supposedly engineering-quality fix. A senior professional recognizes when the asymmetry between cost and understanding points to something deeper. You don’t always get it right. But that hunch deserves to be heard.

Four days without interruption, 8 a.m. to midnight, Sunday, Monday, Tuesday, Wednesday, resolved Thursday morning. How many times did the AI suggest “honestly, we should just accept the current result and document”? Four or five. Each technically defensible. Human perseverance is the difference between “the game works well enough” and “the game works, and I know why”.

The real cost of this journey

investigation-effort-accounting.md catalogs everything before cleanup. Some highlights:

• 3 days of active work (Apr 21-23, 2026).
• 33 numbered phases + sweeps + side threads = 54 docs, 412 KB, 6,867 lines of prose.
• 44 commits on the gamma-debug fork. 15,668 lines added, 1,204 removed.
• src/video_core/renderer_vulkan/vk_rasterizer.cpp grew from 1,364 to 4,680 lines (3.4×) with instrumentation, pin lifecycles, recording harness.
• 32 probe env vars defined. 1 effectively used to find the bug (SHADPS4_DC_LOG_STREAMCOPY, in Phase 30).
• 61 MB of shadPS4 log accumulated. 57 MB of shader dumps (5,803 files). ~470 MB of total reclaimable artifacts once closed.

Resolution: 1 integer in the config.

The ratio of 6,867 lines of prose : 1 integer amuses me. But it isn’t a joke about inefficiency. It’s the real cost of learning a system you didn’t know. Every line of prose ruled out a hypothesis. Every commit taught a layer of the stack. The integer was the end; the path was the product.

An honest note: despite the 15,668 lines added on the gamma-debug fork, almost none of it is useful to contribute upstream to shadPS4. What’s there is instrumentation: torture probes, recording harness, pin lifecycles, calibrate-at-arm, UBO snapshots, dozens of debug env vars. Diagnostic code, not production code. Diagnostics that only make sense for DriveClub under those specific conditions.

The fork is going to stay public, but not as a contribution branch to the shadPS4 project. Unfortunately. It stays as a study document: 54 md files covering the full process, 44 commits showing the sequence of hypotheses, rule-outs and failures. It’s material for anyone who wants to understand how the debugging process unfolded, or to reuse some of the techniques in similar investigations. No upstream-ready PR is coming out of that tree.

Closing

Yes, the final solution was a config toggle that already existed. It’s been in shadPS4’s code for seven months. But on Sunday night, with zero PS4 knowledge, zero emulator knowledge, zero notion that auto-exposure was a GPU→CPU feedback loop, I had no technical authority to say “flip readbacks Precise, done”.

I had to see the whole chain to understand why it works. Why Relaxed isn’t enough (it only write-protects, and DriveClub reads, it doesn’t write into the histogram SSBO). Why Precise is expensive (per-page mprotect + per-fault GPU stall). Why the maintainer hid it behind “Advanced” (Bloodborne hangs, AMD tanks to 12 FPS). Why nobody in the community had connected Precise to DriveClub before: the compat tracker admits “readbacks enabled” but doesn’t cite the mode, and nobody had seen the monotonic-drift signature through the GPU→CPU lens.

That’s the difference between knowing the answer and knowing the terrain well enough to recognize the answer. To the junior asking me “how do I learn today, in the AI era”: that’s my answer. Don’t ask. Dive in. Use AI to speed up the search, to read code in parallel, to index old forums, to compile, to parse logs. But insist on understanding the why. When the AI suggests “let’s accept and document” (and it will, because that’s often the right behavior), ask yourself whether you actually understood the chain. If the itch “this is wrong but I don’t know why” is still there, keep going.

You’re probably going to spend four days on something that has a one-integer solution. You’re probably going to discover five wrong paths before the right one. Probably half your probes will be torture shotguns that never pointed at the fix.

And you’ll probably, when you finish, know a domain you didn’t know before.

• Fork gamma-debug: github.com/akitaonrails/shadPS4/tree/gamma-debug
• 54 investigation docs: docs/driveclub-investigation/
• Operational runbook (recipe): distrobox-gaming/docs/driveclub-shadps4.md
• Phase 31 resolution: readbacks_mode: 2

Now I’m going to go play DriveClub. Night race in Canada, natural brightness, no blackout. Good Thursday.

I’ve been following Uncle Bob for many years. I’ve exchanged messages with him a few times over the decades, I have formed opinions about his positions, and I did an hour-long live stream on my channel with him about Clean Code, Agile, Craftsmanship, and where the industry was heading. If you’ve never watched it, I recommend it:

Clean Code specifically set a standard: code is written once but read dozens of times. The programmer’s job isn’t just to make it work. It’s to make it work in a way that another programmer can understand, modify, and not break. Meaningful names, small functions, one responsibility per class, no duplication, automated tests, clear structure. The target audience was always another human being sitting at an editor trying to figure out what the first one did.

In 2026, that audience changed.

The audience isn’t human anymore

Last week I wrote VS Code Is the New Punch Card. The thesis is that typing code manually into a text editor is becoming a niche activity, the same way typing binary directly on an Altair front panel became a relic after compilers got good. The AI agent is the new compiler: I describe intent in natural language, the agent navigates code, edits, runs tests, adjusts, delivers.

If that thesis holds, the next question is obvious: who are we writing code for now?

Not for the human programmer who’ll sit down tomorrow to maintain it. It’s for the agent that’ll read, edit, and extend it. And an agent is not human. Agents have different technical constraints, different biases, different limitations. Part of Clean Code still applies (in some cases more critically). Another part shifts in weight. And new demands emerge that Uncle Bob couldn’t have anticipated in 2008.

This article is about that. What’s the version of Clean Code that makes sense when the primary reader is an LLM?

The real agent constraints

Before re-ranking, worth reviewing what agents actually face.

File truncation. Most agent CLIs limit file reads to small ranges. Claude Code reads 2000 lines per chunk by default. Cursor, Codex, Windsurf, all have similar caps. A giant file simply doesn’t fit into the context window in one shot. The agent has to ask for piece by piece, or worse, use grep and reconstruct mentally.

Attention degrades with context. Claude Opus has a 200k-token window, Sonnet 1M, Gemini 1M. Sounds like a lot. In practice, “needle in haystack” tests show retrieval quality drops well before the claimed limit. Flash Attention and variants speed up the computation, but they don’t replace full native attention. The more you stuff into the window, the worse the detail precision. And the agent’s context isn’t just your code: it holds CLAUDE.md, the system prompt, chat history, tool output, error logs, test output. All competing for the same window.

Grep is cheaper than read. The agent knows this. It prefers rg "funcName" over loading a whole file. It’s faster, uses fewer tokens, hits the target. Unique, distinctive names make that much more effective. This isn’t a shortcut, it’s an architectural choice: I wrote about this in detail in Is RAG Dead? Long Context, Grep, and the End of the Mandatory Vector DB, showing that Claude Code itself navigates a repo with Glob and Grep, no vector DB, no embedding, and that’s not a deficiency, it’s mature design. Lexical search + smart reader consuming raw text beats dense retriever + top-k on practically every real-domain benchmark. You benefit from that when you organize your code: greppable names aren’t just “nice for humans”, they’re the agent’s primary navigation API.

Tool calls cost tokens. Every Read or Edit or Bash burns input and output tokens. Short files, small test output, concise logs — all of that keeps the agent productive and the bill low.

Latency matters. Agent in a loop, each tool call adds seconds. A large file slow to process becomes perceptible session friction.

Grepping by visual pattern is hard. If you used inconsistent indentation, mixed tabs and spaces, varied brace style between files, the agent spends tokens internalizing the mess. Consistency helps.

From those constraints, Clean Code principles can be re-ranked by relevance for agent-facing work.

Re-ranking: Clean Code in the age of agents

Most important to least. A caveat: it’s not that the ones at the bottom stop mattering. It’s that the ones at the top started mattering MUCH more.

1. Small functions (and small files)

Uncle Bob: “functions should do ONE thing, they should do it WELL, and they should do it only”. Ideal size 4 to 20 lines, per the book.

For an agent, that recommendation became a technical obligation. A small function fits in a single tool call without truncation. A short file (keep it under 500 lines, ideally 200-300) fits in a single read. If the agent can grab the whole unit of meaning in one call, it reasons about it with full attention. If it has to paginate, it builds a fragmented mental model, and each fragment costs attention.

Before, “small function” was good for humans because it aided reading. Today, “small function” is good because it matches the model’s unit of processing. If there’s one recommendation to take to heart, it’s this one.

2. Single Responsibility Principle (SRP)

Each module does one thing and has one reason to change. It was already the heart of Clean Code. For an agent, it becomes even more critical because:

• The agent can isolate the unit to understand without loading the rest of the system
• You can run focused tests on it
• You can edit without fearing side effects
• Grepping by responsibility becomes predictable

Code with tangled responsibilities forces the agent to load way more context for any simple change. An 800-line class that does three things is worse for the agent than three 250-line classes, even if the total is the same.

3. Meaningful and unique names

Clean Code already preached: names reveal intention, no disinformation, distinctive, pronounceable, searchable. For the agent, “searchable” became the most important property of that list.

The agent searches code via grep/ripgrep all the time. A generic name (data, process, handler, Manager, Service) returns fifty matches and forces the agent to read each one. A distinctive name (UserRegistrationValidator, InvoiceLineItemTotal, ClaudeCodeSessionTracker) returns three matches and the agent goes straight to the right one.

Rule of thumb: if you grep the name and a lot of irrelevant stuff comes back, the name is bad for the agent. If only what matters comes back, the name is right.

4. Comments with context and provenance

This is where the inversion is most jarring. For Uncle Bob in 2008, the axiom was: “good code explains itself, excessive comments are a code smell, every comment is debt that gets stale”. Every experienced programmer who read the book absorbed that rule. Well-named code doesn’t need comments. Too many comments = flag of bad code trying to justify itself.

Now flip it. The agent reads comments. And likes them. Comments become first-class context. The agent has perfect syntax fluency, knows exactly what x++ does, doesn’t need obvious captions (that kind is still bad, see item 13). What it DOESN’T know is why you chose this approach over the obvious one, what production bug motivated this weird logic, what business constraint forces this specific order, what workaround exists because the upstream lib has known bug #1234, which commit introduced this decision, which Jira issue is the reference. That kind of information is provenance: the why of the decision. It only exists in the head of the human who wrote it, in the commit message, or in a well-placed comment. For the agent, the comment is the most accessible source during a tool call.

Docstrings with intent and usage examples also became strong signals. When the agent picks up a function without understanding the context, a header docstring (JSDoc-style with examples, Python """, Rust ///) drastically shortens the path to a correct change. Uncle Bob was skeptical of JavaDoc in 2008 because they got stale. Today, with the agent able to rewrite the docstring alongside the code, that counter-argument lost weight.

A practical consequence: don’t prune the comments the agent writes. If you have the reflex “verbose comment is noise” inherited from the original Clean Code era, that rule flipped. The agent wrote that comment because, in the act of generating the code, it decided that information was worth preserving for future edits. Removing the comment in code review strips context that the agent itself will want to read on the next interaction. Let the agent comment. It knows what it’s doing. The only kind of agent-authored comment worth removing is the obvious redundant one (item 13), and modern models rarely produce those if the system prompt is well written.

5. Explicit types

This isn’t in 2008’s Clean Code because the industry hadn’t converted yet. But in 2026 it’s a fundamental criterion.

Python without type hints, JavaScript instead of TypeScript, Ruby without RBS. Dynamic code without annotations forces the agent to infer types from usage, which costs reasoning and gets it wrong frequently. Typed code gives an immediate answer key: the signature says what goes in, what comes out, which states are valid. The agent saves discovery work and makes fewer mistakes.

If you’re still on Python 3 without type hints, the transition will boost agent productivity more than any logic refactor.

6. DRY (Don’t Repeat Yourself)

Clean Code already said duplication is the root of all evil. For an agent, duplication is worse than for a human for one specific reason: when the agent has to change something that’s replicated, it can update one copy and forget the others. The attention window doesn’t have natural gravity pulling “oh, there are two more copies of this in other files”. The agent has to find each one via grep, and if the pattern has subtle variation between copies, the result ends up inconsistent.

Factoring into a reusable function or module isn’t aesthetic. It’s automated-refactor safety.

7. Tests the agent can run

Uncle Bob dedicates a full chapter to Unit Tests and F.I.R.S.T (Fast, Independent, Repeatable, Self-Validating, Timely). All of it still applies, with an important addendum: the test has to be executable by the agent without human setup.

Meaning: the command to run the test is in the README or CLAUDE.md, in the Makefile, in the package.json. Output has a predictable format the agent parses. It doesn’t depend on manually seeding the database, on a config file that isn’t in the repo, on a secret credential. The agent writes code, runs tests, reads output, adjusts, runs again. That cycle is the foundation. If the tests don’t run headless, the agent goes blind.

Here I speak from field experience. I documented this in From Zero to Post-Production in 1 Week Using AI, where I went hard on a real project: 274 commits in 8 days, 4 integrated applications, 1,323 automated tests by the end. What made it work wasn’t “AI programs on its own”. It was Extreme Programming with the agent as pair instead of a human pair. Running tests on every commit, tight CI, coverage above 80% (95%+ on business logic), test-line-to-code-line ratio above 1:1 on some modules. Sounds like overkill. It isn’t. In 274 commits, CI caught real bugs more than 50 times, bugs that would have gone straight to production if I had blindly trusted the agent. Without tests, the agent hands you plausible code that silently breaks something that worked yesterday. With strong tests, the agent becomes a multiplier: it generates a test, the test validates the code it wrote, the test is the safety net for the next change it makes. Virtuous loop.

XP practices (pair programming, CI, tests first, continuous refactoring, short feedback) didn’t become obsolete. They became exactly the right way to work with an agent. Whoever programs in cowboy mode without tests today isn’t rebellious. They’re just slow, because the agent without tests keeps guessing, and guesses need manual review, which kills the speed the agent should bring. Good tests with good coverage became the difference between a productive agent and an agent that keeps flailing. Or, put another way: TDD became a technical obligation, not a philosophy.

I covered this theme from another angle in Software Is Never “Done”, showing that post-deploy life is where tests matter most: in ten days of operation after launch, I ran 56 commits of fixes, hardening, and adjustment in response to real behavior, and each commit came with a regression test. Without the net, each of those 56 commits would be an opportunity to break something that worked yesterday. TDD isn’t a phase, it’s a habit.

8. Predictable directory structure

Clean Code barely discusses this (it was more focused on code inside a file). For an agent, tree organization matters. If src/controllers/users.rb implies src/models/user.rb and src/views/users/, the agent can anticipate paths without listing directories. If the project uses idiosyncratic naming (random files, unpatterned names, everything flat in one folder), the agent loses time with find.

Strong framework conventions (Rails, Django, Next.js, Laravel) help the agent a lot. Project without convention, the agent builds one over time, but until then it burns tokens exploring.

9. Dependency Injection and Testability

Code with injected dependencies (not hardcoded) is easier to test in isolation. The agent benefits from this. It can swap the real EmailSender for a FakeEmailSender in a test without touching the logic. Code that instantiates its dependencies internally forces the agent into monkey-patch-fake-server-hacks that are slow, fragile, and pollute the session with infra grime.

DI isn’t ceremony. It’s isolation scope. And in a real project, DI quickly becomes a load-bearing refactor: on one of my projects (the M.Akita Chronicles), I discovered after launch that I needed to swap the default LLM model to another provider. The environment variable had existed from the start. But the model name was still hardcoded in references across 24 files. A whole commit (Centralize LLM model config) touched all 24 to isolate the config into a single constant. Swapping models after that became a one-line change. That’s exactly the kind of refactor that only shows up after software meets reality, and it’s where DI and config isolation pay dearly if you didn’t do it earlier.

10. Avoid deep nesting

Clean Code talks about single level of abstraction per function. A corollary: avoid if inside for inside if inside try. Every indentation level is more attention the model has to spend tracking state. Four levels of indentation is MUCH more cognitively expensive for the agent than two levels with early return.

Pattern matching, guard clauses, early returns, flattening logic, all of this improves readability for the model the same way it improves it for the human, except measurably so, because the cost is measured in response quality.

11. Errors with context

raise ValueError("invalid input") doesn’t help the agent when it reads the stack trace. raise ValueError(f"invalid input: received {repr(x)}, expected non-empty string of digits") does. The agent uses exception messages as debug signal. Vague message = agent runs an extra round to figure out what went wrong.

Uncle Bob talked about this in Error Handling: “Provide context with exceptions”. It became critical now.

12. Formatting and style

Don’t waste time on this. Use the default or most popular formatter for your language: cargo fmt for Rust, gofmt for Go, prettier for JS/TS, black or ruff for Python, rubocop -A for Ruby. Configure it in pre-commit, configure it in your editor to run on save, and move on. The agent handles any consistent style just fine, and the auto-formatter keeps the diff tidy between commits. Tab vs space, 80 vs 100 columns, brace style, all of that became noise. The formatter decides, you accept.

13. Comments that describe the obvious

Last on the list. Still bad, got even worse. Comments like // increment i by 1 above i++ waste the agent’s tokens the same way they wasted the human’s patience. The model knows how to read code, it doesn’t need obvious captions.

If you have the habit of writing obvious comments because some school taught you that way, this is the moment to stop. In 2008 it was bad because it polluted visual space. In 2026 it’s bad because it costs real money in tokens.

What Uncle Bob couldn’t foresee

Beyond re-ranking what was in the book, some new things emerged that are specific to the agent world:

Meta-documentation files for agents. CLAUDE.md, AGENTS.md, .cursor/rules, and so on. These are files the agent reads before any tool call, describing project conventions, important commands, caveats, things that don’t go in a docstring. Writing these files is a new skill: short, direct, imperative, action-oriented. No philosophical prose. Bullet points of what the agent needs to know to not mess up.

README with high-level architecture. Uncle Bob barely cared about README (the book is about code). For the agent, well-made READMEs drastically shorten the path to understanding the shape of the project. A simple ASCII or Mermaid diagram helps.

Structured logging. JSON logs with named fields are much more useful for the agent than prose logs. The agent parses JSON trivially, uses fields to filter relevant errors, correlates across services. A loose printf in free text forces heuristic parsing.

Accessible observability commands. pnpm test, make lint, cargo check, python -m mypy — the more the project exposes predictable commands the agent can invoke to validate changes, the better. If running tests requires 10 manual setup steps, the agent won’t run tests, and the feedback loop breaks.

Idempotent setup scripts. The agent has to be able to run bin/setup or scripts/bootstrap.sh on a clean machine and reach a state where it can work. If onboarding depends on instructions in someone’s head, the agent is locked out.

Instructing the agent to write clean code

There’s an important detail that only becomes clear after about 500 hours of using agents: no LLM does any of this by default. You tell it “implement feature X” and it’ll implement it the way the model considers average. No dependency injection. 80-line functions. No tests, or tests that mock the wrong thing. Duplicated logic because it’s faster. 2000-line files because “everything’s in one place”. You need to WRITE these rules. The agent reads, the agent follows.

Where to write: CLAUDE.md, AGENTS.md, .cursor/rules, .github/copilot-instructions.md, depending on the CLI. Format: short, imperative, action-oriented. The agent reads these files on every iteration (Claude Code re-reads CLAUDE.md on every query), so each line burns context tokens — density matters.

Below is a proposal for a template you can drop into a CLAUDE.md on a new project, consolidating what I discussed above in a format the agent consumes. This is not a definitive version, it’s a starting point to test and tune to your language, your team, your flow. If a rule doesn’t fit your context, remove it. If you need a new rule, add it. The point is to have a structured skeleton:

## Code style

- Functions: 4-20 lines. Split if longer.
- Files: under 500 lines. Split by responsibility.
- One thing per function, one responsibility per module (SRP).
- Names: specific and unique. Avoid `data`, `handler`, `Manager`.
  Prefer names that return <5 grep hits in the codebase.
- Types: explicit. No `any`, no `Dict`, no untyped functions.
- No code duplication. Extract shared logic into a function/module.
- Early returns over nested ifs. Max 2 levels of indentation.
- Exception messages must include the offending value and expected shape.

## Comments

- Keep your own comments. Don't strip them on refactor — they carry
  intent and provenance.
- Write WHY, not WHAT. Skip `// increment counter` above `i++`.
- Docstrings on public functions: intent + one usage example.
- Reference issue numbers / commit SHAs when a line exists because
  of a specific bug or upstream constraint.

## Tests

- Tests run with a single command: `<project-specific>`.
- Every new function gets a test. Bug fixes get a regression test.
- Mock external I/O (API, DB, filesystem) with named fake classes,
  not inline stubs.
- Tests must be F.I.R.S.T: fast, independent, repeatable,
  self-validating, timely.

## Dependencies

- Inject dependencies through constructor/parameter, not global/import.
- Wrap third-party libs behind a thin interface owned by this project.

## Structure

- Follow the framework's convention (Rails, Django, Next.js, etc.).
- Prefer small focused modules over god files.
- Predictable paths: controller/model/view, src/lib/test, etc.

## Formatting

- Use the language default formatter (`cargo fmt`, `gofmt`, `prettier`,
  `black`, `rubocop -A`). Don't discuss style beyond that.

## Logging

- Structured JSON when logging for debugging / observability.
- Plain text only for user-facing CLI output.

This block fits in under 100 lines and costs about 500 tokens per iteration. Sounds like a lot, but the savings in code quality and absence of rework easily make up for it, especially if you’re on a pay-per-token API account. Use it as a base and evolve it with your own experience.

Some items (SRP, small functions, tests) the agent will try to do on its own. Others (DI, strict DRY, explicit types EVERYWHERE, aggressively unique names) it only does when you say so explicitly. And some (like “don’t strip the comments you wrote yourself on a refactor”) are so counterintuitive to its default training that without the instruction it WILL prune them. Hence the importance of having a rules file that gets read every iteration.

An analogous pattern shows up around defensive programming: the agent implements circuit breaker, retry with backoff, aggressive timeout, graceful degradation, all of it nicely — when you ask. But on its own it won’t propose them. The agent doesn’t know what your system’s operational failure points are, so it implements the happy path and waits for instruction. If your CLAUDE.md lists the categories of defensive code the project needs (rate limit, retry, breaker, fallback), the agent covers them. If it doesn’t list them, the agent doesn’t invent them. It’s another case where explicit instruction to the agent is what separates robust code from naive code.

If you use the same agent across different projects, it’s worth having a base template and adding project-specific rules on top. But start with something like the above and iterate from there.

The short version

Uncle Bob wrote Clean Code to be read by other humans. In 2026, the primary reader became the agent. The good news is that most of what the book preached still holds. The bad news is that some things that were opinions (“a file should have N lines”) became technical constraints (“a file with X lines makes the agent perform worse”). The difference is that now there’s a metric: token cost, tool-call latency, output quality. Whoever writes clean code for the agent saves API-bill money, session time, and gets less hallucination in the output.

And there’s a cultural bonus worth registering: all these practices (XP, TDD, SOLID, SRP, DI, small code, abundant tests) were falling out of fashion in the 2010s, replaced by “move fast and break things” and two-month bootcamps. Programmers who invested in fundamentals became a minority, and it became fashion to trash Uncle Bob on the internet. Turns out those very fundamentals became the technical differentiator of working with agents. Whoever kept the discipline is well served. Whoever dismissed it is now struggling to teach the agent not to commit mistakes the XP crowd had mapped out 25 years ago.

Clean code was never fashion. It became infrastructure.

Two monsters sit at the top of that list. First, Driveclub on shadPS4. It’s a PS4 exclusive, never got a port, Evolution Studios was shut down, no remaster. To play it outside the original PS4, emulation is the only option, and PS4 emulation is still the most immature part of the ecosystem. This is by far the hardest on the list.

Second, Forza Motorsport 4 with Project Forza Plus on Xenia Canary. FM4 is the GOAT of the Xbox 360 era, Project Forza Plus is the community mod that consolidates patches and content, and getting the two to run together on Xenia with decent graphics, no audio crashes and no shadow bugs took serious hours of trial and error.

Around those two I organized the rest of what I already knew worked at some level, just needed consolidating into a reproducible setup: Gran Turismo 4 with Retexture 3.0 and HD HUD, Gran Turismo 3 with HD textures and widescreen, Gran Turismo 2 with the Spec II mod, the PS3 Gran Turismos (GT5 and GT6), Forza Horizon 1 and 2, the PGRs, Ridge Racer, Enthusia, Colin McRae. I had an idea how to make these work, I just needed a setup that doesn’t break the next time I reinstall the system.

Before the details, two things to clarify.

First, on infra: I’m not going to repeat here how the setup was built. I wrote that in detail in An Emulation Distrobox with Claude Code. Arch Linux in a distrobox with --nvidia, 17 Ansible roles, every emulator from the AUR, ES-DE as frontend, automated per-game configs, Python scripts for PS3 update checking and Xbox 360 title updates, Xenia via Wine. Go read that one. The repo is at akitaonrails/distrobox-gaming if you want to reproduce. Here I’m going to talk about the games.

Second, on taste: I like simcade racing. Gran Turismo has been my declared addiction since PS1, and I wrote about the rest in the Formula FX1 cockpit article. Direct-drive wheel, load-cell pedal, triple monitor when I’m feeling masochistic. That’s the kind of racing I like.

The warning for the “well, actually” crowd

Yes, I know iRacing and the rest of the current sims and simcades. I have 12 TB of ISOs and ROMs on the NAS, I probably have one you’d remember to mention. It’s not for lack of options that I’m focusing on emulation today.

On the new side, the games I’m genuinely anticipating: Forza Horizon 6 in Tokyo, Assetto Corsa EVO, and Assetto Corsa Rally. I’ve been playing the demos of both Assetto Corsa titles and enjoying their single-player campaigns a lot. When those ship, they’ll become my main sim rotation. This article covers a different side of the collection, pulling classics out of oblivion that still don’t have a remaster.

Today, here, I’m interested in these specific games I listed above. Period. You do what you want, I do what I want. If you want iRacing, fire up Steam and go in peace. This article is about messing with emulators, preserving old games, and pulling these gems out of oblivion on a Linux setup. If you’re here for current-sim reviews, you won’t find them.

Now to what matters.

A note on the videos: most of them have no audio because I forgot to turn on sound capture in OBS before recording and I was too lazy to re-record. Audio works perfectly on every emulator here; this is my OBS mistake, not a setup issue.

Global settings per emulator

Before the games, a quick consolidation of the global configs that apply across each emulator. This is automated in the repo, but if you’re setting up by hand, here’s the summary.

DuckStation (PS1)

• Renderer: Vulkan
• Internal Resolution Scale: 8x (8K internal, downscaled to the monitor)
• Texture Filtering: JINC2 (preserves pixel art but smooths)
• PGXP: on (fixes the typical PS1 vertex wobble)
• Widescreen Hack: on as fallback, but I prefer per-game widescreen cheats
• Aspect Ratio: 16:9 with widescreen cheat, 4:3 without

PS1 runs smoothly on DuckStation these days. It’s the most mature emulator on the list. The attention goes to per-game choices (some games need a specific widescreen cheat).

PCSX2 (PS2)

• Renderer: Vulkan
• Upscale: 4x SSAA (1440p native → 4K internal)
• Anisotropic Filtering: 16x
• Post Processing: FXAA on, PCRTC antiblur on
• Deinterlacing: Automatic (some games need override)
• Controller: Xbox-style bindings (I use an 8BitDo)

PCSX2 2.7.x is much better than the 2.6.3 still in Arch’s official repo. The AUR’s pcsx2-latest-bin tracks 2.7.x and that’s where texture replacement, modern FXAA and PCRTC antiblur live. If you’re on a different distro stuck on 2.6.3, get the official AppImage.

RPCS3 (PS3)

• Renderer: Vulkan
• Resolution Scale: 300% (generally) or native (for games with upscale issues)
• Shader Precision: Ultra
• Force High Precision Z: on
• SPU XFloat: Accurate
• Multithreaded RSX: on
• Write Color Buffers (WCB) / Read Color Buffers (RCB): off by default (GT-series safety)

RPCS3 is where the most traps are. Each game has a recommended preset in the official compatibility DB. And a heads-up: per-game configs live in ~/.config/rpcs3/custom_configs/config_<SERIAL>.yml. The config_ prefix is mandatory. It cost me time to figure out. RPCS3 silently accepts the YAML and then ignores it if the name is wrong.

Xenia Canary (Xbox 360)

• Build: Canary (master has been stagnant for months, Canary is where development lives)
• Renderer: Vulkan
• Render Target Path: rtv by default, fsi for specific games (PGR4)
• User Profile: created once, persists
• Wine Prefix: dedicated, managed by Xenia Manager

Xenia on Linux runs via Wine, managed by Xenia Manager. There’s no decent native build. It works well, but each game needs specific tuning, and Title Updates have to be pulled manually from archive.org (I wrote a script for that, details in the previous article).

shadPS4 (PS4)

Gets its own section at the end. TL;DR: works for some simple games, Driveclub is still a moving target. Still a shot in the dark.

PS1 on DuckStation

Gran Turismo (the first, from 1997)

This one is pure sentiment. GT1 was one of the first games I bought for the PS1 and I played it until the CD cracked. At the time, it was on another level. Real simulation on a machine with 128K of video RAM, decent physics, 140 cars when everybody else had 15, memorable soundtrack.

But let’s be honest: you can’t go back today. GT1’s physics has exaggerated drift, the car slides more than it should on any corner above 80 km/h. It’s part of the 1997 charm but gets annoying in 2026. The handling model was refined starting in GT2, and everything after only got better. Between GT1 and GT2, GT2 wins on content (650+ cars vs 140) and especially on drivability.

I keep GT1 in ES-DE to open in nostalgic moments, drive 10 minutes at Trial Mountain, and close it. For serious PS1-era gameplay, it’s GT2.

Gran Turismo 2 (Spec II Mod)

The original PS1 Gran Turismo is a historical milestone. I played a lot of it back then. To replay today? No. GT2 exists, and GT2 is superior in everything. More cars (650+), more tracks, more modes, and most importantly, a much better handling model. GT1 has that exaggerated drift where the car slides more than it should, GT2 tightened that up to something closer to what the series would become starting on PS2. Between playing GT1 or GT2, always GT2.

And the GT2 I run today is the GT2 Spec II Mod by Project A-Spec, a community project that merges the two regional variants (Arcade + Simulation) into a single game, brings back events that were cut from the final release, fixes physics bugs, adds native widescreen support, and ships quality-of-life menu updates. It’s the definitive way to play GT2 in 2026. The project doesn’t maintain its own website anymore, updates come through the author’s Twitter.

To run it:

The 8 MB RAM cheat matters for crowded tracks (Seattle in populated races for example) where audio starts clipping. It simulates the memory expansion of the Japanese version that never made it West.

Colin McRae Rally 1 and 2

Iconic PS1 games. CMR1 has that rough first-gen rally feel that has its charm. CMR2 is technically superior, better physics, more rallies, better graphics. But honestly: to play CMR2 today, it’s worth looking for the original PC version. Higher resolution, native 60fps (the PS1 version is locked to 30), direct keyboard/wheel support. Codemasters repacks exist on the internet, a 40-second search will find them. I’m not going to link them, you know where to look.

On PS1 via DuckStation they run smoothly, nostalgia guaranteed, but it’s not where I spend my time.

PS2 on PCSX2

Gran Turismo 3 A-Spec

GT3 was a generational leap. Out of the blocky PS1 world into shaders, decent environment mapping, serious polygon car models, physics that finally started to feel like actual physics. The soundtrack with Feeder’s “Just a Day” opening the game still gives me goosebumps.

The problem is that GT3 has LESS content than GT2. Polyphony was more cautious, cut modes to focus on polish. The A/B/S license tree is smaller, fewer cars, fewer tracks. But what’s there is polished.

In 2026 on PCSX2 2.7.x, GT3 looks great. Community HD textures, widescreen pnach, anti-aliasing via SSAA, 16x AF. Feels like a re-release.

Caveat on the retexture pack: when enabled, some car-showcase cutscenes in the garage have momentary flicker due to NFS streaming. Doesn’t bother in-race. If it bothers you in menus, turn it off.

Reminder: for the widescreen pnach to take effect, you still need to go into the in-game options and switch the aspect ratio to 16:9. The pnach unlocks the option in the menu, it doesn’t apply automatically.

Gran Turismo 4 (Spec II Mod)

GT4 is my GOAT in the series. 700+ cars, 50+ tracks, physics still respectable by 2026 standards, and that soundtrack mixing alternative rock, Japanese lounge, and Moby’s infamous “Sail Away” on the main menu. It’s the game I poured the most hours into back in 2004, and it’s what I play the most today.

Like GT2, the GT4 I run today is not the original disc. It’s the Gran Turismo 4: Spec II maintained by TheAdmiester — a massive community mod that’s objectively the best way to play GT4 in 2026. It combines the final USA disc, the 2003 Beta prototype, and the original Japanese release into one game, restoring cut cars (including several that never left Japan), cancelled events, dozens of missing soundtrack tracks, adding 16:9 widescreen support, over 30 built-in cheats exposed as menu options (pro tuning, top speed, fuel economy), the option to switch between English and Japanese, and original bug fixes. The project is active, still gets patches, and ships its own installer that applies over a clean USA ISO.

In practice, Spec II is what GT4 should have been if Polyphony had six more months to polish. Playing it today feels like GT4 with all the content that got left out, plus modern quality-of-life. For anyone who enjoyed the original, it’s mandatory.

On top of that goes the community’s Retexture 3.0 (HD texture pack) and the HD HUD by Silentwarior112. With those three pieces together (Spec II Mod + Retexture + HD HUD), GT4 runs at 1440p SSAA on PCSX2 2.7.x with 16x AF, FXAA, and a look that’s honestly indistinguishable from a new low-poly-style release. It’s my current favorite to sit down and play long.

Spec II users need to pay attention to the CRC: the vanilla GT4 HD packs were built for 77E61C8A (USA), so on Spec II with CRC 4CE521F2 I symlink the assets into the CRC-suffixed folder that PCSX2 looks for. The widescreen pnach was also renamed to match the Spec II CRC. Without that, the game runs but the mods don’t load.

In-game reminders: same as GT3, the widescreen pnach only unlocks the option, you still need to enter Options in-game and switch to 16:9. And important: change the video mode to progressive 480p (also in Options). The default is interlaced 480i, which looks terrible on a modern screen. Spec II Mod has native progressive support, just flip it on.

If I could recommend a single GT in the series for someone starting today, it would be this one. If you like racing and never played GT4 in full, you’re missing out.

Enthusia Professional Racing

Enthusia is the forgotten Konami game from 2005. Launched in GT4’s shadow and died on the shelves. It’s a shame, because Enthusia’s physics was more realistic than GT4’s. Car weight, mass transfer, limit behavior, all closer to real-world behavior. The sim-racing community of the 2000s knew this and the game has a cult following today.

Enthusia’s problem was the Enthusia Points system: you earned points for driving clean, lost them for crashing, and the game’s progression depended on those points. A lot of people found it punitive. I found it perfect. It forced you to drive with your head.

On PCSX2 with retexture and widescreen, the game looks great. Strong recommendation for anyone who wants something different from Gran Turismo.

Ridge Racer V

Ridge Racer is its own thing. Not simcade, pure arcade. Drift everything, cartoony grip, electronic soundtrack, saturated colors. Ridge Racer V was the Japanese PS2 launch title and it carries that “show what the console can do” vibe, with massive scenery and a sense of speed GT never attempted.

On PCSX2 it runs well, with a catch: car textures sometimes flicker on the hardware renderer (PCSX2 issues #3639 and #13729). Software renderer fixes it but kills performance. I stay on hardware and accept the occasional flicker.

Colin McRae Rally 3, 4, 5 (PS2)

PS2 Colin McRae versions run well on PCSX2 with default configs. CMR3 and CMR04 are good. CMR05 (the last before the rebrand to Dirt) is the best of the three technically. But again: if you’re on PC, look for the native version. The PS2 ports were relatively inferior to PC of the era, ran at lower resolution, and a modern PC with a repack will hit 144Hz easily.

I keep them on PCSX2 just for collection completeness.

PS3 on RPCS3

Gran Turismo 5

GT5 is controversial. Polyphony promised the world and delivered a somewhat fragmented game: gorgeous Premium models next to Standards that were basically HD GT4 cars, a level system some loved and others hated, online that went to mud when PSN service was cut, a Top Gear mode that was weird. The contemporary critical reception was mixed, and I remember entire communities fighting over whether the game was a disappointment or a masterpiece.

For me, it’s a masterpiece. GT5 has the Course Maker (design your own track from real sections), real 24h Nurburgring with dynamic weather, the Moon Rover (yes, a drive-on-the-moon mode), Red Bull X-Challenge with Vettel, and the single-player endurance experience is ridiculously big. Anyone who went deep into the game knows there’s content for a whole year.

On RPCS3 in 2026, GT5 runs really well. Stable, without the serious bugs from years past. It’s the most stable GT I have emulated today.

The Shader Precision Ultra + Force High Precision Z combo kills the typical RSX dithering that made GT5 look grainy on RPCS3 in years past. Without those two, asphalt looks permanently noisy. With them, the game looks clean.

Gran Turismo 6

GT6 is one of my favorites in the series. It came out in 2013 for an end-of-life PS3 while the competition was already looking at PS4. Sold poorly. A lot of people didn’t play it. That’s a shame, because GT6 took the GT5 base, cut the fat (Standards were reduced), added more Premiums, better Moon circuit sessions, dynamic weather on more tracks, physics refinement. It’s basically GT5 polished.

On content, GT6 is comparable to GT4. A lot of old-guard players put GT4 above it because of the PS2-era charm. I stay between the two and go GT6 on a normal day, GT4 on a nostalgic day.

On RPCS3, GT6 has a serious catch: patches 1.06 and beyond regress visually. Black surfaces on cars in the garage menu, flicker in cockpit view, full-screen flashing on certain tracks. The version that works well in 2026 is pinned at v1.05. The repo’s extract_ps3_dlc.py script has a per-title version ceiling specifically to pin GT6 at 1.05 even when PSN serves 1.22 as “most recent”.

Also, Force CPU Blit is mandatory. Without it, full-screen flicker in the menu. The trade-off is the rear-view mirror stays permanently black. I prefer losing the mirror to having the flicker. Anyone who wants the mirror can enable Write Color Buffers, but then resolution drops to 720p native.

In 2026, with these settings, GT6 is in my rotation. Not perfect, but playable enough that I can spend an afternoon doing endurance.

Ridge Racer 7

Ridge Racer 7 was a PS3 launch title in 2006 and the last mainline in the franchise. Arcade like Ridge Racer V, drift-first, electronic soundtrack, cinematic camera. For a PS3 of that era it was a pretty tech demo.

On RPCS3 it runs, but with caveats: requires Write Color Buffers on to avoid lighting issues, and the recommended preset in the compat DB is different from my GT preset. I use a dedicated per-game config. Not my favorite, but it’s there for completeness.

No video for this one, I’ll record later.

Xbox 360 on Xenia Canary

This is the part that caused me the most headaches this Sunday. Xbox 360 on Linux is hostile territory. Xenia runs via Wine, each game needs specific tweaks, title updates have to come from archive.org, and Forza Motorsport 4 specifically had serious problems until recently.

Forza Motorsport 4 (the GOAT)

FM4 is, for a lot of people, the best Forza Motorsport ever released. Polyphony made Gran Turismo, Turn 10 made Forza, and FM4 is the peak of the 360 era. Beautiful car models for their time, well-designed tracks, solid physics without being a hard sim, Autovista mode with Jeremy Clarkson narration, epic soundtrack, and that feeling of the Xbox 360 being pushed to its limit.

FM4 on Xenia was a nightmare until recently. Severe shadow artifacts, constant texture pop-in on the car, grainy pixelated track textures, sky brightness completely wrong (it came out white-blown-out instead of the deep blue of the original), and worst: frequent audio crashes where XMA (the Xbox 360’s proprietary codec) would freeze and the audio would turn into a high-pitched noise until the game hung. I spent hours this Sunday messing with configs, testing builds, searching the xenia-canary issue tracker, testing different title updates.

What unlocked it:

• Latest Xenia Canary build (master is stagnant, Canary tracks active development)
• Render Target Path: rtv (the default works fine for FM4)
• Title Update 1.0.17.0 installed via Xenia Manager (version matters, older ones regress shadows)
• Vulkan GPU with NVIDIA ICD forced (on my hybrid setup with AMD iGPU, I had to hardforce the 5090)

After that, FM4 ran. Not perfectly. Still gets the occasional audio crash (xenia-canary issue #161 open). But it’s playable, and I spent two hours of the Sunday at Top Gear Test Track just admiring the Koenigsegg CCX. Worth every hour of debugging.

Forza Motorsport 3

FM3 is one of the solid entries in the series, sitting between FM2’s rougher charm and FM4’s technical peak. Getting it to emulate was surprisingly annoying, because I was using the wrong ISO.

There are two releases of FM3: the retail (original disc sold in stores) and the Ultimate Edition (all DLCs packaged on a second disc). I was trying to run the Ultimate, which combines both discs into a hybrid ISO that Xenia can’t parse correctly. I swapped to the standard retail + DLCs installed separately via Title Update, and bang, the game ran first try.

Moral: if your FM3 isn’t running on Xenia, check that it’s retail. Ultimate breaks.

Forza Motorsport 2

FM2 is from 2007, first-gen 360. Less refined systems, more basic modeling, but that original Forza charm some prefer to FM4’s sophistication. On Xenia it ran practically out of the box. No special tweak.

Forza Horizon 2

FH2 was the most polished Forza Horizon of the 360 generation (there’s also the Xbox One version, which is technically better, but the 360 has its charm because of the smaller map and more focused progression). Open world in southern Europe, iconic soundtrack, Horizon festival at its peak.

On Xenia it ran without asking for anything extra. Same as FM2.

Forza Horizon 1 (with XE Mod)

Original FH1 runs OK on Xenia, but there’s a community maintaining the Forza Horizon 1 XE Mod, which improves traffic AI, rebalances progression, adds cars that were cut, fixes known bugs, and brings quality-of-life tweaks to the UI. I tested the XE Mod this Sunday and it’s worth it. The game feels more alive and progression feels fairer.

Install details for the XE Mod are on the project site. Basically it’s a patch over the original ISO + a few custom title updates.

For comparison, here’s FH1 without the mod, running vanilla:

The most visible difference is traffic and the variety of situations that come up, but the XE Mod has a lot of stuff you only notice after a few hours.

Project Gotham Racing 3 and 4

PGR3 was a 360 launch title in 2005 and still looks gorgeous today. Urban tracks (New York, Tokyo, Nurburgring, Las Vegas), kudos system, cinematic camera. PGR4 added dynamic weather (rain and snow) and motorcycles (some people love them, I prefer to pretend they don’t exist).

PGR3 on Xenia Canary runs reasonably well with default configs. PGR4 needs a specific tweak: render_target_path_vulkan = "fsi" in the config. Without it, some tracks break with severe visual artifacts (green bars across the screen in snow races).

And PGR4 on NVIDIA has a known audio bug: XMA decoding produces intermittent garbage (open xenia-canary issue, no resolution). Not game-breaking, but annoying.

Ridge Racer 6

Ridge Racer 6 was the Ridge Racer of the 360, skipping the 7 that stayed on PS3. Pure arcade, like Ridge Racer V of the PS2. On Xenia Canary it runs with default config, no special tweak. Fun for short sessions. No video for this one in the article, but it’s in the catalog running.

PS4 on shadPS4: the state of the emulator

shadPS4 still doesn’t have a stable release. The project is under active development, the main branch changes several times a week, and “what works today” can regress on a rebase tomorrow. That said, many games already boot and run well enough. The community list is on the compatibility tracker and grows every week.

The difference between shadPS4 and the other emulators in this article is the kind of effort. PCSX2, RPCS3, Xenia are mature projects where each game has a reasonably up-to-date wiki page. shadPS4 is the opposite: you read a Reddit guide, try to reproduce, discover the guide uses a specific fork (not the official main), or a two-month-old commit, or a firmware with sys_modules symlinked in a particular way, or XML patches applied in a specific order that the author didn’t document. Reproducing a shadPS4 setup from a YouTube video is like trying to solve a Rubik’s Cube blindfolded.

But that doesn’t mean you shouldn’t try. It means you need to treat shadPS4 as a hobby, not a workflow. And if you have the patience, you can pull off impressive results.

Driveclub: the impossible, finally possible

Driveclub is my Moby Dick of emulation. It’s the only PS4 game I really want to run. Released in 2014 by Evolution Studios, had a catastrophic launch (online servers collapsed on day one), got patched over two years until it became one of the best racing games of the generation, and was discontinued by Sony when Evolution was closed in 2016. No PC port. No remaster. No sequel. Only exists on PS4.

And today, after many hours of debugging, it’s running here. Main menu loads, intro plays, races start, controller responds, audio works, daytime tracks visible, night tracks with headlights lighting the road. The video above is real gameplay, stable 30 FPS, v1.28 with DLC content accessible.

Getting here required dismantling several traps. Worth documenting, because most online guides don’t mention any of them.

Trap 1: the FMOD loop error that wasn’t FMOD

When you try to boot Driveclub on shadPS4 straight from the retail PKG, the log hits an infinite loop of:

/app0/audio/fmodstudio/masterbank.bank failed, file does not exist

The first reaction is to investigate FMOD. Some people online spent hours messing with sceFont, libtbb, sceNgs2, convinced it was an audio or HLE lib problem. None of that is the cause. The masterbank.bank file literally doesn’t exist on disk, because it’s packed inside the gameNNN.dat files in a custom Evolution Studios archive format that shadPS4’s VFS can’t read. Same story for fonts, models, shaders. All the game’s content lives inside the .dat files.

The only public tool that parses that format is Nenkai’s DriveClubFS. It’s a .NET app that reads game.ndx (the index) and decompresses the .dat files into loose files. Without that unpack, shadPS4 can’t open anything.

Build detail: the DriveClubFS project targets net9.0, and Arch has net8 and net10. You need to retarget the csproj to net10.0 before building. The exact command is documented in the repo’s docs/driveclub-shadps4.md.

Trap 2: v1.28 is a patch, not a base installer

Like every PS4 update, v1.28 is a patch that layers on top of a base install. The v1.28 PKG ships the updated eboot, new-content .dat files, and patch content (sce_sys/about/right.sprx), but no param.sfo, no disc_info.dat, no keystone. Those metadata files live in the v1.00 base — on a real PS4 they’d already be on disk from the original install.

And there’s more: v1.28’s game.ndx references both the base .dat files and the new ones. Running DriveClubFS against v1.28 alone makes the index point at files that aren’t there.

The cruelest symptom hits later: the game boots, the Qt Launcher shows the tile, you click, the loading screen comes up. Then the game decides no content “has been released yet” and asks you to download. Download obviously isn’t happening because PSN for PS4 isn’t accessible. You get stuck thinking it’s a network bug, when actually it’s missing metadata.

The correct flow is to treat v1.28 as an overlay on top of the base. First, extract the v1.00 PKG into a dedicated dir (CUSA00003.v100-working-backup/ works well, and doubles as a rollback snapshot if some experiment breaks the live install). Then extract v1.28 into staging and symlink the base’s low-index .dat files into the staging dir so DriveClubFS sees the full set. Run the unpack. You get 8018 loose files, ~47 GB.

Move that into the live CUSA00003/ dir, copy v1.28’s updated eboot and new patch content on top, then pull param.sfo, disc_info.dat, and keystone from the v1.00 base. The base’s param.sfo already has APP_VER = 01.28 recorded (because it was the version that received the patch originally), so there’s no version conflict. The v1.28 eboot reads those files and unlocks the content.

Trap 3: the 60fps XML patch produces slow-motion

There’s a community Driveclub.xml patch that makes the game render at 60fps. Intuitively, it looks like pure upside. In practice, the patch rewrites the render rate but doesn’t touch the game’s fixed logic tickrate, which is locked at 30fps. On a real PS4 Pro, the hardware reconciles the mismatch. On shadPS4, it doesn’t.

Result: the game renders smoothly at 60fps, but the physics, AI, audio, race timing all run in slow motion. You press the throttle and the car takes a perceptible two seconds to launch. Looks like a random bug until you understand the mismatch.

Disabling the XML patch is the move (just rename the file to something like .disabled). Without the patch, the game runs at native 30 FPS, same speed as a stock PS4 base. Which is what we want. If someone in the future produces a patch that moves both rates (render + logic), we’ll flip it back on.

Trap 4: pipeline cache has to be on

shadPS4’s default ships with pipeline_cache_enabled = false. On a large game like Driveclub, which has hundreds of Vulkan shaders and pipelines, that means every cold launch recompiles everything. My first launch counted ~864 shaders and ~590 pipelines being compiled in real time. The menu animated at 2-3 fps. A minute later, with everything compiled, it snapped to normal fluidity. Next launch, same from-scratch compilation cycle.

Just enable "pipeline_cache_enabled": true in the global config.json. The first session pays the one-time compilation cost, subsequent sessions read from cache and start up instantly.

Trap 5: TOML silently ignored

shadPS4 migrated from TOML to JSON for per-game configs in late 2025. If you have an old CUSA00003.toml in the custom_configs/ folder, it’s silently ignored, no warning in the log. You think your config is active, in reality you’re running all defaults.

Delete any TOML and use CUSA00003.json. The per-game configs that work for Driveclub are specific and detailed, all documented in the docs/driveclub-shadps4.md of the repo.

Trap 6: controller not detected without hidapi hints

shadPS4’s Qt Launcher calls an internal Shadps4-sdl.AppImage. Without specific SDL hidapi env vars, the controller (8BitDo Ultimate 2 in my case) isn’t detected, even though it works in every other emulator. The fix is to wrap the AppImage in a shell that exports SDL_JOYSTICK_HIDAPI=1 and platform-specific variants (PS4, PS5, Xbox), before executing the original.

Plugging the controller in before opening the Qt Launcher also helps. Hot-plug works during the game, not before.

Trap 7: night tracks are pitch black on upstream

This one needed a code patch, not just config. On upstream shadPS4, Driveclub night tracks came out pitch black. The HUD rendered on top, but the track, the car, everything hidden in absolute black. Not even the car’s own headlights lit anything up.

Investigation pointed at the log repeating 1325 times the message ResolveDepthOverlap: Unimplemented depth overlap copy. The cause: Driveclub uses a forward+ renderer, which writes scene depth into a 4x MSAA D32Sfloat buffer, then reads that same buffer as R32G32B32A32Sfloat 1x for effects like SSAO, volumetrics, and dynamic lighting (headlights). shadPS4 upstream has a path for MSAA → MSAA and for color → color as MSAA depth, but it didn’t have a path for “MSAA depth 4x becomes color 1x” in that specific format. It falls into the final else, frees the buffer, and the shader reads uninitialized memory — i.e., black.

I implemented in my local shadPS4 fork a ReinterpretMsDepthAsColor symmetric to the existing ReinterpretColorAsMsDepth. It’s a tiny fragment shader (ms_depth_to_color.frag) that does texelFetch of sample 0’s depth and writes it as vec4(depth, 0, 0, 1) to the color attachment. Plus a BlitHelper helper and a new else if branch in TextureCache::ResolveDepthOverlap. With that, night tracks light up properly, opponent headlights appear, AO and volumetrics on day scenes get more precise too.

The fix lives on a gamma-debug branch of my fork, ready to become an upstream PR. Until it merges, anyone who wants to race at night on Driveclub on shadPS4 needs to build from that branch. Anyone sticking to daytime can use upstream nightly directly.

What finally worked

All of this is encapsulated in docs/driveclub-shadps4.md in the repo, with the exact step-by-step for extraction, config, and wrapper. The full technical investigation (5 phases, detailed engineering log) lives in the fork’s driveclub-v128-investigation.md.

How playable it is today

Good. The video above is real gameplay, stable 30 FPS, physics responding, audio in sync, HUD correct, v1.28 with DLC accessible. Day races and night races both work (with the MSAA depth fork for night). What’s left as limitation:

• Daytime brightness sits a bit below what the PS4 delivered. Not an emulator bug. I spent hours testing tonemap, auto-exposure, gamma curves, ACES, various post-processing shaders, and in the end discovered the game writes already-correct SDR to the framebuffer. What was missing was the display-calibration pipeline that PS4 firmware 4.0+ applied on the outside, and that Linux doesn’t have. The in-game brightness slider (which on shadPS4 maps to sceVideoOutAdjustColor) works, but only up to the point where the game expected the firmware to pick up the rest. The 5-second dim at the start of a race is also the game’s own cinematic fade-in VFX, not an emulator fault. Accepted.
• Native 30 FPS. No viable 60fps patch (due to the fixed logic tickrate explained above). Stock PS4 speed.
• MSAA depth fix still on the fork. PR candidate ready, awaiting upstream merge.

“Achievement Unlocked”. The game runs, with sound, controller, gameplay, day and night, and I complete a whole race without crashing. That’s a personal milestone. I spent years trying to get this game running on Linux and would always hit a point where I just gave up. Now it’s part of my ES-DE, shortcut on the desktop, sitting there waiting for me to play.

If you want to replicate, the repo is public. Good luck. You’re going to need patience.

“Achievement Unlocked”

I’ve been trying to make these games work, at some level, since each respective emulator came out of alpha. I’ve been running GT2 since ePSXe. I’ve been messing with GT4 since PCSX2 0.9.6. I tried to get FM4 running on Xenia twice in past years and gave up both times. And I looked at shadPS4’s face three times before this Sunday and swallowed hard.

Today it closed. The two monsters that opened this article (Driveclub on shadPS4 and FM4 with Project Forza Plus on Xenia) are running, along with the rest of the Gran Turismo, Forza, Ridge Racer, Colin McRae, and Enthusia collection. All in a single setup, reproducible, automated. I’m now part of the very small group of people who brute-forced their way into emulating Driveclub on Linux, and that alone made the Sunday unforgettable.

The frustration of years wasn’t lack of information. It was the OPPOSITE. Too much information, poorly indexed, scattered across dead forums, YouTube videos that went stale, Reddit threads with solutions for two-year-old emulator versions that don’t apply today, wikis that are out of date on half the pages, and mods with VERY specific requirements of CRC, version, patch, path, setting. Every time I sat down to get one of these games running right, I spent three hours reading conflicting material before writing the first line of config. Worse still when the good material was buried under wrong diagnoses, like the Driveclub FMOD loop everyone investigated as if it was an audio problem when in reality it was Evolution Studios’ proprietary archive format.

What changed in the last year is that Claude Code can be my aggregator. I tell Claude to hit the Xenia issue tracker, the PCSX2 wiki, the RPCS3 subreddit, shadPS4 PRs, cross-reference all that info with the emulator version I have installed, cross-reference with the logs I’m looking at, and give me back the combination that works today. It reads source code when needed, understands why Force CPU Blit changes behavior on GT6, finds which FM4 title update was the one that fixed the shadow bug, discovers that DriveClubFS needs a retarget to .NET 10 before compiling. What used to take three weekends of research now takes an afternoon of assisted execution.

This Sunday is the consolidated result of all that work. distrobox-gaming is that knowledge turned into code, reproducible, automated. Starting on a fresh machine, one ansible-playbook site.yml puts me back in this state in under two hours. Fewer than 10 commands separate “vanilla Arch Linux” from “Driveclub running”.

If anyone wants to contribute, test on different hardware, report a bug, or send a config that’s missing, the repo is open. The more people test on different setups, the more resilient the project gets. If you improve the Driveclub situation (get the MSAA depth fix merged upstream, a 60fps patch that also fixes the logic tickrate, font dumps that don’t need jailbroken hardware), send a PR and I’ll embrace it.

For now, I’m going to do a race in Iceland on Driveclub. Good Sunday night.

⚠️ Obsolete article (updated 2026-04-24). The conclusions and rankings in this post were superseded after I re-audited the benchmark against the ruby_llm gem source. The core finding (multi-model is not worth it for greenfield coding) still holds and has been folded into the canonical post. The canonical version lives at LLM Coding Benchmark (April 2026). This post stays as a historical record.

TL;DR: Yes, the title is clickbait. The answer is no, it’s not worth it. Keep using Claude Code with Opus 4.6 or 4.7. Details below.

A few weeks ago I wrote a detailed LLM coding benchmark comparing 33 open source and commercial models on the same test: build a Rails app using RubyLLM. The conclusion was that only 4 models generated code that works on first try (both Claudes, GLM 5, and GLM 5.1), and that for anyone who doesn’t want to waste time fixing API hallucinations, Claude Opus via Claude Code remains the most rational choice despite the price.

This article is a follow-up. I’ll keep that benchmark updated as new models come out (Opus 4.7, Qwen 3.6, GPT 5.4 via Codex are already in). This one tackles a different question that shows up in my feed every week: what if I combine two models in the same project? Opus to plan, GLM to execute. Does that work?

Short answer: no, it doesn’t. Long answer is the rest of this article.

First: a word about Opus 4.7

There are people on Reddit claiming Opus 4.7 is an absurd downgrade from 4.6, that it regressed, that it “got worse at coding”. I get suspicious whenever I see “everything’s getting worse” narratives. I have hundreds of hours with Opus 4.6, and I’ve been testing 4.7 since it came out a few days ago. Quality is equal to or better than 4.6 on non-trivial tasks where I have a reference for how 4.6 used to behave.

When you see someone complaining “4.7 is terrible”, ask for the exact prompt, the repo, the context. Most of the time they can’t reproduce it, or the repo has a badly written CLAUDE.md, or the task is too subjective to measure. “Felt like it got worse” isn’t data. I got caught by that feeling myself in a 4.7 session where the context had been contaminated with a bunch of stale docs. The culprit was my config, not the model.

In the benchmarks I ran this week, Opus 4.7 on opencode delivered clean Tier 1, same level as the Opus 4.6 baseline. The tests it ran via Claude Code had a weirder story, and there the blame is likely the harness, not the model. More on that below.

What’s new in the benchmark

The benchmark now supports testing model combinations across the three main harnesses:

1. Claude Code (claude -p --output-format stream-json) — supports sub-agents declared in .claude/agents/*.md that Opus can delegate to via the Task tool
2. opencode — has its own sub-agent system that can run different models
3. Codex CLI — got sub-agent support via TOML with -c agents.<name>.config_file=...

On top of these three, I configured 7 combinations:

Each runs the same prompt: build a Rails app with RubyLLM, Tailwind, Stimulus, Turbo Streams, Minitest tests, Brakeman, RuboCop, Dockerfile, docker-compose. Same prompt as the original benchmark.

How to enable multi-model in each harness

Before showing what went wrong, it’s worth understanding how each harness exposes the sub-agent and who decides to call it. The mechanics are similar across all three, but the details matter.

Claude Code

Claude Code automatically reads files in .claude/agents/*.md from the project directory. Each file is an agent definition:

---
name: sonnet-coder
description: Claude Sonnet 4.6 for concrete coding execution. Use PROACTIVELY for any code change where the plan is already clear. Opus should plan and delegate; Sonnet should execute. Only skip delegation for cross-file architectural decisions.
model: claude-sonnet-4-6
---

You are a focused coding agent. The parent (Opus) has already decided
the approach — your job is to execute cleanly.

Rules:
- Follow the provided instructions precisely. Don't re-plan.
- Prefer editing existing files over creating new ones.
- Match the existing codebase style.
- Keep changes minimal.
- Default to no comments.

The YAML frontmatter has three required fields: name (the handle the primary model uses), model (which model runs the agent), and description (what the primary reads to decide whether to delegate). The file body is the system prompt the sub-agent receives when invoked.

To invoke, Opus uses the native Task(subagent_type="sonnet-coder", prompt="...") tool. Claude Code bills tokens to the sub-agent’s model, not the primary’s.

opencode

opencode uses a JSON config file (can be the default opencode.json or a custom one via --config). Agents live under an agents key:

{
  "model": "openrouter/anthropic/claude-opus-4.7",
  "agents": {
    "coder": {
      "model_id": "zai/glm-5.1",
      "provider": "zai",
      "description": "Use proactively for concrete coding execution...",
      "prompt": "You are a focused coding agent. The parent..."
    }
  }
}

Each entry has model_id, provider, description, and prompt. The primary model (set at the top) invokes the agent via a task tool, passing the name (coder in the example) and specific instructions.

Codex CLI

Codex uses TOML files per agent, passed via -c flags on the command line:

# .codex-coder.toml
name = "coder"
model = "gpt-5.4"
reasoning_effort = "medium"
description = "Use proactively for concrete coding execution..."
prompt = "You are a focused coding agent. The parent (xhigh)..."

And invoked:

codex exec \
  --dangerously-bypass-approvals-and-sandbox \
  -c model_reasoning_effort=xhigh \
  -c agents.coder.config_file=.codex-coder.toml \
  -p "<main prompt>"

The primary model gets access to the spawn_agent tool to invoke the coder. Codex lets you configure a different reasoning_effort for the primary and the sub-agent, which is exactly what the multi_balanced and multi_faster variants test.

Who decides which model runs each task

In all three harnesses, the decision to delegate is made by the primary model at runtime, not by a programmatic rule. There’s no deterministic heuristic like “if the file is larger than X lines, call the sub-agent”. What exists is the primary model reading the sub-agent’s description and judging, step by step, whether the current task fits.

Three consequences:

1. The sub-agent description is the only control knob. If you write “use PROACTIVELY for X” without caveats, the model tends to delegate more. If you add “skip for Y”, it tends not to delegate on Y.

2. The primary model is conservative by default. Across all three, current training favors not delegating when the task needs cross-file context or architectural decisions. A greenfield Rails app is exactly that kind of task.

3. You can’t force delegation via config. You can write an aggressive description, but if the model judges the task doesn’t fit, it ignores the sub-agent. No --force-subagent flag exists. The call is the model’s, not the operator’s.

Matters for what comes next.

The finding that kills the argument

I opened the logs of each run expecting to see delegation happen. Tools like Task (Claude Code) or spawn_agent (Codex) should show up in the ndjson every time the primary model calls the sub-agent.

Across 7 runs, the delegation tool was called zero times. No Opus called Sonnet. No Opus called Haiku. No Opus called GLM 5.1 or the local Qwen 3.6. No GPT xHigh called GPT medium or low.

All primary models did the entire job alone, ignoring the sub-agent that was registered and visible to them. The sub-agents were read, parsed, listed, and never invoked. It’s like hiring an assistant and letting them sit at their desk all day while you do everything yourself.

Why did this happen? Two layers of explanation.

The technical layer

The primary models read the sub-agent descriptions and decided the task didn’t fit. Descriptions typically said “use proactively for concrete code execution” with a caveat “skip for cross-file architectural decisions”. Except an entire Rails app is cross-file architectural decision. Controller depends on service, service depends on initializer, view depends on partial, all depend on how tests mock the LLM. There’s no isolated piece you can hand off to a dumber executor without losing context.

I could have written the sub-agent description more imperatively, forcing delegation. But that would be cheating to get a result. The point of the test is to see what the model does freely, not what it does under force. And freely, it didn’t delegate.

The management layer

Delegation has coordination cost. That’s basic project management knowledge, not news. When you outsource a task, you have to:

• Write a clear spec for the other executor
• Wait for the result
• Review
• Request adjustments if there’s a gap between what you wanted and what came back
• Reintegrate into the rest of the work

For seniors outsourcing to juniors, that cost is real. Productivity doesn’t scale linearly with the number of executors. Doubling the team doesn’t double speed. In many cases, outsourcing costs more time than doing it yourself would have.

With LLMs the same thing happens, compounded by a specific trait: Opus’s planning is rarely perfect on the first try. Never is. Opus reads the prompt, builds a plan, starts implementing, hits a problem (library that doesn’t have that version, method that doesn’t exist as it imagined, test that fails for a reason it didn’t anticipate), adjusts the plan, tries again. That “plan → try → adjust” loop is inherent to the work. Not an Opus failure, it’s the nature of software development.

Now imagine you insert a smaller model in the middle of that loop. Opus plans, hands off to Qwen to execute, Qwen writes code that likely hallucinates the API (as we saw in the previous benchmark, Qwen invents RubyLLM::Client.new which doesn’t exist), Opus gets the code back, finds it’s wrong, has to make a sub-plan to fix it, hands back to Qwen, which invents something else, and on it goes. The communication and correction overhead explodes.

That’s why the models themselves, without being forced, decided not to delegate. They know the coordination cost outweighs the benefit, especially for a cohesive task like building a Rails app from scratch.

Notes per run

Even without delegation happening, the 7 runs produced different results. Let me comment on each.

Claude Code: Opus 4.7 alone

11 minutes, $6.74, 24 tests, 1742 files. Result Tier 3 (broken). Opus in this run hallucinated the chat.complete method on RubyLLM, which doesn’t exist, and used chat.add_message(role:, content:) with keyword args instead of a positional hash. Same typical hallucination other models have, now from Opus itself. Weird, because the same Opus 4.7 on opencode delivered correct Tier 1 code on the same prompt.

Claude Code: Opus 4.7 + Sonnet 4.6

10 minutes, $5.13, 18 tests, 1829 files. Result Tier 2 (first message works, multi-turn breaks). Better than the Opus-alone baseline, but still has the keyword-args bug on add_message. Zero delegations to Sonnet.

Claude Code: Opus 4.7 + Haiku 4.5

15 minutes, $7.83, 34 tests, 1984 files. Result Tier 3, same hallucination as Opus alone. The highest test count (34!) all pass because the test fakes mock the hallucinated API Opus itself invented. Tests that prove nothing.

The point worth underlining: Opus 4.7 on Claude Code wrote 34 passing tests, and none of them prove the code works. The hallucinated API is tested against a hallucinated implementation. In the real world, the app crashes on the first message. Test count is a vanity metric when the mock is wrong.

opencode: Opus 4.7 + GLM 5.1

19 minutes, $1.10, Tier 1 (works on first try). Correct RubyLLM API. Both phases (build + Docker validation) completed clean. Zero calls to GLM 5.1, Opus did everything.

opencode: Opus 4.7 + local Qwen 3.6

30 minutes, $1.10 (only Opus billed, local Qwen is free), Tier 1. Same quality as above. Zero calls to the Qwen 3.6 running on the 5090.

Codex: xHigh planning, medium executing

21 minutes, ~$11, Tier 1. The most expensive multi-agent run on the Codex side, but curiously the one that generated the best code, and fixed the add_message bug the previous benchmark caught on GPT 5.4 alone. But zero delegations, all the work came from xHigh.

Codex: xHigh planning, low executing

20 minutes, ~$10, Tier 2. Reproduced the keyword-args bug. Cheaper than the above but worse code. Zero delegations to low either.

Same model, different runs, different results

Here’s the real story of this benchmark, which becomes clearer when you group by model instead of by combination.

Since the sub-agents never ran, each “multi-model” combination effectively became another run of the primary model. That gave me something I didn’t have in the previous benchmark: multiple runs of the same model on the same prompt. Let me compare.

GPT 5.4 xHigh: three runs

In last week’s benchmark, GPT 5.4 via Codex with xHigh ran once, scoring Tier 2 (first message works, multi-turn breaks due to chat.add_message(role:, content:) with keyword args instead of positional hash).

This week I ran two more, with different sub-agent configurations (which weren’t used, but the presence changes the primary’s behavior, as I showed above):

Same model, same prompt, three runs. One of them wrote chat.add_message(message) with positional hash (Tier 1, works in multi-turn). The other two wrote it with keyword args (Tier 2, breaks on the second message).

No sub-agent was called in any of the multi variants. The only thing that changed between the three runs was the text of the available sub-agent description (or its absence). Even so, that GPT 5.4 “got” the API right in one run and “got it wrong” in the other two.

Claude Opus 4.7: six runs

With Opus it was even more instructive. Six different runs, same model, same prompt, results spread from Tier 1 to Tier 3:

The three Opus runs on opencode: consistent Tier 1. Correct RubyLLM API, works in multi-turn, clean code.

The three Opus runs on Claude Code: one Tier 2 and two Tier 3. Code that hallucinated chat.complete (method doesn’t exist) or got the add_message signature wrong.

Same model. Same prompt. Different harness = different result.

What that means

Two possible readings:

The lazy reading: “Opus 4.7 on Claude Code regressed, switch to 4.6” or “opencode is better than Claude Code”. Both would be wrong conclusions from such a small benchmark.

The honest reading: a single-run benchmark, or even three runs, isn’t enough to assert anything about the absolute quality of a model. Variance is high, the context loaded by the harness (CLAUDE.md, tool schemas, agent registries) shifts the “mental model” the model activates, and the result can swing between tiers.

In the previous benchmark, I got lucky (or unlucky) with runs consistent enough for hierarchies like “Claude/GLM work, Kimi/DeepSeek/Qwen hallucinate the API” to hold. But even there, run-to-run variance is real. If I run Kimi K2.5 ten times, maybe two or three of those runs would hit the API right. I didn’t test this, but it’s plausible.

This benchmark reinforces the point: the rankings in the previous article count as signal, not proof. “Works on first try 80% of the time” is different from “always works”. For production use, you want a model robust to variance, one that doesn’t have a 20% chance of returning hallucinated code. Today, the only models that meet that bar for me are Claude Opus and Claude Sonnet, on any harness. GLM 5.1 is close but I don’t have a large sample yet.

Does that mean Opus 4.7 “got worse”? No. Does it mean Claude Code “is worse than opencode”? No. It means a single-run benchmark on a greenfield Rails app doesn’t capture model variance. Worth knowing before jumping to strong conclusions.

Execution time: is multi-model slower?

Adjacent question worth measuring: if the sub-agent never ran, were the multi-model runs slower than the alone baselines? My initial intuition was yes, since without cross-session parallelism the primary model does the work serially. The data tells another story.

Some multi-model runs were faster than the alone baseline. opencode + GLM 5.1 was almost half the time of opencode alone (10m vs 18m). Claude Code + Sonnet was 1 minute faster than pure Opus. Codex multi-agent variants ended up slightly faster than xHigh alone.

Others were slower: Claude Code + Haiku took 15m (4m more than baseline). opencode + Qwen 3.6 ran 19m (same as baseline, likely penalized by llama-swap overhead even without invoking the model).

No consistent pattern of “multi-model is always slower” or “always faster”. What happened, looking at tool calls and test counts, is more interesting: the primary model changes its own behavior when it sees a sub-agent is available, even without calling it.

• Claude Code Opus alone: 24 tests, 11m
• Claude Code Opus + Sonnet: 18 tests, 10m (fewer tests, faster)
• Claude Code Opus + Haiku: 34 tests, 15m (more tests, slower)

The pattern: when the sub-agent exists in the description as “executor”, the primary model sometimes produces leaner output, as if “leaving work for later”. When the sub-agent describes more expensive execution (Haiku as “high-volume execution”), the model seems to assume it can afford to write more tests because “the cheap executor will handle it”. The executor is never called in either case. But the sub-agent’s presence influences the primary’s planning.

Subtle effect, like a delegation placebo. The model doesn’t delegate, but behaves as if it would. It can be good (more focused output) or bad (lower test coverage than baseline). Not something you control, it’s emergent behavior from the model reading the sub-agent description.

So is it worth configuring Haiku just for the placebo?

You might be tempted: “if Opus wrote more code and more tests with Haiku configured, then it’s worth configuring Haiku as a sub-agent even if it never runs, just for the placebo”. The numbers say no.

Comparing Opus alone vs Opus with Haiku configured, both on Claude Code:

With Haiku configured, Opus spent 3.7 more minutes, $1.09 more, and wrote 10 more tests. The quality tier stayed the same. The same chat.complete hallucination appeared in both runs. The 10 extra tests mock the same hallucinated API, so they prove nothing the original 24 weren’t already proving. More code, not better code.

Delegation placebo can shift quantity but doesn’t fix factual errors. And with a sample of 1 run each, even the quantity increase isn’t reliable, because Opus-alone run-to-run variance is also high (probably another Opus-alone run would hit 30+ tests by chance).

Practical takeaway: don’t configure a “fake” sub-agent just to try to manipulate the primary. The cost in tokens/time is certain, the benefit is speculative. Opus alone, no sub-agent, stays the recommended default configuration. Sub-agents are only worth it when you have a real delegation use case that works (and we saw here that greenfield isn’t one).

“Multi-model is slower” hypothesis doesn’t hold

Back to the original question: no, you can’t say multi-model without delegation is consistently slower. Sometimes it is, sometimes it’s faster, depends on the model and the sub-agent description. What you can say is that the sub-agent’s presence shifts the primary’s behavior in unpredictable ways, and that alone is an argument against multi-model configurations with no clear need.

Two unexpected findings

Outside the main topic (multi-model didn’t work), two patterns showed up.

First: the harness affects code quality, not just cost

The same Opus 4.7 produced Tier 1 on opencode and Tier 2/Tier 3 on Claude Code, same prompt. That’s new. As far as I know, this is the first benchmark evidence that the harness (the CLI wrapping the model) can degrade factual correctness, not just cost.

The hypothesis is that Claude Code carries 6-11 million cache-read tokens per run (CLAUDE.md, tool schemas, agent registries, etc.), against opencode’s ~210 thousand. That volume of context seems to pull Opus toward a generic OpenAI SDK “mental model”, where chat.complete makes sense, instead of the specific mental model for the RubyLLM gem. Speculation on my part, I can’t prove it. But the Tier difference between the two harnesses running the same model is concrete.

This does not mean opencode is better than Claude Code for daily use. In my day-to-day, Claude Code with Opus beats opencode on almost everything: editor integration, long-session context management, native tool support, multi-step planning quality. The benchmark has a narrow scope (greenfield Rails app, specific prompt, no human iteration) that doesn’t reflect real use.

What the data says: variance between harnesses is real and measurable. Worth keeping in mind when you’re evaluating a model.

Second: cost of Claude Code vs opencode

Running the same Opus 4.7 on the same prompt:

• Claude Code: $5 to $8 per run
• opencode: $1.10 per run

Claude Code costs 5 to 7 times more per run on the same model. The difference is cache-read: Claude Code loads 6-11M context tokens per run, opencode loads ~210K. There’s a legit technical reason (tool schemas, TodoWrite, agent registries, CLAUDE.md, editor integration), but the overhead is real and shows up directly on the bill of anyone paying per token.

Worth a more refined take here, because this changes the calculus depending on how you consume.

If you’re on Pro or Max: use Claude Code. Period. Subscription covers the tokens, you get the full feature set (native tool support, skills, agents, Plan mode, better long-session context). No reason to switch.

If you pay per token directly through the API, the math changes with volume.

For light use (a few hundred dollars a month): opencode with Opus is cheaper, and in this specific benchmark hit Tier 1 while Claude Code landed in Tier 2/3. Works well for automated pipelines, CI, benchmarks, server-side agents.

For heavy use (thousands of dollars a month on API): staying on per-token doesn’t make sense. The Max 20x subscription at $200/month covers heavy volume and includes Claude Code. For a heavy vibe-coder, Max is cheaper than Opus on API by a wide margin. Then you’re back in the first bucket, on Claude Code.

Opencode is better, regardless of cost, for:

• Headless or automated use (CI, benchmarks, server agents)
• Multi-provider setups where you want the same harness hitting OpenRouter, Z.ai, and local llama-swap
• When you need structured JSON output (--format json)
• Neutral model comparisons

Claude Code is better, regardless of cost, for:

• Interactive coding sessions with a human in the loop
• Projects with CLAUDE.md, skills, custom MCP
• Work where Opus’s Plan mode matters
• Long iterative sessions where accumulated context helps

Honest reading: this benchmark measures a narrow scenario (greenfield, one-shot, no human iteration). For real daily work, Claude Code with Max remains the recommendation for 99% of people. Opencode’s cost win shows up in a specific niche (automated pipelines or per-token API use below the Max break-even). Most people aren’t in that niche.

The “Opus plans, Qwen executes” myth

Every so often someone on Twitter talks about setting up a pipeline where Opus makes the detailed technical plan and a smaller model (Qwen, GLM 5, Haiku, Sonnet) executes. “Save tokens, same quality, everybody wins”.

Doesn’t work. Or rather, works for a demo, doesn’t work for a real project.

The most serious problem is that the plan is never perfect on the first pass. Code is never one-shot. You implement, find a problem, adjust. With one big model, that adjustment happens in real time by the model itself. With two models, every adjustment has to go back to the planner, be reprocessed, a new plan written, a new executor invoked. The loop is slower.

Then there’s the question of factual API knowledge. If Opus’s plan says “use RubyLLM to call OpenRouter”, Opus knows it’s RubyLLM.chat(model:).ask(msg).content. The smaller Qwen reads the plan and implements with the API it thinks exists, which may be RubyLLM::Client.new.complete. The plan doesn’t correct this because the plan doesn’t carry the gem’s factual knowledge. Only the model that knows that API can implement it correctly.

And then there’s coordination cost, which explodes with iteration. Every round of “plan → execute → fail → re-plan → execute again” costs more tokens than just letting the big model do everything in one session. You pay in planning tokens AND in wrong-code tokens that need to be rewritten.

In theory, multi-model makes sense. In practice, it’s work for a Twitter thread with pretty animations, not the workflow of someone who ships code.

When multi-model can make sense

I don’t want to sound absolute. There are scenarios where multi-model is the right pick.

The main one is genuinely parallel and decoupled tasks. API migration across 30 identical files, for example: each file follows the same pattern, no dependencies between them. Opus could supervise 20 sub-agents doing the same transformation on 20 different files. In that case, the coordination cost is amortized by the parallelism.

Another is tasks with a heavy research phase followed by a direct implementation phase. Opus does the architectural spike exploring legacy code, then delegates the mechanical implementation to the smaller model.

A real example I went through last week: I translated 700+ posts and all the video subtitles of the blog to English using Claude Code. I burned through the Max 20x and blew another $1120 in extra usage on top. Translation is exactly the kind of task that would have benefited from multi-model: each post is independent of the others, no cross-file dependency, zero architectural planning, just batch translation. Opus orchestrating + Sonnet executing each file’s translation would have cut the cost in half, easily. Didn’t occur to me at the time, I ran everything on Opus. The lesson I take: for genuinely parallel tasks, multi-model with Sonnet as executor makes sense, and I missed a clear chance to save money.

But neither of the cases above is “greenfield Rails app”. A new app from scratch is the worst scenario for multi-model because every part depends on every other part. The models aren’t dumb, they recognize this and refuse to delegate.

The rule of thumb stays the same

For 90% of day-to-day programming work, my recommendation remains:

• Claude Code + Opus (4.6 or 4.7)
• If cost is critical and you’re OK plugging into OpenRouter, GLM 5.1 is a comfortable second place
• If you have good GPU (5090 or equivalent), local Qwen 3.6 35B is acceptable for simple tasks, with caveats

Multi-model? Only for specific cases where the parallelism is genuine. For normal projects, it’s unnecessary overhead.

Benchmarks aren’t absolute truth

This benchmark measures a specific thing: greenfield Rails app, deterministic prompt, no human iteration, in automated runners. A narrow slice of real use.

If you want to know which combination works for YOUR workflow, YOUR types of projects, YOUR quality expectations, don’t trust my benchmark. Run your own. The code is all on GitHub, the harness is extensible, you swap the prompt and you have your own comparison.

What I hope this work contributes is methodology, not a definitive answer. “Claude is better than Qwen” depends on what you’re doing. “Multi-model doesn’t work” depends on the type of task. Benchmarks narrow the space for speculation with concrete data, they don’t close the discussion.

Meanwhile, if someone tells you they combined Claude + GLM and it was magical, ask for the code, the prompt, the repo. Most of the time they measured something quite different, or have a specific task where that combination fits. Don’t generalize from a tweet.

I bought a Lenovo Thinkpad T14 Gen 6 and installed Omarchy on it. It’s not my main machine, and it’s not supposed to be. It’s a companion: a notebook I can open on the 3D printing office desk, SSH into the desktop, fire up Claude Code, access files on the NAS, debug the network through ethernet without hunting for a USB dongle and a long cable. This article covers the hardware choice, the Omarchy setup on top, the customizations specific to a laptop and to this Thinkpad in particular, and the architecture decisions that might not be obvious.

Mini-review of the Thinkpad T14 Gen 6

Let’s get this out of the way: this isn’t the notebook of my dreams. If I were picking by looks, I’d grab an Asus Zenbook S 14 with an OLED screen. If I were picking by portability, the Thinkpad T14s with the aluminum shell, which is lighter and much better looking. The regular T14 has a 14" 1920x1200 IPS panel, 400 nits, 60Hz, no HDR. It gets the job done, but it’s a far cry from the Zenbook’s screen. The shell is plastic with a rubberized finish, which makes it scratch-resistant but not premium. Reviews from NotebookCheck and XDA Developers land on the same verdict: good price, good connectivity, fine performance for office work, but the screen is dated.

What makes up for it:

• Port selection. Full-size HDMI. Gigabit ethernet. USB-A, USB-C Thunderbolt 4, charges over USB-C (not a proprietary charger). For a debug companion, this is exactly what I wanted. The Zenbook S 14, being thinner, cuts ports.
• Fingerprint sensor that actually works on Linux (Goodix MOC, works with libfprint on kernel 6.11+). I use this, details later.
• Thinkpad keyboard. 1.5mm key travel, trackpoint, classic layout. It’s not the best keyboard in the world in 2026, but it’s reliable and durable.
• Rugged shell. It will fall, it will scratch, it will travel in a backpack. If I put a Zenbook OLED or a Macbook Pro on the 3D printing office desk next to the printer with PLA dust in the air, I’d be nervous. The Thinkpad can take a beating.

If I wanted a gaming machine, I’d get an Asus Zephyrus G14, my favorite gaming notebook. If I wanted a creative work machine, I’d get the Asus Zenbook Duo (UX8406) with two vertical OLED screens, great for video editing and 3D modeling. I can afford any Macbook Pro or Mac Studio, and I chose not to go that way. I’ll explain in the next section.

My use case

My main PC is a desktop with Ryzen 9 7950X3D, 96 GB of RAM, RTX 5090 with 32 GB. That’s where I work, experiment with local models, run containers, edit the blog. For gaming, I have a separate mini-PC with an RTX 4090. Those two cover 100% of what I need to do at home.

The notebook exists to cover the remaining 1%: sitting on the couch, taking it to the 3D printing office, taking it to the kitchen, short trips. It’s not meant to replace the desktop. It’s meant to give me remote access to the desktop when I’m away from it.

In practice it looks like this: open the notebook, split the Hyprland layout, left pane SSHs into the main desktop, right pane is the notebook itself. Same Omarchy on both, same keybindings, same bash. The notebook becomes an extension of the desktop, not a parallel environment I have to re-learn in my head every time I switch.

SSH from outside the house: Tailscale

Inside the local network, SSH is trivial, the notebook talks to the desktop through the internal IP. Outside the house is another story. My home IP is dynamic, opening port 22 to the internet is a terrible idea, and even with DDNS and port forwarding you’re putting SSH on the public internet for any scanner to find.

The solution I use is Tailscale. For those who don’t know: Tailscale is a mesh VPN built on WireGuard that creates a private network between your devices (the “tailnet”). Each machine runs the agent, authenticates once, and gets a fixed IP on the private network (something like 100.x.y.z). Traffic between your own devices goes peer-to-peer, encrypted by WireGuard. It doesn’t route through Tailscale’s central server, they only coordinate NAT traversal. Result: from my notebook in a café anywhere in the world, I run ssh hal9000 and land on my home desktop as if I were on the same network.

More sophisticated options exist: Cloudflare Tunnel with Zero Trust to expose services publicly with SSO auth, self-hosted headscale, raw WireGuard with manual config, Nebula, OpenVPN. Each has its use case. If you need to expose services to third parties, control granular per-identity access, or run the whole infrastructure at home without depending on anyone, those options win. In my case, it’s just notebook talking to desktop, for short periods (it’s not a full week of work, it’s a weekend debug session), so free Tailscale covers it. The free tier accepts up to 100 devices and 3 users, way more than I need.

Setup is as simple as it gets:

# On Arch/Omarchy
sudo pacman -S tailscale
sudo systemctl enable --now tailscaled.service
sudo tailscale up --ssh

The --ssh flag enables Tailscale SSH, which authenticates via tailnet identity instead of a local SSH key. Once you log in through the browser to tailscale, each registered machine can SSH into the others based on ACL policy defined in the admin panel. Zero key management.

I repeat the same on the desktop, log in with the same account, done. Both machines show up in the panel (hal9000 and hal9666 in the screenshot above, both with SSH enabled). From the notebook: ssh hal9000. From the desktop to the notebook: ssh hal9666. No port forwarding, no public IP, no port 22 exposed to the internet. If the notebook is stolen, I remove it from the tailnet with one click.

A practical detail: since the tailnet gives stable names, I added entries to ~/.ssh/config to use these short names:

Host hal9000
  HostName hal9000
  User akitaonrails

Now ssh hal9000 works from anywhere that has Tailscale connected. It’s the closest thing to “it just works” I’ve seen for remote SSH.

Why not a Mac

I have no use for macOS. As a dev, I live better in native Linux. Every tool I need has a first-class Linux version, and on macOS I’d get a second-class version via Homebrew. I don’t do iOS, so I don’t need XCode. For mobile I use Flutter or Hotwire Native, which run on any OS. iTerm2 and Ghostty on Mac are fine, but Alacritty, Kitty and Ghostty itself on Linux work just as well. Every good piece of software lands on Linux first and gets ported afterwards. Arch with AUR covers everything in a single yay.

For creative work, I haven’t done it professionally in years. DaVinci Resolve Studio on Linux is better than Final Cut Pro. Krita or Affinity Photo replace Photoshop for most cases. Clip Studio Paint on Android is better than Procreate. I simply don’t have a workflow that depends on Apple, and the App Store annoys me.

For gaming, Mac is terrible. Apple Silicon has a decent GPU for some things, but the native macOS game library is pathetic compared to Windows or Linux. Game Porting Toolkit exists, CrossOver exists, but for anyone who games seriously, it doesn’t cut it. I won’t be gaming on the Thinkpad, I have the main desktop and the mini-PC with the RTX 4090 for that. But if I ever feel like running Hollow Knight or some indie on a train, I just install Steam and let Proton handle it. Linux became a real gaming platform in the last few years, with Proton/DXVK running almost the entire Steam catalog (check ProtonDB). I recently wrote about running my emulation library in distrobox without polluting the host system. With Mac, those options don’t exist.

Another argument that always shows up: “but a Mac Mini M4 or a Mac Studio with 128GB of unified memory runs large models locally, it’s a ChatGPT replacement.” I already tested that thesis and wrote a detailed benchmark. The conclusion: expensive local hardware to run LLMs is a weekend hobby, not a production tool. The open source models that fit don’t deliver the quality Claude Opus delivers. I have a home server with AMD Strix Halo and 96 GB of unified RAM, I ran models for dozens of hours, and in my real coding flow they’re fine for simple tasks. For complex tasks, Claude Opus. Before spending $4000 on a Mac Studio justifying it with local models, actually test it first. You’ll probably end up paying for Opus again.

Why Omarchy

I’ve been using Omarchy on the desktop for months and documented the path in a series of articles. Omarchy 2.0 has its own installer with LUKS, Btrfs, Limine, snapper and SDDM already configured. I wrote about using the official ISO, about ZSH customizations with atuin, starship, secrets properly organized, about Mise for multiple languages, about LazyVim and LazyExtras, about SSH and Yubikeys, about modern TUIs. There’s also Omarchy 3 with dual GPU AMD + NVIDIA and Crush as a coding agent.

For those who don’t know: Omarchy is plain Arch Linux with a cosmetic layer on top of Hyprland/Wayland. Pre-configured with sane defaults. I could build all of it from scratch, I’ve done it several times in my life, but why redo work someone already did well? I install Omarchy, I stack the tweaks that are mine on top, and I have customized Arch in a fraction of the time.

A point I raise every time I recommend Omarchy: the documentation is excellent. There’s an official manual covering everything from installation to theme customization, keybindings, Hyprland, Waybar, the works. If you’re coming from Ubuntu or Fedora and are wary of Arch, this manual handles most of the doubts. If you’ve never touched Hyprland, open it and read around. It’s not a README dumped on GitHub, it’s a real manual with chapters and an index.

The story of this article starts in a previous thread. I recently migrated my home server, swapping an old Ubuntu box for a Minisforum MS-S1 running openSUSE MicroOS configured with Claude Code. That was the first serious experiment of letting Claude Code drive an entire infra migration, with containers, NFS, services, networking. It worked. And it left an idea in the air: why not use the same approach to configure a new notebook?

That’s what I did. I grabbed the Thinkpad, downloaded the latest Omarchy ISO, burned it to a flash drive, installed it over Windows. From zero to working desktop in under an hour. From there on, it’s all tweaking, which I documented as I went.

I’ll detail the two layers of customization: what any notebook needs, and what’s specific to this Thinkpad.

Laptop-specific configs

A notebook has problems a desktop doesn’t: battery, suspend, lid, brightness, trackpad. Those are the parts Omarchy default doesn’t cover the way I want.

Power management with TLP

Omarchy defaults to power-profiles-daemon. I swapped it for TLP, which gives granular control over CPU scaling, battery thresholds and dynamic profiles based on AC vs battery.

sudo pacman -S tlp tlp-rdw
sudo systemctl mask power-profiles-daemon.service
sudo systemctl enable --now tlp.service

The mask is necessary because upower pulls power-profiles-daemon back in if you just disable it.

Charge thresholds: 60% to start, 85% to stop. The notebook spends most of its time plugged in on the office desk, and keeping the battery at 100% 24/7 wrecks capacity over time. With 60/85, the battery spends most of its time in the healthy lithium range and still has decent usable capacity.

Profiles: balanced with balance_power on battery, performance on AC. TLP’s low-power was too aggressive on the Core Ultra 5 235U, window and terminal response became noticeable. Balanced gives the best consumption/responsiveness ratio for normal use.

There’s a gotcha: tlp auto after tlp ac doesn’t always re-apply the battery profile. I wrote a small script bound to Super+Ctrl+P that reads the current state and calls tlp bat or tlp ac explicitly:

#!/bin/bash
set -euo pipefail

profile=$(cat /sys/firmware/acpi/platform_profile 2>/dev/null || echo unknown)
on_ac=$(cat /sys/class/power_supply/AC*/online 2>/dev/null | head -1 || echo 0)

if [[ "$profile" == "performance" ]]; then
  if [[ "$on_ac" == "1" ]]; then
    sudo /usr/bin/tlp auto >/dev/null
    label="Plugged in — back to AC auto"
  else
    sudo /usr/bin/tlp bat >/dev/null
    label="On battery — normal profile"
  fi
  notify-send -t 2000 "Performance mode: off" "$label" 2>/dev/null || true
else
  sudo /usr/bin/tlp ac >/dev/null
  notify-send -t 2000 "Performance mode: on" "Forcing AC profile" 2>/dev/null || true
fi

In waybar, a custom module custom/perf shows the current state (󰓅 PERF, 󰌪 ECO, or empty for balanced) and accepts a click to toggle. The output script is tiny:

#!/bin/bash
p=$(cat /sys/firmware/acpi/platform_profile 2>/dev/null)
case "$p" in
  performance) printf '󰓅 PERF' ;;
  low-power)   printf '󰌪 ECO'  ;;
  balanced|"") printf ''       ;;
  *)           printf '%s' "$p" ;;
esac

Suspend, hibernate, and the lid

This is what changed compared to the notebooks I used in 2015. The T14 Gen 6 closes the lid, suspends, and wakes up when you open it. No bug, no weird delay, no needing to log in again mid graphical session. Hyprlock kicks in after the suspend, accepts fingerprint or password, and brings me back to the desktop in seconds. This is the behavior Apple has had for years and that on Linux used to be an adventure. In 2026, on modern hardware with kernel 6.11+, it just works.

Mem sleep mode is s2idle (no deep sleep). Hibernation is enabled via a ~30 GB Btrfs swapfile and resume=/dev/mapper/root resume_offset=... on the Limine kernel cmdline. I rarely use it, but it’s there.

Hypridle has aggressive timeouts for a laptop:

• 2.5 min → screensaver
• 5 min → lock
• 5.5 min → DPMS off + keyboard backlight off

After lock, another 5 min and the screen turns off completely. On unlock, it restores screen and keyboard brightness to the previous level. These timings are much shorter than on the desktop (20-40 min there). The battery difference over a day is measurable.

Brightness and keyboard backlight

brightnessctl controls both. Fn+Space toggles the keyboard backlight across three levels. Hypridle saves the current level before turning off and restores it on resume. Command I use in the script:

brightnessctl -sd '*::kbd_backlight' set 0    # save and turn off
brightnessctl -rd '*::kbd_backlight'          # restore

Touchpad

In hypr/input.conf:

touchpad {
    natural_scroll = true
    clickfinger_behavior = true
    disable_while_typing = true
    scroll_factor = 0.4
}
gesture = 3, horizontal, workspace

clickfinger_behavior swaps the 2-finger click as right-click (more comfortable than hitting the lower-right zone). disable_while_typing is basic palm rejection. Three-finger horizontal swipes switch workspaces, the most useful gesture in Hyprland.

Thinkpad-specific configs

This is what’s specific to this model. Some things modern Linux handles on its own, others need explicit configuration.

Fingerprint sensor

Goodix MOC 27c6:6594, works with libfprint 1.94.9+ on kernel 6.11+. Package is fprintd.

sudo pacman -S fprintd
fprintd-enroll                        # right index finger by default
fprintd-enroll -f left-index-finger   # other finger

To make sudo accept fingerprint, I added auth sufficient pam_fprintd.so above the pam_unix.so line in /etc/pam.d/sudo. With sufficient, if the fingerprint passes, it authenticates directly. If it fails or I hit ESC, it falls back to the password prompt. This is genuinely worth it: dozens of times a day, sudo pacman -Syu or sudo systemctl restart something, and I just touch the sensor.

On hyprlock, I use hyprlock’s native configuration, not PAM:

auth {
    fingerprint {
        enabled = true
        ready_message = Scan fingerprint or type password
        present_message = Scanning...
        retry_delay = 250
    }
}

The PAM path gives a double prompt. Configured natively, hyprlock accepts fingerprint or password, whichever succeeds first unlocks.

On SDDM (initial login), I kept password only. The reason: the login password unlocks the GNOME keyring, and the fingerprint can’t provide plaintext for that. Once the keyring is unlocked, hyprlock can use fingerprint without issues.

In practice, sudo looks like that. Touch the sensor, authenticate, move on.

Brazilian Thinkpad keyboard

The Brazilian Thinkpad keyboard has an annoying quirk. The /? key sits where the right Ctrl would be (keycode 97), not in the traditional ABNT2 AB11 position (keycode 89). If you use the standard br(abnt2) layout, that key is inaccessible. It literally prints nothing.

The solution is the br(thinkpad) variant that exists in /usr/share/X11/xkb/symbols/br:

xkb_symbols "thinkpad" {
    include "br(abnt2)"
    name[Group1]="Portuguese (Brazil, IBM/Lenovo ThinkPad)";
    key <RCTL> { [ slash, question, degree, questiondown ] };
};

In hypr/input.conf:

kb_layout = br
kb_variant = thinkpad
kb_model = thinkpad60

And system-wide for TTY/X11:

sudo localectl set-keymap br-abnt2
sudo localectl set-x11-keymap br thinkpad thinkpad60

I wrote a small Python that reads raw scancodes from /dev/input/event* to diagnose these quirks. Useful when a key decides not to work and you need to find out if it’s hardware, kernel, or xkb.

Input method: fcitx5

Alongside the layout I install fcitx5. Input method, for those who don’t know, is the layer that turns a key sequence into characters. It handles deadkeys (tilde for nasalization, acute accent, circumflex), composing characters that aren’t on the keyboard (ç, Ç, uppercase accented letters), emoji support. In Qt or GTK apps, the input method also drives context menus for cedilla and accents.

Packages:

sudo pacman -S --needed fcitx5 fcitx5-configtool fcitx5-gtk fcitx5-qt

And the environment variables for toolkits to find fcitx5. I created ~/.config/environment.d/fcitx.conf:

INPUT_METHOD=fcitx
QT_IM_MODULE=fcitx
XMODIFIERS=@im=fcitx
SDL_IM_MODULE=fcitx

systemd’s environment.d is loaded before graphical sessions, so Brave, Alacritty, VS Code and any GTK/Qt app pick it up automatically. I enable autostart in Hyprland:

exec-once = fcitx5 -d

Typing ~a produces ã, 'e produces é, ç works as it should in every app. On a Brazilian Thinkpad keyboard, this is the difference between typing Portuguese naturally or hunting for each character.

SOF audio

Realtek ALC3306/ALC287 codec via Sound Open Firmware. Without sof-firmware, the kernel module loads but the DSP never boots and PipeWire silently falls back to auto_null. Result: you think the speaker is on mute, but actually PipeWire has no device at all.

sudo pacman -S --needed sof-firmware alsa-ucm-conf pipewire pipewire-pulse wireplumber

If you need to force SOF instead of legacy HDA:

echo "options snd-intel-dspcfg dsp_driver=3" | sudo tee /etc/modprobe.d/alsa.conf

Reload without reboot:

sudo modprobe -r snd_sof_pci_intel_mtl
sudo modprobe snd_sof_pci_intel_mtl
systemctl --user restart wireplumber pipewire pipewire-pulse

Firmware updates via fwupd

fwupdmgr update works, but with Limine there’s a gotcha: fwupd tries to write to /boot/EFI/systemd/ or /boot/EFI/arch/, which don’t exist. The workaround:

sudo mkdir -p /boot/EFI/arch
sudo fwupdmgr update -y --no-reboot-check
fwupdmgr get-history  # should show "Success"

HiDPI / fractional scaling

14" panel at 1920x1200, Hyprland’s free resolution. Omarchy’s auto 1.5x felt too chunky. I pinned it at 1.333x:

env = GDK_SCALE,1
monitor=,preferred,auto,1.3333,vrr,2

Effective 1440x900. GTK with GDK_SCALE=1 renders 1:1 with Hyprland (no double magnification). VRR mode 2 only in fullscreen, because LCD panels tend to flicker on static content with VRR active.

Brave and Chromium flags to render well at this scale:

--ozone-platform=wayland
--enable-features=WaylandFractionalScaleV1,UseOzonePlatform,VaapiVideoDecoder,VaapiVideoEncoder
--enable-gpu-rasterization

VAAPI makes a real difference on YouTube battery life.

Tuning Omarchy to be mine

Omarchy comes with good defaults. What I adjust stacks on top of them, without touching ~/.local/share/omarchy/ (which is clobbered by omarchy-update). All customization lives in ~/.config/.

Infra: Btrfs, snapshots, Snapper

Omarchy already ships with Btrfs and separate subvolumes:

@home separated means ~/.cache, ~/.config/BraveSoftware, etc. don’t bloat root snapshots. Snapshot is for system, not profile.

Swap: 4 GB zram at priority 100 (hit first), plus a 30 GB swapfile at priority 0 (enables hibernation, sized to match RAM).

The snapshot stack: Snapper takes a snapshot before and after every pacman -Syu via snap-pac. limine-snapper-sync writes those snapshots into the Limine menu, so you can boot into a previous snapshot to roll back. If something breaks after an update, you hold a key on boot, pick the pre-update snapshot, boot read-only to verify, and if it’s good, run snapper rollback.

Omarchy leaves snapper-cleanup.timer and snapper-boot.timer disabled by default. I enabled both and configured retention to fit on a 1 TB SSD without blowing up:

TIMELINE_LIMIT_HOURLY=10
TIMELINE_LIMIT_DAILY=0
TIMELINE_LIMIT_WEEKLY=1
TIMELINE_LIMIT_MONTHLY=1
NUMBER_LIMIT=50

A detail that costs debug time if you forget: Docker and Ollama write gigabytes into /var/lib/docker and /var/lib/ollama. If that falls inside @, snapshots go catastrophic. Each Docker image or Ollama model downloaded triples in size. I created nested subvolumes for both, with chattr +C to disable CoW:

sudo btrfs subvolume create /var/lib/docker
sudo chattr +C /var/lib/docker
sudo btrfs subvolume create /var/lib/ollama

This has to be done BEFORE Docker or Ollama writes any data. If they already have data there, you need to migrate.

NFS to the Synology NAS

My Synology exposes three volumes. On the desktop, I mount them the usual way. On the notebook, it has to be more defensive. The notebook moves around, forgets networks, connects to public WiFi. Notebook’s fstab:

nfs4  _netdev,noauto,nofail,x-systemd.automount,x-systemd.idle-timeout=10min,x-systemd.mount-timeout=15s,noatime,nodiratime,nconnect=4,actimeo=10,soft,timeo=30,retrans=2

Critical difference vs the desktop: soft with short timeouts (doesn’t hang forever), x-systemd.idle-timeout=10min (auto-unmount when idle), no network-online.target in the require (doesn’t slow boot). Practical result: cd /mnt/gigachad at home mounts lazily, away from home it fails fast without locking the shell.

Another important detail: my user on the notebook has UID 1026, which matches the share permissions on the Synology. Linux defaults to creating users at 1000, the Synology enforces identity via UID on the wire. If the UIDs don’t match, you can’t read the files, or worse, you write as nobody. I ran the usermod/groupmod from a TTY (with the user logged out) to remap the user to 1026/1026 and did chown -R on /home.

Public WiFi hardening

The notebook will leave the house. In an airport or café, I don’t want to announce hostname, don’t want a trackable MAC, don’t want a service listening on an open port.

/etc/NetworkManager/conf.d/00-macrandomize.conf:

[device]
wifi.scan-rand-mac-address=yes

[connection]
wifi.cloned-mac-address=stable
ethernet.cloned-mac-address=stable
connection.stable-id=${CONNECTION}/${BOOT}

ipv6.ip6-privacy=2
ipv6.addr-gen-mode=stable-privacy

Random MAC per scan (passive anti-fingerprinting). Stable cloned MAC per SSID (captive portals don’t re-prompt you every time) but different MACs between networks. IPv6 with temporary addresses and interface ID derived from a stable secret, not from the MAC (no EUI-64 leak).

/etc/systemd/resolved.conf.d/hardening.conf:

[Resolve]
LLMNR=no
MulticastDNS=no

Kills hostname broadcast on LLMNR and mDNS. I also disable avahi:

sudo systemctl disable --now avahi-daemon.service avahi-daemon.socket

UFW firewall:

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw --force enable

SSH server is already off by default on Omarchy. Nothing listening. Even if the firewall leaks, there’s no surface.

All of it rolls into a single initial setup ritual.

SSH agent persistence (keyring + keychain)

If you use SSH seriously, you want to type the passphrase once per boot and have ssh, git push, scp stay silent for the rest of the day. On current Arch there’s a catch: gnome-keyring 50 dropped its SSH component, and the replacement (gcr-ssh-agent) is a plain in-memory agent with no passphrase persistence. The “remember this key” checkbox you saw in old guides simply doesn’t exist anymore.

The combination that works has three pieces:

1. gcr-ssh-agent.socket managed by systemd serves SSH_AUTH_SOCK at $XDG_RUNTIME_DIR/gcr/ssh
2. pam_gnome_keyring on SDDM login unlocks the keyring with the login password (used by GUI apps like Brave, not by SSH)
3. keychain (wrapper) keeps an ssh-agent alive across logouts, overrides SSH_AUTH_SOCK to point at that persistent agent, and caches the PID in ~/.keychain/<host>-sh

First, install the keyring:

sudo pacman -S --needed gnome-keyring seahorse keychain

Then edit /etc/pam.d/sddm so the login password unlocks the keyring automatically. Add at the top:

-auth      optional    pam_gnome_keyring.so

And at the end:

-session   optional    pam_gnome_keyring.so    auto_start

The leading hyphen (-auth, -session) marks it optional, so if the module fails to load, login doesn’t break.

Pin SSH_AUTH_SOCK for graphical and TTY sessions via ~/.config/environment.d/ssh-agent.conf:

SSH_AUTH_SOCK=%t/gcr/ssh

%t resolves to $XDG_RUNTIME_DIR, something like /run/user/1026. Enable the gcr socket and user linger (so user daemons survive logout):

systemctl --user enable --now gcr-ssh-agent.socket
sudo loginctl enable-linger $USER

Finally, in ~/.config/bash/init.sh, keychain starts or reuses the agent:

if command -v keychain &>/dev/null && [[ -r ~/.ssh/id_ed25519 ]]; then
  eval "$(keychain --eval --quiet ~/.ssh/id_ed25519)"
fi

--eval emits shell assignments (SSH_AUTH_SOCK, SSH_AGENT_PID) pointing to keychain’s agent, overriding the gcr path set by environment.d. --quiet silences the banner once the key is loaded.

Flow in practice: boot → first terminal → keychain prompts for the passphrase once → key stays loaded. Logout → login again → new shells reattach to the same agent (via ~/.keychain/<host>-sh) → zero prompts. ssh-add -l confirms the key is there, echo $SSH_AUTH_SOCK confirms it’s at keychain’s path.

When you’ll re-enter the passphrase: reboot, ssh-add -D, or keychain --clear. In normal use, once a day.

Bash instead of ZSH

On the desktop I use ZSH. On the notebook I went with Bash to align with Omarchy’s default, without having to maintain a parallel stack of modular layers. ~/.bashrc is a symlink to ~/.config/bash/bashrc, which sources Omarchy’s defaults first and then stacks my customizations:

source ~/.local/share/omarchy/default/bash/rc
source ~/.config/bash/envs.sh
source ~/.config/bash/aliases.sh
source ~/.config/bash/mounts.sh
source ~/.config/bash/init.sh
source ~/.config/bash/secrets    # gitignored, chmod 600

envs.sh has what’s mine: OpenRouter base URL, Ollama pointing to the LAN GPU box (192.168.0.14), AWS region, Hugo analytics, zoxide and SSH agent configs. aliases.sh has TLP shortcuts, an alias for shell-gpt via Docker, and functions to harden PATH when running makepkg or yay (prevents binary injection via a malicious user config).

init.sh does the integration work. Atuin with a manual bind for Ctrl-R (so the up arrow keeps bash’s default history-search, which I use more). Keychain loading ~/.ssh/id_ed25519 once per boot and reusing it across shells (no need to re-authenticate SSH every time). Blesh if installed (ZSH-style autosuggestions for Bash). And a function that has PROMPT_COMMAND set the window title to the current pwd and the running command:

__title_idle() { printf '\033]2;%s\007' "${PWD/#$HOME/~}"; }
__title_busy() {
  local cmd="${BASH_COMMAND}"
  [[ "$cmd" == "__title_"* || "$cmd" == *"PROMPT_COMMAND"* ]] && return
  printf '\033]2;%s — %s\007' "${PWD/#$HOME/~}" "$cmd"
}
if [[ -n "${PROMPT_COMMAND-}" ]]; then
  PROMPT_COMMAND="__title_idle; ${PROMPT_COMMAND}"
else
  PROMPT_COMMAND="__title_idle"
fi
trap '__title_busy' DEBUG

Idle, the title shows just the pwd. With a command running, trap DEBUG catches the BASH_COMMAND and updates the title. Waybar’s hyprland/window picks that up and displays it.

For the modern Rust toolbelt, the list:

sudo pacman -S --needed \
  eza bat fd ripgrep sd git-delta dust procs bottom duf tokei hyperfine \
  zoxide atuin tldr starship

eza replaces ls. bat replaces cat with syntax highlighting. fd replaces find. ripgrep replaces grep. sd replaces sed. delta plugs into git for colored side-by-side diff. dust for visual du. procs for ps. btm (bottom) for top. duf for df. tokei counts lines of code. hyperfine for command benchmarking. zoxide is cd with memory (very useful). atuin is shell history with encrypted sync (I point it to my home server via sync_address = "http://192.168.0.90:8888"). starship is the prompt. tldr is a man page in 10 lines.

The atuin key has to be backed up offline. If you lose it, you lose the encrypted history. I saved mine in my self-hosted Bitwarden (Vaultwarden), documented in the Bitwarden self-hosted article.

Git pipes diff through delta:

[core]        pager = delta
[interactive] diffFilter = delta --color-only
[delta]       navigate side-by-side line-numbers hyperlinks, light=false
[merge]       conflictstyle = zdiff3

Hyprland and Waybar

Visual and UX customizations on top of the default.

In hypr/looknfeel.conf, smaller gaps (2/5 vs the default 5/10), slide animation between workspaces, VFR on (reduces consumption when the screen is static), allow_session_lock_restore (if hyprlock crashes, it goes back to the lock screen instead of dumping you on the desktop).

In hypr/bindings.conf:

On Waybar, three custom modules I recommend:

Window title: the hyprland/window module shows what’s focused. In bash, PROMPT_COMMAND updates the title to something like “~/Projects/blog — hugo server”. So in waybar the directory and running command show up, without me needing to look at the terminal.

"hyprland/window": {
    "format": "{title}",
    "max-length": 50,
    "rewrite": { "(.{47}).+": "$1…" }
}

Perf mode: custom/perf runs a script that reads TLP state and shows an icon:

"custom/perf": {
    "exec": "~/.config/scripts/perf-waybar.sh",
    "interval": 3,
    "format": "{}",
    "on-click": "~/.config/scripts/perf-toggle.sh"
}

Empty for balanced, 󰓅 PERF for performance, 󰌪 ECO for low-power. Click toggles. Useful to quickly see what mode the machine is in.

Claudebar: I integrated claudebar as a custom module that shows the Claude Code session usage % and extra spend inline in waybar. No need to open another window.

The clock:

"clock": {
    "format": "{:L%A %d %B - %H:%M}",
    "format-alt": "{:L%A W%V %Y - %H:%M}"
}

Shows “Thursday 17 April - 14:32” by default, click toggles to “Thursday W16 2026 - 14:32” with the ISO week number, useful for planning articles and tasks.

Self-hosted Atuin

Atuin runs on my home server at 192.168.0.90:8888. I made a separate account for the notebook (akitaonrails-thinkpad), I don’t mix history with the desktop on purpose. atuin sync runs every 5 minutes and all history is encrypted before going to the server. The server doesn’t see the commands, only encrypted bytes.

Conclusion: picking a notebook for Linux

One thing I learned on this journey: picking a notebook to run Linux comfortably is not trivial. You have to check the ArchWiki for your specific model before buying. The T14s Gen 6 AMD page, for example, catalogs every hardware quirk and how to work around it. Without that reference, you discover the problems during install.

Rule I follow: never buy a freshly-released model. Let 6 to 12 months go by after launch. That gives the community time to iron out bugs, drivers to land mainline, the ArchWiki to have a decent page, libfprint to include the fingerprint sensor, and the kernel to cover WiFi and the IR camera. Buying on day one means signing up as a beta tester.

Brands with a decent Linux track record: Lenovo (especially Thinkpad, they ship Ubuntu and Fedora pre-loaded), Dell (the XPS and Latitude lines), Asus (Zenbook and ROG have reasonable support), Framework (built for Linux from the factory). Any recent Mac is cut off from Linux mainline or runs through Asahi with caveats.

The Thinkpad T14 Gen 6 isn’t the prettiest notebook I could have bought. But it’s rugged, it has the right ports, the fingerprint sensor works, and the plastic shell lets it fall, get scratched, travel in a backpack without making me nervous. To serve as a remote debug companion, it’s what I needed. If that’s your use case too, I recommend it. If you want OLED and metal, go Zenbook or T14s. Every premium comes with a compromise, no Linux notebook in 2026 is perfect.

Everything I described here is versioned in a private repo of mine. If I need to reinstall tomorrow, I run half a dozen steps in order and I’m back at the same place. That’s the whole point of keeping config in Git: notebook is commodity, config is mine.

Every time I get pulled into an online thread about LLMs I hear the same chorus, in slightly different keys. “Claude didn’t perform as well as GPT for me.” “GPT did a way better job than Claude, I’m canceling my sub.” “Honestly, Kimi or MiniMax does the job for me just fine, I’m not paying for anything.” Anecdote piled on anecdote, each one a variation of “works on my machine” vs. “doesn’t work on my machine.” It sounds off to me.

I’ve already benchmarked most of the relevant open source and commercial models in my LLM testing post, so I’m not pulling this out of thin air. And beyond the benchmarks, I’ve got 500+ hours in Claude Code and Codex on real projects. 16 hours a day, two and a half months straight, something in the neighborhood of 400,000 effective lines of code generated.

And look: on neither of them, Claude or Codex, did I ever see the model wander off, do something I didn’t ask for, or flat-out fail to deliver what I wanted. Not once. When the model really couldn’t do something, it told me so upfront instead of inventing. So when someone tells me “Claude blew it,” my first question is always the same: what did you ask it for, exactly?

The fake problem

The ecosystem’s answer to this supposed “wandering off” problem is to pile on more layers. Spec Driven Development showed up, 15-section prompt templates showed up, whole frameworks to force the LLM to ask more questions before it starts. I respect the effort, but I think they’re treating the symptom, not the cause.

I practice what I call Agile Vibe Coding: applying XP techniques (pair programming, test-driven, short feedback loops, continuous refactor) on top of normal prompting. I don’t need a framework. I don’t need a three-page template. I need the same things that have always been needed to work on software in a team: know what I want, know what I don’t want, know how to validate it when it lands.

The real problem is one thing: nobody knows how to communicate

I’ve got an old post from 2013 called Programmers are terrible communicators (UDP vs TCP). Go read it if you haven’t, because the problem I described there in 2013 is exactly the thing blowing up now that everyone’s flying an LLM. Nothing changed. The tech got more powerful, but the people are the same people.

Here’s how it works. You’ve got a pile of information in your head. Project context, history, stack constraints, personal preference, things that went sideways in the past, decisions that got made in a meeting two months back. And then you walk into a conversation, whether it’s with a human coworker or an LLM, and fire off your request assuming everything in your head is also in the head of whoever is on the other side. “It’s obvious, everybody knows that.” So you write “do what I’m telling you,” except what you’re telling them is really “do what I’m thinking.” And you don’t even notice they’re not the same thing.

Developers are terrible communicators. Managers are terrible communicators too, and that’s exactly why most of the useful hours in a corporate week get burned in pointless meetings. Nobody gets to the point on time, nobody aligns expectations, the result comes in below the bar, and the default managerial answer to that is “more of the same.” More meetings, more spreadsheets, more reports. Except if your communication was bad at volume 1, it’s going to stay bad at volume 5. The problem is quality. Volume doesn’t fix bad quality.

How I actually talk to Claude or Codex

I treat any LLM exactly how I’d treat a human during a pair programming session. No ceremony, no form to fill out, no 10-page spec. But with communication discipline. Let me walk you through a real example, from last week.

I’ve got about 12 TB of ROMs piled up on my NAS, under /mnt/terachad/Emulators, split across two trees (ROMS/ and ROMS2/) that accumulated across different collections over the last 10-plus years. More than 400,000 files total. Uncompressed romsets, .7z, .rar, giant CDI/GDI bundles, inconsistent file naming, duplicates everywhere. I wanted to consolidate all of it, by platform, into a new ROMS_FINAL/ tree, using standardized naming (No-Intro / Redump / TOSEC) so that when I run Screenscraper later the match is automatic. That’s the goal, stated up front.

But I don’t stop there. I tell it what I DON’T want, too. “Never dedup by filename, only by sha1 + size, filenames lie way too much in this world.” “A Neo Geo romset depends on which emulator is going to consume it, so the MAME zip, the FBNeo bundle, and the Darksoft MVS cart are three mutually incompatible things, keep one canonical copy of each.” “Same idea for NAOMI: the MAME romset is not the same file as the GDI.” “Saturn has USA, Japan, and Europe versions, I want to keep a copy of each region, region is not duplicate.” If I leave that out, the model has no way to know, because that knowledge is in my head and not in the code. If I don’t give it, it’ll assume its own most-reasonable default, which might be the opposite of what I need.

Then I get into method detail. “Create a docs/ directory to serve as living knowledge base, and docs/scripts/ with the steps broken into numbered files (01_walk_and_hash.py, 02_classify.py, etc.). Each step has to be idempotent so I can re-run it if it crashes or if I need to resume halfway through. Progress state lives in a SQLite catalog, not in-memory variables.” This isn’t micromanaging the model, this is aligning the way I work. I know an operation this size is going to hit problems, and I want to be able to come back without losing the previous hours of hashing and classification.

Then, even after it hands me its plan, I keep thinking about what could go wrong. “Zero deletions under ROMS/ and ROMS2/. Whatever doesn’t get forwarded to ROMS_FINAL/ just stays where it was. The only thing the whole pipeline is allowed to delete is temporary files from an extraction that bailed halfway through. Also, the phase that actually executes the moves can only run after I manually approve the planning phase, create a flag file docs/.phase4-approved, and make phase 5 refuse to start without it.” This is the equivalent of making a commit before a big refactor, plus a human gate between planning and applying. I’m protecting against my own mistakes, its mistakes, or both at once.

When the model gets going, I don’t leave the room. I keep asking for status. I notice the hash ETA is way longer than the problem warrants, so I interrupt: “I think we can parallelize, I’ve got spare CPU and 10GbE talking to the NAS, and the Synology over NFS can handle it. Bump up the concurrency, test, check that it’s still stable and that the SQLite transaction ordering doesn’t break.” That’s real pair programming, not blind automation.

The structure behind it

Notice the pattern. I don’t say “solve this problem.” I say “solve this problem, this way and that way, and not this way or that way, and when you’re done, validate X and Y.” In other words, I’m communicating four things, not one:

First, what I want. The end goal in plain language. Second, how I want it done, in broad strokes, leaving room for it to suggest a better solution if it has one, because it usually does. Third, what I don’t want. This is the part most people skip, and it’s the most critical, because it’s where all the unspoken assumptions live, the ones that turn into bugs later. Fourth, how we validate it landed. What’s the expected result, what’s the test, what’s the “done” signal.

And that fourth part is a killer. Most of the clients I’ve worked with over the past 20 years couldn’t tell me what the expected result was. Because it’s easy to want something, and hard to say how you’d measure whether it showed up. Without a success metric, expectations break by definition, because there was no concrete expectation to begin with. That’s one of the main reasons consulting projects go sideways, and it’s identical in the world of AI agents.

When I hand the model all four blocks, it almost never fails. And when it actually can’t do the thing, because the task is impossible given my constraints or because there’s information I forgot to pass along, it doesn’t try to guess. It tells me: “given your constraints, I can’t proceed because of X or Y.” Then I adjust, or I loosen a constraint, or I realize I didn’t actually know what I wanted. It all works.

Once the context is solid, ask instead of prescribe

There’s a shift I make after the first few well-loaded prompts. In the opening turns I pour in a ton: goal, constraints, method, validation, all the context the model needs to understand the terrain. It’s a lot of detail, it’s my job to front-load it, and I already explained why there’s no way around that.

But once that ground is solid, I stop prescribing solutions and start asking for suggestions. Instead of saying “implement it this way, with that library, following this pattern,” I switch to “given everything we’ve already covered, what’s the best approach here? Research online if you need to, compare the options, and come back with the solution you’d pick for this goal.”

That’s the step most people skip, and it’s exactly where the LLM earns useful autonomy. It’s got way more vocabulary than I do across a pile of topics. It read the whole internet; I read whatever I had time for. If I prescribe line by line, I’m throwing that edge away. If I set the context and then ask, it comes back with options I hadn’t considered, with trade-offs laid out, sometimes better than my original idea, and I get to pick.

The trick is simple: asking well requires having set the context well first. A dry question with no ground gets back a generic answer, or the first idea that seemed to fit. A question resting on ground you already laid comes back with a real proposal, alternatives compared, references cited. The model is ready for that kind of contribution, it just won’t give it to you until you’ve spent the time setting the stage.

And look: this method wasn’t invented for LLMs. It’s the same way I’d work with any human developer, senior or not. Give them the context, give them the goal, explain what I care about, then ask “what’s the best way to do this?” instead of dictating the solution. The only difference is the LLM gives it back in seconds when a human would take days. The way you run the conversation is the same.

It’s not a 10-page spec

And here’s the important bit: what I’m describing is not a formalism. It’s not a long spec, it’s not a Confluence doc, it’s not a template. It’s just how I talk to anyone who has to deliver something to me. I picked it up running projects, managing contractors, integrating teams that weren’t mine, and getting knocked around every time my communication was bad. After a while it becomes second nature.

If I don’t really care about the final result, say a quick experiment, a weekend toy, something disposable, I cut way back. I know my expectations might break, and that’s fine, the cost of a bug here is cheap. But if the result actually matters, I invest the time needed to give the other side (human or AI) the best shot at delivering what I want. Output is proportional to the time you spend on input. If you’re not willing to explain what you want properly, don’t complain when what comes back is wrong.

To illustrate: this very post you’re reading was written by Claude, off a prompt I gave it. Below is the screenshot of what I typed. Notice: no hidden assumptions, clear goal, references to earlier posts baked in, constraints stated explicitly, enough detail that it didn’t have to guess.

But look, that’s just the first prompt. It wasn’t the only one. While Claude was writing, I kept tracking, sending corrections, adding points I forgot to put in the first prompt, flagging factual errors I caught in the generated text, and fine-tuning tone. “Hey, I also forgot to tell you we need to cover X.” “No, that reference is out of date, OpenAI’s Sora got shut down, fix that.” “Go read what we already documented over at /mnt/terachad/Emulators/docs/ and see if you can sharpen up the ROMs example.” This very observation you’re reading right now started as a mid-flight prompt:

And the conversation kept going all the way to the commit. I had already told it to humanize, translate to English, and push, and I still interrupted at the last second because I spotted an unnecessary English loanword I wanted to fix before it went up. Here’s that moment:

That’s real pair programming. Nobody sits down with a colleague, drops a 15-line task, stands up, and walks away expecting magic. You stay there, you watch the execution, you see the code come together, you suggest adjustments, you catch errors while they’re still cheap to fix, you add context you just remembered. The initial prompt is the starting point, not the final contract. Agile Vibe Coding in action: short cycles, fast feedback, continuous correction.

This isn’t a formal spec. It’s a conversation that keeps going during the work, not before it. And that’s how it’s always going to be, with me and with any good professional.

“Akita, you write too much detail, shouldn’t the AI figure this out on its own?”

That’s the question I know is coming, so let me answer it upfront. No, the AI is not going to figure it out on its own. There is no future version of Claude, GPT, Gemini, whatever, that’s going to guess what’s in your head. Context doesn’t generate itself by osmosis. If the information isn’t in the code, in the docs, or in my prompt, it simply doesn’t exist for the model. Full stop.

Neo Geo romsets being different per emulator? That’s domain knowledge. Saturn having separate regions? Domain knowledge. My NAS having 10GbE to handle aggressive parallelism? Environment context. Having docs/ with a SQLite catalog to survive crashes? An engineering decision I made. The model has no way to “discover” any of this. All of it is my job to bring to the conversation. And if I’m not willing to spend my own time understanding these details, why would anyone, or anything, do it for me for free?

The rule is simple: the quality of what you get back is directly proportional to the effort you put into asking. It has always been this way. Anybody who’s hired a contractor knows it: vague requests, ill-defined scope, “the client knows what they want, they just can’t explain it,” that’s a guaranteed recipe for a project to go off the rails. Always was. The LLM is the same thing, just faster and more patient. Think of it as modern outsourcing, not magic. A magician solves the problem without you saying anything. A contractor solves exactly what you asked for, exactly the way you asked, with the information you provided. If you didn’t ask properly, you don’t get it properly.

The frustration of people showing up here burned out on Claude or Codex is almost always the same: they asked for little, expected a lot. And when the result came back short, they blamed the tool. Never the question.

That’s why AI won’t replace the good ones

That’s exactly why I say, with full conviction, that AI agents aren’t going to replace good professionals. They’re going to replace people who can’t frame their own question properly, who don’t know what they want, who don’t know how to validate a result, who need somebody to think for them. And look, those people were always replaceable, it’s just that now the replacement is cheaper. The market is doing the math.

The good professional, meanwhile, got more productive. Uses the LLM as a pair programming partner at 2 a.m., no complaints, no union, no ego clash. Ships in a week what used to take a month. And is still the same good professional they were, because the skill that mattered, knowing what to ask for, what not to accept, and how to measure, is still 100% theirs. The tool just executes.

Stark + Jarvis = Iron Man

Let me drop a metaphor that I think wraps the whole thing up. Think about Tony Stark, in the MCU. He’s got Jarvis, probably the most advanced fictional AI pop culture has produced in the last two decades. Voice control, context awareness, planning, parallel execution, even a sharp personality. Technologically, Jarvis would easily be the best AI agent you could imagine today.

And even so, Jarvis on his own doesn’t build an Iron Man suit. Doesn’t build the Arc reactor. Doesn’t build any of the gear that makes Stark be Stark. All that advanced tech, with no Stark to guide it, just sits there. It’s Stark’s genius, his vision, his stubbornness, his engineer’s intuition about where to push next, that makes any of it real. Jarvis executes. Stark thinks.

There’s another detail in that story almost nobody remembers: not even Stark, with all his genius and with Jarvis riding shotgun, nails the perfect suit on the first try. He spends movie after movie iterating. The Mark I was literally bolted together in a cave out of scrap. The Mark II could fly, but iced over at altitude. The Mark III fixed the ice but weighed too much. And on it goes, each iteration fixing a specific flaw in the last, all the way to the Mark LXXXV in Endgame, his 85th suit. Eighty-five. The whole MCU Iron Man arc is basically a ten-year campaign of iterative development on one extremely complicated product.

That’s exactly the mental model I think we should be using when we work with AI today. You don’t fire off a prompt and wait for the definitive solution to pop out. You, sitting in the Stark chair, use the AI (your own Jarvis) as an accelerator on each lap of the cycle: propose, test, see what broke, fix it, propose again. The AI speeds up every lap, it doesn’t erase the laps. If someone swapped iteration for “one magic final answer,” they never understood that engineering was never like that, human or no human.

Put Stark and Jarvis together and now you’ve got Iron Man. Take either one away and the half that actually matters is missing.

Claude Code vs. Codex: my pick today (April 2026)

A quick aside so this doesn’t go unsaid: these days I’m alternating between Claude Code and Codex, but I’ve been leaning into Claude Code. Let me spell out why, because it’s not about the LLM itself.

Claude Opus and GPT-5.4 xHigh, to me, are basically tied as models. On the hard tasks, when one of them can’t pull it off, I swap over to the other and the other usually does. Head to head, both are strong. What separates them today is the harness, not the model.

And the Claude Code harness, right now, is flat-out better. Two concrete reasons: planning and parallel execution.

Planning. Claude Code breaks a long task into subtasks, keeps a visible to-do list I can actually watch on screen, tries to run things in parallel when it can, and doesn’t drop items. When it tells me “done,” I know the full list got executed, because it’s right there for me to check. That detail changes the whole game: I trust the “done” without having to chase every single item with “hey, did you actually do that other one?”.

Parallel execution. This one is clean-cut. If Claude Code is mid-task and I hit ESC to throw in something else, it typically keeps the first task running and kicks off the second in parallel, unless the new request actually requires cancelling the first. Codex, same situation, stops the first to deal with the second, and doesn’t always know how to resume the first from where it left off without me prodding it manually. With Claude Code I get to actually flow, opening new fronts while the old ones keep running. With Codex I have to go serial, be patient, and be more deliberate about every request, because interrupting is expensive.

None of which means Codex is bad. It’s good. Plenty of times when Claude Code gets jammed on a hairy task I pop over to Codex and it unjams it immediately. But then my way of working shifts: smaller requests, more focused, one at a time, wait for it, move on. Works fine, it’s just not the flow I prefer.

Codex is probably going to catch up on the harness side over the next few months, and the conversation will shift. But today, April 15th, 2026, if I have to pick one as my daily driver, it’s Claude Code, and the reason is the harness, not because OpenAI’s LLM is somehow inferior. Writing this down so that six months from now I can reread it and laugh.

Which is why my company is called Codeminer 42

To close with a reference I’ve been carrying around for years: my company is called Codeminer 42. The 42 isn’t a random number. It’s a direct nod to Douglas Adams, from The Hitchhiker’s Guide to the Galaxy.

If you don’t know the bit, here’s how it goes. An entire civilization builds a planet-sized supercomputer to calculate the Answer to Life, the Universe, and Everything. After millions of years of processing, the machine finally spits out the final answer: 42. And then there’s that awkward silence, because nobody there could remember what the original question had been. 42 is a technically correct answer to a question no one bothered to formulate properly. Which is to say, it means absolutely nothing. Plenty of people seem to think 42 has some deep meaning baked into it. It doesn’t. It’s the wrong answer to the wrong question.

That’s the sharpest lesson about engineering I’ve ever read in fiction. Every expectation that breaks, breaks because the question was wrong, not because the answer was badly executed. That’s what Codeminer 42 exists for, and it’s exactly what I practice day to day, whether the other side is a human client or an LLM. Before I deliver what you asked for, my job is to make you discover that what you think you want is probably wrong, to force you to rethink the assumptions you walked in with, and only once the question is sharpened do I get to hand you the best possible result. Skip that step and anything I deliver is going to be a 42.

So next time you read somebody saying “I canceled Claude because it doesn’t deliver,” or “GPT is way better,” or the other way around, take a closer look at the question the person was asking. Nine times out of ten, the problem isn’t the model. It’s the question. And nine times out of ten, the answer that person got back was 42.

The pitch is strong. It’s a multimodal video generation model that takes text, up to 9 reference images, 3 reference video clips, and 3 audio tracks all in the same call. On top of that, it produces up to 15 seconds of output with native synced audio (dialogue, sound effects, ambient music), supports video extension, surgical editing of characters and objects, and prompt-driven camera planning. ByteDance is pitching it at commercial advertising, explainer videos, film production, e-commerce, and gaming. Translation: for content creators trying to climb out of the “random meme” tier and start producing things that look professional.

If you want a quick visual tour before going further, here’s a great walkthrough from Stefan, of the Stefan 3D AI Lab channel, which I already plugged in the post on AI 3D modeling:

The main interface is Dreamina’s “Photo Studio,” where you pick the generation mode and stack your references. So far I’ve only tested the standard multi-reference mode.

Test 1: lip sync with podcast audio

My first test was simple. I grabbed a few seconds of the opening bumper from my podcast The M.Akita Chronicles, which is generated by AI through an ElevenLabs v3 pipeline, passed in my new anime-style avatar as a reference image, and asked Seedance to make the character lip-sync and gesture along with that audio.

The result is decent. All of that came from a single still image. The lip sync follows the speech reasonably well, the expression has some life to it, and the hand gesture lands at the right beat. But this is a YouTube short or Instagram clip at best. Not the kind of animation you’d open a serious video with.

The feature that actually matters: video reference

And here’s what I think is the only real use of these models for actual work: feeding in video as a reference. Text alone is never going to be precise enough. You can describe a scene with whatever vocabulary you want, swap adjectives, specify lens, angle, framing, and every generation will still hand you back something subtly different. It’s a slot machine. Great for memes, terrible for production.

Most amateurs see one random clip that comes out nice on the first try and go straight to flooding their X and Instagram feeds with it. That’s not control. That’s luck. For film, for ads, for show openers, for anything where the next shot has to match the previous one, you have to be able to tell the model: “do exactly this motion, with exactly this camera.” That’s where reference video changes the game, because it replaces hours of 3D modeling, rigging, animation, and rendering that would cost a fortune in a studio.

For my test, I recycled the model I’d already generated in the post on AI 3D with Hunyuan and Nano Banana, where I tested how far you can take 3D modeling from a prompt and even hit “print” on the result. But for something more cinematic I wanted a model with a proper animation cycle. So I grabbed the Darth Talon model from Sketchfab, which has a short, well-made motion sequence, just because it looked cool.

I imported the FBX into Blender, set up a basic camera and lighting, and did a quick Cycles render. Nothing pretty about it, just a sketch to feed in as motion and framing reference.

I uploaded that render to Seedance as a video reference along with three t-pose images of the character (front, back, left side) for visual consistency:

First attempt, with a generic prompt:

Not bad. The character keeps its identity, the lighting got a serious upgrade over my raw render, and the clip is coherent. But the motion and camera position drifted noticeably from the reference. The model basically read it as “there’s a character here that looks like that doing something like that,” and improvised the rest.

Then I remembered Stefan’s tutorial: the trick is to literally drop something like Follow exact motion and camera from reference video into the prompt. Tried again:

A lot better. It’s clearly following the reference choreography, the camera angle matches in several beats, and the character looks more polished than anything I could hand-render in a quick Cycles sketch. But it’s still not a frame-for-frame match. In some shots the model is still taking liberties with timing, position, and framing. There are other prompting tricks and parameters to play with, but I stopped here to write this up while the launch is still fresh.

ComfyUI, Runway, and the rest of the ecosystem

Seedance 2.0 also already shipped as a ComfyUI cloud node, which is great for anyone who wants to drop the model into a bigger pipeline without bouncing between web UIs. If you’ve already got an image-gen workflow built in ComfyUI, this is genuinely handy.

And for anyone who wants volume without doing the per-generation credit math, Runway is offering Seedance 2.0 as part of their Unlimited plan, which runs around $76/month annual or $95/month monthly. “Unlimited” means no per-generation charge, but you do trade for lower queue priority at peak hours and an output storage cap. If you iterate a lot, the subscription model makes way more sense than buying credits one at a time.

The price question

Seedance’s own pricing is credit-based. The Standard plan is $24.90/month annual or $49.90/month monthly, and gets you 2,500 credits a month. Every 10 seconds of generated video burns 6 credits.

The math is brutal. With 2,500 credits on Standard, you get about 416 ten-second generations a month. Sounds like a lot, until you remember my own test: it took at least two tries to get close to what I wanted, and even then it wasn’t a one-to-one match. In practice, plan on 3 to 5 regenerations per usable scene. That drops your real number to something like 80 to 140 short clips per month. Maybe enough for a solo creator doing short-form content. Nowhere near enough for production that needs minutes of polished, continuous video.

The higher tiers scale credits roughly linearly, but the same problem holds: at today’s price, Seedance 2.0 is still a tool for short clips and well-made memes, or for pre-vis sketches before you send the real thing to an actual studio. It doesn’t replace continuous professional production. For that use case, Runway with Unlimited is honestly the cheaper option in practice. Full pricing table here.

What nobody wants to talk about: restrictions and deepfakes

Two things I don’t want to leave out. First: Seedance 2.0 took its sweet time getting to the public partly because ByteDance is being a lot more conservative than the competition when it comes to moderation. The model blocks generation that uses real people as reference (celebrities, politicians, public figures) and filters strong-IP characters from Disney, Marvel/DC, Nintendo, and registered trademarks generally. If you want the details of what passes, what doesn’t, and why ByteDance went that way, this MindStudio piece breaks it down. It makes sense: ByteDance operates across dozens of jurisdictions, lives under heavy regulatory scrutiny worldwide, and has the elephant in the room of Hollywood pushing the entire industry with copyright suits over training data and generation. The release got delayed and arrived with heavier filters precisely because of that.

Second point, and this is the one that matters more: for you, the average reader, the message is that deepfakes are no longer hypothetical. Photos on the internet stopped counting as proof a long time ago, because image models like Nano Banana, Hunyuan, and the rest deliver realism that fools anyone. Now video sits in the same bucket. What we just saw above, where a couple of references and two prompts get you a coherent animated scene in minutes, is just the start. The average person, with no training, isn’t going to be able to tell generated video from real video at a glance anymore. And Seedance’s filters only block above-board, legitimate use. Anyone with bad intent will always find a path through open source models, workarounds, or less strict platforms. That’s the world we’re in now, and the sooner we collectively accept it, the better off we are.

No, this doesn’t replace real artists

Let me cut off the usual speech before it shows up in the comments. No, Seedance doesn’t replace VFX artists, directors, editors, none of that. This is a hammer. The tool is the same for everybody. What comes out the other end depends entirely on who’s swinging it.

Anyone who’s actually studied framing, pacing, continuity, art direction, editing, color, composition is going to use Seedance to 10x the work they were already capable of delivering. Anyone who hasn’t studied any of that is going to crank out the same Instagram meme they were already cranking out, just 10x faster. The AI reflects who you are. If you’re a real artist, the tool multiplies you. If you only think you are, the tool multiplies the mediocrity. There’s no miracle here.

This is exactly why the whole “now everyone can be a film director with AI” wave is the same song we’ve heard with the digital camera, with Photoshop, with After Effects, with Premiere, and with every powerful tool that’s shown up in the last 30 years. The technical bar drops. The bar of taste, reference, and study sits exactly where it always has. Good people get more productive. Everyone else still needs to hire real ones to do real work.

Where this goes next

Seedance 2.0 is clearly a step in the right direction, but it’s not the tool that replaces professional production yet. Text alone stays imprecise, video reference helps but still drifts, and the price per minute of polished output is high relative to what you actually get. The good news is that this story always rhymes: Google has Veo, Runway has its own model and is also reselling Seedance, Kling and Hailuo from China keep pushing, and the open source models are gaining ground. OpenAI had Sora, but they shut it down. As competition tightens, quality goes up and price comes down. A year or two from now we’ll be looking back at this post and finding what I just showed pretty quaint. Same as it ever was.

On my YouTube channel I even used old games to teach computer science fundamentals. In this Akitando episode about Super Mario and old computers, I explain the 6502, memory maps, the PPU, hardware constraints, and why those games were programmed the way they were. If you never watched it, start there:

The problem is always the same: every few years I decide to set up a new emulation machine, download the main emulators again, and there I go repeating the same masochistic ritual. PCSX2, RPCS3, Eden, Azahar, Dolphin, RetroArch, Flycast, shadPS4, and so on. Each one with its quirks. Each one with its own particular way of wasting hours of your life.

In theory, setting all this up should be fun. In practice, it takes days. And that’s not an exaggeration. Dolphin still manages to be one of the worst because GameCube and Wii controller setups have no standard. RPCS3 requires per-game tuning. Eden needs DLC, updates and cheats in the right place. shadPS4 is a festival of trial and error. When I’d finally finish configuring everything, I didn’t feel like playing anything anymore. I just wanted to close the menus and go do something else.

I’ve been known to say that maybe the fun was the tuning itself. I don’t think that anymore. After repeating this process too many times, I’m done. I want to play the games, not fill out forms hidden inside emulator GUIs.

The problem was never Linux

I’ve solved this kind of thing in different ways in the past. Years ago I ran Linux on the host and a virtualized Windows with GPU passthrough to play inside the VM. At the time that made sense. I made a whole video about it:

But that was before Valve, Proton, modern Wine and the whole open source community pushed the Linux desktop to a much better place. Today you can avoid Windows in most cases. In the other video below I explain the evolution of CPU, GPU, OpenGL, Vulkan, and why we ended up here:

My gaming mini-PC with the RTX 4090 is still my main Steam machine, especially now that I’ve built a proper sim racing cockpit. On it I use EmuDeck, which was born to automate installing and configuring emulators on the Steam Deck, then grew Windows support, and helps cut the complexity of setting up this kind of environment. But my main desktop is also way too powerful to leave underused. It has an RTX 5090, and today I use that GPU mostly to test LLMs and for benchmarking, as I wrote in Testing Open Source and Commercial LLMs. Leaving it idle for gaming would be a waste.

Only on Linux I wanted something else. I didn’t want a black box doing everything for me without me knowing exactly what was being changed, especially on my main PC, which is my work machine. I wanted my own setup, handmade in the right sense: not clicking GUI by GUI, but understanding what’s being configured, keeping the files under my control, and being able to rebuild everything the way I like. I know the NixOS folks will jump in here to say “just use Nix” — I’ll explain why I ruled that out below. I also didn’t want to turn my work machine into a carnival of emulator packages, GTK themes, wrappers, launchers, weird runtimes and configs buried in ~/.config. Nor did I want dual boot or a VM. In 2026, the best answer for this, in my opinion, is Distrobox.

From what the project itself explains, Distrobox is a wrapper on top of podman, docker or lilipod to create containers tightly integrated with the host, with access to HOME, Wayland/X11, audio, USB devices, external storage and GPU. In other words: exactly the kind of pragmatic isolation I wanted. It’s not a security boundary, and the project site makes that clear. Don’t use it thinking about high-security sandboxing. Use it thinking about separating environments without paying the price of a VM.

And before anyone repeats the usual confusion: a container is not a virtual machine. I explain this calmly in this other episode:

The setup

The idea is simple: a vanilla Arch Linux inside a Distrobox called gaming, with NAS paths mounted read-only, Steam library accessible where it makes sense, and all emulators installed inside. Since the container has access to the NVIDIA GPU, audio, USB and other peripherals, I can separate work and gaming on the same machine without practical performance penalty.

The initial bootstrap looks roughly like this:

distrobox create --name gaming --image archlinux:latest --nvidia \
  --home /mnt/data/distrobox/gaming \
  --volume /mnt/data/steam:/mnt/data/steam \
  --volume /mnt/terachad/Emulators:/mnt/terachad/Emulators:ro

Even that first step has a catch. archlinux:latest inside Distrobox comes without [multilib] in pacman.conf, with a misconfigured sudoers, and with the old --nvidia problem: the host driver libs get bind-mounted read-only, so any install that depends on nvidia-utils breaks with file conflicts. Just that alone is the kind of headache that, a few years ago, would make me open half a dozen tabs, a bunch of terminals, and spend a whole night in trial and error.

This time I did it differently.

Claude Code as an infrastructure assistant

I’ve been getting more and more comfortable using Claude Code as my infrastructure assistant on my personal machines. I wouldn’t do this blindly on a client server. But on my own machine, in an environment I can destroy and rebuild however many times I want, it makes all the sense in the world. I wrote about this in Migrating my Home Server with Claude Code, when I used Claude to install and configure openSUSE MicroOS, Docker, NFS, firewall, hardening, and all the rest without me having to remember annoying shell commands.

So I thought: why not do the same thing here?

That’s exactly what I did. I started with a sequence of objective prompts, always asking for two things at once: do the work, and document enough for me to rebuild everything later. The most important history ended up in docs/distrobox-gaming-prompts.md.

A clarification worth making: those prompts on GitHub aren’t my raw messages, the way they came out in real time. After everything worked, I asked Claude itself to rewrite the prompts in a much more organized and detailed way, purely for documentation. The original prompts were much simpler and much less specific. I described the goal and let Claude figure out paths, config files, formats and commands on its own.

The first prompt created the box with --nvidia, a separate --home, and correct mounts. The second solved the three classic problems of Arch inside Distrobox: sudo, multilib, and the nvidia-utils dummy package. The third installed the gaming base, including a detail I would have easily forgotten if I was doing it by hand: pipewire-pulse, needed so several emulators don’t end up mute or out of sync.

The point isn’t the text itself. The point is the method. I don’t need to remember the exact order, the precise options, or where the docs for each detail are. I describe the goal and let the agent carry the piano. I stay in the tech-lead role: watching, reviewing, course-correcting when needed, and telling it to keep going.

The GitHub project

The setup lives in akitaonrails/distrobox-gaming, structured as an Ansible project. 17 roles cover everything from box creation, package bootstrap, config seeding, DLC installation, controller setup, to post-setup verification. The main playbooks are:

• site.yml: full setup from scratch
• reset-configs.yml: reset configs only (useful when you want to wipe tuning and redeploy)
• backup.yml / restore.yml: container snapshot and restore via podman commit
• refresh-shadps4.yml: standalone shadPS4 update
• install-xenia.yml: optional Xenia Manager install (Wine prefix)

Full walkthrough is in docs/rebuild-runbook.md. Package decisions (why AUR instead of Flatpak, for example) are in docs/distrobox-gaming-packages.md.

Why not Nix?

Someone will ask. “You’re recreating a reproducible environment. Why not use NixOS, or at least nix-shell/flakes?”

I considered and ruled it out. The emulator ecosystem I need lives on the AUR. AUR -bin packages are wrappers around AppImages that ship the official upstream binary without compiling anything. rpcs3-bin, pcsx2-latest-bin, eden-bin, duckstation-qt-bin, shadps4-bin — these binaries track upstream practically on release day. On Nixpkgs, many of these emulators are weeks or months behind release, and some don’t exist. Creating a Nix overlay for every emulator I need, maintaining it, and dealing with compatibility patches when upstream changes is work I don’t want to have.

There’s also the mental model. I don’t want to learn the Nix language, the derivation system and the evaluation model just to set up a personal gaming environment. I already know Ansible, roles are folders with YAML tasks, and debugging is ansible-playbook -vvv. When something goes wrong, I read the error, open the task that failed, and know exactly where to fix it. If I needed the same level of reproducibility at scale, across a cluster, with atomic rollback, then Nix would have an argument. For a distrobox with emulators on my personal machine, Ansible solves it with much less friction.

Flatpak was also tested and ruled out. Flatpak’s bwrap (bubblewrap) doesn’t nest properly inside Docker’s mount namespaces, so Flatpak apps simply don’t run inside distrobox. The alternative would be installing Flatpak on the host, but then you’re back to polluting the work machine with gaming packages. Plus, Flatpak versions of emulators lag well behind AUR — the AUR’s pcsx2-latest-bin tracks the 2.7.x AppImage, while Flathub still ships v2.6.3.

Platforms covered

The setup covers 12 platforms today:

RetroArch comes on top to cover the rest (NES, SNES, Genesis, N64, arcade, etc.), with 21 buildbot cores and 8 asset packs (databases, shaders, cheats, overlays, autoconfig).

Frontend is ES-DE. Custom system definitions live in ansible/group_vars/all/esde.yml, and each emulator comes with a wrapper that sets the right GPU environment variables (more on that in a sec).

GPU hardforce for NVIDIA

On a hybrid system with NVIDIA dGPU + AMD iGPU (my case on the desktop), Vulkan sometimes picks the iGPU on its own and you end up with an emulator running at 15 fps while the 5090 sits idle. The fix is to force NVIDIA’s Vulkan ICD in every launcher.

Each desktop entry rendered by Ansible exports VK_ICD_FILENAMES pointing to NVIDIA’s ICD, and the ES-DE wrapper does the same before launching any core. Combined with the --nvidia flag at box creation, which bind-mounts host drivers read-only, the result is predictable: Vulkan always on the NVIDIA dGPU, regardless of system state at runtime.

This mostly matters for hybrid setups. On a desktop with a single GPU, the ICD filtering is placebo, but it doesn’t hurt.

PS2: PCSX2 with per-game tuning

The Gran Turismo line is my declared addiction. Each version needs its own specific tweak. The PCSX2 setup today has sane global configs (Vulkan, 4x SSAA, widescreen 16:9, Xbox-style bindings, FXAA + PCRTC antiblur, 16x anisotropic, Automatic deinterlace) and per-game INIs for the titles I actually play:

• Gran Turismo 3 A-spec (SCUS-97102 + bundle PBPX-95503): widescreen pnach, optional retexture pack (disabled by default because NFS streaming causes flicker in car-showcase cutscenes)
• Gran Turismo 4 USA (SCUS-97328): Silentwarior112 HD HUD, full retexture pack, Silent’s trigger/cam patches, widescreen pnach
• Gran Turismo 4 Spec II (SCUS-97436, CRC 4CE521F2): special case — the vanilla GT4 HD packs are linked via symlink because Spec II has the same structure but a different CRC. Widescreen pnach renamed to match the CRC. Deinterlace mode 8 (Adaptive TFF), ShadeBoost tuning (+10 saturation, +3 brightness, +2 contrast) to fix pause-interlace ghosting and the anemic upscale saturation
• Enthusia Professional Racing (SLUS-20967): HD textures + widescreen
• Ridge Racer V (SLUS-20002): widescreen + no-interlace pnach

Silent’s and community pnach files are downloaded automatically by the pcsx2_textures role, which also deploys the cheats pack from the NAS and installs the Spec II HD packs via symlink. Widescreen is enabled per-CRC via gamesettings (PCSX2 identifies games by CRC before applying pnach).

On PCSX2 versioning: the AUR’s pcsx2-latest-bin tracks the 2.7.x line, which is where all the modern features live (texture replacement, FXAA, PCRTC antiblur). The default pcsx2 in Arch repos is still on 2.6.3. The gap is over 250 commits of fixes and new features.

PS3: RPCS3 with curated per-game configs

RPCS3 has an annoying detail: per-game configs live in ~/.config/rpcs3/custom_configs/config_<SERIAL>.yml. The file format has a version, and if you hand-write YAML with the wrong version, RPCS3 silently rejects it and falls back to defaults. That cost me time to figure out.

The rpcs3_per_game_configs role handles it like this:

1. Queries the RPCS3 community compatibility DB for recommended presets per title
2. Applies curated overrides on top for titles I know need specific tuning (typically GT5 and GT6)
3. Saves the YAML with the exact filename convention (config_<SERIAL>.yml, config_ prefix mandatory)

For the Gran Turismo line:

• GT5 (BCUS98114, BCES00569): Resolution Scale 300%, Shader Precision Ultra, Force High Precision Z, SPU XFloat Accurate, Multithreaded RSX. The combo kills the typical RSX dithering without breaking the GT-series safety config (WCB/RCB off).
• GT6 (BCES01893 + regional variants): special case, version pinned to v1.05. Patches 1.06+ regress with black surfaces on cars in the garage menu. The extract_ps3_dlc.py script has a per-title PATCH ceiling specifically to pin GT6 at 1.05 even when PSN serves newer patches. Also, Force CPU Blit is mandatory (without it, full-screen flicker). The trade-off is that the rear-view mirror stays permanently black — turning WCB on would restore the mirror but downgrade to native 720p. I’ll take no mirror.

More details on those two in docs/gt5-rpcs3.md and docs/gt6-rpcs3.md.

PS3 update checker