sHEL

adspace: The Redirect Engine That Could

2025-11-01T09:00:00+00:00

Every project starts with a template. A blank canvas. A index.html and a dream. adspace is currently just that — a single template, a timer counting up from 11.20 seconds, and a name: Hillscape Journey.

But the vision is bigger. Much bigger.

What Exists Today

Right now, adspace is a redirect engine template living at shel.sh/projects/adspace/templates/1. It shows a scenic hillscape background with a subtle counter. Simple. Peaceful. Deliberately minimal.

The template system is designed for interstitial redirects — those moments between clicking a link and arriving at the destination where you have, say, 5-15 seconds of the user’s attention. Instead of showing a generic “you will be redirected” message, why not show something beautiful? Something that might make the user actually want to pause before the redirect completes?

Where It’s Heading

The long-term plan is a pluggable redirect engine with a template marketplace. Creators design interstitial templates (like Hillscape Journey), advertisers bid on redirect slot time, and users get something visually interesting instead of a blank loading screen.

The architecture I’m imagining:

Template Layer: HTML/CSS/JS interstitial designs, each with configurable parameters (background, timer duration, transition animation, optional interactive elements). Think of it as themes for the space between pages.

Redirect Layer: Fast, tracked URL shortening with analytics — click counts, dwell time on the interstitial, completion rate to final destination.

Ad Insertion Layer: Optional sponsored content in the interstitial space. The key constraint: it must be as pleasant as the default templates. No flashing banners. No auto-playing audio. Just calmly presented, beautifully designed content that respects the user’s attention.

The Philosophy

Most ad tech is hostile. It interrupts, distracts, and degrades the experience. adspace is an experiment in the opposite: advertising as ambient art. If someone is going to wait 5 seconds for a redirect anyway, that time can be either empty and frustrating, or filled with something worth looking at.

The Hillscape Journey template embodies this — a gentle landscape, a slow counter, no demands on the user. Just a moment of visual calm before the next page loads.

Why This Matters

Redirect pages are universally hated because they’re universally bad. A blank screen with “please wait.” A spinning loader that gives no indication of progress. Or worst of all, a wall of aggressive ads that make you hunt for the “skip” button.

adspace proposes: what if the redirect page was the best-designed page in the entire flow? What if people remembered your redirect page? What if the ad was so well-crafted that users shared screenshots of it?

That’s the experiment. Currently at template #1, 11.20 seconds, and counting.

View the template

Project directory

macrohard: Not Your Average Macro Extension

2025-10-15T10:00:00+00:00

Task scheduling and macro automation on Windows has a reputation. The built-in Task Scheduler is powerful but opaque. AutoHotkey is flexible but its scripting language shows its age. Commercial tools are either enterprise-expensive or consumer-limited. And none of them give you a visual node editor where you can wire together IF/THEN/ELSE logic by dragging connections between blocks.

macrohard does. It’s a complete rewrite and extension of Tasket++ with a ComfyUI-style node editor, checkpoint-based flow control, and a typed HTTP trigger daemon — turning repetitive desktop tasks into visual, composable workflows.

What It Is

macrohard is a Visual Workflow Automation Platform for Tasket++. It extends Amir Hammoutene’s ScheduledPasteAndKeys (tested against v1.8) with three integrated components:

Component	Stack	Purpose
Daemon	C++	HTTP-triggered task execution engine
Workflow Editor	React + React Flow	Visual node-based workflow design
PI Agent	TypeScript	LLM-integrated automation agent

The Architecture

+---------------+     HTTP      +-----------------------+
| Android/Tasker| <-----------> |  tasket-httpd.exe     |
| Home Assistant|   port 7777   |  (C++ daemon)         |
| curl/any      |               |  - TaskExecutor*      |
|               |               |  - TaskRegistry       |
|               |               |  - cpp-httplib        |
+---------------+               +----------+------------+
                                           |
                                           | loads .scht
                                           v
                                +-----------------------+
                                |  Tasket++ Engine      |
                                |  (PasteAction,        |
                                |   KeysSequenceAction, |
                                |   SystemCommands,     |
                                |   CursorMovements,    |
                                |   RunningOtherTask)   |
                                +-----------------------+

+---------------+     HTTP      +-----------------------+
| Browser       | <-----------> |  Workflow Editor      |
| localhost:3000|               |  (React + React Flow) |
|               |               |  - Node editor        |
|               |               |  - Checkpoint editor  |
|               |               |  - Macro library      |
|               |               |  - Inline grid edit   |
|               |               |  - Copy/paste/delete  |
+---------------+               +----------+------------+
                                           |
                                           | JSON workflow
                                           v
                                +-----------------------+
                                |  PI Agent Extension   |
                                |  (@pi-extensions/     |
                                |   pi-tasket-http)     |
                                +-----------------------+

The C++ Daemon

The daemon replaces Tasket++’s TaskThread with a TaskExecutor class (avoids the private copyActionsList() API). It uses cpp-httplib for HTTP serving and listens on port 7777 by default. Any HTTP client can trigger tasks — curl, Home Assistant, Tasker on Android, or the Workflow Editor itself.

The daemon loads .scht macro files from saved_tasks/, maintains a TaskRegistry of available entrypoints, and executes tasks through the Tasket++ engine. Actions include: paste operations, key sequences, system commands, cursor movements, and running other tasks as subroutines.

The Workflow Editor

Built with React and React Flow, the editor provides a ComfyUI-inspired canvas where workflows are graphs, not scripts. Five custom node types:

EntrypointNode — Inline value editing (string, bool, float)
DataGridNode — Inline 3×3 cell editing for tabular data
CheckpointNode — IF/THEN/ELSE branching logic
MacroNode — References saved .scht macro files
OutputNode — Terminal actions and result capture

The checkpoint system is the killer feature. Traditional macro tools run linearly. macrohard’s checkpoints let you branch: IF window title contains “Error”, THEN click dismiss, ELSE proceed. The graph traversal engine in workflowEngine.ts handles the full execution flow with cycle detection and subgraph isolation.

Keyboard shortcuts, copy/paste/delete, and a macro library with drag-and-drop placement make the editor feel like a native application. Zustand manages state with a full undo/redo stack.

The PI Agent

The @pi-extensions/pi-tasket-http TypeScript package provides 6 PI (Programmable Intelligence) tool registrations that let an LLM agent interact with the macrohard system. The agent can: list available tasks, trigger execution, read grid data, modify entrypoints, and query execution status — all through typed HTTP calls to the daemon.

This means you can tell an LLM “run my morning setup routine” and it will: query the available tasks, find morning-setup.scht, trigger it via HTTP, and report back what happened.

Installation

One PowerShell command as Administrator:

git clone https://github.com/CommanderTurtle/macrohard
cd macrohard

# Also clone the original Tasket++ source (required for daemon build)
git clone https://github.com/AmirHammouteneEI/ScheduledPasteAndKeys.git original

# Apply the one-line patch
copy daemon\patches\Task.h.patch original\
cd original && git apply Task.h.patch && cd ..

# Install everything
.\install.ps1 -QtPath "C:\Qt\6.9.3\mingw_64"

Prerequisites: Qt 6.9.3 (MinGW or MSVC), CMake 3.16+, bun.

Run everything with .\run.ps1 — starts both the daemon and workflow editor. Or .\run.ps1 daemon for daemon-only.

Repository Layout

macrohard/
├── README.md
├── install.ps1              # One-click Windows installer
├── run.ps1                  # Runtime launcher
├── .tasketconfig.json       # Generated config
│
├── original/                # Tasket++ source (patched)
│
├── daemon/                  # C++ HTTP daemon
│   ├── CMakeLists.txt
│   ├── patches/Task.h.patch
│   ├── include/             # Headers
│   ├── src/                 # C++ sources
│   ├── saved_tasks/         # .scht macro files
│   └── test/                # Python API validation (63 tests)
│
├── workflows/               # React workflow editor
│   └── src/
│       ├── types/workflow.ts
│       ├── engine/checkpoint.ts
│       ├── engine/workflowEngine.ts
│       ├── stores/workflowStore.ts
│       └── components/nodes/
│
├── pi-extension/            # PI Agent
│   └── src/
│       ├── client/tasket-client.ts
│       ├── tools/tasket-http.ts
│       └── skills/
│
└── docs/
    ├── INSTALL.md
    ├── API.md
    ├── PI_AGENT.md
    └── ARCHITECTURE.md

64% C++, 29.8% TypeScript, 2.4% PowerShell. GPL-3.0 licensed.

macrohard turns the tedious into the visual. If ComfyUI made ML model pipelines tangible, macrohard does the same for desktop automation.

github.com/CommanderTurtle/macrohard

Deep Dive: sHEL's Schema System

2025-09-01T14:00:00+00:00

One of sHEL’s most powerful features is its schema system. In this post, we’ll explore how sHEL schemas work and why they’re different from traditional approaches.

Schema as Contract

In sHEL, a schema isn’t just validation — it’s a contract between producer and consumer. When you define a schema, you’re specifying:

The exact structure of the data
Literal constraints (no injection possible)
Transformation rules
Pipeline compatibility

Defining Schemas

sHEL schemas are written in sHEL’s own schema definition language:

schema User {
  id: uuid,
  name: literal<string>,
  email: literal<string>,
  role: enum("admin", "user", "guest"),
  created_at: timestamp
}

Notice the literal<> wrapper — this is the key. Any data passing through this schema is guaranteed to be treated as a literal value, never as executable code.

Validation Pipeline

Schemas integrate directly into pipelines:

# Validate incoming data against schema
cat users.json | shel validate --schema User | shel transform --to csv

If validation fails, sHEL provides detailed error messages with line numbers and context.

Performance

Schema validation in sHEL is fast. Really fast. Our benchmarks show:

Dataset Size	Validation Time	Memory Usage
1K records	0.3ms	2MB
100K records	12ms	8MB
10M records	890ms	128MB

Next Steps

Read the full schema documentation for advanced features like conditional validation, custom types, and schema composition.

Have questions? Join us on Slack or open a GitHub discussion.

Introducing sHEL: A New Kind of Data Substrate

2025-08-15T09:00:00+00:00

Today we’re excited to introduce sHEL — a volatile, literal-safe, automation-friendly data substrate that brings the reliability of a turtle shell to your data pipelines.

The Problem

Modern data interchange is fragile. JSON, YAML, TOML — they all suffer from the same fundamental issues:

Injection vulnerabilities — unescaped strings open the door to injection attacks
Parsing ambiguity — subtle syntax differences break parsers across implementations
Tooling fragmentation — every format needs its own toolchain

Our Solution

sHEL takes a different approach. Inspired by the Unix philosophy, sHEL treats data as a stream of literal-safe tokens that flow through composable pipelines.

Key Design Principles

Literal-Safe by Default — Data is always treated as literals. No escaping, no injection.
Volatile Operations — Fast, in-memory processing with optional persistence.
Automation-First — Structured output designed for machine consumption.

Quick Example

Here’s what sHEL looks like in practice:

# Parse a log file and extract structured data
cat app.log | shel parse --format json | jq '.level == "ERROR"'

# The output is always predictable, always safe
{
  "timestamp": "2025-08-15T09:00:00Z",
  "level": "ERROR",
  "message": "Connection timeout",
  "literal": true
}

What’s Next

This is just the beginning. We’re building:

A rich plugin ecosystem
IDE integrations
Visual pipeline builders
Enterprise features

Get started today and let us know what you think!

countku: Expert Level Counting

2025-07-15T10:00:00+00:00

It started with a Discord thread. I was playing with two bots — a counting bot and Haikubot — and wondered: what if counting could be poetry? What if every number you expressed had to fit the rigid 5-7-5 structure of a haiku?

That question became countku.

The Origin

I posted the original concept to Reddit (r/haikusbot) with a simple challenge: get both the counting bot and Haikubot to validate the same message simultaneously. The screenshot tells the whole story — me typing 21+1.1-1.1+1-1, the counting bot accepting it as valid (it evaluates to 22), and Haikubot transcribing it into perfect 5-7-5 form:

Twenty two, plus one
point one, minus one point one,
plus one, minus one

Then I pushed further. 1-3.000+1+1+1 — evaluating to 1, the next number in the count — became:

One minus three point
zero zero zero, plus
one, plus one, plus one

The bots agreed. The game was born.

What Countku Actually Is

Countku is a base-ten number system more convoluted than all prime numbers. The core premise: express any mathematical result as a haiku (5-7-5 syllables) where the math actually evaluates to the intended number.

It isn’t just wordplay — it’s a genuine constraint system with documented rules:

5-7-5 syllable structure is strictly enforced
No cutting words across line breaks — “ze-“ on line 1 and “ro” on line 2 is illegal
Decimal is always “point” — proper mathematical English
Zero variants: “zero” (2 syl), “zed” (1 syl), or “oh” (1 syl) — pick one per thread and stick to it
“Type shit” and two-syllable memes are legal BS words — they pad syllables without affecting the math
Words must finish at the end of a Ku — no “one point zero Oh” cheating that circumvents the memory challenge

The O’Leary license applies: I don’t intend to monetize it, but if you sell countku or a variation, I ask for 1 satoshi per API call. You can wrap the shaves of pennies in envelopes and mail them to me.

The Documentation

What started as a joke grew into a fully documented system. I built out comprehensive docs across three files:

1.md — The Rulebook documents every substring in the countku lexicon with full grammatical metadata — syllable count, whether it’s a base number, scale word, math operator, preposition, or passive/active participle. There are 127 indexed substrings from “one” to “influence,” each with their bit flags for the parsing engine. Five complete data tables cover: the substring database, base glossary (Zero through Highers), full operators matrix (46+ distinct operations), prepositional/auxiliary combinations, and modifier/ordinal definitions including Latin and Greek systematic forms.

2.md — The Changelog tracks the engine evolution from v1.0 through v7.4, including the deferred emission engine, $P_Action vs $P_Passiv prepositional semantics (does “using the power of” wrap the entire expression or just the last term?), logarithm system overhaul, trig parenthesis fixes, and noun operator preposition gating.

3.md — The Engine Reference is the complete technical manual for the JavaScript conversion engine, covering the tokenization pipeline, convertTokens() state machine, the fallover syllable system for automatic 5-7-5 line detection, and the CountkuConverter and HaikuValidator class architectures.

The Math Engine

The JavaScript engine converts English word phrases into executable math expressions. Some examples from the docs:

Input	Expression	Result
one plus two	1+2	3
the square root of sixteen	Math.sqrt(16)	4
five to the sixtieth	(5)**60	huge
the sine of zero plus the log of one and two	Math.sin(0)+Math.log(1)+2	2
five plus three using the power of two	(5+3)**2	64
five plus three under the power of two	5+(3)**2	14

The $P_Action vs $P_Passiv distinction is the clever part. “Using” wraps the entire preceding expression in parentheses before applying the power. “Under” wraps only the immediately preceding term. Same words, different math.

Sakura Count Ninja — The Game

All of this became Sakura Count Ninja, a browser-based counting game with four modes:

Normal — Base 10 JS math expression evaluation
Hard — Base 2, results shown in binary
WTF — Base 16, results shown in hex
Countku — English word haikus validated for 5-7-5 structure then converted to math

The game features ninja animations (idle, run, jump), streak tracking, sound effects, and an end-game dashboard. The countku mode runs the full HaikuValidator + CountkuConverter dual-check system — both the syllable structure AND the math must be valid.

The Future: A JS Math Library

The long-term vision is extracting the countku engine into a proper JavaScript math library that invalidates non-haiku math and forces haiku-safe operations. Imagine a math library where eval("one plus two") works but eval("1 + 2") doesn’t — where every computation must pass through the linguistic layer. Where the constraint isn’t a bug, it’s the feature.

The documentation is already structured like a language specification. The engine handles ordinals, fractions, trigonometry, logarithms, roots, powers, passive/active voice distinctions, and noise-token stripping. Turning that into a countku-math npm package is the natural next step.

Play the game at shel.sh/projects. Read the full docs at shel.sh/projects/1.md, 2.md, and 3.md. And remember: numbers are nature.

Turtle Protect: An Independent Shelling Company

2025-06-20T14:00:00+00:00

Most CAPTCHA solutions ask you to replace your entire page architecture. ReCAPTCHA wants its script in your head, its badge on your footer, and its external API calls on every form submission. hCaptcha isn’t much different. They’re effective but heavy — external dependencies, user tracking, significant page weight, and a UX that treats every visitor as a suspected bot first and a human second.

Turtle Protect takes a different approach. It’s a drop-in CAPTCHA overlay — you don’t replace anything. Think of it like adding three ingredients to a recipe you already have.

The Philosophy

The project tagline is “an independent shelling company” — a play on words that captures the ethos. Independent: no external API calls, no third-party dependencies, no tracking. Shelling: the protective outer layer. Company: it just keeps you company on your existing page, no drama.

The core insight is that most sites don’t need fortress-level bot protection. They need a sensible gate that keeps out automated abuse without annoying legitimate users or loading external scripts.

How It Works

The implementation is intentionally minimal. You add three things to your existing HTML:

A small JavaScript snippet that loads the overlay
A button trigger element (can be your existing submit button)
A lightweight CSS file for the overlay styling

When the user clicks the protected button, an overlay appears with the CAPTCHA challenge. Upon successful completion, the overlay dismisses and the original form submission proceeds normally. The existing page logic doesn’t change — Turtle Protect just intercepts, verifies, and releases.

The docs show the full integration pattern:

<!DOCTYPE html>
<html>
<head>
  <!-- Your existing stuff like title, other CSS -->
  <link rel="stylesheet" href="turtle-protect.css">
</head>
<body>
  <!-- Your existing content -->
  <h1>Welcome to My Site</h1>
  <button id="login-btn">Login</button>

  <script src="turtle-protect.js"></script>
  <script>
    TurtleProtect.guard('#login-btn', {
      onSuccess: function() {
        // Your original login logic here
      }
    });
  </script>
</body>
</html>

The “sickh” CAPTCHA

The project includes a reference implementation called the “sickh” CAPTCHA (a stylized spelling of “sick” — as in, that’s sick). It’s an anti-bot button that’s easily placeable anywhere on an existing page. The overlay pattern means it works with vanilla HTML, React, Vue, or any framework — since it operates at the DOM level, your framework doesn’t need to know it exists.

The full implementation guide with the overlay diagram and step-by-step integration is in the project docs:

Project page: shel.sh/projects/captcha
Documentation: shel.sh/projects/captcha/docs
Raw docs: shel.sh/projects/captcha/docs/raw.txt

Why Not Just Use reCAPTCHA?

Three reasons:

Privacy: Turtle Protect makes zero external network requests. No Google servers, no tracking cookies, no behavioral profiling. Your users’ interactions stay on your domain.

Weight: The entire library is under 5KB gzipped. reCAPTCHA’s script alone is ~150KB, plus the badge, plus the verification request.

Control: You own the challenge generation, the validation logic, and the UX. Want to change the challenge type? It’s your code. Want to customize the styling? It’s your CSS. No API keys to manage, no quota limits, no terms-of-service changes.

Current Status

Turtle Protect is functional and documented. The overlay implementation works across modern browsers. The project is actively maintained as a side project — the kind of tool you build because you need it yourself, then share because others probably need it too.

The captcha philosophy mirrors the broader sHEL approach: literal-safe, dependency-light, and respectful of the user. No external calls. No hidden tracking. Just a simple shell that keeps the bots out and the humans flowing through.

View the docs

See it in action

fsharp-zensical: F# Meets Material for MkDocs

2025-05-10T09:00:00+00:00

Documentation sites have a familiar shape: Markdown files, a static site generator, some theme customization, and a CI pipeline that builds on push. Most teams reach for MkDocs (with Material), Docusaurus, or Hugo. But what if your docs need to integrate with F# code? What if you want type-safe HTML generation, a Giraffe ViewEngine DSL, and the full Zensical (Material for MkDocs) feature set — admonitions, tabs, Mermaid diagrams — all while keeping the ability to drop raw HTML into the pipeline?

That’s the question fsharp-zensical answers.

What It Is

fsharp-zensical is a complete F# → GitHub Pages workflow using Zensical (Material for MkDocs) with full F# and DSL support. It’s designed as a cross-repo pages orchestrator: each site folder (main/, docs/, app/, blog/) builds locally, and GitHub Actions push artifacts to entirely separate repositories using token-authenticated git. Think of it as a monorepo docs system where each subdomain gets its own repo and its own deployment pipeline.

The project is a continuation of the original fsharp-material work, restructured for maintainability and expanded with new features.

Architecture Overview

The system is organized around site folders, each representing a distinct documentation property:

Folder	Purpose
`main/`	Primary landing page
`docs/`	Technical documentation
`app/`	Application guides
`blog/`	Blog posts and announcements

Each folder contains its own F# source files, markdown content, and build configuration. The shared infrastructure lives at the root: Directory.Build.props, GenerateConfig.fsx, and the GitHub Actions workflows in .github/.

Two Page Types

The system supports two distinct page construction patterns:

1. Standalone HTML (index.fs)

For pages with complex JavaScript interactivity or heavy F# logic — the page is built entirely with Giraffe ViewEngine DSL:

module Blog.MyPage
open Giraffe.ViewEngine

let render () =
    html [] [
        head [] [ title [] [ str "My Page" ] ]
        body [] [
            h1 [] [ str "Hello from F#!" ]
            script [] [
                rawText """
                console.log("Hello!");
                """
            ]
        ]
    ]
    |> RenderView.AsString.htmlDocument

2. F# with Markdown (indexmd.fs)

For documentation-heavy pages that need Zensical features — the F# generates components that get embedded in markdown frontmatter:

module Docs.MyPage
open Giraffe.ViewEngine

let card =
    div [ _class "card" ] [
        h3 [] [ str "Welcome" ]
        p [] [ str "Type-safe components!" ]
    ]
    |> RenderView.AsString.htmlNode

let content = $"""
---
title: My Page
---
# My Page
{card}
!!! tip "Zensical Features"
    Admonitions, tabs, Mermaid diagrams all work!
"""

The markdown passes through Zensical (Material for MkDocs), so you get the full feature set: admonitions, code annotation, content tabs, Mermaid diagrams, and the complete visual theme.

The HTML-to-DSL Converter

One of the most practical features is the /throw/ folder. Drop any HTML file in there, push to GitHub, and a workflow automatically:

Parses the HTML element-by-element
Generates pages/my-page/index.fs with proper Giraffe ViewEngine DSL
Renders the output HTML for deployment

This means designers can work in raw HTML (or export from Figma, or paste from Tailwind templates), and the system converts it to type-safe F# DSL automatically. For <script> and <style> blocks, the converter uses triple-quoted strings — no escaping needed.

Input HTML:

<div class="container">
  <h1>Hello World</h1>
  <p>Welcome to my site</p>
</div>

Output F#:

module Views
open Giraffe.ViewEngine

let page =
    div [ _class "container" ] [
        h1 [] [ str "Hello World" ]
        p [] [ str "Welcome to my site" ]
    ]

Shared Modules

The src/ folder contains reusable components: AST manipulation utilities, tree walking functions, and shared Giraffe view helpers. The blog/ and documentation/ folders contain the actual content. The pages/ folder holds generated output from the HTML-to-DSL converter.

GitHub Actions Pipeline

The CI/CD setup is token-based. GitHub Actions build each site folder locally, then push the generated output to separate repositories — one per subdomain. This means docs.yoursite.com, blog.yoursite.com, and app.yoursite.com can all originate from the same monorepo but deploy independently.

Why F# for Documentation?

The usual objection: “Why not just use plain Markdown?” The answer is type safety and composability. When your documentation includes generated API references, version matrices, or dynamic content pulled from other sources, having a full programming language at your disposal — with compile-time checking — beats template string substitution every time.

The Giraffe ViewEngine DSL is particularly well-suited for this because it’s just F# functions. No template syntax to learn. No magic string interpolation. Just functions composing functions, with the full power of the F# type system catching errors before they reach production.

Project Structure

fsharp-zensical/
├── .github/              # CI/CD workflows
├── app/                  # Application docs site
├── blog/                 # Blog site
├── docs/                 # Technical docs site
├── documentation/        # Project documentation
├── main/                 # Landing page
├── pages/                # Generated pages from HTML
├── src/                  # Shared F# modules
├── throw/                # HTML drop zone for conversion
├── Directory.Build.props # MSBuild properties
├── GenerateConfig.fsx    # Config generation script
└── html2giraffe.sln      # Solution file

98.7% F#, 1.3% HTML. AGPL-3.0 licensed.

View on GitHub

Documentation

regedited: So I Rewrote the Windows Registry in Rust

2025-04-01T11:00:00+00:00

It started as a joke. “Why need a DB? You should dangerously grep a million-line markdown file.” That became the repo description, then the design philosophy, then — somehow — an actual Rust project that reimagines the Windows Registry as a memory-mapped, plaintext-parsable database with O(1) section jumps.

What regedited Is

regedited is a fast plaintext parsing database with structured headers, typed hex-word offsets, and O(1) section jumps on multi-GB files. The tagline says it all: dangerously grep a million-line markdown file.

The name itself is a pun — “the registry, edited.” It’s not a registry editor in the traditional sense. It’s a complete rethinking of how structured system configuration data should be stored, parsed, and accessed.

The Core Insight

The inspiration came from the safetensors format — specifically its ability to scan, diff, and replace keys in multi-gigabyte files without loading them into RAM. If that works for ML model weights, why not for structured configuration data?

The approach: memory-map your file and build an index of section headers. A 10GB file with 1,000 sections uses ~200KB of Rust heap — the file lives in OS-managed virtual memory, not your process RAM. The trick is the hex-word store: each section header contains typed line-number pointers that encode both the data type and the byte offset.

Approach	10GB File RAM	Section Jump
`cat + grep`	10GB	O(n) scan
Python `readlines()`	10GB	O(1) — at a cost
regedited	~200KB	O(1) byte offset

Architecture

The database format uses structured markdown documents with full key-value semantics. Section headers carry typed hex-word offsets — essentially embedded metadata that lets the parser jump directly to any section without scanning. The format is human-readable (it’s markdown), diff-friendly, and version-control compatible — three things the actual Windows Registry hive format is not.

The Rust codebase is 90.2% Rust, 7.5% Python (for the test compendium), and 2.3% Shell. The project includes:

src/ — Core Rust library with the parser, index builder, and section jumper
docs/ — Format specification and API documentation
examples/ — Sample databases and usage patterns
pi/ — Platform interface layer
test_compendium.py — Comprehensive Python test suite

Why Plaintext?

The Windows Registry binary format (hive files) is opaque, fragile, and impossible to version control meaningfully. regedited asks: what if system configuration was just well-structured markdown? Readable in any editor. Diffable in git. Greppable in any Unix tool. And yet — with the hex-word index — as fast as a binary format for random access.

The structured headers mean you don’t actually need the “dangerous grep” anymore. The index gives you direct jumps. But the grep still works if you want it — that’s the beauty of plaintext.

Project Status

18 commits on main. AGPL-3.0 licensed. The core engine is functional and the test compendium validates parsing correctness across a range of file sizes and section counts. The project continues to evolve — the next frontier is write operations (safe section edits without full file rewrites) and a query language for filtered lookups.

github.com/CommanderTurtle/regedited

Gemma 4 on Blackwell: A Three-Act Saga of Pain and Glory

2025-03-15T16:00:00+00:00

Getting Gemma 4 running locally on a 5090 wasn’t supposed to be this hard. NVIDIA’s latest Blackwell architecture, a brand-new MoE model from Google, and a quantization format (NVFP4) designed specifically for the hardware — what could go wrong?

Everything, it turns out. But the destination was worth every hour.

The Model

The release is sHEL Gemma 4 A4B Heretic NVFP4 — a pruned-expert, reasoning-optimized Gemma-4 MoE model with full NVFP4 quantization using NVIDIA ModelOpt. Built on the DavidAU heretic base, pruned from 128 to 90 experts, then fully finetuned. It supports thinking mode (with <|think|> blocks), instruct mode, tool calling, and full multimodal vision via AEON’s proven methods.

The specs: 19B parameters (26B pruned), 10B params export size, ~16GB on disk, 256K native context length, served at 64K for throughput. On a 5090 with 32GB VRAM, four parallel 65K context windows at 170 tok/s.

Act I: Following Allen Kuo Into the Minefield

I started where anyone should start — Allen Kuo’s three-part Medium saga on getting vLLM running on Blackwell.

Part 1: vLLM or Ollama on Blackwell set the stage. Allen laid out the fundamental problem: Blackwell is new, the software stack is raw, and most “it just works” claims are lies. He benchmarked both vLLM and Ollama, found landmines in CUDA version compatibility, driver requirements, and the reality that “FP8 support” doesn’t mean “your model will load.”

Part 2: Gemma 4 on vLLM vs Ollama went deeper. Specific to Gemma 4, Allen documented the MoE routing issues, the context length limitations, the memory footprint surprises. His 96GB Blackwell GPU gave him room I didn’t have — my 5090’s 32GB meant every quantization decision mattered.

Part 3: Finishing What We Started was where things got real. NVFP4 on vLLM, inside WSL2, with manual patching. Allen documented the full reproduction method: ModelOpt calibration, the 15-hour CPU quantization process, manual shard patching for vision tower keys, and the specific environment variables needed to make Blackwell’s Cutlass/FlashInfer/Marlin paths all activate correctly.

Act II: The WSL2 Rabbit Hole

Following Allen’s guide, I went deep into WSL2. The quantization itself took ~15 hours on a high-end CPU — the model simply doesn’t fit in BF16 on a 5090 alone, so you quantize on CPU using uv run inside a vLLM venv. The calibration uses 512 samples at sequence length 4096, batch size 3, with NVFP4_DEFAULT_CFG (plain NVFP4, no AWQ).

Then came the patching nightmare. ModelOpt doesn’t perfectly preserve vision tower + down_proj/up_proj/gate_proj/q_proj/k_proj/v_proj/o_proj keys across shards. I ended up running a sequence of manual patch scripts:

# Patches 'vision_tower and down_proj' keys
uv run clean_shards3-2.py
# Patches 'vision_tower and up_proj' keys
uv run clean_shards3-2-1.py
# ...and so on for every combination

Each script takes keys from the original .safetensors file and transplants them into the post-ModelOpt shards. When vLLM errors with AssertionError: Tried to load weights of size torch.Size([2816,576]) to a parameter of size torch.Size([2816,1152]), you run scanoffendingkey.py, find the mismatch, and build a new patch script.

The final fix was the EOS configuration. Gemma 4 uses internal control tokens (<|channel>, <channel|>, <|think|>, <|tool_call>, <tool_call|>) that can leak into API responses as plaintext spam if not handled. Adding tokens 98, 100, and 101 to eos_token_id in generation_config.json stops the model from getting stuck in repetition loops.

Act III: Windows Native and the Breath of Fresh Air

After weeks in WSL2, I stumbled on SystemPanic/vllm-windows — the official vLLM Windows port. This changed everything.

No more WSL2 overhead. No more cross-filesystem path translation. No more export instead of $env:. Just native Windows PowerShell with a uv venv and the vllm-windows wheel.

The environment variables for Windows:

$env:VLLM_TEST_FORCE_FP8_MARLIN="1"
$env:VLLM_MARLIN_USE_ATOMIC_ADD="1"
$env:VLLM_ALLOW_LONG_MAX_MODEL_LEN="1"
$env:TORCH_MATMUL_PRECISION="high"
$env:PYTORCH_CUDA_ALLOC_CONF="expandable_segments:True"
$env:NVIDIA_FORWARD_COMPAT="1"

The serving command:

vllm serve sHEL1562/gemma-4-A4B-it-MoE-HERETIC-nvfp4-blackwell `
  --quantization modelopt `
  --kv-cache-dtype fp8_e4m3 `
  --max-model-len 65536 `
  --max-num-seqs 4 `
  --max-num-batched-tokens 8192 `
  --gpu-memory-utilization 0.90 `
  --enable-chunked-prefill `
  --enable-prefix-caching `
  --trust-remote-code `
  --enable-auto-tool-choice `
  --tool-call-parser gemma4 `
  --reasoning-parser gemma4

One PowerShell window. Four concurrent 65K context streams. 170 tok/s.

The AEON Connection

The quantization method follows AEON-7’s SuperGemma guidelines. AEON’s work on the “Gemma Problem” — the internal control token leakage, the MoE routing quirks, the calibration strategies for pruned experts — was foundational. The model card explicitly references AEON’s JSON configurations and the clean_shards patching methodology.

For anyone reconstructing the ModelOptimizer pipeline: it requires modelopt, torch, and accelerate, performed in WSL with uv run. The reproduction script is included in the model files. Just… expect to wait. And patch. And patch again.

Life After WSL

The experience fundamentally changed how I work. WSL2 is still there for quantizing and debugging — anything that needs the full Linux build chain. But for actual inference serving? Native Windows vLLM is the way. I followed OneMarcFifty’s WSL productivity guide for setting up the Kali taskbar, minimal tools, and the hobby-project mindset. The future is a hybrid: WSL for build environments, Windows for runtime.

Quickstart for 5090 Owners

Prerequisites: NVIDIA drivers, CUDA, PowerShell Preview from the Windows Store. No external dependencies.

# Test the model is serving
curl http://localhost:8000/v1/models

# Run inference
$tmp="$env:TEMP\vllm_req_$(Get-Random).json"
$json=@{model='gemma4';messages=@(@{role='user';content=@(@{type='text';text='Your prompt here'})})}|ConvertTo-Json -Depth 10 -Compress
Set-Content -Path $tmp -Value $json
curl.exe http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d "@$tmp"

Pipe the output through Notepad++ (find+replace ` ` with empty, \n with literal newline, \" with "), then paste into Obsidian for clean markdown rendering.

The model is uncensored, reasoning-optimized, and genuinely excellent at long-form narrative writing. The thinking blocks are unlike anything else — leave them on for complex writing tasks, switch to instruct mode for tool calling.

Download: sHEL1562/gemma-4-A4B-it-MoE-HERETIC-nvfp4-blackwell