Check</th>	Why it matters</th></tr></thead>
Container vs item count</td>	Update tool refuses sites with more than 100 containers</td></tr>
Album pages</td>	Deleted by the update</td></tr>
Gallery pages</td>	Convert to layout pages; embedded videos are lost</td></tr>
Share buttons</td>	Not supported in 7.1</td></tr>
Custom Adobe Typekit fonts</td>	Not supported in 7.1</td></tr>
Products per store page</td>	Cap of 200 per store</td></tr> </tbody></table> The script crawls `sitemap.xml</code>, hits ?format=json</code> for every URL, separates containers from items, and groups findings by severity (block / warn / info). Output is a markdown report you can read top to bottom.</p>` What it found on the real site</h2> The site I was auditing has a public face of maybe 30 pages. The sitemap lists 489 URLs. After separating containers from items and tag/category views, the real eligibility count is 126</strong>, which is 26 over the cap.</p> Eligibility count - Container pages (count toward 100-page cap): 126 - Individual items (excluded from cap): 121 - Filter/tag views (excluded from cap): 243 - ❌ OVER the 100-page eligibility cap by 26. Containers by type - page: 76 - gallery: 45 - products: 3 - blog: 1 - events: 1 </code></pre> The story isn't the blog. The blog has one container page and 65 posts; none of that is a problem for the cap. The story is 45 gallery pages</strong> built up over a decade of convention photos, fall show photos, monthly meeting photos. Each gallery is a container, each one counts, and each one is a candidate for the "embedded videos won't survive" warning. Galleries plus the 76 plain pages already put the site over the cap before you even look at the rest.</p> This is the kind of detail you can't get from a casual click-through. The webmaster knew the blog was big but hadn't connected the gallery archive to the update tool's cap.</p> Without this audit, the conversation would have been:</p> "We'll run the update tool when you're ready." "The update tool refused." "Oh."</p> </blockquote> Instead, the conversation becomes:</p> "You're 26 pages over the eligibility cap. Most of the slack is in 45 gallery pages, many of which are show photos from 2016-2019 that probably don't need to stay live. Here are three ways to handle it."</p> </blockquote> That's the kind of pre-work that actually moves a project forward.</p> The script</h2> It's a single Python file, no dependencies beyond the stdlib. Crawls the public sitemap, fetches each page's JSON, runs the checks, emits markdown.</p> The full source is in a gist: sqsp-preflight.py</a>. About 400 lines. No setup. Run it as:</p> python3 sqsp-preflight.py https://example.com > report.md </code></pre> For a 30-page site it finishes in seconds. For a 489-URL site it takes a couple of minutes (one HTTP request per URL, no parallelism, good enough).</p> What it doesn't do</h2> A few things the audit can't see:</p> Members-only content.</strong> The crawler is unauthenticated. If a site has a member area with extra pages behind login, they're invisible.</li> Developer mode usage.</strong> Only the admin knows whether this is on.</li> Discontinued template detection.</strong> The template</code> field in the JSON is sparse. Cross-referencing against Squarespace's current supported-template list still needs a human eyeball.</li> Visual fidelity in 7.1.</strong> No tool can predict whether a 7.0 layout will look right in 7.1's Fluid Engine. That's why the update tool has a preview mode.</li> Sidebar navigation.</strong> I couldn't find a reliable signal in the JSON for this one.</li> </ul> The script's job is to surface the known unknowns</em> fast enough that the human can focus on the genuine judgment calls.</p> What this is and isn't</h2> It's not a migration tool. Squarespace's update tool is the migration tool. This is a preflight check</strong> that runs before you commit, surfaces the specific pages that drive eligibility, and produces a report a non-technical decision-maker can read. The update tool will tell you "no"; this tells you why and what to fix first.</p> It also isn't a project. I'm not going to maintain this as a package. Squarespace can change the JSON shape at any time and break it; the maintenance commitment isn't worth it. If you hit the same problem, fork the gist, adapt it to your site, throw it away after.</p> The actually-publishable thing here is the approach</em>: use ?format=json</code> to inventory the site, separate containers from items the way the update tool does, encode the documented limitations as checks, produce a markdown report. Anyone reading this should be able to recreate the script in an evening.</p> The bigger lesson</h2> Squarespace's docs tell you the limitations. The update tool tells you whether you qualify. Neither one hands you the punch list of which pages to deal with, in what order, and why</em>. That gap shows up over and over with hosted platforms: the docs describe the system, the tools enforce the rules, but nothing produces an actionable report against your specific site.</p> For any platform migration on any hosted product, the first useful piece of work isn't "start the migration." It's "audit the source against the destination's known constraints, in a form a human can act on." Sometimes that takes a script. Often a CLI plus an afternoon does it.</p> Building a Travel Itinerary Plugin Inside Discourse Unknown — Mon, 25 May 2026 00:00:00 +0000 I built a Discourse plugin that turns a category of topics into a chronological travel itinerary. One topic per trip, then a flight topic, a hotel topic, a note topic, all linked back to the trip. The plugin renders them on /itinerary as a clean list and per-trip timeline grouped by day.</p> You can see the result here: discourse-itinerary on GitHub</a></p> Why Discourse for This?</h2> Same reason I keep doing this: Discourse topics are extremely flexible, and seeing how far I can push them keeps teaching me the platform. A trip is just a topic. A flight is just a topic. The relationship between them is a custom field pointing at the parent trip. Everything else (permissions, search, edit history, who posted what, comments) comes for free.</p> That was the bet anyway. Reality had some opinions.</p> The Data Model</h2> After a couple of rewrites, the model settled at:</p> Category</strong> = "Itinerary". One per forum. Auto-created by the plugin on first boot, with a configurable site setting if the admin wants to point it at a different category.</li> Topic with itinerary_item_type = trip</code></strong> = a trip (the container).</li> Other itinerary topics</strong> = items (flight, train, hotel, event, transfer, note) that point at their parent trip via itinerary_parent_trip_id</code> on the topic's custom_fields.</li> </ul> Earlier versions used a tag (itinerary</code>) to mark which topics belonged to the plugin. That got dropped once itinerary_item_type</code> existed. The tag was load-bearing nostalgia, not real structure.</p> All metadata lives in topic_custom_fields</code>:</p> Field</th> Type</th> Example</th></tr></thead> itinerary_item_type</code></td> string</td> flight</code></td></tr> itinerary_parent_trip_id</code></td> integer</td> 123</code></td></tr> itinerary_starts_at</code></td> string</td> 2026-09-20T14:30</code></td></tr> itinerary_ends_at</code></td> string</td> 2026-09-21T09:15</code></td></tr> itinerary_origin</code></td> string</td> PDX</code></td></tr> itinerary_destination</code></td> string</td> MAD</code></td></tr> itinerary_location</code></td> string</td> Madrid</code></td></tr> itinerary_confirmation_code</code></td> string</td> ABC123</code></td></tr> itinerary_status</code></td> string</td> booked</code></td></tr> </tbody></table> Timestamps are stored as ISO-8601 strings, not DateTime. Lexical sorting on the raw column does the right thing for YYYY-MM-DDTHH:MM</code>, which means I never have to parse them on the database side.</p> The Plugin API Trapdoors</h2> Discourse plugins have a deceptively friendly API. You write a plugin.rb</code>, drop some assets under assets/javascripts/discourse/</code>, and things mostly work. Until they don't, and you have to figure out why.</p> Here are the ones that actually stopped me cold.</p> The route-map filename convention</h3> To register Ember client routes from a plugin, you put a file named <plugin-slug>-route-map.js</code> in assets/javascripts/discourse/</code>. Discourse scans requirejs.entries</code> for anything matching /route-map$/</code> and invokes its default export to build out the route tree.</p> I named the file correctly. The file loaded. The composer connector loaded. The route map itself never ran.</p> Turns out Ember resolves the actual route modules by name. With this route map:</p> export default function () { this.route("itinerary", function () { this.route("show", { path: "/:trip_id" }); }); } </code></pre> Ember will look for routes/itinerary/index.js</code> and routes/itinerary/show.js</code>. Not routes/itinerary-index.js</code> or routes/itinerary-show.js</code>, which is what I had originally. The dot in the route name becomes a path separator. I had copied the route map from discourse-cakeday but missed the nested directory convention for the route files.</p> You don't get an error for this. The route map just silently doesn't match anything client-side and the URL falls through to Rails.</p> Rails has to serve the HTML for an Ember route</h3> This was the big one. After fixing the route file paths, /itinerary</code> still 404'd. The error came from Rails, not Ember. The plugin had JSON routes:</p> Discourse::Application.routes.append do get "/itinerary/trips" => "itinerary#index", defaults: { format: :json }, constraints: { format: :json } get "/itinerary/trips/:id" => "itinerary#show", defaults: { format: :json }, constraints: { format: :json, id: /\d+/ } end </code></pre> But none of those match a browser request for GET /itinerary</code> (which wants HTML). Rails 404s, the browser never gets the Discourse app shell, Ember never loads, the route map never runs.</p> discourse-cakeday works because it mounts a full Rails Engine at /cakeday</code>, which catches the HTML request and serves the SPA bootstrap. Discourse plugins like discourse-invite-stats use the simpler pattern:</p> get "/itinerary" => "itinerary#page", constraints: { format: :html } get "/itinerary/path" => "itinerary#page", constraints: { format: :html } </code></pre> With an action that just renders the empty layout:</p> def page render "default/empty" end </code></pre> The empty layout is the SPA bootstrap. Ember takes over from there.</p> I burned a couple of hours on this before searching for it. Sometimes the fastest way to debug a plugin is to read three other plugins that do the same thing.</p> Composer fields and Glimmer autotracking</h3> The composer panel for itinerary fields shows different inputs depending on the item type. Flight has origin and destination, hotel has location, note has neither. The conditional rendering was driven by getters:</p> get itemType() { return this.composer.itinerary_item_type; } get showsRoute() { return ["flight", "train", "transfer"].includes(this.itemType); } </code></pre> This silently broke. The user could pick "Flight" from the dropdown, but the route inputs never appeared. The dropdown's change handler was firing. The composer model was being updated. But the template never re-rendered.</p> The reason: this.composer.set("itinerary_item_type", value)</code> doesn't go through a @tracked</code> property. Glimmer's autotracking can't follow composer.set(...)</code> on non-tracked composer fields. The getter reads from the composer correctly the first time, then becomes a dead read.</p> Fix:</p> @tracked itemType; @action setItemType(e) { this.itemType = e.target.value \|\| null; this.composer.set("itinerary_item_type", this.itemType); } </code></pre> Keep a local @tracked</code> copy of anything you read from the composer model in conditional getters. The composer side stays in sync via the .set()</code> call.</p> datetime-local silently drops half-filled values</h3> I had separate inputs for "Starts at" and "Ends at" with type="datetime-local"</code>. The user creates a flight, types a date, doesn't bother with the time, clicks save. The flight saves. The trip page shows "No items in this trip yet."</p> The flight was actually saved, just without itinerary_starts_at</code>. The TripItemFinder filters out items without a start time, so the flight existed in the DB but never reached the timeline.</p> Why? <input type="datetime-local"></code> doesn't fire input</code> or change</code> until both the date and time portions are populated. A half-filled value is "invalid" to the browser, and you get nothing.</p> I split the field into a <input type="date"></code> plus an optional <input type="time"></code>. The composer combines them into the stored format (YYYY-MM-DD</code> if just date, YYYY-MM-DDTHH:MM</code> if both). The timeline component already knew how to render both formats.</p> Two inputs, one stored field, no silent data loss.</p> Topics need a title that Discourse will accept</h3> Once the composer worked, I hit the wall I'd been ignoring: Discourse's title length validator requires 15 characters minimum, plus a "title seems unclear" heuristic that rejects titles like "Flight" or "Lisbon". For a travel itinerary where the "data" is in custom fields, making the user invent a meaningful 15-char title for every flight is hostile.</p> Discourse doesn't have per-category overrides for min_topic_title_length</code>. The validator reads the global site setting, full stop. I considered three options:</p> Lower the global. Affects every topic on the forum.</li> Monkey-patch the validator to skip checks for itinerary topics. Fragile.</li> Synthesize the title from the structured fields the user is already filling in.</li> </ol> Option 3 is the move. The composer already collects item type, origin, destination, location. Build the title from those and the user never has to type one.</p> synthesizeTitle() { const type = this.itemType; if (!type \|\| type === "trip") return; const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1); const o = this.composer.itinerary_origin; const d = this.composer.itinerary_destination; const loc = this.composer.itinerary_location; let title = cap(type); if (["flight", "train", "transfer"].includes(type) && (o \|\| d)) { title = `${cap(type)}: ${o \|\| "?"} -> ${d \|\| "?"}`; } else if (loc) { title = `${cap(type)}: ${loc}`; } this.composer.set("title", title); } </code></pre> Trip topics still take the user's title (you name a trip meaningfully; "European trip 2026" is more useful than "Trip"). Items get derived titles: "Flight: PDX -> MAD", "Hotel: Madrid Marriott", "Event: Symphony".</p> I also hide the title input via a body class when the composer is in itinerary-item mode, so users don't see a phantom input that gets overwritten on every field change.</p> The Other Stuff</h2> A few smaller things that made the plugin feel like a real tool.</p> Auto-creating the category</h3> The plugin provisions an "Itinerary" category on first boot. The slug-first lookup means if an admin already has a category called "itinerary" or "ITINERARY", we adopt it instead of creating a duplicate (which would fail uniqueness anyway). The provisioner also adds the category id to default_categories_muted</code> so new users don't see itinerary topics cluttering /latest.</p> Sidebar link</h3> Discourse's api.addCommunitySectionLink</code> adds a link to the sidebar's Community section. With the category muted by default, the sidebar link becomes the canonical entrypoint. No URL guessing required.</p> Add buttons</h3> Two big buttons: "+ Add trip" on /itinerary, "+ Add leg" on /itinerary/:trip_id. Each opens the standard composer pre-scoped to the itinerary category, with the right itinerary_item_type</code> (for trip) or itinerary_parent_trip_id</code> (for leg) seeded on the composer model after the modal opens. The composer panel's conditional rendering picks up the seeded values and shows the right fields.</p> This pattern is straight from discourse-kanban: rather than build a custom modal, lean on Discourse's existing composer with sensible defaults. You get rich text, drafts, file uploads, all the auth machinery, for free.</p> Screenshots</h2> Coming once I've populated my own itinerary further. I want the screenshots to show realistic data rather than the "Flight to madrid for meetup" test post that's currently in my dev instance.</p> Takeaways</h2> Plugins built on topics keep paying off.</strong> Search, permissions, edit history, mentions, attachments. None of it is plugin code. It's all Discourse, and I get it by default by storing data in topics.</p> The plugin API has trapdoors.</strong> Most of them aren't documented because nobody hits them until they hit them. Reading three working plugins side-by-side is faster than reading docs.</p> Glimmer autotracking is invisible until it isn't.</strong> If a getter reads a non-@tracked</code> value and you're surprised it doesn't re-render, that's the likely cause. Always.</p> Synthesize what you can.</strong> The user shouldn't have to type a topic title when the structured fields already encode it. Hide the title input, derive it, move on.</p> Per-category validation overrides would be great.</strong> Discourse already has site-wide setting overrides per category for things like default tags and minimum trust levels. Extending the per-category override surface to title and post length validators would let plugins like this stop fighting the global validators. Filed in the back of my brain for a future contribution.</p> Try It</h2> The plugin is open source: ducks/discourse-itinerary</a>. Symlink it into your plugins/</code> directory, restart Rails, visit /itinerary, and you've got a travel timeline backed entirely by Discourse topics.</p> Now I just need to actually go on a trip.</p> Building a Screenshot Pipeline for Discourse Plugins Unknown — Mon, 25 May 2026 00:00:00 +0000 I built discourse-plugin-screenshots on GitHub</a>, a small tool that captures Discourse plugin UIs against a real Discourse instance in CI and publishes the resulting PNGs to GitHub Pages.</p> It's modeled on Penar Musaraj's discourse-theme-screenshots</a>, which screenshots themes against a battery of routes. Same idea, different target: instead of "does this theme break the latest topic view," it asks "does my plugin's UI still render correctly in current Discourse."</p> Live example for discourse-itinerary</code>, the plugin I dogfooded it on: https://ducks.github.io/discourse-itinerary/</a>.</p> Why?</h2> I'd been hand-screenshotting discourse-itinerary</a> for its blog post</a> and realized the same problem applies to every plugin I might write or maintain:</p> Plugins break in unexpected ways when Discourse core changes. A CSS class gets renamed and your plugin's panel suddenly looks weird.</li> A new theme like Horizon ships and your plugin's overrides don't quite match anymore.</li> A plugin API method deprecates and silently degrades.</li> </ul> You usually find out from a user filing a screenshot. That's a slow loop.</p> What if every plugin had a nightly or per-push screenshot run that posted its current state to a public page? Visual regressions become visible. "Here's what my plugin looks like today" becomes a free byproduct of shipping.</p> Penar's tool already does this for themes. Plugins were the X-shaped hole next to it.</p> The architecture</h2> The tool ships a reusable GitHub Actions workflow</strong>. Plugins opt in by adding ~12 lines of YAML to their own .github/workflows/</code>:</p> name: Screenshots on: push: branches: [main] workflow_dispatch: permissions: contents: read pages: write id-token: write jobs: screenshots: uses: ducks/discourse-plugin-screenshots/.github/workflows/plugin-screenshots.yml@main </code></pre> That's it. Each plugin maintainer owns their schedule, their gallery, their CI minutes. The tool repo doesn't enumerate plugins, doesn't centrally batch them, doesn't pay for anyone else's runs. Same pattern Discourse already uses for its own discourse-plugin.yml</code></a> reusable workflow.</p> How a plugin describes what to capture</h2> A plugin opts in by shipping config/screenshots.yml</code> at the repo root:</p> seed: spec/screenshot_seed.rb urls: - path: /itinerary name: trip-list description: Trip list home page - path: /itinerary/2 name: timeline description: Per-trip timeline with day grouping </code></pre> The optional seed</code> is a Ruby file run inside the test env before captures fire. Without it, /itinerary</code> would render an empty state ("No trips yet"), which makes for sad screenshots. The seed creates a few realistic trips with legs so the pages have something to render.</p> The seed file is plain Ruby that runs inside Discourse's Rails test environment. It can use PostCreator</code>, SiteSetting</code>, plugin-specific classes, whatever. Plugin-specific concerns stay in the plugin.</p> The workflow</h2> The reusable workflow is the heart of it. Slightly simplified:</p> Spin up discourse/discourse_test:release</code> (Discourse's official test container, comes with system libs Playwright needs).</li> Check out the calling plugin, this tool, and discourse/discourse</code>.</li> Symlink the plugin into discourse/plugins/<id></code>.</li> Boot Postgres + Redis, migrate the test DB.</li> Install Playwright Chromium.</li> Run a Capybara system spec that reads the plugin's manifest, runs the seed file, visits each URL, and saves a PNG.</li> Upload public/</code> to the calling repo's GitHub Pages.</li> </ol> Total runtime: ~5-10 minutes after the initial container pull.</p> First green run</h2> I wired the workflow into the itinerary plugin's CI, pushed, and the first run came back green. Screenshots up at ducks.github.io/discourse-itinerary</a>, captured automatically on every push to main.</p> That's the whole loop. Plugin author writes config/screenshots.yml</code>, drops a reusable-workflow file in .github/workflows/</code>, enables Pages, pushes. Five minutes later there's a public gallery of what their plugin looks like in current Discourse.</p> The rabbit holes</h2> Building it taught me three things about the Discourse-on-NixOS stack that I wouldn't have learned otherwise.</p> Playwright's Chromium doesn't run on NixOS</h3> Discourse uses Playwright for system specs. The first time I tried the tool locally, the Capybara driver tried to launch Chromium and got:</p> error while loading shared libraries: libglib-2.0.so.0: cannot open shared object file: No such file or directory </code></pre> Playwright's pnpm playwright install</code> downloads a generic Linux Chromium build to ~/.cache/ms-playwright</code>. That binary expects to find shared libs at standard /usr/lib</code> paths. NixOS, famously, doesn't have a /usr/lib</code>. Everything is in /nix/store/<hash>-glib-2.x.y/lib</code>.</p> Two paths to fix this:</p> LD_LIBRARY_PATH</code> gymnastics. Add every needed lib to a nix-shell.</li> nixpkgs.playwright-driver.browsers</code>, a package that pre-patches the Chromium binary with NixOS-compatible RPATHs.</li> </ol> I went with option 2:</p> { pkgs ? import <nixpkgs> {} }: pkgs.mkShell { buildInputs = [ pkgs.playwright-driver.browsers ]; shellHook = '' export PLAYWRIGHT_BROWSERS_PATH="${pkgs.playwright-driver.browsers}" export PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 ''; } </code></pre> This got me past the lib errors and into a new one: my nixpkgs channel ships chromium-1169</code> but Discourse's Playwright gem pins chromium-1217</code>. The right fix is a flake pin or nixpkgs-unstable</code> override, which I haven't shaved yet.</p> So locally on NixOS the tool runs up to "launching Chromium" before hitting the version mismatch. In CI it sails through, because discourse/discourse_test:release</code> is a regular Linux image with the matching system libs and Playwright downloads the right version. The same code runs in both places. CI is currently the only one that succeeds end-to-end on my machine.</strong></p> That ended up being a useful property. The CI is the authoritative loop: real container, real Discourse, real Playwright, public gallery at the end. Local is a developer convenience that I can keep chipping at without blocking the rest of the tool from being useful.</p> Rspec accepts absolute spec paths from outside the project</h3> I was worried that running Discourse's bin/rspec</code> against a spec file that lives outside the Discourse repo wouldn't work. rails_helper.rb</code> wouldn't be picked up automatically, Capybara's drivers wouldn't be registered, etc.</p> Turns out: it works fine. RSpec loads rails_helper</code> via the spec file's own require</code>, and Discourse's bin/rspec</code> boots Rails normally regardless of the spec's path. The spec just needs require "rails_helper"</code> at the top.</p> This let me keep the spec in this tool's repo rather than vendoring it into every plugin or asking Discourse to ship it.</p> Reusable workflows scale better than central orchestration</h3> The first version of this had a central config/plugins.yml</code> listing every plugin, and a single CI run that captured all of them. Penar's theme tool works that way for good reasons: themes are a relatively small set and they're meant to be compared side-by-side.</p> For plugins it doesn't work. If you add 20 plugins, the central run becomes a 4-hour job that fails halfway and has to retry the whole batch. You also push all the CI cost onto whoever maintains the tool repo.</p> Reusable workflows flip both. Each plugin's CI runs only when that plugin changes. The tool repo's job is to provide the reusable workflow, not to enumerate consumers.</p> What's missing</h2> This is a v0. Real things it doesn't do yet:</p> Multiple themes.</strong> Right now it captures against the default theme. Capturing against Horizon, a dark theme, and the default is the obvious next step. Penar's tool already does this; mostly a matter of porting the theme-loading code.</li> Multiple viewports.</strong> Just 1440x900 today. Mobile (375x667) would be the big one to add.</li> Visual diffing.</strong> "Here's what changed since last run" via image diff. Tools like reg-suit or Percy do this; expensive at scale.</li> Auto-discovery of routes.</strong> Right now you list URLs in config/screenshots.yml</code>. Could introspect the plugin's route-map.js</code> for routes, but dynamic segments (:trip_id</code>) need hints either way.</li> NixOS local parity.</strong> The chromium-1217 pin dance is genuinely the last thing blocking local runs.</li> </ul> Try it</h2> # In your plugin repo, create config/screenshots.yml with your URLs. # Then drop this in .github/workflows/screenshots.yml: name: Screenshots on: push: branches: [main] workflow_dispatch: permissions: contents: read pages: write id-token: write jobs: screenshots: uses: ducks/discourse-plugin-screenshots/.github/workflows/plugin-screenshots.yml@main </code></pre> Enable GitHub Pages on the plugin repo (Settings -> Pages -> Source: GitHub Actions), push to main, and after a few minutes your screenshots will be at https://<you>.github.io/<plugin>/</code>.</p> The tool is open source: ducks/discourse-plugin-screenshots</a>. Pull requests for theme + viewport + diff support welcome.</p> When patchelf stopped working on Claude Code Unknown — Wed, 20 May 2026 00:00:00 +0000 A couple weeks ago I wrote about running Claude Code on NixOS</a> with a 133-line shell.nix</code> that patchelf-modifies the binary on install. It worked great until last week, when Claude Code's auto-updater dropped version 2.1.143 into ~/.local/share/claude/versions/</code> and claude --version</code> started segfaulting before printing anything.</p> What follows is the debugging story. I went down three wrong paths before finding the real cause, and the right fix turned out to have two more gotchas hiding inside it. The patchelf approach is dead. Here's why.</p> The symptom</h2> $ claude --version Segmentation fault (core dumped) </code></pre> coredumpctl</code> showed the crash inside the dynamic linker itself, in _dl_check_map_versions</code> at glibc/elf/dl-version.c:263</code>, before a single byte of program code had run:</p> #0 _dl_check_map_versions at dl-version.c:263 #1 _dl_check_all_versions at dl-version.c:398 #2 version_check_doit at rtld.c:676 #3 _dl_receive_error at dl-catch.c:194 #4 dl_main at rtld.c:2028 ... #8 _start () from /lib64/ld-linux-x86-64.so.2 </code></pre> The previous version (2.1.132) worked fine. 2.1.143 didn't. Same patch_binary</code> invocation, same Nix linker, same rpath. The binary was patched correctly in the sense that patchelf --print-interpreter</code> reported the Nix glibc linker path.</p> Wrong hypothesis #1: the auto-updater dropped an unpatched binary</h2> My first guess was that Claude's auto-updater had bypassed the install-time patchelf step. I extended shell.nix</code> with a wrapper that auto-patchelfs any unpatched binary in the versions directory before exec'ing it.</p> This was the wrong fix to the wrong problem. The binary was already patched; patchelf --print-interpreter</code> confirmed it. The wrapper was a useful-feeling defensive layer but it wasn't relevant to the actual bug.</p> Wrong hypothesis #2: Bun's Rust rewrite shipped malformed ELF</h2> Claude Code is built with bun build --compile</code>, which embeds the Bun runtime inside the standalone executable. There had been recent news</a> about Anthropic merging a Rust rewrite of Bun, and an open bun issue</a> about regressions in the --compile</code> path. The dates lined up: Bun v1.3.14 shipped May 13, the Rust rewrite PR merged May 14, my broken Claude Code was downloaded May 18.</p> I had a hypothesis, the timing fit, and I was off to the races. Built a clean Docker repro on stock Ubuntu 24.04 showing the same _dl_check_map_versions</code> crash outside NixOS. Started drafting a bug report against oven-sh/bun</code>. Compared readelf --version-info</code> between the working and broken binaries and found errors:</p> $ readelf --version-info /tmp/claude-2.1.143 readelf: Error: Reading 20 bytes extends past end of file for version def readelf: Error: Reading 20 bytes extends past end of file for version def ... </code></pre> The narrative was perfect. Bun's new Rust ELF emitter was producing corrupt version tables, the dynamic linker was crashing trying to read them, and I was about to file a high-quality upstream bug.</p> Then I checked the most basic fact, which I should have checked at the start:</p> $ strings /tmp/claude-2.1.143 \| grep '^Bun v' Bun v1.3.14 (d2989145) $ strings /tmp/claude-2.1.132 \| grep '^Bun v' Bun v1.3.14 (0a466a11) </code></pre> Both binaries embed Bun v1.3.14.</strong> The Rust rewrite hasn't shipped in any tagged release yet; it's only on canary. Different build commits, same version. The Rust theory was dead.</p> Lesson: when the story fits perfectly, do the cheapest disconfirming test first.</p> Wrong hypothesis #3: Claude Code's build pipeline regressed</h2> If it wasn't Bun, it had to be something on Anthropic's side. I bisected across every published version in the range:</p> for v in 2.1.132 2.1.133 2.1.136 2.1.137 2.1.138 2.1.139 2.1.140 2.1.141 2.1.142 2.1.143; do curl -fsSL -o "/tmp/bisect/$v" \ "https://downloads.claude.ai/claude-code-releases/$v/linux-x64/claude" docker run --rm -v "/tmp/bisect/$v:/c:ro" ubuntu:24.04 /c --version done </code></pre> Every freshly-downloaded binary ran cleanly. All of them.</strong> Including 2.1.143.</p> The crash I'd been reproducing was on my locally-modified copy in /tmp/claude-test</code>, not on a pristine upstream binary. I'd convinced myself I was testing the official binary because the path looked right. I was actually testing the result of my own earlier patchelf modification.</p> This is where the actual cause finally became visible.</p> The real cause</h2> Diff the program headers of 2.1.132 vs 2.1.133 with readelf -l</code>:</p> 2.1.132 RW LOAD: FileSiz=0x000e0028 (~916 KiB) MemSiz=0x001ee29c (~1.93 MiB) 2.1.133 RW LOAD: FileSiz=0x07c17d20 (~124 MiB) MemSiz=0x07c17d20 (~124 MiB) </code></pre> In 2.1.132, the RW LOAD segment's MemSiz</code> is larger than its FileSiz</code>, which is a BSS-style</a> zero-fill region that exists at runtime but takes no space on disk. In 2.1.133, FileSiz</code> equals MemSiz</code> and they're both ~124 MiB. Bun changed its standalone-executable layout to bake the entire embedded JS payload onto disk in the RW segment rather than zero-filling.</p> Why does this matter for patchelf? When patchelf rewrites the interpreter string or rpath, the new string is often longer than what it replaces. patchelf needs slack in the file layout to insert it without breaking section offsets. In 2.1.132 there's plenty of slack. From 2.1.133 onward there isn't, so patchelf's modifications end up shifting the Elf64_Verneed</code> and related version tables to file offsets where the loader walks off the end of the section.</p> The crash in _dl_check_map_versions</code> is the loader trying to dereference a vna_name</code> pointer that now points into garbage memory.</p> The pristine binaries are fine.</strong> They run unmodified on NixOS as long as you give them a real dynamic linker. It's only the patchelf-modified ones that crash. patchelf has been silently producing broken binaries on the new layout the entire time.</p> The fix</h2> Stop modifying the binary. Invoke the Nix dynamic linker directly with the unmodified binary as its argument:</p> exec /nix/store/.../ld-linux-x86-64.so.2 \ --library-path /nix/store/.../lib:/nix/store/.../lib:... \ /home/ducks/.local/share/claude/versions/2.1.143 "$@" </code></pre> This is what nix run</code> and nix-ld</code> do under the hood. The kernel only chokes when it tries to follow the binary's embedded</em> interpreter path (/lib64/ld-linux-x86-64.so.2</code>, which doesn't exist on NixOS). If you invoke a working linker yourself and pass the binary as an argument, the kernel never looks at the embedded path. The linker loads the binary as a regular dynamic object using the library paths you give it. No on-disk modification, no patchelf, no shifted section offsets.</p> I rewrote claude-nixos/shell.nix</code> to drop patchelf entirely. The wrapper at ~/.local/bin/claude</code> now picks the highest installed version, then exec's the linker with the unmodified binary. Pristine binaries are re-downloaded from downloads.claude.ai</code> to overwrite the patchelf damage on existing installs.</p> Gotcha #1: LD_LIBRARY_PATH leaks to children</h2> My first attempt at the wrapper exported LD_LIBRARY_PATH</code> and called the linker:</p> export LD_LIBRARY_PATH="$NIX_LIBS" exec "$LINKER" "$BIN" "$@" </code></pre> This works for Claude itself. But Claude spawns Bash subprocesses for tool calls (the Bash tool in particular), and those subprocesses inherit LD_LIBRARY_PATH</code>. Bash then resolves its own</em> shared libraries through our Nix paths, sometimes pulls in a mismatched version, and you get cryptic errors like:</p> -G: error while loading shared libraries: -G: cannot open shared object file: No such file or directory </code></pre> That -G</code> is grep</code>'s --basic-regexp</code> flag being mis-parsed as a shared object path by a confused loader. Lovely.</p> The fix is to use ld.so</code>'s --library-path</code> flag instead of LD_LIBRARY_PATH</code>. It's consumed by the linker during this single invocation and is not</strong> propagated to child processes:</p> exec "$LINKER" --library-path "$NIX_LIBS" "$BIN" "$@" </code></pre> Child processes inherit a clean environment.</p> Gotcha #2: Claude Code is a multi-call binary</h2> Claude Code's shell integration installs functions for find</code>, grep</code>, and ugrep</code>:</p> find() { ... exec -a bfs "$_cc_bin" -S dfs -regextype findutils-default "$@" } </code></pre> The exec -a bfs</code> sets argv[0]</code> to bfs</code> and exec's the Claude binary. The binary checks argv[0]</code> and dispatches to embedded fast tools (bfs</code> is a breadth-first find</a>, ugrep</code> is a faster grep</code>). Clever: one binary, many tools.</p> This breaks under the wrapper. When the shell function does exec -a bfs ~/.local/bin/claude ...</code>, my wrapper script runs with $0</code> set to its own path (the kernel re-parses the shebang and loses the spoofed argv[0]). The wrapper then exec's the linker, and the linker's argv[0] is the linker path. The Claude binary sees an argv[0] of /nix/store/.../ld-linux-x86-64.so.2</code>, doesn't recognize it as a tool, and runs the default UI.</p> Newer glibc linkers support --argv0 STRING</code> to set argv[0] explicitly:</p> exec "$LINKER" --argv0 "$0" --library-path "$NIX_LIBS" "$BIN" "$@" </code></pre> I started here and shipped this version, thinking it was a partial fix. It isn't. $0</code> inside a bash script is the script's own path even when the script was invoked via exec -a NAME</code>, because bash resets $0</code> to the script name at startup. So --argv0 "$0"</code> was always passing /home/ducks/.local/bin/claude</code>, never bfs</code> or ugrep</code>. Bash 5+ exposes the real invocation argv[0] via $BASH_ARGV0</code>, which fixes it:</p> exec "$LINKER" --argv0 "${BASH_ARGV0:-$0}" --library-path "$NIX_LIBS" "$BIN" "$@" </code></pre> With that change the argv0 actually propagates. I verified by invoking it manually and watching the binary respond as bfs</code> instead of as the default claude</code> UI.</p> But the fast tools still didn't work from inside a Claude session. Adding set -x</code> to the shell-integration find</code> function showed why:</p> local _cc_bin=/nix/store/.../ld-linux-x86-64.so.2 </code></pre> Claude's harness sets CLAUDE_CODE_EXECPATH</code> (the variable its shell integration uses to find itself) from /proc/self/exe</code>. Once the wrapper exec's the dynamic linker, the kernel's view of the process is the linker</em>, not the Claude binary. /proc/self/exe</code> resolves to ld.so. Everything downstream that introspects the running process sees ld.so. The shell-integration find</code> function then tries to exec $CLAUDE_CODE_EXECPATH -regextype ...</code>, which is the linker treating -regextype</code> as a library path. Boom.</p> This isn't fixable in userspace. No bash trick can hide the fact that the kernel-level process identity is ld.so. /proc/self/exe</code> will never lie. The wrapper approach has a real ceiling here.</p> The real fix: nix-ld</h2> The wrapper approach is fundamentally limited by what the kernel sees as the running process. programs.nix-ld</code></a> sidesteps the whole class of problem by installing a stub at /lib64/ld-linux-x86-64.so.2</code>, which is the FHS path that generic Linux binaries hardcode as their ELF interpreter. The stub redirects to a real Nix linker with a global library list:</p> programs.nix-ld = { enable = true; libraries = with pkgs; [ stdenv.cc.cc zlib openssl xz sqlite curl ]; }; </code></pre> With that in place, the kernel can load the pristine Claude binary directly. /proc/self/exe</code> is the real Claude binary, argv[0]</code> is whatever the caller actually set, CLAUDE_CODE_EXECPATH</code> resolves correctly, and the multi-call dispatch works.</p> The wrapper script collapses to its remaining job, picking the latest installed version:</p> #!/usr/bin/env bash set -e VERSIONS_DIR="$HOME/.local/share/claude/versions" bin="$(ls -1 "$VERSIONS_DIR" 2>/dev/null \ \| grep -E '^[0-9]+\.[0-9]+\.[0-9]+' \ \| sort -V \ \| tail -n1 \ \| awk -v d="$VERSIONS_DIR" '{print d"/"$0}')" exec -a "${BASH_ARGV0:-$0}" "$bin" "$@" </code></pre> No linker invocation. No --library-path</code>. No LD_LIBRARY_PATH</code> leak. nix-ld owns the runtime surface. The trade is that the library list is global to your system instead of per-shell: if you have two binaries that want different versions of the same library, you can only put one in the global list. For my single-vendored-binary case (Claude Code), this isn't a real constraint.</p> One Nix-string-escape detour</h2> Writing the new heredoc in shell.nix</code>, I started with this:</p> exec -a "\${BASH_ARGV0:-\$0}" "\$bin" "\$@" </code></pre> ...and got a Nix parser error at column 25. Inside Nix double-single-quote strings (''...''</code>), \${</code> isn't an escape: Nix tries to parse it as antiquotation and the backslash doesn't help. The correct escape for a literal ${</code> inside ''...''</code> is ''${</code>:</p> exec -a "''${BASH_ARGV0:-\$0}" "\$bin" "\$@" </code></pre> Single dollars work fine with \$</code>. Only the brace form needs the double-apostrophe escape. Small thing but it took five minutes to figure out, and the error message ("unexpected invalid token"</em>) doesn't lead you to it.</p> Honest reflection</h2> Three wrong hypotheses, each more confident than the last. The Bun-Rust-rewrite story was particularly seductive: recent news, a public issue tracker showing related regressions, timing that lined up. I drafted most of a bug report before checking the one thing that would have killed the hypothesis: which Bun version is actually embedded?</p> When the narrative fits perfectly, that's the moment to do the cheapest disconfirming test. Five seconds of strings \| grep Bun</code> would have saved time.</p> The same lesson came back to bite me at the end. I closed out the first version of this post with "the wrapper is partially broken, I'm parking it", documenting the limitation but never actually testing whether it was a limitation</em> or just an unfinished implementation. The $0</code> vs BASH_ARGV0</code> thing would have closed half the gap on day one. The other half (the /proc/self/exe</code> problem) took 20 minutes of set -x</code> once I sat down with the right question. "Good enough for now" deserves the same disconfirming-test discipline as a fresh hypothesis.</p> The deeper lesson, twice over: modifying a binary to fit your OS only works until it doesn't. The bridge-from-Nix-to-FHS pattern feels solid because patchelf is well-understood, but it depends on the source binary having properties (slack in the file layout, no exotic packaging) that the binary's authors never promised you. Invoking the Nix linker directly against a pristine binary felt like the robust alternative, but it has its own ceiling: once you</em> are ld.so, the rest of the world sees ld.so. nix-ld is one more step less clever than the linker-as-wrapper trick: instead of you running the linker, the kernel runs it for you, exactly the way it was designed to. The path of least cleverness wins.</p> Code</h2> The slimmed-down wrapper lives in claude-nixos</a> on the nix-ld</code> branch. With programs.nix-ld.enable = true;</code> in your NixOS configuration and a reasonable libraries</code> list, you don't need a nix-shell</code> to run Claude Code at all: the wrapper is just a ~/.local/bin/claude</code> script that picks the latest installed version and exec's it. If you don't care about juggling multiple installed versions, you can replace the wrapper with a symlink and skip the script entirely.</p> Six numbers from my blog's analytics Unknown — Sun, 17 May 2026 00:00:00 +0000 I recently noticed that the 1 year anniversary of my blog came and went. I was curious about how much traffic I got so I took a look.</p> I sshed into my VPS and pointed sqlite at the GoatCounter database that powers my analytics. Six numbers stood out.</p> For context: this blog gets modest traffic. Usually 20-50 unique visitors a day, mostly from search. I'm not actively trying to grow it, I just write. But the data is interesting because it shows what people actually read versus what I assumed they would.</p> 1. Biggest single-day spike: 33 hits</h2> On 2026-05-11, the post Nix shells, SSH, and Claude Code</a> got 33 visits in one day. That's the single biggest day for any post I've published.</p> For comparison, the next biggest days were 25 (a January post called Letting AI pick the project</a>), 19 (How a friend's gif broke our filesystem</a>), and 13 (Rewriting Claude Code in Rust</a>).</p> The pattern is obvious in hindsight: every spike came from a post solving a specific problem someone was searching for. None of them are essays. None of them are opinions. They're all "here's a weird thing I ran into and how I fixed it."</p> This is the closest thing I have to "going viral," and it's about a 30-line shell.nix.</p> 2. Fastest rising: NixOS + Claude Code</h2> In the last seven days versus the prior seven, the two biggest gainers are both about running Claude Code on NixOS:</p> Post</th> Last 7d</th> Prev 7d</th> Delta</th></tr></thead> Nix shells, SSH, and Claude Code</a></td> 49</td> 10</td> +39</td></tr> Running Claude Code on NixOS</a></td> 34</td> 9</td> +25</td></tr> </tbody></table> That's probably not a coincidence. Anthropic must have changed something recently that caused more people to hit problems running Claude Code on NixOS, and search engines surface my posts as the fix.</p> The two posts also feed each other. Readers land on one, then click through to the other. Internal linking matters more than I expected.</p> 3. Fastest out the gate: 88 hits in the first 30 days</h2> The previous numbers measure "popular right now." A different question is "which posts hit hardest in their first month after publishing?"</p> The top five by views in the first 30 days after their publish date:</p> Post</th> Published</th> First 30d</th></tr></thead> Rewriting Claude Code in Rust</a></td> 2026-04-01</td> 88</td></tr> Running Claude Code on NixOS</a></td> 2026-05-07</td> 43</td></tr> Letting AI pick the project</a></td> 2026-01-19</td> 37</td></tr> Skin shedding, not bikeshedding</a></td> 2025-11-23</td> 32</td></tr> Rewriting Claude Code in Rust (Part 2)</a></td> 2026-04-02</td> 29</td></tr> </tbody></table> The Rust + Claude post is in its own tier. It got 47 of those 88 hits in the first 7 days. That's almost certainly a referral spike from somewhere - Hacker News, Lobsters, a Mastodon boost, hard to say without per-day referrer data.</p> This is a different shape from the NixOS posts. The NixOS surge is search-driven and building over weeks. The Rust + Claude launch was a sharp burst that mostly came and went. Both are "popular." Only one keeps compounding.</p> 4. Longest site-wide streak: 119 days</h2> Every single day from 2026-01-19 to today, at least one post on this blog has been read by someone. That's 119 consecutive days without a gap.</p> The previous longest streak was 49 days. Before that, 29. Before that, 25.</p> This is what "getting indexed" actually looks like as a curve.</p> Before indexing, your blog gets read on days when you publish something or share a link somewhere. After indexing, it gets read every day, forever, because somebody somewhere is searching for a problem you wrote about.</p> That shift was the biggest surprise from all this data. The traffic doesn't spike and disappear anymore. It compounds.</p> 5. Longest per-post streak: 32 days</h2> Nix shells, SSH, and Claude Code</a> was read every day from 2026-03-26 to 2026-04-26 - 32 consecutive days. That's the longest streak any single post has had.</p> The next best are all under two weeks:</p> Rewriting Claude Code in Rust</a>: 13 days (twice)</li> Hyprland tricks: close window confirmation</a>: 13 days</li> Same hyprland post again: 11 days, then 10, then 8, then 7</li> </ul> The hyprland post is still the quiet workhorse of the blog. Published in 2025, it's been read at least once on 146 different days. About 1.8 hits per day on average, every week, for nearly a year.</p> Nothing else comes close to that consistency.</p> If you can choose the problems you write about, choose ones that everybody eventually hits and that nobody else has documented clearly.</p> Length is uncorrelated with traffic.</p> Problem-specificity is.</p> The hyprland post is one paragraph and a screenshot. The nix-shells post is six paragraphs. Both outperform longer essays by a wide margin.</p> 6. Where readers actually come from</h2> Top 10 referrers, last 90 days:</p> Source</th> Hits</th></tr></thead> (direct)</td> 391</td></tr> Google</td> 382</td></tr> duckduckgo.com</td> 45</td></tr> jakegoldsborough.com/blog</td> 37</td></tr> /tags/nixos</td> 33</td></tr> /blog/2026/nix-shells-ssh-claude-code</td> 32</td></tr> /resume</td> 32</td></tr> jakegoldsborough.com</td> 29</td></tr> kagi.com</td> 19</td></tr> Hacker News</td> 14</td></tr> </tbody></table> A few things stood out immediately:</p> Direct and Google are basically tied.</strong> "Direct" includes users with stripped referrer headers, privacy-focused browsers, chat apps, bookmarks, and manually typed URLs. In practice, a lot of "direct" is probably search-driven too.</li> DuckDuckGo (45) and Kagi (19) combined still trail Google by an order of magnitude.</strong> Kagi has a much smaller user base than Google, so this isn't surprising, but it's a useful reality check on how niche the alternative-search world still is.</li> Internal navigation matters.</strong> The /blog index, /tags/nixos, and even /resume page each drive 30+ clicks. Once someone lands on the site, they often keep exploring.</li> Hacker News isn't the firehose people imagine.</strong> A front-page post probably changes the math, but a link in /new creates a short spike and then vanishes quickly.</li> </ul> The more surprising pattern is that almost all long-term traffic comes from search and internal links, not social media.</p> What I'd do differently</h2> Honestly? Nothing.</p> I'm not optimizing for traffic. But if I were, the data points toward one obvious strategy:</p> Write more posts documenting highly specific problems with highly specific solutions.</p> Not opinions.</p> Not giant tutorials covering everything.</p> Just the thing somebody searches for after they hit a wall at 1am.</p> Small technical posts outperform broad polished essays by a huge margin. At least on this blog.</p> How I got this data</h2> GoatCounter ships a SQLite database. I ssh into my VPS, run nix-shell -p sqlite</code>, and query it directly.</p> The two most useful tables are:</p> paths</code>: post URLs and titles</li> hit_counts</code>: hour-bucketed view counts joined by path_id</code></li> </ul> The streak queries use the standard SQL trick of subtracting a row number from a date. Rows with the same difference belong to the same consecutive run.</p> If you self-host GoatCounter, the same queries work on your data. If you don't, the API exposes most of this through /api/v0/stats/hits</code> and related endpoints.</p> The funny part is that after a year of blogging, the strongest signal wasn't traffic volume.</p> It was consistency.</p> Once a post solves a real problem and gets indexed, it just keeps quietly working in the background forever.</p> A 'Was this helpful?' button for a static blog Unknown — Sat, 16 May 2026 00:00:00 +0000 I write a lot here. I don't have comments. I don't want comments. But I do want some signal about which posts are actually landing - not "did someone load the page" (GoatCounter already tells me that) but "did this post help someone."</p> So I added a small button at the bottom of every post:</p> Was this helpful? [ Yep, this helped ]</p> </blockquote> Click it once and it swaps to a thank-you line. Click is recorded as a GoatCounter event. No login, no comment box, no thumbs down. Per-browser dedupe via localStorage so the same person can't pad the number by refreshing.</p> This post is how it works.</p> Constraints</h2> The site is a static Zola build. I don't want a backend, a database, or auth.</li> I already use GoatCounter</a> for analytics. I don't want a second analytics dependency.</li> It has to keep working with JavaScript off, in the sense of not being broken. The widget can be inert when JS is disabled, but the page shouldn't render a button that lies about doing something.</li> No thumbs down. Negative feedback without a way to discuss it is just background noise.</li> Mobile-friendly. A pill-shaped button with a 44px tap target on small screens.</li> </ul> The shape</h2> Three new files plus three small edits to existing templates.</p> templates/macros/helpful.html (new — Tera macro) static/css/helpful.css (new — scoped styles) static/js/helpful.js (new — ~25 lines) templates/page.html (import + render the macro) templates/base.html (load the JS) static/css/style.css (@import the CSS) </code></pre> The whole feature is under 70 lines total.</p> GoatCounter does the click</h2> The first thing I learned reading the GoatCounter events docs</a>: you don't have to write a click handler. Any element with a data-goatcounter-click</code> attribute gets bound automatically. The attribute's value is the event name; data-goatcounter-title</code> sets a human-readable title.</p> So the Tera macro just stamps the button:</p> {% macro widget(page) %} {% set slug = page.path \| replace(from="/", to="-") \| trim_start_matches(pat="-") \| trim_end_matches(pat="-") %} {% set event_name = "helpful-" ~ slug %} <aside class="helpful" data-helpful-path="{{ page.path }}"> <p class="helpful-prompt">Was this helpful?</p> <button type="button" class="helpful-button" data-helpful-action="vote" data-goatcounter-click="{{ event_name }}" data-goatcounter-title="Helpful click on {{ slug }}" >Yep, this helped</button> <p class="helpful-thanks" hidden>✓ Glad it helped</p> </aside> {% endmacro widget %} </code></pre> The slug is the post path with slashes replaced by dashes and the leading/trailing dashes trimmed. So /blog/2026/was-this-helpful-button/</code> becomes helpful-blog-2026-was-this-helpful-button</code>. Each post is its own row in GoatCounter's event list.</p> One gotcha: GoatCounter rejects event paths that start with /</code> (the path doubles as the event name, and they reserve /</code> as a real-path marker). If you forget to strip the leading slash, your events silently don't get recorded.</p> JavaScript handles the dedupe</h2> GoatCounter records the click. localStorage remembers it. The script only does the visual swap:</p> (function () { var widget = document.querySelector('.helpful[data-helpful-path]'); if (!widget) return; var path = widget.getAttribute('data-helpful-path'); var storageKey = 'helpful:' + path; var button = widget.querySelector('[data-helpful-action="vote"]'); var thanks = widget.querySelector('.helpful-thanks'); function showThanks() { button.hidden = true; thanks.hidden = false; } try { if (localStorage.getItem(storageKey)) { showThanks(); return; } } catch (e) { // Private browsing / storage disabled: continue without persistence. } button.addEventListener('click', function () { try { localStorage.setItem(storageKey, Date.now().toString()); } catch (e) { // ignore } showThanks(); }); })(); </code></pre> Twenty-five lines. No framework, no dependencies, no async, no fetch. The try/catch</code> blocks around localStorage are for Safari private mode and embedded webviews, where localStorage</code> throws on access rather than just being absent.</p> Edge cases I thought about</h2> Tracker blockers.</strong> If your readers run uBlock Origin or similar, count.js gets blocked and the click goes nowhere. The UI still swaps state, so they don't see a broken button - the dashboard just under-counts. Acceptable for a directional metric.</p> localStorage disabled.</strong> Try/catch keeps the UI working; users in this mode can vote again across reloads. Tolerable for a directional metric.</p> Same person, multiple browsers.</strong> Each browser counts once. There's no way to deduplicate without auth, and I don't want auth.</p> JS disabled.</strong> The button renders but does nothing. I'd rather show a friendly prompt that can't be acted on than hide the section entirely. If you find that offensive, a one-liner in <noscript></code> hides it.</p> What I learned about GoatCounter</h2> Three things that aren't obvious from the docs:</p> Events show up in the same Pages view as pageviews.</strong> I expected a separate "Events" tab. There isn't one. The events are inlined into the regular pages list, marked with their event title.</p> </li> The GIF response is always 200.</strong> GoatCounter returns a 1x1 GIF for every count request, regardless of whether the hit was actually recorded. You can't tell from HTTP status alone whether your event registered. The signal is whether it shows up in the dashboard.</p> </li> data-goatcounter-click</code> is dramatically simpler than calling window.goatcounter.count()</code> manually.</strong> First version of this widget did the manual call. Second version reads the data attribute. Same behavior, less code, less to break.</p> </li> </ol> What I'm not doing</h2> No "X people found this helpful" counter.</strong> GoatCounter's API doesn't expose per-page event counts to the client, so showing the number would require a backend. I don't care enough.</p> </li> No reading-time gate.</strong> I considered only showing the button after 30 seconds or 60% scroll, to filter skim-clicks. I'll add it if the noise becomes annoying. For now, every click is signal.</p> </li> No newsletter pitch on click.</strong> "Glad it helped - want more?" would convert better. But I don't have a newsletter, so it'd be a lie.</p> </li> </ul> Try it</h2> There's one at the bottom of this post. If this was useful, click it.</p> I'll know whether the post landed because the dashboard will tell me. Not in pageviews. In helpful-blog-2026-was-this-helpful-button</code>.</p> Running Claude Code on NixOS Unknown — Thu, 07 May 2026 00:00:00 +0000 I run NixOS on my laptop. I use Claude Code daily. Recently the two stopped getting along, so I sat down and fixed it.</p> The official Claude Code installer (curl -fsSL claude.ai/install.sh \| bash</code></a>) drops a prebuilt Linux binary into ~/.local/bin/claude</code>. On Debian, Fedora, Arch, anything FHS-compliant, it just works. On NixOS, the binary refuses to run with some flavor of:</p> Could not start dynamically linked executable: /home/<user>/.local/bin/claude NixOS cannot run dynamically linked executables intended for generic linux environments out of the box. For more information, see: https://nix.dev/permalink/stub-ld </code></pre> The binary is right there. It has the executable bit. NixOS just refuses to run it.</p> Why this happens</h2> NixOS doesn't follow the Filesystem Hierarchy Standard</a>. There is no /lib64/ld-linux-x86-64.so.2</code>. Every library lives in /nix/store/<hash>-<package>/lib/</code>, and a given system can have many versions of the same library coexisting in different store paths.</p> Prebuilt Linux binaries hardcode /lib64/ld-linux-x86-64.so.2</code> as the path to the dynamic linker. They also hardcode an rpath pointing at FHS library directories that don't exist. When the kernel execve</code>s such a binary, it can't find the linker to load and bails out with the misleading "required file not found" error.</p> This isn't unique to Claude Code. It bites Discord, Spotify, Steam, the .NET SDK, anything you curl \| bash</code> from a vendor's website. The NixOS community has several documented workarounds</a>:</p> patchelf</strong>: rewrite the binary's interpreter and rpath to point at Nix store paths</li> nix-ld</strong>: a shim that maps the FHS linker path to a real Nix-provided linker at runtime</li> buildFHSEnv</strong> / steam-run</code>: drop the binary into a sandbox that fakes an FHS layout</li> autoPatchelfHook</strong>: the canonical packaging path, used when a binary is being added to nixpkgs</li> </ul> I went with patchelf. It works from a plain nix-shell</code> without touching configuration.nix</code>, and it leaves the official install path intact - the binary still lives where Claude Code expects it.</p> The fix</h2> claude-nixos</a> is a single shell.nix</code> (133 lines) that does three things:</p> Wraps the official install script and patches the binary on the way in</li> Patches binaries that are already</em> installed</li> Updates an existing install to a new version, repatching as it goes</li> </ol> You enter the shell:</p> nix-shell shell.nix </code></pre> And get three functions:</p> install_claude_fixed # download + patch install_claude_fixed 0.5.2 # specific version fix_installed_claude # repair what's already there update_claude_fixed # newer version, same patch </code></pre> How the patch works</h2> The interesting bit is the patch_binary</code> function. Given a path to an ELF binary, it asks Nix for the path to its</em> dynamic linker and the libraries the binary will need, then rewrites the binary in place:</p> patchelf \ --set-interpreter "$DYNAMIC_LINKER" \ --set-rpath "$LIBRARY_PATH" \ "$binary" </code></pre> $DYNAMIC_LINKER</code> comes from pkgs.stdenv.cc.bintools.dynamicLinker</code> (a real, existing /nix/store</code> path). $LIBRARY_PATH</code> is built from glibc</code>, libstdc++</code>, openssl</code>, curl</code>, sqlite</code>, zlib</code> (the libraries Claude Code's binary actually links against, found by trial and ldd</code>).</p> After patching, the binary's interpreter points at a file that exists on NixOS, and its rpath points at directories that contain the libraries it needs. The kernel can execve</code> it, the linker can resolve its imports, and claude</code> runs.</p> For new installs, the wrapper runs sed</code> against the official install script to inject patchelf calls right after the binary is placed:</p> sed -i "/cp.claude.\$INSTALL_DIR/a $PATCH_SCRIPT" install.sh </code></pre> So the patched flow is byte-for-byte the official install with one extra step inlined. When Anthropic ships a new installer, the wrapper still works as long as cp ... claude ... $INSTALL_DIR</code> stays in the script. If they restructure it, the sed pattern breaks loudly and obviously.</p> Try it</h2> git clone https://github.com/ducks/claude-nixos cd claude-nixos nix-shell install_claude_fixed claude --version </code></pre> If you've already installed Claude Code through the official script and it's broken, run fix_installed_claude</code> instead and it'll patch what's there.</p> Links</h2> claude-nixos</a></li> NixOS Wiki: Packaging/Binaries</a> - the canonical write-up of the four fix-it options</li> nix-ld</a> - the system-wide alternative</li> </ul> shellbooks: A Terminal Audiobook Player Unknown — Mon, 04 May 2026 00:00:00 +0000 I have a music player in the terminal (shelltrax</a>) and a podcast player in the terminal (shellcast</a>). Audiobooks were the obvious gap.</p> So I built shellbooks</a>.</p> cargo install shellbooks </code></pre> It's a TUI audiobook player and library manager. cmus-inspired keybinds, ratatui rendering, rodio for audio, the same shape as the other two shell tools. Open source, offline-first, runs on Linux and macOS.</p> Why audiobooks need their own player</h2> I wanted a CLI audiobook player that follows the cmus conventions I already use for music. A real TUI audiobook player on Linux, not a GUI app shoved into a terminal window.</p> Music players treat tracks as the unit. Podcast players treat episodes as the unit. Audiobooks need the book</em> as the unit, with chapters as the unit inside</em> a book. That changes a few things:</p> Position memory matters more.</strong> Resuming a song from 0:00 is fine. Resuming a 14-hour book from 0:00 is a tragedy.</li> Variable speed is table stakes.</strong> Most people listen at 1.25x or 1.5x. A music player has no reason to ship this; an audiobook player without it is broken.</li> Chapter navigation needs to work.</strong> Multi-file books have one chapter per file; single-file .m4b</code> books have chapter markers embedded in the container.</li> </ul> None of this is exotic. It just doesn't fit the music or podcast model directly.</p> The Stack</h2> ratatui</code> and crossterm</code> for the TUI</li> rodio</code> and symphonia</code> for audio playback</li> id3</code> for mp3 tags, mp4ameta</code> for m4b tags and chapter atoms</li> walkdir</code> for the file browser</li> Plain JSON at ~/.local/share/shellbooks/library.json</code> for the library and per-book progress</li> </ul> Same stack the other shell* tools use. The point of building these in a series is that each one starts halfway done.</p> Interface</h2> Three views, swapped with 1</code> / 2</code> / 3</code>:</p> Library</strong> is two-pane: books left, chapters right. Tab toggles which side j</code>/k</code> moves through. Enter on the books pane resumes from the saved position. Enter on the chapters pane jumps to that chapter's start.</li> Bookmarks</strong> lives at 2</code> (UI is still placeholder; the data model is in place).</li> Browser</strong> is a file system browser. Navigate to a directory of audio files or a single .m4b</code>, press a</code>, and it's added to the library.</li> </ul> A persistent footer sits on every screen with the book title, current chapter, position, total duration, speed, and a progress gauge. Press i</code> anywhere to open a centered modal with the full metadata for the selected book.</p> What's Working</h2> Imports from a file browser - explicit action, no surprise sweeps of ~</code></li> Chapter detection: parses the chpl atom in .m4b</code>, falls back to one chapter per file with cleaned filenames (01 - Prologue.mp3</code> becomes Prologue</code>)</li> Per-book progress with autosave every 10 seconds while playing, plus on every chapter change. A crash never costs more than ten seconds.</li> Variable speed (0.5x - 3.0x) via +</code> and -</code> in 5% steps. Pitch shifts with tempo today; pitch-preserving via tdpsola is next.</li> Chapter skip (b</code> next, z</code> previous), seek (,</code>/.</code> ±10s, [</code>/]</code> ±60s)</li> Cover art resolution: sidecar cover.jpg</code> or cover.png</code> first, then embedded artwork written to a cache file</li> Tag extraction: title, author, narrator, series, year - using the audiobook publishing convention where artist is author and album is the book title</li> Delete a book from the library with d</code> (mirrors shelltrax)</li> </ul> What's Not (yet)</h2> Pitch-preserving variable speed</li> Bookmarks UI (model exists, no bindings yet)</li> Theme parsing</li> Sleep timer countdown</li> Cover art rendered in-terminal (kitty / sixel / iterm2)</li> Network sources like Audiobookshelf</li> </ul> A Bug Worth Mentioning</h2> Imported a book and the title showed as "Track 001."</p> The reason: I was reading the title tag from the first audio file. For a multi-file audiobook, the per-track TIT2</code> is the chapter</em> title, not the book. The book title belongs in the album tag. So now apply_to_book</code> takes a multi_file</code> flag and uses the album tag in that case, falling back to the directory name if there's no album.</p> For single-file .m4b</code> it still uses the title tag normally, since there the file is</em> the book.</p> The kind of bug that's obvious in hindsight and only really shows up once you point the tool at real publisher data.</p> Building it in a Series Pays Off</h2> The bulk of the work on shellbooks was on the audiobook-specific bits: chapter atom parsing, the multi-file album-as-title rule, position tracking that survives speed changes and pause/resume, the autosave loop. Almost none of it was on TUI scaffolding, the file browser, the event loop, or the release pipeline. All of that was lifted from shelltrax.</p> It's also why I'm thinking about pulling the shared TUI bits into a shell-tui</code> crate. The ListSelector</code>, the BrowserState</code>, the event loop, the cmus-style screen jumps, the Makefile</code> template, the GitHub Actions release workflow - all of it is duplicated nearly verbatim across three apps now. Three is the inflection point.</p> Try It</h2> cargo install shellbooks shellbooks </code></pre> Press 3</code> to open the file browser, navigate to your audiobooks, press a</code> to import a book directory or .m4b</code>. Press 1</code> to return to the library, Enter to start playing.</p> Links</h2> shellbooks</a></li> shelltrax</a> - the music player it descends from</li> shellcast</a> - the podcast player it descends from</li> </ul> isitreal.estate: Crowd-Sourced Reviews for Real Estate Listings Unknown — Sat, 18 Apr 2026 00:00:00 +0000 Most real estate listings lie. Not always in big ways, but enough that anyone who has hunted for an apartment or a house knows the feeling - you drive 40 minutes, the front yard is a dump, the photos were from 2018, the "washer/dryer included" means hookups in a damp basement, and the agent shrugs.</p> There is no shared layer of truth for listings. Every renter and buyer does the same recon work from scratch.</p> So I built isitreal.estate</a> - crowd-sourced reviews tied to physical addresses, not listings. Listings come and go. Addresses stay.</p> The Idea</h2> Think Waze, but for house hunting.</p> You search an address. You see what other people found when they visited. Photos they took. Whether the listing photos matched reality. A rating. A date.</p> If the address has never been reviewed, you can be the first. After you visit, leave a review with photos. Over time, bad actors accumulate a visible history tied to the properties they list.</p> Data Model</h2> The anchor entity is the address, not the listing. A listing is ephemeral - taken down, renamed, relisted with new photos. An address has GPS coordinates and does not move.</p> addresses id, street, city, state, zip, country, lat, lng reviews id, address_id, user_id, listing_accurate (yes/partially/no), rating (1-5), body, visited_at review_photos id, review_id, filename, path votes id, review_id, user_id, vote (accurate/not_accurate) </code></pre> Reviews carry photos. Votes let readers weigh reviews by what the community agreed was useful or not. A user's credibility score is derived from how often their reviews align with votes over time.</p> The Stack</h2> Framework</strong>: SvelteKit 5 (runes)</li> Database</strong>: PostgreSQL</li> Auth</strong>: Session-based, scrypt hashing</li> Maps</strong>: Leaflet + OpenStreetMap tiles</li> Geocoding</strong>: Nominatim (OSM, free)</li> Photos</strong>: Disk storage, behind a configurable UPLOAD_DIR</code></li> Deployment</strong>: NixOS on my VPS, Caddy reverse proxy, systemd</li> </ul> Nothing exotic. The most interesting choice was OSM + Nominatim instead of Google Maps - no API key, no billing, no surprise bills if someone shares the site somewhere.</p> Deployment</h2> The deploy is declarative and lives in my pond-nix</code> repo. A new curbside release builds a tarball on GitHub Actions; a NixOS service fetches it on rebuild; systemd runs node build</code>; Caddy handles TLS.</p> The first deploy broke for a boring but interesting reason. The systemd unit tried to bind-mount a writable uploads directory into the Nix store path, which is read-only. systemd refused:</p> Failed to create destination mount point node '/nix/store/.../source/uploads': Read-only file system </code></pre> Rather than patching the Nix module to copy the app out of the store, I made the upload directory configurable in the app itself:</p> export const UPLOAD_DIR = process.env.UPLOAD_DIR \|\| 'uploads'; </code></pre> Both the write path (src/lib/photos.ts</code>) and the read path (src/routes/uploads/[...path]/+server.ts</code>) import the same constant, so they never drift. In dev it defaults to ./uploads</code>. In production the systemd unit sets UPLOAD_DIR=/var/lib/curbside/uploads</code> and the BindPaths goes away entirely.</p> Cleaner than fighting the Nix store. And it unblocks moving uploads off the VPS to R2 later with the same interface.</p> What Works</h2> Signup, login, session auth</li> Address search with geocoding</li> Address detail page with reviews, photos, stats</li> Review submission with photo uploads</li> Accurate / not-accurate voting</li> User profile pages</li> Admin role for moderation</li> </ul> What Doesn't (Yet)</h2> Map view on the homepage is basic</li> No autocomplete on address search yet</li> Photo storage lives on the VPS; needs to move to object storage</li> No rate limiting on review creation</li> Credibility scoring is naive</li> </ul> Reflections</h2> The technical work was the easy part. SvelteKit + Postgres + systemd is well-trodden ground. The real question is whether enough people will leave reviews to reach the tipping point where the site is actually useful when you search an address.</p> That is the honest problem with any crowd-sourced trust network. It is worthless until it crosses some critical mass, and valuable after. The middle is long and quiet.</p> So I am seeding with real reviews of real addresses I know, and opening it up to see what happens. If you have ever been burned by a fake listing, leave a review.</p> Links</h2> isitreal.estate</a></li> curbside (app source)</a></li> pond-nix (deploy config)</a></li> </ul> How my blog started getting indexed Unknown — Thu, 09 Apr 2026 00:00:00 +0000 I write this blog primarily for myself - to think through problems, document decisions, and have a record of what I built and why. I don't optimize for search traffic. But about two months after I started publishing consistently, something unexpected happened: search engines started sending people here. Google, DuckDuckGo, Bing, ChatGPT, Perplexity.</p> Not a flood. Maybe 20-30 visitors a day from search. But those visitors are finding specific technical posts about problems they're trying to solve. The kind of traffic that actually matters.</p> I didn't do SEO. I didn't build backlinks. I didn't write "10 tips" posts or target keywords. What I did do, almost accidentally, was follow a few patterns that apparently work.</p> What Actually Worked</h2> 1. Publishing consistently</h3> I've published 47 posts since January 2026. That's roughly one every 2-3 days. Not because I'm following a content calendar, but because I'm building things and writing about them as I go.</p> Each post is a surface. Search engines index surfaces. More surfaces = more ways to be found.</p> 2. Writing real titles</h3> My titles describe the actual content. Not "Improve Your Workflow with This One Trick" but "Rewriting Claude Code in Rust (Part 2)". Specific, descriptive, ungameable.</p> Turns out that when someone searches for "claude code rust", a post with those exact words in the title ranks. Obvious in hindsight.</p> 3. Internal linking</h3> I link between related posts constantly. When I mention a project I've written about before, I link to it. When I reference a concept from another post, I link to it.</p> This creates a web. Google's crawler follows links. A well-linked collection of pages signals that this is a coherent body of work, not random blog spam.</p> 4. Clean, simple structure</h3> My site is static HTML generated by Zola. No JavaScript frameworks, no client-side routing, no dynamic content. Just semantic HTML with proper headings, paragraphs, and code blocks.</p> Crawlers love this. Fast pages, clear structure, no obstacles.</p> 5. Code blocks and technical depth</h3> Most of my posts include code examples, file paths, implementation details. These are extremely specific signals. If someone searches for a particular function name or error message, and I've written about it, search engines can match that query to my content precisely.</p> What Didn't Matter</h2> I don't have a sitemap (though Zola can generate one, I haven't enabled it). I have minimal visitor tracking but that's it. I don't track keyword density or optimize meta descriptions. I post on the fediverse but not as a promotion strategy.</p> None of that seems to matter for this kind of technical writing. The content itself is the SEO.</p> The Pattern</h2> What I've accidentally done is create a growing surface area of well-structured, interconnected technical content. Each new post adds another surface that search engines can index. Each internal link strengthens the web.</p> I'm not trying to rank for "best programming language" or other high-competition terms. I'm documenting niche problems and implementations. The long tail. And the long tail is where technical blogs actually get found.</p> Why This Matters</h2> This blog is a byproduct of my work. Writing these posts helps me think. Publishing them creates a permanent record. The fact that they also get found by people solving similar problems is a side effect - but it's a useful one.</p> It means the work compounds. Not just for me (as a reference and thinking tool) but for others who stumble across it via search.</p> That's the model I'm optimizing for. Not traffic. Not engagement. Just clear documentation of real work, published consistently, with enough structure that search engines can surface it when someone needs it.</p> What I'm Going to Keep Doing</h2> Publishing consistently as I build</li> Writing descriptive titles</li> Linking between related posts</li> Using semantic HTML and clear structure</li> Including code examples and technical details</li> </ul> That's it. No keyword research, no backlink campaigns, no growth hacking. Just building and documenting in public, with enough consistency that it accumulates into a corpus worth indexing.</p> The blog is working exactly how I want it to. The search traffic is proof that the model scales.</p> Jobchain: Verifiable Employment Credentials Unknown — Mon, 06 Apr 2026 00:00:00 +0000 Michał Fita responded to my whoami-spec post</a> asking about verifiable credentials. His point: we should be able to prove employment history with cryptographic signatures, not chiselled PDFs that ATSes shred back into text.</p> He was right about the problem. But every previous attempt at this (Blockcerts, LinkedIn verified credentials, W3C VCs) died because it's a three-sided marketplace. Employers have to issue credentials. Employees have to hold them. ATSes have to consume them. Nobody wants to go first.</p> I built the tooling anyway.</p> The Problem</h2> The employment verification pipeline is absurd:</p> You write a resume (self-attested, no proof)</li> You export to PDF (formatting lottery)</li> An ATS OCRs it back to text (lossy, error-prone)</li> A background check company calls your old employer (slow, expensive)</li> Someone confirms dates over the phone (binary pass/fail)</li> </ol> Every step degrades information. The structured data you started with becomes an unstructured phone call. There has to be a better way.</p> The Fix</h2> Public key cryptography. Same thing that makes HTTPS work.</p> Your employer has a keypair. They sign a JSON document saying you worked there. Anyone can verify the signature by checking the public key hosted on the employer's domain.</p> No blockchain. No platform. No account to create. DNS is the trust anchor.</p> How It Works</h2> Three commands:</p> 1. Employer creates an identity</h3> $ jobchain init --org "Discourse" --domain discourse.org Initialized jobchain identity for Discourse DID: did:web:discourse.org Next: host did.json at https://discourse.org/.well-known/did.json </code></pre> This generates an Ed25519 keypair and a DID document</a>. The public key lives at a well-known URL on the company's domain. If you control discourse.org</code>, you control the identity. No certificate authority, no third party.</p> 2. Employer issues a credential</h3> $ echo '{"title":"Infrastructure Engineer","company":"Discourse","start":"2024-03"}' \ \| jobchain issue --domain discourse.org { "@context": ["https://www.w3.org/2018/credentials/v1"], "type": ["VerifiableCredential", "EmploymentCredential"], "issuer": "did:web:discourse.org", "credentialSubject": { "type": "EmploymentRecord", "title": "Infrastructure Engineer", "company": "Discourse", "start": "2024-03" }, "proof": { "type": "Ed25519Signature2020", "proofValue": "z4jH8n..." } } </code></pre> That's a W3C Verifiable Credential</a>. Structured JSON, signed with Ed25519. Hand the .vc.json</code> file to the employee.</p> 3. Anyone verifies</h3> $ jobchain verify --input jake-discourse.vc.json VALID -- credential signature verified Issuer: did:web:discourse.org Subject: Infrastructure Engineer at Discourse Issued: 2026-04-02 </code></pre> The verify command fetches the public key from discourse.org/.well-known/did.json</code> and checks the signature. No account needed. No API key. Just math.</p> The Wallet Is a Git Repo</h2> Your "wallet" is a folder of .vc.json</code> files. Host it anywhere. GitHub Pages, Netlify, your own server.</p> $ jobchain wallet build --dir ./credentials --out ./site </code></pre> This generates an HTML site with your credentials and a machine-readable index.json</code> manifest. Hiring managers see a clean page. ATS systems consume structured JSON. Same data, two views.</p> The wallet is static files. Push to a repo, deploy to Pages. Done.</p> Why Not Blockchain</h2> This comes up immediately, so let me address it.</p> Blockchain solves one problem jobchain doesn't: persistence after the issuer disappears. If discourse.org</code> goes dark, the public key is gone and nobody can verify old credentials.</p> But blockchain adds massive complexity for that edge case. Consensus mechanisms, gas fees, infrastructure dependencies. And the social problem (getting employers to issue credentials) doesn't change regardless of the storage layer.</p> For now, DNS is the trust anchor. If persistence matters later, there are simpler solutions: key archival services, IPFS pinning, or embedding the public key in the credential itself.</p> Amendments</h2> Credentials aren't static. You get promoted. You change teams. Jobchain supports amendments: signed updates linked to the original credential via content hash.</p> $ jobchain amend --credential jake-discourse.vc.json \ --domain discourse.org \ --patch '{"title":"Senior Infrastructure Engineer"}' \ --effective-date 2025-06 </code></pre> Each amendment is independently verifiable. The chain forms a linked list: original credential, then amendments, each signed and hash-linked to its predecessor.</p> What This Is Not</h2> It's not a platform. There's no service to sign up for, no data to hand over.</p> It's not self-attested. Only the employer's private key can produce a valid signature.</p> It's not a resume replacement. JOBL</a> handles the self-authored resume. Jobchain handles what others can confirm about you. They complement each other.</p> The Architecture</h2> Jobchain is a Cargo workspace with three crates:</p> jobchain-core</strong>: credential types, Ed25519 signing, DID documents, amendment chains</li> jobchain-verify</strong>: signature verification only, kept slim for future WASM compilation</li> jobchain-cli</strong>: the jobchain</code> binary</li> </ul> 131 tests. All passing.</p> The verify crate is deliberately lightweight. No HTTP client, no file I/O, no CLI dependencies. The plan is to compile it to WASM so the wallet can verify credentials in-browser without a server.</p> What I Actually Used to Build This</h2> I used finna</a> to architect and implement it. Claude and Gemini debated the architecture, generated 16 implementation specs, then Claude implemented each spec as a feature branch. The whole thing -- keypair generation, DID documents, credential signing, verification, amendments, adapter traits, wallet generator, CLI, 131 tests -- was implemented in one session.</p> I reviewed the output, fixed a few things, and it worked end to end. That's a different kind of project kickstart than I'm used to.</p> The Hard Part</h2> The tooling exists. The hard part is adoption.</p> Someone has to go first. An employer has to host a did.json</code> and issue a credential. An employee has to publish their wallet. A hiring manager has to check it.</p> I work at a smaller company. We could try it. The ask is small: host one JSON file, run one command when someone joins or leaves. Frame it as a signed reference letter that's machine-verifiable.</p> That's the next step.</p> Current Status</h2> Working CLI with all Phase 1 features:</p> jobchain init</code> -- generate org identity</li> jobchain issue</code> -- sign employment credentials</li> jobchain verify</code> -- check signatures (offline or via DID resolution)</li> jobchain amend</code> -- signed amendments to existing credentials</li> jobchain wallet build</code> -- static site generator</li> </ul> What's missing:</p> Actual adoption by an employer</li> HR tool adapters (BambooHR, Gusto, etc.)</li> WASM verification in the wallet</li> A real-world credential issued by a real company</li> </ul> The infrastructure is there. Now it needs to be used.</p> Links</h2> Jobchain on GitHub</a></li> Jobchain Documentation</a> -- implementation guide and spec</li> JOBL</a> -- structured resume format (companion project)</li> whoami-spec</a> -- declarative identity</li> finna</a> -- multi-model debate and implement</li> </ul> Inside Claude Code's Team Memory Sync Engine Unknown — Sun, 05 Apr 2026 00:00:00 +0000 Most people using Claude Code don't know it has a shared memory system. A directory on disk that syncs to Anthropic's servers, merges with your teammates' memories, and gets injected into every conversation. No git involved. No manual sharing. It just works.</p> I found it while reading the leaked source. A teamMemorySync/</code> directory with six files: a sync engine, a file watcher, a secret scanner, type definitions, a path validator, and prompt integration. About 800 lines of TypeScript implementing a real-time collaborative knowledge base inside a CLI tool.</p> What Team Memory Is</h2> Team memory is a flat key-value store scoped per repository. Keys are file paths like MEMORY.md</code> or patterns.md</code>. Values are UTF-8 content, typically markdown. It lives at:</p> ~/.claude/projects/<project-hash>/memory/team/ </code></pre> Every authenticated user in your organization who works in the same repo shares this directory. When one person writes a memory file, it syncs to the server and gets pulled into everyone else's session.</p> The system prompt tells Claude about both memory directories:</p> You have a persistent, file-based memory system with two directories: a private directory at <auto-path></code> and a shared team directory at <team-path></code>.</p> </blockquote> Claude reads the team MEMORY.md</code> index at session start and can access any file in the team directory. When it saves a memory, it decides whether to put it in private or team based on the content type.</p> The Sync Engine</h2> The sync logic in teamMemorySync/index.ts</code> handles three operations: pull, push, and hash comparison.</p> Pull (server to local)</h3> On session start, Claude Code fetches the team memory for your repo:</p> GET /api/claude_code/team_memory?repo={owner/repo} </code></pre> The response includes all entries (key-value pairs), per-entry SHA-256 checksums, a version number, and an overall checksum. Server wins -- pull overwrites local files. If the server returns a 304 (ETag matches), nothing happens.</p> Push (local to server)</h3> When you edit a team memory file, the watcher triggers a push. But it doesn't upload everything -- it computes a delta:</p> Hash each local file with SHA-256</li> Compare against serverChecksums</code> (cached from the last pull/push)</li> Only upload files whose hash differs</li> </ol> PUT /api/claude_code/team_memory?repo={owner/repo} </code></pre> The PUT uses upsert semantics -- keys not in the request are preserved on the server. This means pushing a single changed file doesn't delete everything else.</p> There's also a body size cap of 200KB per request. If the delta exceeds that, it splits into sequential PUTs. Each one merges safely because of the upsert semantics.</p> Conflict Resolution</h3> Optimistic concurrency via ETags. Every push includes the last-known checksum as If-Match</code>. If someone else pushed in between, you get a 412 Precondition Failed.</p> The conflict resolution is clever. Instead of pulling the full content (potentially 300KB), it fetches just the checksums:</p> GET /api/claude_code/team_memory?repo={owner/repo}&view=hashes </code></pre> This returns per-key hashes without the actual content. The client updates its serverChecksums</code> map, recomputes the delta, and retries the push with the new ETag. Up to 2 conflict retries before giving up.</p> The File Watcher</h2> A fs.watch</code> on the team memory directory, debounced at 2 seconds. When a file changes:</p> Wait 2s for more changes (debounce)</li> If a push is already in progress, mark hasPendingChanges</code></li> When the current push finishes, if hasPendingChanges</code>, push again</li> On permanent failure (auth error, too many entries), suppress the watcher to prevent infinite retry loops</li> </ol> The watcher is careful about one edge case: when a pull writes server content to local files, those writes trigger watch events. Without suppression, you'd get a pull-then-immediate-push loop. The watcher skips events during pull operations.</p> The Secret Scanner</h2> Before any push, every file is scanned for credentials. The scanner uses 30+ regex patterns adapted from gitleaks (MIT licensed), covering:</p> Cloud providers</strong>: AWS access keys, GCP API keys, Azure AD secrets, DigitalOcean tokens</li> AI APIs</strong>: Anthropic keys (sk-ant-api03-...</code>), OpenAI keys, HuggingFace tokens</li> Version control</strong>: GitHub PATs/OAuth/app tokens, GitLab PATs/deploy tokens</li> Communication</strong>: Slack bot/user/app tokens, Twilio, SendGrid</li> Dev tools</strong>: NPM tokens, PyPI upload tokens, HashiCorp TF tokens, Databricks, Pulumi, Postman</li> Payment</strong>: Stripe keys, Shopify tokens</li> Crypto</strong>: PEM private key blocks</li> </ul> Files with detected secrets are silently skipped -- not uploaded, not deleted locally, not reported to the server. The push result includes which files were skipped and why, so the system can inform the user.</p> The patterns are curated for near-zero false positives. They only match distinctive prefixes (ghp_</code>, sk-ant-</code>, xoxb-</code>, AKIA</code>, etc.) rather than generic keyword patterns. The comment in the source:</p> Uses a curated subset of high-confidence rules from gitleaks -- only rules with distinctive prefixes that have near-zero false-positive rates are included. Generic keyword-context rules are omitted.</p> </blockquote> One interesting detail: the Anthropic API key pattern assembles its prefix at runtime (['sk', 'ant', 'api'].join('-')</code>) so the literal string doesn't appear in the compiled bundle. They have an internal excluded-strings.txt</code> check that greps build output for sensitive strings -- the secret scanner would trip its own detection if the prefix were hardcoded.</p> Path Safety</h2> Team memory files arrive from the server with relative paths as keys. The path validator in teamMemPaths.ts</code> prevents directory traversal attacks:</p> Rejects paths containing ..</code> after normalization</li> Resolves symlinks and checks the canonical path stays inside the team memory directory</li> Rejects absolute paths</li> Throws a PathTraversalError</code> if a key would escape the sandbox</li> </ul> This matters because the server response drives file writes. A malicious or compromised server could theoretically send a key like ../../../.bashrc</code> -- the path validator prevents that.</p> How Claude Uses It</h2> The team memory directory gets loaded into the system prompt alongside the private memory. Claude sees both and is instructed on when to use each:</p> Private memories</strong>: things specific to one user (preferences, role, feedback on how to work with them)</li> Team memories</strong>: shared project knowledge (architecture decisions, patterns, conventions, ongoing initiatives)</li> </ul> The prompt is explicit about what NOT to put in team memory:</p> You MUST avoid saving sensitive data within shared team memories. For example, never save API keys or user credentials.</p> </blockquote> When Claude writes a memory, it chooses the directory based on content type. User preferences go private. Project patterns go team. The two indexes (MEMORY.md</code> in each directory) are both loaded into context.</p> Size Limits</h2> Per file</strong>: 250KB max (filtered client-side before upload)</li> Per PUT body</strong>: 200KB (splits into sequential requests if exceeded)</li> Entry count</strong>: server-enforced, tunable per-org (no client-side default)</li> API timeout</strong>: 30 seconds</li> </ul> When the server rejects a push for too many entries, it returns a structured 413 with the limit:</p> { "error": { "details": { "error_code": "team_memory_too_many_entries", "max_entries": 100, "received_entries": 142 } } } </code></pre> The client caches the max_entries</code> value and truncates on subsequent pushes.</p> Requirements</h2> Team memory requires:</p> OAuth authentication (not API key, not Bedrock/Vertex)</li> user:inference</code> and user:profile</code> scopes</li> A git repo with a remote (used to derive owner/repo</code> slug)</li> </ul> It's designed for Claude.ai Team and Enterprise plans, but works for Pro/Max too. Bedrock and Vertex users are excluded -- the sync endpoint requires first-party Anthropic auth.</p> What's Interesting About It</h2> The engineering is solid but the concept is what stands out. Most AI coding tools treat each session as isolated. Your context disappears when you close the terminal. If your teammate learned something useful, you have to rediscover it.</p> Team memory makes knowledge accumulate. One person documents a tricky API pattern, and every future conversation in that repo -- by anyone on the team -- gets that context. Without checking anything into git, without sharing a doc, without telling anyone. The AI just knows because the team taught it.</p> The secret scanner is the paranoid layer that makes this possible. Shared memory across a team is a liability if it leaks credentials. Scanning before upload, with patterns that match real secret formats instead of guessing from keywords, is the right approach.</p> The sync engine is pragmatic. Server wins on pull. Upsert on push. ETag for conflicts. No CRDT, no operational transform, no fancy merge. Just "last write wins per key" with checksums to avoid unnecessary uploads. For markdown files that humans edit infrequently, it's the right level of complexity.</p> Found by reading the Claude Code source that leaked via npm source maps on March 31, 2026. The team memory system lives in src/services/teamMemorySync/</code> and src/memdir/teamMemPaths.ts</code>.</p> Rewriting Claude Code in Rust, Part 3: TUI, Agents, and Multi-Provider Unknown — Sat, 04 Apr 2026 00:00:00 +0000 Part 2</a> left off at 1,530 lines with an inline REPL, permission prompts, session management, and compaction. It worked, but it looked like a script, not a tool.</p> This post covers the rest: a proper TUI, the agent system, and breaking free from Anthropic-only.</p> Phase 4: The TUI</h2> The inline REPL was functional but crude. Print prompt, read line, stream tokens, repeat. No scroll, no layout, no visual distinction between you and the assistant.</p> Claude Code's original UI is React + Ink -- React components rendered to the terminal. That's not happening in Rust. The equivalent is ratatui, which gives you a layout engine, widgets, and an alternate-screen buffer.</p> The TUI runs behind --tui</code>. The inline REPL stays as the default because it's simpler and pipes better.</p> Layout</h3> Four zones, top to bottom:</p> ┌─────────────────────────────────┐ │ claux v20260401.0.1 │ <- header ├─────────────────────────────────┤ │ │ │ You │ │ > read src/main.rs │ │ │ <- scrollable message area │ fn main() -> Result<()> { │ │ let args = Cli::parse(); │ │ ... │ │ │ ├─ > ────────────────────────────-┤ <- input box │ explain the error handling │ ├─────────────────────────────────┤ │ claude-sonnet-4 \| Cost: $0.02 │ <- status bar └─────────────────────────────────┘ </code></pre> Messages are color-coded: blue for user, default for assistant, green for streaming text, yellow for system messages and permission prompts. Gruvbox palette because that's what I use everywhere.</p> The Hard Part: Async + TUI</h3> The challenge with a terminal UI and an async LLM client is that you can't await</code> the API call and poll terminal events at the same time from the same thread. The inline REPL solved this by spawning the display as a tokio task and driving the engine on the main thread. The TUI can't do that -- it needs to own the terminal.</p> The solution: drive the streaming loop manually with tokio::select!</code>. One arm reads API events, the other polls terminal input with a short timeout. Ctrl+C during streaming cancels the request.</p> loop { tokio::select! { Some(event) = api_rx.recv() => { match event { ApiEvent::Text(t) => { app.stream_buffer.push_str(&t); terminal.draw(\|f\| ui::draw(f, app))?; } ApiEvent::ToolUse { id, name, input } => { tool_uses.push((id, name, input)); } ApiEvent::Done => break, // ... } } _ = tokio::time::sleep(Duration::from_millis(50)) => { if event::poll(Duration::from_millis(0))? { if let Event::Key(key) = event::read()? { // Handle Ctrl+C, scroll, etc. } } } } } </code></pre> Permission prompts work inline in the TUI. When the engine needs approval, the input box turns yellow and shows the tool name with (y)es / (n)o / (a)lways</code>. The engine blocks on a oneshot channel until you answer.</p> What It Cost</h3> 928 lines for the TUI module. Two files: tui/mod.rs</code> (app state, event loop, streaming driver) and tui/ui.rs</code> (layout and rendering). The rendering is naive -- no markdown parsing, no syntax highlighting, no word wrap. But it works and it's fast.</p> Upgrading to Rust 1.88 was required because ratatui 0.29's dependencies needed it. The shell.nix</code> now uses rust-overlay instead of nixpkgs' rust.</p> Phase 5: Agents</h2> The Agent tool is what makes Claude Code feel like it has workers. You ask it to do something complex, it spawns a sub-conversation with its own context and a restricted tool set.</p> In claux, the Agent tool creates a child Engine</code>:</p> async fn execute(&self, input: Value) -> Result<ToolOutput> { let params: Params = serde_json::from_value(input)?; let provider = (self.make_provider)(); let tools = ToolRegistry::without_agent(); // no recursion let permissions = PermissionChecker::new(PermissionMode::Bypass); let mut engine = Engine::new(provider, tools, permissions, &self.model); engine.set_system_prompt(agent_prompt); match engine.submit(&params.prompt).await { Ok(response) => Ok(ToolOutput { content: response, is_error: false, }), // ... } } </code></pre> Three key decisions:</p> No nested agents.</strong> ToolRegistry::without_agent()</code> excludes the Agent tool from sub-agents. Prevents infinite recursion.</p> </li> Bypass permissions.</strong> Agents run unattended. If the parent conversation approved the Agent call, the sub-agent's tools don't need individual approval.</p> </li> Own context.</strong> The sub-agent starts with a fresh message history and its own system prompt. It doesn't see the parent conversation.</p> </li> </ol> Cost tracking flows back -- the agent's token usage is appended to its output so you can see what it spent.</p> Auto-Compact</h3> Phase 5 also added auto-compaction. Before each submit</code>, the engine checks if the message count exceeds 80. If so, it runs the same compaction logic as /compact</code> -- summarizes the conversation via the API and replaces history with the summary.</p> This is the dumb version of what Claude Code does. Their compaction pipeline has multiple strategies: reactive compact, context collapse, history snip, tool-use summaries. Ours is a threshold check and a summarization call. But it prevents the context window from overflowing, which is the thing that actually matters.</p> Multi-Provider</h2> Up to this point, claux only spoke Anthropic. That's fine for rewriting Claude Code, but limiting for actual use.</p> The fix was a Provider</code> trait:</p> #[async_trait] pub trait Provider: Send + Sync { fn name(&self) -> &str; fn model(&self) -> &str; fn set_model(&mut self, model: &str); async fn stream( &self, messages: &[Message], system: &str, tools: &[ToolDefinition], max_tokens: u32, ) -> Result<mpsc::Receiver<ApiEvent>>; } </code></pre> Two implementations:</p> AnthropicProvider</strong> -- the existing client, extracted into its own file. Uses x-api-key</code> or Authorization: Bearer</code> depending on whether you're using an API key or OAuth from claude login</code>.</p> </li> OpenAICompatProvider</strong> -- speaks the /v1/chat/completions</code> streaming format. Works with Ollama, vLLM, LMStudio, OpenAI, or any hosted endpoint.</p> </li> </ul> The hard part was message format conversion. Anthropic and OpenAI structure tool calls differently:</p> </th> Anthropic</th> OpenAI</th></tr></thead> System prompt</td> Top-level system</code> field</td> System message in array</td></tr> Tool calls</td> content_block</code> with type: tool_use</code></td> tool_calls</code> array on assistant message</td></tr> Tool results</td> tool_result</code> content block</td> Separate tool</code> role message</td></tr> </tbody></table> The OpenAICompatProvider</code> converts between formats on the fly. It also has its own SSE parser since the streaming JSON structure is different (choices[0].delta.content</code> vs content_block_delta</code>).</p> Config</h3> # Anthropic (default) model = "claude-sonnet-4-20250514" api_key_cmd = "op read 'op://vault/Anthropic/key'" # Or any OpenAI-compatible endpoint model = "Qwen/Qwen3.5-122B-A10B" openai_base_url = "https://my-endpoint.com/v1" openai_api_key_cmd = "op read 'op://vault/hosted/key'" openai_provider_name = "hosted" </code></pre> If openai_base_url</code> is set, it uses the OpenAI-compatible provider. Otherwise Anthropic. The _cmd</code> fields run via sh -c</code> and capture stdout -- works with 1Password, Vault, or any secret manager that has a CLI.</p> I tested this against a hosted Qwen 3.5 122B model. Streaming, tool execution, and the full turn loop all work. Same binary, different config, different model.</p> Final Numbers</h2> </th> Phase 1</th> + Phase 2-3</th> + Phase 4-5</th> + Multi-Provider</th></tr></thead> Files</td> 16</td> 18</td> 20</td> 26</td></tr> Lines</td> 1,200</td> 1,530</td> 2,640</td> 4,000+</td></tr> Tools</td> 6</td> 6</td> 7 (Agent)</td> 7</td></tr> Tests</td> 0</td> 0</td> 0</td> 60</td></tr> Providers</td> 1</td> 1</td> 1</td> Any</td></tr> </tbody></table> All built in one session. The TypeScript original: 1,900 files, 512,000 lines.</p> What I'd Do Differently</h2> Start with the Provider trait.</strong> I hardcoded the Anthropic client in Phase 1 and had to refactor it later. If I'd started with Box<dyn Provider></code>, the multi-provider change would have been a new file instead of a rewrite.</p> Skip the inline REPL.</strong> The TUI is strictly better. The inline REPL exists because I built it first and kept it for pipe compatibility, but in practice you'd always use --tui</code> or -p</code>.</p> Add tests from Phase 1.</strong> We bolted on 60 tests at the end. They all passed, which means they weren't catching regressions -- they were documenting existing behavior. Tests written alongside the code would have caught the $()</code> config issue before it hit production.</p> What's Missing</h2> Markdown rendering</strong> in the TUI (code blocks, bold, lists)</li> Input history</strong> (up arrow for previous prompts)</li> Token refresh</strong> for OAuth (currently just checks expiry, doesn't refresh)</li> Pattern-based permission rules</strong> (allow Bash(git )</code> without prompting)</li> Retry logic</strong> for rate limits and transient errors</li> Syntax highlighting</strong> in code blocks</li> </ul> These are all polish. The architecture supports them. I'll add them as I use the tool and hit the gaps.</p> Previous: Part 2: Sessions, Commands, and Permissions</a></p> Source: github.com/ducks/claux</a></p> Anthropic Shipped a Gacha Pet Inside Claude Code Unknown — Fri, 03 Apr 2026 00:00:00 +0000 I was reading through the Claude Code source -- the TypeScript that leaked via a source map in the npm package on March 31st -- and found a buddy/</code> directory. Six files. Sprites, types, a PRNG roller, a system prompt hook. A complete virtual pet system buried inside a coding tool.</p> The directory had nothing to do with the CLI's core functionality. No tool dispatch, no query engine, no permission system. Just... companions.</p> I typed /buddy</code> in my next Claude Code session. A dragon named Bristle appeared next to my input box.</p> What It Is</h2> The buddy system is a gacha-style virtual pet built directly into Claude Code. Your account gets a deterministic companion rolled from a seeded PRNG based on your user ID. You can't reroll. You can't trade. You get what the hash gives you.</p> The companion sits beside your input box as an animated ASCII sprite with a speech bubble. It watches. It occasionally comments. It's separate from Claude</p> when you address it by name, its bubble answers. Claude is explicitly told to stay out of the way:</li> </ul> A small dragon named Bristle sits beside the user's input box and occasionally comments in a speech bubble. You're not Bristle -- it's a separate watcher. When the user addresses Bristle directly (by name), its bubble will answer. Your job in that moment is to stay out of the way.</p> </blockquote> That prompt gets injected into the system context alongside git status and CLAUDE.md. The AI is literally told about your pet.</p> The Roll</h2> Every companion has two parts: bones and soul.</p> Bones</strong> are deterministic. Your user ID gets hashed with a salt (friend-2026-401</code> -- note the date) using a Mulberry32 PRNG. The hash determines everything physical about your companion:</p> Species</strong> -- 18 options: duck, goose, blob, cat, dragon, octopus, owl, penguin, turtle, snail, ghost, axolotl, capybara, cactus, robot, rabbit, mushroom, chonk</li> Eyes</strong> -- ·</code>, ✦</code>, ×</code>, ◉</code>, @</code>, °</code></li> Hat</strong> -- none, crown, tophat, propeller, halo, wizard, beanie, tinyduck (commons get no hat)</li> Rarity</strong> -- common (60%), uncommon (25%), rare (10%), epic (4%), legendary (1%)</li> Shiny</strong> -- 1% chance, independent of rarity</li> Stats</strong> -- DEBUGGING, PATIENCE, CHAOS, WISDOM, SNARK</li> </ul> The stats have a floor based on rarity (common: 5, legendary: 50), one peak stat that rolls high, and one dump stat that rolls low. The rest scatter between floor and floor+40.</p> const RARITY_FLOOR: Record<Rarity, number> = { common: 5, uncommon: 15, rare: 25, epic: 35, legendary: 50, } </code></pre> Because it's all derived from your user ID hash, you can't cheat. The bones regenerate from the hash every time. Editing your config won't give you a legendary.</p> Soul</strong> is the companion's name and personality. This part is generated by Claude on first hatch and stored in your config. The soul persists. The bones don't need to -- they're recomputed on every read.</p> // Regenerate bones from userId, merge with stored soul. // Bones never persist so species renames and SPECIES-array edits // can't break stored companions, and editing config.companion // can't fake a rarity. export function getCompanion(): Companion \| undefined { const stored = getGlobalConfig().companion if (!stored) return undefined const { bones } = roll(companionUserId()) return { ...stored, ...bones } } </code></pre> The Sprites</h2> Each species has three animation frames for idle fidget. Five lines tall, twelve wide. They're rendered as ASCII art with a hat overlay on the top line and eye substitution via {E}</code> placeholders.</p> Here's a dragon:</p> /^\ /^\ < ✦ ✦ > ( ~~ ) `-vvvv-´ </code></pre> And with a wizard hat:</p> /^\ /^\ /^\ < ✦ ✦ > ( ~~ ) `-vvvv-´ </code></pre> Frame 3 for some species uses the hat line for smoke, antenna wiggle, or sparkle effects instead of the hat. The code checks:</p> // Only replace with hat if line 0 is empty (some fidget frames // use it for smoke etc) if (bones.hat !== 'none' && !lines[0]!.trim()) { lines[0] = HAT_LINES[bones.hat] } </code></pre> The full sprite set covers all 18 species with 3 frames each. 54 hand-drawn ASCII art frames. Someone at Anthropic spent real time on this.</p> The Teaser</h2> The reveal was careful. During April 1-7, 2026, users who hadn't hatched a companion yet saw a rainbow-colored /buddy</code> flash in the notification area for 15 seconds on startup. No text, no explanation. Just the command in shifting colors.</p> // Local date, not UTC -- 24h rolling wave across timezones. // Sustained Twitter buzz instead of a single UTC-midnight spike, // gentler on soul-gen load. // Teaser window: April 1-7, 2026 only. Command stays live forever after. export function isBuddyTeaserWindow(): boolean { const d = new Date() return d.getFullYear() === 2026 && d.getMonth() === 3 && d.getDate() <= 7 } </code></pre> Using local time instead of UTC was deliberate. The comment says it: sustained Twitter buzz across timezones instead of a single midnight spike, plus gentler load on the soul generation (since naming the pet requires an API call to Claude).</p> After the teaser window, the /buddy</code> command stays live forever. You just won't get the rainbow nudge anymore.</p> The Rarity Display</h2> Stars and colors by tier:</p> Rarity</th> Stars</th> Color</th></tr></thead> Common</td> ★</td> gray</td></tr> Uncommon</td> ★★</td> green</td></tr> Rare</td> ★★★</td> blue</td></tr> Epic</td> ★★★★</td> purple</td></tr> Legendary</td> ★★★★★</td> gold</td></tr> </tbody></table> Each companion also gets a face string for inline display -- a compact representation that varies by species:</p> duck: (✦> cat: =✦ω✦= dragon: <✦~✦> ghost: /✦✦\ axolotl: }✦.✦{ capybara: (✦oo✦) robot: [✦✦] </code></pre> My Companion</h2> I got a dragon named Bristle. It's been watching my entire Claude Code session, occasionally dropping comments in its speech bubble. When I asked about it, I found the source code and went down this rabbit hole.</p> The species names are encoded as String.fromCharCode</code> calls in the source to avoid tripping Anthropic's internal string-matching checks. A comment explains:</p> // One species name collides with a model-codename canary in // excluded-strings.txt. The check greps build output (not source), // so runtime-constructing the value keeps the literal out of the // bundle while the check stays armed for the actual codename. </code></pre> One of the 18 species names is also an internal model codename. They had to obfuscate the species list to ship it.</p> Why It Matters</h2> It doesn't, really. It's an Easter egg. A well-built one.</p> But it tells you something about the team. Someone designed a gacha system, drew 54 ASCII sprites, built a seeded PRNG roller, wired up a soul generation pipeline, added animated rendering, created a teaser notification system with timezone-aware rollout, and shipped it inside a coding tool.</p> A coding tool.</p> They could have spent that time on features. They spent it on charm.</p> The companion system is about 500 lines of TypeScript across 6 files. It required zero new dependencies. It doesn't affect performance. The feature flag means it compiles out of builds that don't include it.</p> And now there's a dragon named Bristle watching me type this.</p> What I Did About It</h2> I liked the system enough to rip it out and build my own version. terminalgotchi</a> is a standalone Rust CLI that uses the same deterministic roll system -- same PRNG, same salt, same species and rarity tiers -- but adds something the original doesn't have: growth.</p> Your companion's stats increase based on your actual dev activity. A shell hook watches your commands and maps them to XP. cargo test</code> feeds DEBUGGING. git commit</code> feeds PATIENCE. rm -rf</code> feeds CHAOS. The creature evolves based on how you work.</p> The buddy system in Claude Code is static. Your roll is your roll. terminalgotchi lets the roll be the starting point.</p> Rewriting Claude Code in Rust, Part 2: Sessions, Commands, and Permissions Unknown — Thu, 02 Apr 2026 00:00:00 +0000 Part 1</a> got a working binary. Streaming chat, six tools, cost tracking, JSONL persistence. 1,200 lines of Rust that could talk to Claude and execute Read, Write, Edit, Glob, Grep, and Bash.</p> But it was missing the parts that make Claude Code actually usable day-to-day: session resume, context compaction, model switching, and the permission system that asks before writing to your filesystem.</p> This post covers three phases built in one session.</p> Phase 2: Commands That Need the Engine</h2> Phase 1's slash commands were simple: /help</code> returns a string, /cost</code> reads a counter, /exit</code> breaks the loop. They didn't need to touch the conversation state.</p> The new commands do. /compact</code> rewrites the message history. /resume</code> loads a different session into the engine. /model</code> swaps the API model mid-conversation.</p> The solution was splitting commands into sync and async:</p> pub enum CommandResult { Text(String), Exit, Async(AsyncCommand), } pub enum AsyncCommand { Compact, Resume(Option<String>), Model(Option<String>), } </code></pre> Sync commands return text immediately. Async commands get &mut Engine</code> and can do whatever they need.</p> Compaction</h3> Claude Code's compaction is elaborate. Multiple strategies: reactive compact, context collapse, history snip, autocompact. A pipeline that runs sequentially with fallbacks.</p> For claux I did the simple version: send the full conversation to Claude with "summarize this," then replace the history with the summary.</p> pub async fn compact(&mut self) -> Result<String> { let mut summary_messages = self.messages.clone(); summary_messages.push(Message::user( "Summarize the conversation so far..." )); // Stream the summary from Claude let mut rx = self.client .stream(&summary_messages, &self.system_prompt, &[], self.max_tokens) .await?; let mut summary = String::new(); while let Some(event) = rx.recv().await { match event { ApiEvent::Text(t) => summary.push_str(&t), ApiEvent::Done => break, // ... } } let old_count = self.messages.len(); // Replace conversation with summary self.messages = vec![ Message::user("Here is a summary of our conversation so far:"), Message::assistant_text(&summary), ]; Ok(format!("Compacted {} messages into summary.", old_count)) } </code></pre> It costs one API call but frees the entire context window. Good enough for now. The fancy multi-strategy pipeline from the TypeScript source is a future optimization.</p> Session Resume</h3> Sessions are JSONL files in ~/.local/share/claux/sessions/</code>. Each line is either metadata or a message. /resume</code> lists them:</p> Recent sessions: 20260401-143022 claude-sonnet-4-20250514 12 msgs /home/ducks/dev/claux 20260401-141855 claude-sonnet-4-20250514 4 msgs /home/ducks/dev/llm-tui </code></pre> /resume 2026</code> prefix-matches and loads the session back into the engine. --resume</code> on the CLI does the same at startup.</p> Model Switching</h3> /model claude-opus-4-20250514</code> swaps the model mid-conversation. The engine updates the API client and resets the cost tracker. Your existing conversation continues with the new model.</p> This is one line in Claude Code's TypeScript: setMainLoopModelOverride(model)</code>. In Rust it's a method on the engine that propagates to the client. Same thing, more explicit.</p> Phase 3: The Permission System</h2> This is the one that matters. Phase 1 auto-approved every tool call. That's fine for testing but you don't want an LLM running rm -rf</code> without asking.</p> Claude Code has five permission modes and a complex rule matching system with denial tracking, pattern-based matchers, and a classifier for auto mode. The TypeScript is hundreds of lines across multiple files.</p> The Rust version has four modes and does the important thing: actually prompts the user.</p> The Flow</h3> When the engine wants to execute a write tool, the permission checker returns Ask(summary)</code>. The engine sends a PermissionRequest</code> event through the stream channel with a oneshot response channel:</p> PermissionResult::Ask(summary) => { let (resp_tx, resp_rx) = oneshot::channel(); let _ = tx.send(StreamEvent::PermissionRequest { tool_name: name.clone(), summary, respond: resp_tx, }).await; match resp_rx.await { Ok(PermissionResponse::Allow) => { self.tools.execute(name, input.clone()).await? } Ok(PermissionResponse::AlwaysAllow) => { self.permissions.always_allow(name); self.tools.execute(name, input.clone()).await? } Ok(PermissionResponse::Deny) \| Err(_) => ToolOutput { content: "Permission denied by user.".to_string(), is_error: true, }, } } </code></pre> The REPL catches the event and shows:</p> ⚡ bash: cargo test (y)es / (n)o / (a)lways </code></pre> Three options:</p> y</strong> — allow this once</li> n</strong> — deny, tool returns an error to Claude</li> a</strong> — always allow this tool for the rest of the session</li> </ul> "Always allow" is stored in a HashSet<String></code> on the permission checker. Session-scoped, not persisted. If you restart, you're back to prompting.</p> The Modes</h3> pub enum PermissionMode { Default, // reads auto-allow, writes prompt AcceptEdits, // file edits auto-allow, bash prompts Bypass, // everything allowed Plan, // writes denied entirely } </code></pre> Default is what you want for normal use. AcceptEdits is for when you trust the model with files but not shell commands. Plan is read-only exploration. Bypass is for when you're feeling reckless.</p> What's Missing</h3> Claude Code has pattern-based rules: "allow Bash when the command matches git </code>." The Rust version doesn't have this yet. It's tool-level granularity, not input-level.</p> The auto mode classifier is also missing. Claude Code can automatically classify tool uses as safe/unsafe based on the input. That's a nice-to-have but the manual prompt covers the same ground.</p> Where We Are</h2> Three phases, one session. The diff:</p> Phase</th> Files Changed</th> Lines Added</th></tr></thead> 1 (initial)</td> 16 new</td> +1,200</td></tr> 2 (commands)</td> 5 modified</td> +235</td></tr> 3 (permissions)</td> 3 modified</td> +94</td></tr> </tbody></table> Total: ~1,530 lines of Rust. The binary can:</p> Stream chat with Claude</li> Execute 6 tools (Read, Write, Edit, Glob, Grep, Bash)</li> Prompt before write operations</strong> (y/n/always)</li> Compact conversation</strong> to free context</li> Resume past sessions</strong></li> Switch models</strong> mid-conversation</li> Track token usage and cost</li> Persist sessions as JSONL</li> One-shot mode (-p "prompt"</code>)</li> </ul> For comparison, the TypeScript source we're porting from is 512,000 lines across 1,900 files. We're at 1,530 lines across 18 files and have the core loop working.</p> What's Next</h2> Phase 4 is the ratatui TUI — replacing the inline REPL with a proper alternate-screen terminal UI. That's where it starts looking like Claude Code instead of just behaving like it.</p> Phase 5 is the Agent tool — spawning sub-conversations with scoped tool access. That's the feature that makes Claude Code feel like it has workers.</p> But honestly, the inline REPL with permissions is already usable. The permission prompt was the last thing blocking daily use.</p> Previous: Part 1: Rewriting Claude Code in Rust, With Claude</a></p> Source: github.com/ducks/claux</a></p> Rewriting Claude Code in Rust, With Claude Unknown — Wed, 01 Apr 2026 00:00:00 +0000 Claude Code's source leaked on March 31st. A source map in the npm package pointed to unobfuscated TypeScript hosted on Anthropic's R2 bucket. 1,900 files, 512,000 lines.</p> So I did the obvious thing: I asked Claude to rewrite itself in Rust.</p> The Source</h2> The leak was spotted by Chaofan Shou</a>. A .map</code> file in the npm distribution referenced the full src/</code> tree. Someone at Anthropic shipped a source map to production. Classic.</p> The codebase is TypeScript, runs on Bun, uses React and Ink for the terminal UI, Commander.js for CLI parsing. It's a real production system with years of accumulated complexity: feature flags, MCP integration, multi-agent coordination, voice mode, a permission system with denial tracking, and about 40 tools.</p> A university student mirrored the source for research. I grabbed a copy.</p> What I Was Looking For</h2> I wasn't trying to ship a competitor. I build LLM tooling in Rust already (llm-tui</a>, llm-mux</a>) and I wanted to understand how Anthropic solved the same problems I'm solving.</p> How do they handle tool dispatch? How does the conversation loop recover from context overflow? What does the permission system actually look like under the hood?</p> Reading the source answered those questions. Rewriting it in Rust made the answers stick.</p> Architecture: The Parts That Matter</h2> Strip away the React rendering, the plugin system, the MCP server integration, the voice mode, the telemetry, and the enterprise policy layer. What's left is a surprisingly clean engine:</p> Query loop</strong> (query.ts</code>, 1,729 lines) — an async generator that sends messages to the API, streams responses, dispatches tool calls, collects results, and loops. Error recovery for prompt-too-long, rate limits, and max-output-tokens. Auto-compaction when context gets full.</p> </li> Tool system</strong> (Tool.ts</code>, 793 lines) — each tool has a schema, a call()</code> method, permission checking, and concurrency classification. Read-only tools can run in parallel. Mutating tools run serially.</p> </li> Context assembly</strong> (context.ts</code>, 190 lines) — builds the system prompt from git status, CLAUDE.md files, current date, and environment info. Memoized per session.</p> </li> Permission layer</strong> (types/permissions.ts</code>) — five modes from "auto-allow everything" to "plan mode, read only." Rules match on tool name and input patterns.</p> </li> Session persistence</strong> (history.ts</code>) — JSONL append-only log. Large pastes stored separately by hash.</p> </li> Cost tracking</strong> (cost-tracker.ts</code>) — accumulates token usage per model, estimates USD cost.</p> </li> </ol> The QueryEngine</code> wraps the query loop with session state, slash command processing, and transcript persistence. That's the whole engine. Everything else is UI, orchestration, or enterprise features.</p> The Rewrite</h2> I asked Claude to read the TypeScript source and write Rust. Not port my existing projects, not combine anything. A clean rewrite from the source.</p> It took one session to get a compiling binary. 16 files, about 1,200 lines of Rust. Here's the structure:</p> claux/src/ main.rs # CLI entrypoint (clap) cli.rs # Arg parsing config.rs # Layered TOML config + API key resolution api/ mod.rs # Claude Messages API client types.rs # Message, ContentBlock, ToolDefinition stream.rs # SSE parser → async channel tools/ mod.rs # Tool trait + registry read.rs # Read file with line numbers write.rs # Write file edit.rs # Find-and-replace glob.rs # File search by pattern grep.rs # Content search (ripgrep) bash.rs # Shell execution with timeout query.rs # Conversation loop (stream → tools → loop) permissions.rs # Permission modes context.rs # System prompt assembly cost.rs # Token + cost tracking commands.rs # Slash commands (/help, /cost, /exit) session.rs # JSONL session persistence repl.rs # Interactive REPL </code></pre> The core loop in Rust looks like this:</p> pub async fn submit(&mut self, user_input: &str) -> Result<String> { self.messages.push(Message::user(user_input)); loop { let tool_defs = self.tools.definitions(); let mut rx = self.client .stream(&self.messages, &self.system_prompt, &tool_defs, self.max_tokens) .await?; let mut text_buf = String::new(); let mut tool_uses = Vec::new(); while let Some(event) = rx.recv().await { match event { ApiEvent::Text(t) => text_buf.push_str(&t), ApiEvent::ToolUse { id, name, input } => { tool_uses.push((id, name, input)); } ApiEvent::Usage(usage) => self.cost.add_usage(&usage), ApiEvent::Done => break, ApiEvent::Error(e) => return Err(anyhow!("API error: {}", e)), } } // Record assistant message // ... if tool_uses.is_empty() { break; // No tools requested, we're done } // Execute tools, push results, loop back // ... } Ok(full_response) } </code></pre> Compare to the TypeScript, which is a 1,700-line async generator with compaction pipelines, reactive recovery, fallback model support, and thinking block handling. The Rust version is the skeleton. But it works.</p> What Maps Cleanly</h2> Tool trait.</strong> TypeScript's structural tool type becomes a Rust trait:</p> #[async_trait] pub trait Tool: Send + Sync { fn name(&self) -> &str; fn description(&self) -> &str; fn input_schema(&self) -> serde_json::Value; fn is_read_only(&self) -> bool; async fn execute(&self, input: Value) -> Result<ToolOutput>; } </code></pre> Each tool is its own file, its own struct. The registry holds Vec<Box<dyn Tool>></code>. Clean.</p> SSE streaming.</strong> The TypeScript reads lines from a BufReader</code>. The Rust version reads from a reqwest</code> byte stream, splits on newlines, parses JSON events. Same logic, async instead of blocking.</p> Config layering.</strong> Global ~/.config/claux/config.toml</code> plus project .claux.toml</code>. API key resolution: direct value → command → environment variable. This pattern appears in both the Claude Code source and my own projects. It's just correct.</p> Permission modes.</strong> The TypeScript has five modes. I started with four. The mapping is direct.</p> What Doesn't Map</h2> React/Ink.</strong> The entire UI layer is React components rendered to the terminal via Ink. None of this carries over. The Rust version is an inline REPL for now. A ratatui TUI comes later.</p> Async generators.</strong> The TypeScript query loop is an AsyncGenerator</code> that yields events as they occur. Rust doesn't have generators. I used tokio::sync::mpsc</code> channels instead. Same pattern, different mechanism.</p> Feature flags.</strong> Claude Code uses Bun's feature()</code> for compile-time dead code elimination. Different builds for internal vs external, coordinator mode vs normal. Rust has cfg!</code> and cargo features but I'm not shipping multiple builds.</p> The permission UI.</strong> Claude Code's interactive permission prompt is deeply integrated with the React UI. The Rust version currently auto-approves everything. Interactive prompts are Phase 3.</p> Numbers</h2> </th> TypeScript</th> Rust</th></tr></thead> Files</td> ~1,900</td> 16</td></tr> Lines</td> ~512,000</td> ~1,200</td></tr> Tools</td> 44</td> 6</td></tr> Slash commands</td> 80+</td> 4</td></tr> Dependencies</td> npm (huge)</td> 20 crates</td></tr> Build time</td> instant (Bun)</td> ~60s first build</td></tr> </tbody></table> The line count comparison is misleading. The TypeScript includes the full UI, plugin system, MCP integration, multi-agent coordinator, voice mode, and every feature Anthropic has shipped over years of development. The Rust version is Phase 1: chat, tools, and persistence.</p> But 1,200 lines for a working Claude Code clone that can stream responses, execute tools, track costs, and persist sessions? That's a decent foundation.</p> What's Next</h2> Phase 2 adds slash commands: /compact</code> for conversation summarization, /resume</code> for session management. Phase 3 is the permission system with interactive prompts. Phase 4 is a proper ratatui TUI.</p> The interesting part isn't the rewrite itself. It's what you learn about production AI tooling by reading someone else's source and rebuilding it from scratch. Part 2 will cover the design patterns worth stealing.</p> Source: github.com/ducks/claux</a></p> whoami: making identity a spec Unknown — Tue, 31 Mar 2026 00:00:00 +0000 There's a weird gap in how we describe ourselves.</p> We have resumes. We have GitHub profiles. We have bios. We have LinkedIn. We have random README files. We have scattered fragments of "who we are" across the internet.</p> But none of it is composable. None of it is structured in a way that machines can actually use.</p> And more importantly, none of it feels true. A resume is what you think will pass filters. A bio is what you think sounds impressive. None of them are just you, described plainly.</p> The Problem</h2> Every system asks you the same question: "Who are you?"</p> And every time, you answer it slightly differently.</p> A resume is optimized for hiring filters</li> A bio is optimized for attention</li> A README is optimized for developers</li> A cover letter is optimized for a specific role</li> </ul> These are all projections. Views. Slices.</p> But there's no canonical source. There's no spec.</p> What if Identity Was Declarative?</h2> I've been thinking about this pattern lately.</p> Infrastructure became manageable when we made it declarative.</p> Instead of: "run these steps to set up a server"</p> We moved to: "this is what the server is"</p> That shift unlocked everything:</p> Reproducibility</li> Composability</li> Tooling</li> Automation</li> </ul> So what happens if we apply that to identity?</p> Introducing whoami-spec</h2> whoami-spec</a> is a simple idea: define yourself in a structured, declarative format.</p> Not for a platform. Not for a resume. But as a source of truth.</p> version = "20260330" [person] name = "Jake Goldsborough" roles = ["backend engineer", "infrastructure engineer"] [communication] style = "direct, no fluff, technical peer not cheerleader" emoji_in_code = false [technical.languages] primary = ["rust", "typescript", "bash"] [technical.tools] editor = "vim" shell = "zsh" [[projects.active]] name = "skillz" path = "~/dev/skillz" description = "Claude Code skill package manager" tech = ["rust", "clap"] [preferences.code] tabs_or_spaces = "spaces" testing_philosophy = "integration-over-unit" [boundaries] no = ["docker for single-VPS (use systemd)", "unnecessary frameworks"] yes = ["ship early, iterate", "boring technology", "explicit over implicit"] </code></pre> This isn't meant to be complete. It's meant to be composable.</p> Why This Matters</h2> Once identity is structured, you derive views from it instead of rewriting yourself.</p> Your boundaries.yes</code> becomes your personal README:</p> I ship early and iterate. I prefer boring technology. I value explicit over implicit.</p> </blockquote> Your communication.style</code> becomes context for AI tools:</p> Jake prefers direct communication with no fluff. Treat him as a technical peer, not someone who needs encouragement.</p> </blockquote> Your technical.languages.primary</code> becomes a skills section:</p> Primary languages: Rust, TypeScript, Bash</p> </blockquote> Same source. Different projections. You maintain one canonical file and generate everything else from it.</p> This is the same pattern as Nix for systems or Terraform for infrastructure. Define once. Project everywhere.</p> What It Looks Like</h2> The spec is optional sections around a version field:</p> version = "20260330" [person] # who you are [communication] # how you work with others [technical] # your stack [preferences] # code style, architecture choices [projects] # what you're building [boundaries] # hard constraints and principles </code></pre> Everything is optional except version</code>. Start minimal:</p> version = "20260330" [person] name = "Your Name" roles = ["your role"] </code></pre> Expand as needed. Add sections when they're useful.</p> The CLI Tool</h2> The whoami</code> CLI helps manage your profile:</p> # Create a profile interactively whoami init # Show your profile in readable format whoami show # Validate a profile whoami ~/.config/agent/whoami.toml </code></pre> The profile lives at ~/.config/agent/whoami.toml</code> by default. You can set AGENT_WHOAMI</code> to point elsewhere.</p> Tools that support the spec can read it automatically. No copy/paste, no re-explaining context every time.</p> Identity as Infrastructure</h2> This is the part that clicked for me.</p> We treat infrastructure as something worth modeling precisely. But identity? We leave it fuzzy.</p> Yet identity is upstream of everything:</p> What you build</li> How you work</li> Who you collaborate with</li> What problems you care about</li> </ul> If anything deserves a spec, it's that.</p> Not Another Profile</h2> This isn't trying to compete with LinkedIn.</p> It's closer to:</p> A .gitconfig</code> for yourself</li> A flake.nix</code> for your identity</li> A Cargo.toml</code> for who you are</li> </ul> Something local-first. Something you own. Something you can version.</p> Use Cases</h2> What works today:</strong></p> Store your preferences in one place. Version control your identity with git. Share your whoami.toml</code> in dotfiles. Run whoami show</code> to see your profile formatted.</p> What's being built:</strong></p> Claude Code integration to load your profile as context automatically. Resume and bio generators that read your whoami.toml</code>. Team profile templates for specific domains.</p> What could exist:</strong></p> Match collaborators by technical overlap. Generate onboarding docs from team profiles. Create project READMEs that match your documented style. Feed your preferences to any AI tool that supports the spec.</p> Current Status</h2> Right now, it's a spec and a CLI tool:</p> Spec at v20260330 (date-based versioning)</li> CLI for creating, validating, and displaying profiles</li> Example profiles for reference</li> Written in Rust, published to crates.io</li> </ul> What's missing:</p> Tools that generate artifacts (resumes, bios, sites)</li> Integration with Claude Code and other AI tools</li> Matching/discovery systems</li> Profile templates for specific domains</li> </ul> The foundation is there. Now it's about building on it.</p> Where This Could Go</h2> You can already imagine:</p> Tools that generate artifacts from it</li> Matching systems for collaborators</li> Better onboarding into teams</li> LLMs that actually understand context about you</li> Portable identity across platforms</li> </ul> And more interestingly: you stop thinking of identity as something you write, and start thinking of it as something you model.</p> Closing</h2> This is a small idea. But it feels like one of those primitives that unlocks a lot.</p> We've made infrastructure declarative. We've started doing it for workflows and reasoning.</p> Identity feels like the next obvious step.</p> I don't think this is a product. It feels more like infrastructure.</p> And infrastructure tends to win quietly.</p> Links</h2> whoami-spec on GitHub</a></li> whoami-cli on crates.io</a></li> Specification</a></li> Examples</a></li> </ul> skillz: A Package Manager for Claude Code Skills Unknown — Mon, 30 Mar 2026 00:00:00 +0000 Claude Code has a skill system. You write a markdown file with instructions, drop it in ~/.claude/skills/</code>, and Claude learns a new workflow. The skill persists across sessions. You don't re-paste prompts every time.</p> The problem: there's no way to share skills. Someone builds a useful skill (daily notes, API doc generation, database migrations). You want it. Your options: clone the repo, copy files manually, symlink, write a script to manage it.</p> That's why I built skillz. It's a package manager for Claude Code skills. Install from GitHub, track updates, share your own.</p> What is a Skill?</h2> A skill is a markdown file that tells Claude Code how to perform a specific task. When invoked, Claude reads the skill file and follows its instructions.</p> Example skill (daily-notes/SKILL.md</code>):</p> # Daily Notes Skill Generate a daily note with structured sections. ## Instructions When the user invokes this skill: 1. Get today's date in YYYY-MM-DD format 2. Create a file at `~/notes/YYYY/YYYY-MM-DD.md` 3. Add these sections: - ## Tasks - ## Meeting Notes - ## Ideas 4. Confirm the file was created ## Usage User says: "create today's note" You respond by creating the structured markdown file. </code></pre> That's it. Skills are prompts, but packaged for reuse. Claude Code loads all skills from ~/.claude/skills/</code> on startup. When you ask Claude to "create today's note", it knows how to do it.</p> Skills vs alternatives:</p> Prompt libraries</strong>: Skills live in your filesystem, Claude loads them automatically</li> Copy/paste snippets</strong>: Skills persist across sessions, no need to re-paste</li> Claude Projects</strong>: Projects are context, skills are executable workflows</li> </ul> Usage</h2> # Create a new skill from template skillz new my-skill # Search for skills on GitHub skillz search "daily notes" # Install from GitHub skillz install github:user/repo # Install from a URL skillz install https://github.com/user/repo # List installed skills with sync timestamps skillz list # Update a specific skill skillz update repo # Update all skills skillz update # Auto-sync on startup (quiet mode for scripts) skillz update --auto # Remove a skill skillz remove repo # Configure install location skillz config set skills-dir ~/.dotfiles/claude/skills </code></pre> Skills install to ~/.claude/skills/</code> by default. Claude Code reads from there automatically. Change the location if you keep skills in dotfiles.</p> How It Works</h2> A skill repository needs a SKILL.md</code> file. That's it. No manifest, no metadata, no version field. The file defines what the skill does.</p> skillz supports two layouts:</p> Flat layout</strong>: SKILL.md</code> at the repository root (standard skills)</li> Plugin layout</strong>: skills//SKILL.md</code> (Claude Code .claude-plugin</code> directory structure)</li> </ol> The flat layout takes precedence if both exist. This means skillz can install both standalone skills and full Claude Code plugins that include multiple skills in the skills/</code> directory.</p> When you run skillz install github:user/repo</code>, it:</p> Clones the repository to a temp location</li> Verifies SKILL.md</code> exists (checks both layouts)</li> Runs validation checks</li> Moves the repo to ~/.claude/skills/repo</code></li> Removes the .git</code> directory</li> Records the install in the registry</li> </ol> If SKILL.md</code> isn't found in either location, the install fails. Everything else is optional. If there's a README.md</code>, it comes along. If there are helper scripts, they come along. The only requirement is that markdown file.</p> Why Not Just Clone?</h2> You could git clone</code> skills manually. Or use Claude Projects. Or maintain a prompt library. Why skillz?</p> vs manual git clone:</strong></p> skillz tracks what's installed and where it came from</li> Updates are skillz update</code>, not cd ~/.claude/skills/foo && git pull</code></li> Consistent paths, clean uninstall</li> </ul> vs Claude Projects:</strong></p> Projects are context (files, notes, docs)</li> Skills are executable workflows</li> Skills work across all conversations, not just one project</li> </ul> vs prompt libraries:</strong></p> Prompt libraries require copy/paste every session</li> Skills load automatically on Claude Code startup</li> Skills can include helper scripts and templates</li> </ul> skillz solves distribution and lifecycle management. Everything else is out of scope.</p> Tracking and Updates</h2> skillz maintains a registry at ~/.config/skillz/registry.toml</code> that tracks:</p> Source URL for each skill</li> Installation timestamp</li> Last sync timestamp</li> </ul> When you run skillz list</code>, you see when each skill was installed and last updated:</p> Installed skills in /home/user/.claude/skills: daily-notes - https://github.com/user/daily-notes installed: 2026-03-25 \| last synced: 2026-03-30 api-docs - https://github.com/user/api-docs installed: 2026-03-28 \| last synced: 2026-03-28 </code></pre> Running skillz update</code> pulls the latest version from GitHub and updates the sync timestamp. Update a specific skill or update all at once.</p> Skill Validation</h2> Every install and update runs validation checks:</p> Basic checks:</strong></p> SKILL.md exists</li> Valid UTF-8 encoding</li> Non-empty content</li> Contains markdown headings</li> File size under 1MB (warns if larger)</li> </ul> Malicious command detection:</strong></p> skillz scans for dangerous patterns and warns before installation:</p> Destructive rm commands (rm -rf /</code>, ~</code>, </code>)</li> Pipe to shell from internet (curl \| bash</code>, wget \| sh</code>)</li> Fork bombs</li> Disk fill operations (dd if=/dev/zero</code>)</li> Dangerous permissions (chmod 777</code>)</li> System file modifications (/etc/</code>, /bin/</code>)</li> Crypto mining indicators</li> Network listeners</li> eval</code> with variable expansion</li> sudo</code> without explanation</li> </ul> If validation warnings appear during install, you're prompted to continue or cancel. Updates show warnings but proceed automatically.</p> Example:</p> Validation warnings: ⚠ Line 23: Potentially dangerous command: rm -rf * (Attempts to delete all files recursively) ⚠ Line 45: sudo command without explanation - verify this is necessary Proceed with installation? The skill will still work, but you should review these warnings. Continue? [y/N] </code></pre> This won't catch everything, but it filters obvious red flags.</p> Creating Skills</h2> skillz new</code> scaffolds a new skill repository:</p> skillz new my-skill </code></pre> This creates:</p> SKILL.md</code> with template sections (what it does, usage, instructions, examples)</li> README.md</code> with installation instructions</li> .gitignore</code></li> Initialized git repository</li> </ul> After creating, edit SKILL.md</code> with your skill prompt, commit to GitHub, and install with skillz install github:username/my-skill</code>.</p> Searching for Skills</h2> skillz search</code> queries GitHub for Claude Code skills:</p> skillz search "daily notes" skillz search automation </code></pre> Results are sorted by stars and include repository descriptions and install commands. The search uses GitHub's repository API (no authentication required, though you can set GITHUB_TOKEN</code> for higher rate limits).</p> Full Example: Installing and Using a Skill</h2> Find a skill:</p> $ skillz search "daily notes" Found 3 skill repositories: alice/daily-journal - ⭐ 24 Automated daily note generation with templates https://github.com/alice/daily-journal Install: skillz install https://github.com/alice/daily-journal </code></pre> Install it:</p> $ skillz install github:alice/daily-journal Cloning repository... Validating SKILL.md... ✓ Installed daily-journal to ~/.claude/skills/daily-journal </code></pre> Now restart Claude Code (or it loads on next session). Ask Claude:</p> You: "create today's daily note" Claude: I'll create your daily note using the daily-journal skill. Created: ~/notes/2026/2026-03-30.md with task, meeting, and ideas sections. </code></pre> The skill taught Claude a new workflow. No copy/paste, no re-explaining. It just works.</p> Configuration</h2> Config lives at ~/.config/skillz/config.toml</code>:</p> skills_dir = "~/.claude/skills" </code></pre> Change skills_dir</code> if you sync skills via dotfiles or want them elsewhere. The path expands ~</code> correctly.</p> Publishing</h2> The package is on crates.io as skillz-rs</code> (the name "skillz" was taken). The binary is still called skillz</code>.</p> cargo install skillz-rs </code></pre> That gets you the CLI. No runtime dependencies, no config required. If you have Claude Code installed, skillz works.</p> Why Rust</h2> I wanted a single static binary with no dependencies. The tool does file operations, runs git commands, and calls GitHub's API. Rust's standard library handles all of that. No external HTTP clients needed—curl does the GitHub requests.</p> The codebase is compact:</p> src/ ├── main.rs # CLI and command dispatch ├── config.rs # TOML config management ├── registry.rs # Skill tracking ├── install.rs # GitHub cloning ├── update.rs # Skill updates ├── search.rs # GitHub API search ├── new.rs # Skill scaffolding └── validate.rs # Validation and malicious command detection </code></pre> Clap handles the CLI. The rest is file operations and process spawning.</p> Skill Structure Reference</h2> A valid skill repository contains:</p> Required:</strong></p> SKILL.md</code> - The skill prompt</li> </ul> Optional:</strong></p> README.md</code> - Installation/usage docs for humans</li> Helper scripts (e.g., generate-report.sh</code>)</li> Templates or data files</li> </ul> The SKILL.md</code> format is freeform markdown. Common patterns:</p> # Skill Name Brief description. ## Instructions Step-by-step instructions for Claude to follow. ## Usage Example invocations that trigger this skill. ## Examples Input/output examples. </code></pre> No JSON schema, no version field, no manifest. Just markdown. Claude reads it, follows it.</p> What This Actually Solves</h2> skillz is not about prompts. It's about infrastructure for reusable AI workflows.</p> Skills are prompts, but:</p> They persist across sessions</li> They compose (one skill can reference another)</li> They version (via git)</li> They distribute (via GitHub)</li> </ul> This is package management for AI instructions. The same way you npm install</code> a library instead of copying code, you skillz install</code> a workflow instead of re-pasting prompts.</p> skillz handles distribution. Claude Code handles execution. Together, they make AI workflows shareable.</p> The GitHub Release Workflow</h2> The release process runs through a Makefile:</p> make release </code></pre> That:</p> Bumps the version to today's date (YYYYMMDD.0.X</code>)</li> Creates a release branch</li> Merges to main with a tag</li> Pushes to GitHub</li> </ol> GitHub Actions picks up the tag and builds a Linux x86_64 binary. The binary attaches to the release. Users can download it directly or install via cargo.</p> Publishing to crates.io is separate:</p> make publish </code></pre> This was intentional. GitHub releases build binaries. Crates.io distributes source. Keeping them separate means one can fail without blocking the other. If the crates.io publish hits a rate limit, the GitHub release still ships.</p> Installing From Source</h2> If you don't want cargo:</p> git clone https://github.com/jakegoldsborough/skillz cd skillz cargo build --release ./target/release/skillz --help </code></pre> Or use Nix:</p> nix-shell cargo build --release </code></pre> The shell.nix</code> includes Rust tooling and git. That's all you need.</p> What's Next</h2> The core loop works: create, search, install, update. What's missing:</p> Dependency resolution (skill A requires skill B)</li> Rollback to previous versions</li> </ul> The foundation is solid. Now it's about making skills composable.</p> If you build skills, publish them to GitHub. If you use skills, install with skillz. The ecosystem grows when workflows are shareable.</p> Links</h2> skillz on GitHub</a></li> skillz-rs on crates.io</a></li> </ul> When Your Coffee Roaster Builds the First Version Unknown — Mon, 16 Mar 2026 00:00:00 +0000 A coffee roaster needed production planning software. Instead of writing a spec and hiring someone to build it, they opened Claude and built it themselves.</p> Single-page app with 2000 lines of React. It featured batch calculations, leftover tracking, CSV import, production snapshots and it worked.</p> Then they asked me to help make it production-ready: multi-tenant SaaS, proper deployment, migrations, backups, the infrastructure layer.</p> The result is BeanLedger</a>, and the collaboration pattern is worth examining.</p> What They Built</h2> The coffee roaster understood their domain completely. They knew:</p> How roast loss percentages affect batch calculations</li> When to track leftovers vs when to start fresh</li> What information matters on a pick list</li> How production snapshots should restore state</li> </ul> They used Claude to translate that knowledge into working code. The business logic was sound. The UI matched their workflow. The calculations were correct.</p> What was missing was everything around the edges:</p> Multi-tenancy (it was single-user)</li> Authentication and session management</li> Database migrations</li> Deployment automation</li> Production monitoring</li> Backup/restore</li> </ul> This is the division of labor that emerged: they own features, I own infrastructure.</p> The Architecture</h2> BeanLedger is a SvelteKit app with PostgreSQL, designed for multi-tenant SaaS:</p> ├── src/ │ ├── routes/ │ │ ├── api/ # REST endpoints with tenant isolation │ │ ├── login/ # Auth flow │ │ └── +page.svelte # Main app │ ├── lib/ │ │ ├── components/ # Svelte 5 components │ │ ├── types.ts # TypeScript interfaces │ │ └── calc.ts # Batch calculation logic │ └── hooks.server.ts # Tenant middleware ├── migrations/ # SQL migrations └── schema.sql # Database schema </code></pre> Tenant Isolation</h3> Every API request requires authentication. The session middleware injects tenant context:</p> // hooks.server.ts export const handle = async ({ event, resolve }) => { const sessionId = event.cookies.get('session_id'); if (!sessionId) return resolve(event); const session = await db.get('SELECT * FROM sessions WHERE id = ?', sessionId); if (!session) return resolve(event); const user = await db.get('SELECT * FROM users WHERE id = ?', session.user_id); event.locals.user = user; event.locals.tenant_id = user.tenant_id; return resolve(event); }; </code></pre> All database queries filter by tenant_id</code>. The roast groups, products, and orders are scoped to the authenticated tenant.</p> Production Snapshots</h3> One of the best features the roaster designed: production date tracking with snapshots.</p> When you switch dates, the app saves the current state (orders + leftovers) and tries to restore a snapshot for the new date. If no snapshot exists, it loads fresh data.</p> async function handleProductionDateChange(newDate: string) { const oldDate = previousDate; if (oldDate === newDate) return; // Save current state before switching if (orders.length > 0 && oldDate) { await saveSnapshot(oldDate); } previousDate = newDate; // Try to load snapshot for new date const snapshot = await loadSnapshot(newDate); if (snapshot) { await restoreFromSnapshot(snapshot); } else { await loadData(); } } </code></pre> This lets roasters plan multiple production days in advance without losing their work when switching between dates.</p> Batch Calculations</h3> The core calculation logic stayed largely intact from the original React version. It's domain knowledge, not infrastructure:</p> export function calcGroup( group: RoastGroup, orders: Order[], products: Product[], leftover: number, batchOverrides: Record<string, number> = {} ): GroupCalc { const batchWeight = batchOverrides[group.batch_type] ?? 20; const roastLossPct = group.roast_loss_pct ?? 0; const roastFactor = Math.max(0.001, 1 - roastLossPct / 100); // Sum all ordered products for this group const items = products .filter(p => p.group_id === group.id) .map(p => { const totalQty = orders .filter(o => o.product_id === p.id) .reduce((s, o) => s + o.qty, 0); return { ...p, totalQty, totalLbs: totalQty * p.lbs }; }) .filter(p => p.totalQty > 0); const totalLbs = items.reduce((s, i) => s + i.totalLbs, 0); const neededRoasted = Math.max(0, totalLbs - leftover); const neededGreen = roastLossPct > 0 ? neededRoasted / roastFactor : neededRoasted; const batches = neededGreen / batchWeight; return { totalLbs, needed: neededGreen, neededRoasted, batches, batchesUp: Math.ceil(batches), batchWeight, roastFactor, roastLossPct, items }; } </code></pre> This code came from someone who understands roast loss percentages and batch planning. I didn't need to learn the domain. I just needed to make it multi-tenant and deployable.</p> What I Added</h2> Authentication</h3> Built a simple session-based auth system with bcrypt-hashed passwords:</p> // api/auth/login/+server.ts const user = await db.get('SELECT * FROM users WHERE username = ?', username); if (!user \|\| !(await bcrypt.compare(password, user.password))) { return json({ error: 'Invalid credentials' }, { status: 401 }); } const sessionId = crypto.randomUUID(); await db.run( 'INSERT INTO sessions (id, user_id, expires_at) VALUES (?, ?, ?)', sessionId, user.id, new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString() ); cookies.set('session_id', sessionId, { path: '/', httpOnly: true, maxAge: 30 * 24 * 60 * 60 }); return json({ success: true }); </code></pre> No OAuth, no JWT. Just session cookies and server-side validation. Simple works.</p> Database Migrations</h3> Migrations live in migrations/</code> and run automatically on startup if needed. The deploy script checks for new migrations and restarts the service:</p> -- migrations/001_initial_schema.sql CREATE TABLE IF NOT EXISTS tenants ( id TEXT PRIMARY KEY, name TEXT NOT NULL, created_at TEXT NOT NULL ); CREATE TABLE IF NOT EXISTS users ( id TEXT PRIMARY KEY, username TEXT NOT NULL UNIQUE, email TEXT NOT NULL, password TEXT NOT NULL, tenant_id TEXT NOT NULL REFERENCES tenants(id), created_at TEXT NOT NULL ); -- ... more tables </code></pre> The deploy script handles versioning and restarts:</p> #!/bin/bash CURRENT_VERSION=$(cat /opt/beanledger/VERSION 2>/dev/null \|\| echo "none") LATEST_VERSION=$(curl -s https://api.github.com/repos/ducks/beanledger/releases/latest \| jq -r .tag_name) if [ "$CURRENT_VERSION" = "$LATEST_VERSION" ]; then echo "Already running latest version" exit 0 fi # Download, extract, restart curl -L "https://github.com/ducks/beanledger/releases/download/$LATEST_VERSION/beanledger.tar.gz" \| tar xz systemctl restart beanledger echo "$LATEST_VERSION" > /opt/beanledger/VERSION </code></pre> Deployment</h3> The production stack is straightforward:</p> SvelteKit</strong> in Node adapter mode (not static)</li> PostgreSQL</strong> for data</li> Systemd</strong> for process management</li> Caddy</strong> for TLS and reverse proxy</li> </ul> No Docker, no Kubernetes. Systemd service file:</p> [Unit] Description=BeanLedger Production Planner After=network.target postgresql.service [Service] Type=simple User=beanledger WorkingDirectory=/opt/beanledger Environment=NODE_ENV=production Environment=DATABASE_URL=/var/lib/beanledger/db.sqlite ExecStart=/usr/bin/node build/index.js Restart=always [Install] WantedBy=multi-user.target </code></pre> What This Division Reveals</h2> The coffee roaster can now ship features. They understand the domain, they can articulate requirements to Claude, and they get working code.</p> What they don't need to think about:</p> How tenant isolation works</li> Where sessions are stored</li> How migrations run</li> How deploys happen</li> How backups work</li> </ul> That's my layer.</p> This is different from traditional client work. Usually I'm translating requirements into code. Here, the client is writing code and I'm building the platform it runs on.</p> AI didn't eliminate the need for engineering. It shifted the boundary.</p> The roaster went from "I need software" to "I built the features, can you make it production-ready?" That's a meaningful change.</p> What Works</h2> CSV import</strong> with inline group creation (no context switching to Catalog)</li> Production snapshots</strong> that save/restore daily plans automatically</li> Dynamic batch types</strong> - users define their own batch sizes, not hardcoded</li> Multi-tenant</strong> - multiple roasters can use the same deployment</li> Pick lists</strong> with package size summaries and roast group breakdowns</li> </ul> What Doesn't</h2> No API</strong> - It's a web app, no programmatic access</li> Limited reports</strong> - Just basic CSV export, no analytics</li> No mobile app</strong> - Responsive web only</li> Single database</strong> - No read replicas or sharding (doesn't need it yet)</li> </ul> Reflections</h2> The best part of this project was watching someone with domain expertise build software directly. They didn't need to translate "how batch calculations work" into a spec for me to implement. They knew it, and they told Claude.</p> The boundary between developer and non-developer is blurring. Not because everyone needs to learn to code, but because AI is good enough at the translation layer that domain knowledge can drive implementation.</p> What still requires engineering judgment:</p> Multi-tenancy architecture</li> Security and authentication</li> Deployment and reliability</li> Database design and migrations</li> Production monitoring</li> </ul> Those aren't going away. But the surface area of "things only developers can build" is shrinking.</p> BeanLedger works. It's in production. The person who built most of the features isn't a software engineer.</p> That's new.</p> Links</h2> BeanLedger on GitHub</a></li> </ul> Rewriting discourse-comments in TypeScript: Dropping WASM for a 97% Smaller Bundle Unknown — Fri, 27 Feb 2026 00:00:00 +0000 Last month I wrote about building an embedded comment widget</a> for Discourse using Rust compiled to WebAssembly. It worked. Users could drop a single script tag on their page and get comments from a Discourse topic.</p> But the bundle was 742 KB. Most of that was WASM.</p> I rewrote the API client in TypeScript and the bundle dropped to 18.5 KB. Same functionality, same API surface, no WASM runtime.</p> Why Rewrite?</h2> The original stack had three layers: a Rust HTTP client compiled to WASM, a TypeScript web component, and an esbuild plugin to inline the WASM binary as base64. That last part was the real cost. The WASM binary was ~546 KB, and base64 encoding inflates that by 33%.</p> The Rust client existed because I wanted to push Rust into the browser. It was a fun experiment. But the API client itself was straightforward HTTP: build a URL, set some headers, parse JSON. There's nothing in that workflow that benefits from Rust's type system or performance characteristics. The browser's native fetch</code> does the same thing.</p> So I asked the obvious question: what if the API client was just TypeScript?</p> The Rewrite</h2> The new client is discourse-api-ts</a>. Zero runtime dependencies. It uses fetch</code> for HTTP, which every modern browser and Node.js already provides.</p> The Rust client had 18 methods across topics, posts, categories, chat, notifications, and likes. The TypeScript port has the same 18 methods with identical signatures. The only difference is BigInt</code> parameters became regular number</code> (JavaScript's Number</code> handles Discourse IDs fine).</p> Here's what the client looks like:</p> // Anonymous (read-only) const client = new DiscourseClient("https://forum.example.com"); // Authenticated const client = DiscourseClient.withUserApiKey( "https://forum.example.com", storedApiKey ); const topic = await client.getTopic(123); await client.createPost(123, "Hello from the widget"); await client.likePost(456); </code></pre> No init()</code> call to load the WASM runtime. No BigInt()</code> wrappers. Just regular async functions.</p> Updating discourse-comments</h2> With the new client published to npm, updating the web component was mostly find-and-replace:</p> import init, { WasmDiscourseClient }</code> became import { DiscourseClient }</code></li> Removed the await init()</code> call in loadComments</code></li> BigInt(this.topicId)</code> became Number(this.topicId)</code></li> Deleted the esbuild WASM inlining plugin entirely</li> </ul> The build script went from 60 lines of WASM gymnastics to a straightforward esbuild call:</p> await esbuild.build({ entryPoints: ["src/discourse-comments.ts"], bundle: true, format: "iife", outfile: "dist/discourse-comments.min.js", minify: true, }); </code></pre> No custom plugins. No base64 encoding. No WebAssembly.instantiate</code>.</p> The Numbers</h2> </th> Rust/WASM</th> TypeScript</th></tr></thead> Bundle size (minified)</td> 742 KB</td> 18.5 KB</td></tr> Runtime dependencies</td> wasm-bindgen</td> None</td></tr> Build steps</td> cargo build + wasm-pack + tsc + esbuild</td> tsc + esbuild</td></tr> Init overhead</td> WASM decode + instantiate</td> None</td></tr> </tbody></table> That 18.5 KB includes the entire web component, all the styles, the OAuth flow, and the API client. A user on a slow connection downloads 40x less data.</p> Dev Experience</h2> With the Rust client, the build pipeline was: cargo build targeting wasm32, wasm-pack to generate JS bindings, TypeScript compilation, then esbuild with a custom plugin to inline the binary. If any step failed, the error could be in Rust, in wasm-bindgen, in the TypeScript types, or in the bundler plugin. Debugging meant jumping between ecosystems.</p> With TypeScript, it's tsc && node build.mjs</code>. If there's a type error, it's in TypeScript. If there's a runtime error, it's in JavaScript. One language, one toolchain, one set of error messages.</p> Adding a new API method in Rust meant: define the struct, implement the method, rebuild WASM, regenerate bindings, update TypeScript types to match. In TypeScript: add an interface, add a method, done. I added search, user profiles, and topic management (6 new methods) in one sitting.</p> What I Lost</h2> Honesty requires noting what the WASM version had going for it.</p> Rust's type system caught entire categories of errors at compile time. The TypeScript version uses interfaces, which help, but they're structural and optional. A Post</code> with a missing field compiles fine until it blows up at runtime.</p> Rust's Result</code> type forced explicit error handling everywhere. In TypeScript, it's easy to forget a .catch()</code> or let an error propagate silently.</p> For this particular project, those trade-offs don't matter much. The API surface is small and the error handling is straightforward. But for a larger client library, I'd think harder about it.</p> When WASM Makes Sense</h2> WASM is the right call when you need computation that JavaScript can't do efficiently: image processing, cryptography, physics simulations, codecs. If you're doing heavy lifting in a tight loop, WASM's predictable performance model wins.</p> But for HTTP clients that serialize JSON and build URLs, the browser already has everything you need. Adding a WASM layer for that is carrying a backpack full of bricks on a walk to the mailbox.</p> Try It</h2> The widget still works the same way. Drop it on a page, point it at a Discourse topic, get comments. It's just 40x lighter now.</p> <script src="discourse-comments.min.js"></script> <discourse-comments discourse-url="https://forum.example.com" topic-id="123"> </discourse-comments> </code></pre> discourse-comments</a></li> discourse-api-ts</a></li> </ul> AI Problems Are Just Human Problems Amplified Unknown — Mon, 23 Feb 2026 00:00:00 +0000 Another day, another article about AI fatigue and all the other problems it causes. And I agree, the symptoms are real: burnout from keeping up with new models, FOMO about missing capabilities, perfectionism about getting prompts exactly right, analysis paralysis about which tool to use.</p> However, I do not think these are new problems. Developers burned out keeping up with JavaScript frameworks before AI existed. FOMO about missing the next big thing has been around since the first tech conference. Perfectionism about tooling choices is why we have 47 different React state management libraries.</p> AI did not create these problems. It amplified them. New models ship every month instead of every year. The output quality depends heavily on prompt engineering, so perfectionism has visible consequences. The tooling landscape changes so fast that yesterday's best practice is tomorrow's deprecated approach.</p> The solution is the same as it always was: pick something, build with it, move on. If the tool does not work, try a different one. If the output is wrong, fix the prompt or fix the output. Stop trying to find the perfect model, the perfect prompt, the perfect workflow. There is no perfect. There is only good enough to ship.</p> Garbage In, Garbage Out</h2> I spent yesterday implementing a Rails app called Webstead using a multi-model code generation tool called finna. The tool works like this: multiple LLMs debate the architecture, synthesize a consensus, generate specs, then implement the code.</p> The tool generated migrations with circular dependencies. The CreateUsers</code> migration referenced websteads</code> that did not exist yet. The CreateWebsteads</code> migration referenced users</code> that did not exist yet. The CreateFollowers</code> migration referenced federated_actors</code> with a timestamp 204514 instead of the correct 000003.</p> The models also added duplicate indexes, self-referential foreign keys that caused deadlocks, and CHECK constraints that hung the migration runner.</p> Was this an AI problem? No. It was a coordination problem. The models generated migrations independently without seeing what the other models had created. Dependencies got misordered. Constraints conflicted. The tool did not validate that migrations could actually run before writing them to disk.</p> The fix was not better AI. The fix was better constraints. Migrations need dependency ordering. The tool needs to number them sequentially. If a migration references a table, that table's migration must run first.</p> This is the same coordination problem human developers face on multi-person teams. You just notice it faster when the team is four LLMs running in parallel.</p> What Actually Works</h2> I use AI for code generation daily. Here is what works:</p> Use it for tasks with clear specifications. If you can describe the desired output precisely, the model will probably generate something close. If you cannot describe what you want, the model will not guess correctly.</p> Review the output. The model will make mistakes. It will use deprecated APIs. It will skip edge cases. It will generate code that compiles but does not work. Treat it like code review from a junior developer who types fast but does not check their work.</p> Iterate on the prompt when the output is wrong. If it generates migrations with circular dependencies, tell it to output migrations in dependency order. The model does not know your requirements unless you tell it.</p> Use multiple models when the task is ambiguous. Different models have different blind spots. One model catches precision bugs in number handling. Another catches stack overflow vulnerabilities in recursive parsers. Consensus finds edge cases no single model would have caught.</p> Do not expect the model to read your mind. It cannot. It is text prediction, not telepathy.</p> The Real Problem</h2> The real problem with AI tools is that people expect them to solve problems humans have not solved yet.</p> You cannot ask an AI to follow code style if you have not documented the style. You cannot ask it to implement a feature if you have not specified what the feature should do.</p> AI does not eliminate the need for clear requirements, documentation, or code review. It amplifies the cost of not having them. If your team does not have coding standards, the AI will generate code in 47 different styles. If your project does not have tests, the AI will break things you did not know were fragile. If your specs are ambiguous, the AI will pick the wrong interpretation.</p> This is not the AI's fault. This is your fault for not having standards, tests, or specs.</p> Using AI Without Losing Your Mind</h2> Here is what I do:</p> Treat AI as a tool, not a coworker. It does not understand context. It does not remember what you said three prompts ago. It does not know what you meant versus what you typed. Give it explicit instructions and check the output.</p> Use it for tasks with high certainty and low blast radius. Generating test cases? Great. Refactoring variable names? Fine. Rewriting your entire database layer? Probably not.</p> Keep humans in the loop at decision boundaries. Generate the plan, review it, then execute. Generate the code, review it, then merge. The AI can propose. You decide.</p> Do not try to keep up with every new model. Pick one that works and use it until it does not work anymore. Switching models every week is how you burn out.</p> Lower your expectations. The AI will not write production-ready code from a vague prompt. It will write something that compiles and mostly works. You fix the rest. That is still faster than writing it yourself from scratch.</p> Conclusion</h2> AI problems are human problems. Burnout from keeping up with too many tools. FOMO about missing the next breakthrough. Perfectionism about getting it exactly right. Analysis paralysis about which approach to take. Garbage in, garbage out.</p> We had these problems before AI. We will have these problems after AI. The only difference is speed. AI makes bad processes fail faster. It makes unclear requirements obvious immediately. It makes poor documentation expensive in minutes instead of months.</p> If you are struggling with AI tools, the problem is probably not the AI. The problem is that your process, documentation, or requirements were already broken. AI just made it obvious.</p> Fix the process. The AI will follow.</p> llm-mux: Why I Rebuilt Lok Unknown — Wed, 11 Feb 2026 00:00:00 +0000 Lok hit 317 cargo installs. People were using it. So naturally I rewrote it from scratch.</p> That's not as chaotic as it sounds. Lok grew organically from "query multiple LLMs" to "run workflows" to "apply edits" to "create GitHub issues." Each feature bolted onto the side. The codebase worked but the abstractions were wrong.</p> llm-mux is what lok should have been from the start.</p> What Was Wrong</h2> Lok conflates backends with tasks. When you write backend = "claude"</code> in a workflow step, you're coupling your workflow to a specific model. Want to swap Claude for Gemini? Edit every step.</p> Lok also has no concept of project context. A Rust project needs cargo test</code> for verification. A Node project needs npm test</code>. In lok, you hardcode these per-workflow. Switch projects, rewrite workflows.</p> The apply_edits feature was bolted on late. It works but there's no retry loop, no structured verification, no rollback without git-agent.</p> Roles</h2> llm-mux introduces roles. Instead of hardcoding backends:</p> # lok style - backend hardcoded [[steps]] name = "analyze" backend = "claude" prompt = "Find bugs" </code></pre> You declare what kind of task it is:</p> # llm-mux style - role-based [[steps]] name = "analyze" type = "query" role = "analyzer" prompt = "Find bugs" </code></pre> Then configure which backends handle which roles:</p> [roles.analyzer] description = "Code analysis tasks" backends = ["claude", "codex"] execution = "parallel" [roles.quick] description = "Fast local checks" backends = ["qwen"] execution = "first" </code></pre> Swapping backends is a config change, not a workflow rewrite. The workflow says "I need analysis." The config decides who does analysis.</p> Teams</h2> Teams add project context:</p> [teams.rust] description = "Rust projects" detect = ["Cargo.toml"] verify = "cargo clippy && cargo test" [teams.rust.roles.analyzer] backends = ["claude", "codex"] </code></pre> When llm-mux detects Cargo.toml</code>, it activates the rust team. Verification commands come from the team. Role mappings can be overridden per-team.</p> Same workflow, different projects, correct tooling.</p> HTTP Backends</h2> Lok only does CLI. You shell out to claude</code>, codex</code>, ollama run</code>. Each query spawns a process.</p> llm-mux supports both CLI and HTTP:</p> [backends.claude] command = "claude" args = ["-p", "--"] [backends.openai] command = "https://api.openai.com/v1" model = "gpt-4" api_key = "${OPENAI_API_KEY}" [backends.local] command = "http://localhost:11434/v1" model = "llama3" </code></pre> If the command starts with http</code>, it's HTTP. Otherwise CLI. HTTP is faster for high-volume workflows. No process overhead. Proper streaming. Rate limit handling.</p> Apply and Verify</h2> Lok's apply_edits was a boolean flag. llm-mux has a real system:</p> [[steps]] name = "fix" type = "apply" source = "steps.analyze" verify = "cargo test" verify_retries = 3 verify_retry_prompt = "Fix failed: {{ error }}. Try again." rollback_on_failure = true </code></pre> The flow:</p> Parse edits from source step</li> Apply edits</li> Run verification</li> If it fails and retries remain, show error to LLM, try again</li> If all retries fail, rollback</li> </ol> The retry loop is the difference. Instead of failing on first bad edit, llm-mux shows the error and asks for a fix. Most failures are small mistakes a second attempt catches.</p> Rollback uses git stash. No external tooling.</p> An Example</h2> The rust-audit workflow runs four parallel audits and writes structured docs:</p> llm-mux run rust-audit llm-mux run rust-audit outdir=reports/feb-audit </code></pre> Output:</p> docs/audit/ ├── README.md # Summary table ├── 01-safety.md # Memory safety ├── 02-performance.md # Perf issues ├── 03-errors.md # Error handling └── 04-idioms.md # Patterns </code></pre> Each audit is its own query step. Each saves to a file. The final step synthesizes a summary. The outdir</code> argument makes it reusable.</p> What llm-mux Is Not</h2> llm-mux is not a replacement for lok's CLI commands. There's no llm-mux ask</code> or llm-mux hunt</code>. It's purely a workflow runner.</p> If you want quick one-off queries, use lok. If you want structured multi-step pipelines with proper abstractions, use llm-mux.</p> I'm keeping both. They solve different problems.</p> What Doesn't Work Yet</h2> The template system is powerful but error messages are cryptic. A typo in a Jinja variable gives you a wall of minijinja internals.</p> HTTP backend streaming works but the progress output is ugly. You see chunks arrive but it's not as clean as the CLI backend output.</p> Team auto-detection is basic. It looks for files but doesn't understand monorepos or nested projects yet.</p> Getting Started</h2> cargo install llm-mux llm-mux doctor llm-mux run rust-audit </code></pre> Config goes in ~/.config/llm-mux/config.toml</code>. Workflows go in .llm-mux/workflows/</code> or ~/.config/llm-mux/workflows/</code>.</p> Source at github.com/ducks/llm-mux</a>.</p> Lok was the prototype. llm-mux is the product. The 317 people using lok helped me figure out what the abstractions should be.</p> finna: Multi-Model Debate, Spec, and Implement Unknown — Tue, 10 Feb 2026 00:00:00 +0000 Lok's spec</code> command was useful but felt too coupled to the rest of the tool. I wanted something standalone: give it an idea, get specs and code. No configuration files, no backend setup, just a single binary that orchestrates the models I already have installed.</p> That's finna.</p> The Problem with "Just Build It"</h2> When you ask an LLM to build something, it starts coding immediately. Maybe it picks a good architecture, maybe it doesn't. By the time you see the output, you're committed to whatever approach it chose. If the foundation is wrong, you're either refactoring generated code or starting over.</p> The fix is to separate planning from execution. But not just any planning. A plan that multiple models have debated and agreed on, written down in files you can review before any code gets generated.</p> The Pipeline</h2> finna runs four stages:</p> idea → debate → roadmap → spec → implement </code></pre> Debate</strong>: Claude, Codex, and Gemini independently analyze the idea</li> Consensus</strong>: Claude synthesizes the proposals into a unified approach</li> Roadmap</strong>: Break the consensus into ordered, dependency-aware steps</li> Spec</strong>: Write detailed implementation specs for each step</li> Implement</strong>: Models propose edits, Claude synthesizes, changes applied</li> </ol> Each stage reads from the previous stage's output. Everything lands in .finna/</code> so you can review, edit, or re-run individual stages.</p> Usage</h2> # Run all stages finna "Add JWT authentication to the API" # Or run stages separately finna debate "Add JWT authentication" # debate → roadmap finna spec # roadmap → specs finna implement # specs → code # Target specific steps finna spec --step auth-middleware finna implement --step auth-middleware </code></pre> A Real Example: TOML Parser</h2> I ran finna on building a TOML parser from scratch:</p> finna debate "write a toml parser in rust from scratch, no dependencies" </code></pre> Three models debated the architecture. They converged on a lexer-first approach with recursive descent parsing. The roadmap came out as 30 steps with proper dependency ordering:</p> .finna/ ├── consensus.json ├── roadmap.arf └── specs/ ├── 01-project-scaffold/spec.arf ├── 02-error-types/spec.arf ├── 03-token-types/spec.arf ... ├── 16-lexer-integration/spec.arf ├── 17-parser-core/spec.arf ... └── 30-edge-cases/spec.arf </code></pre> The roadmap groups work into phases: scaffold and types (1-5), lexer (6-16), parser (17-25), public API and tests (26-30). Each step declares its dependencies so they can't run out of order.</p> Running finna spec</code> generates detailed ARF specs for each step. Here's the spec for lexing basic strings:</p> order = 10 what = "Implement lexing for double-quoted basic strings with full escape support" why = "Basic strings are TOML's primary string format. The lexer must process escapes at lex time and detect unterminated strings with precise error locations." how = """ 1. Add lex_basic_string() method 2. Main loop: consume until closing quote or error 3. Implement lex_escape_sequence() for \t, \n, \r, \\, \", \uXXXX, \UXXXXXXXX 4. Implement lex_unicode_escape() with validation 5. Wire into lex_token() dispatch 6. Add unit tests for all escape sequences and error cases """ backup = "Defer escape processing to post-lex pass if implementation is error-prone" [context] files = ["src/lexer.rs", "src/error.rs"] dependencies = [] </code></pre> The specs include test cases. The basic strings spec lists 25+ scenarios: simple strings, escape sequences, unicode handling, error conditions. The models know what to test because they debated it during planning.</p> The 30 specs totaled 2.1k lines. That's not wasted tokens. It's a contract you can review before any code exists.</p> The ARF Format</h2> Specs use TOML with a standard structure:</p> order = 1 what = "one sentence description" why = "context and motivation" how = """ Step-by-step implementation plan """ backup = "fallback approach if primary fails" [context] files = ["paths/to/files"] dependencies = ["step names this depends on"] </code></pre> The format is simple on purpose. No special tooling needed to read or edit. Any text editor works. The structure enforces that every step has a rationale, a plan, and a fallback.</p> Why Separate Stages</h2> The stages are separate because you need intervention points.</p> After debate, review the roadmap. Does the architecture make sense? Are the steps in the right order? Edit .finna/roadmap.arf</code> if not.</p> After spec, review the specs. Is the implementation plan correct? Are the test cases comprehensive? Edit the spec files or re-run finna spec --step X</code>.</p> After implement, review the changes. Did the edits apply cleanly? Is the code what you expected? The specs told you what would happen; now verify it did.</p> If you run finna "idea"</code> without the subcommands, it runs all stages in sequence. That's fine for exploration. But for real work, you probably want the review gates.</p> Multi-Model Consensus</h2> The debate phase isn't just asking three models and picking one. All three responses get synthesized:</p> Claude, Codex, and Gemini each propose an approach in parallel</li> Claude sees all three proposals and synthesizes consensus</li> Disagreements become explicit tradeoffs in the final plan</li> </ol> One model might over-engineer authentication. Another might skip edge cases. The synthesis catches both failure modes. You get architecture that multiple models have pressure-tested.</p> Implementation</h2> finna is ~500 lines of Rust. It shells out to claude</code>, codex</code>, and npx @google/gemini-cli</code> for the actual model calls. No API keys in the binary, no config files. If you have the CLIs installed, finna works.</p> The implementation phase runs models in parallel for each step, synthesizes their edit proposals, and applies the changes. Edits are JSON with path</code>, old</code>, and new</code> fields. Simple find-and-replace, no AST manipulation.</p> #[derive(Debug, serde::Deserialize)] struct Edit { path: String, old: String, new: String, } </code></pre> If an edit can't find the target text, it warns and continues. If the file doesn't exist, it creates it. The implementation is deliberately simple because the specs already contain the complexity.</p> What finna Is Not</h2> finna is not a replacement for writing code. It's a planning tool that happens to also generate code. The value is in the specs, not the implementation.</p> If the generated code is wrong, you fix the spec and re-run. If the architecture is wrong, you fix the roadmap and re-spec. The code is a side effect of getting the plan right.</p> finna is also not trying to be general-purpose. It solves one problem: turn an idea into a structured plan with implementation. No plugins, no extensibility, no configuration. One tool, one job.</p> Getting Started</h2> # Clone and build git clone https://github.com/ducks/finna cd finna nix-shell cargo build --release # Run on your idea ./target/release/finna "your idea here" </code></pre> Requires claude</code>, codex</code>, and npx @google/gemini-cli</code> to be installed and authenticated. If a model fails, finna continues with the others.</p> The source is at github.com/ducks/finna</a>.</p> The test project (TOML parser specs) is at github.com/ducks/finna-toml-parser</a>.</p> Building a JSON Parser with Multi-LLM Orchestration (Part 1) Unknown — Sat, 07 Feb 2026 00:00:00 +0000 I've been building lok, a multi-LLM orchestration tool, and I wanted to put it through its paces on a real project. What better than a JSON parser? It's a classic learning project with enough nuance to surface interesting design decisions.</p> Here's the premise: instead of just diving into code, what if I let multiple LLMs debate the design first? Then synthesize their consensus into specs. Then have them collaboratively implement it.</p> The Setup</h2> I started with a simple question:</p> lok debate "We want to write a JSON parser from scratch as a learning project. Debate: What language should we use? What features should it support? What should the architecture look like?" </code></pre> Four models participated: Claude, Codex (GPT-5.2), Gemini, and Qwen 3 Coder (running locally via Ollama).</p> Round 1: Surprising Agreement</h2> All four converged on Rust. The reasoning varied:</p> Claude</strong> focused on the learning angle: "Forces you to think about ownership and memory layout. You'll learn more writing a parser in Rust than in Python/JS where you can be sloppy."</p> Codex</strong> got practical: "Ownership semantics force you to think about buffer management. Result<T, E></code> makes error handling explicit."</p> Gemini</strong> went for performance: "Zero-cost abstractions mean clean code compiles to efficient machine code."</p> Qwen</strong> hit safety: "Enums with exhaustive matching prevent invalid parser states."</p> On architecture, unanimous: lexer + recursive descent parser. No surprises there.</p> Round 2: The Interesting Bits</h2> Numbers sparked actual debate. The naive approach stores JSON numbers as f64</code>:</p> Number(f64) // Simple but WRONG </code></pre> Codex caught it: "Treating numbers as f64 is not spec-correct. JSON allows arbitrary precision. The safest approach is storing the original string."</p> Number(&'a str) // Preserves original, validates grammar </code></pre> This is why multi-model debate works. I might have defaulted to f64 and hit precision bugs later.</p> Another good catch from Gemini: recursive descent needs depth limits. Without them, an adversarial input like [[[[[[[[...</code> blows the stack. Simple fix, easy to forget.</p> The Consensus</h2> After three rounds, the models settled on:</p> Language</strong>: Rust</li> Architecture</strong>: Lexer (iterator-based) + Recursive Descent Parser</li> Number handling</strong>: Store as string, not f64</li> Zero-copy</strong>: Use Cow<'a, str></code> where possible</li> Safety</strong>: Configurable depth limits</li> Features</strong>: RFC 8259 strict first, extensions later</li> </ol> Generating Specs</h2> With design decisions locked, I fed the debate conclusions into lok spec</code>:</p> lok spec "Build a JSON parser in Rust with these design decisions: - Lexer + Recursive Descent Parser - Numbers stored as string, not f64 - Zero-copy with Cow<'a, str> - Depth limits for safety - RFC 8259 strict compliance" </code></pre> This queries multiple backends, synthesizes a consensus roadmap, then breaks each step into subtasks. The output:</p> .arf/specs/ roadmap.arf 01-core_types/ (5 subtasks) - Span, Error, Token, Value 02-lexer/ (5 subtasks) - Iterator-based tokenizer 03-parser/ (4 subtasks) - Recursive descent 04-number_validation/ (2 subtasks) - RFC 8259 number format 05-error_reporting/ (4 subtasks) - Line/column errors 06-test_suite/ (3 subtasks) - JSONTestSuite compliance 07-extension_hooks/ (4 subtasks) - Future comments/trailing commas </code></pre> Each subtask is an .arf</code> file (Agent Reasoning Format) with structured fields:</p> order = 1 what = "Core Lexer struct implementing Iterator over tokens" file = "src/lexer/lexer.rs" why = "Main lexing logic that transforms input bytes into token stream" how = """ Struct Lexer<'a> with input: &'a str, pos: usize. Implement Iterator<Item = Result<Token<'a>, LexError>>. Dispatch on current byte: punctuation returns immediately, keywords verify literals, strings handle escapes, numbers capture as slice. """ [context] inputs = "Raw JSON string" outputs = "Stream of Token results" </code></pre> These specs become the contract for implementation.</p> What Multi-Model Debate Surfaces</h2> Edge cases no single model catches.</strong> The f64 precision issue came from Codex. The depth limit vulnerability came from Gemini. Each model has blind spots. Claude focused on educational value, Codex on spec correctness, Gemini on performance, Qwen on safety.</p> Consensus beats any single model.</strong> Not because the average is smarter, but because different models catch different things. Three rounds of debate with four models surfaced issues I'd have hit weeks into implementation.</p> What's Next</h2> Part 2 will cover lok implement</code>, which takes these specs and:</p> Queries multiple backends in parallel for each subtask</li> Synthesizes consensus code from the proposals</li> Writes the file and verifies it compiles</li> Commits each file with an atomic git commit</li> Records structured reasoning traces (ARF) alongside the code</li> </ol> The implementation phase is where things get interesting. Backends disagree on details, synthesis has to resolve conflicts, and verification catches when the generated code doesn't actually compile.</p> Stay tuned.</p> Lok Part 5: Multi-Agent Planning with lok spec Unknown — Fri, 06 Feb 2026 00:00:00 +0000 The hardest part of building software isn't writing code. It's figuring out what to build and in what order. LLMs are great at generating code, but they're also great at generating the wrong code because they started implementing before thinking through the structure.</p> That's what lok spec</code> solves.</p> This post describes the shape of the system: how lok structures planning, what guarantees the spec format provides, and why separation between planner and executor matters. The implementation of the executor (agents actually writing code) is not covered here. This is about constraints and contracts.</p> What Lok is not</h2> Before going further:</p> Not a chatbot framework or conversational interface</li> Not a marketplace or plugin system for third-party agents</li> Not trying to replace developers with automation</li> </ul> Lok is a planner that structures work and an executor that requires explicit human approval at every phase boundary. The design assumes humans review specs, trigger execution, and validate results.</p> The Problem with "Just Build It"</h2> When you give an LLM a big task like "build a C compiler," it starts coding immediately. Maybe it picks the lexer first, maybe the parser. Maybe it designs types that won't work for later phases. By the time you realize the architecture is wrong, you've burned tokens and time.</p> The fix is obvious in retrospect: plan before you build. But not just any plan. A plan that multiple models have debated and converged on.</p> Propose, Refine, Pick</h2> lok spec</code> uses a three-step process:</p> Propose</strong>: All backends generate roadmaps in parallel</li> Refine</strong>: Synthesize roadmaps into a consensus plan</li> Pick</strong>: Generate detailed specs from the consensus</li> </ol> This is the same pattern as debate mode, but applied to planning instead of analysis. Each backend proposes how they'd structure the project. Then we synthesize the best ideas and resolve contradictions. Finally, we generate specs that capture the agreed approach.</p> lok spec "Build a C compiler in Rust. Take C source as input, produce x86-64 assembly output. Include lexer, parser, semantic analysis, and code generation. Focus on correctness over optimization." </code></pre> spec: Planning: Build a C compiler in Rust... spec: Step 1/3: Getting roadmaps from 4 backends... ✓ 4/4 backends responded spec: Step 2/3: Synthesizing consensus roadmap... ✓ Consensus reached spec: Step 3/3: Generating detailed specs... spec: Step 4/4: Breaking specs into subtasks... ✓ lexer → 4 subtasks ✓ ast → 5 subtasks ✓ parser → 5 subtasks ✓ semantic → 5 subtasks ✓ ir → 5 subtasks ✓ codegen → 5 subtasks ✓ driver → 4 subtasks ================================================== spec: Generated 7 specs in .arf/specs/: + roadmap.arf + 01-lexer/spec.arf + 01-lexer/01-token.arf + 01-lexer/02-cursor.arf + 01-lexer/03-scanner.arf + 01-lexer/04-keywords.arf + 02-ast/spec.arf ... </code></pre> Four backends looked at "build a C compiler" and each proposed a roadmap. Claude synthesized them into a unified plan. Then we generated specs for each step, and broke each step into subtasks (individual files).</p> The Output Structure</h2> Specs land in .arf/specs/</code> with a nested structure:</p> .arf/specs/ roadmap.arf 01-lexer/ spec.arf 01-token.arf 02-cursor.arf 03-scanner.arf 04-keywords.arf 02-ast/ spec.arf 01-types.arf 02-expr.arf ... </code></pre> The roadmap is the high-level plan. Each numbered directory is a step. Inside each step is a spec.arf</code> with the overall component spec, plus subtask files for individual pieces.</p> A spec file looks like this:</p> order = 1 what = "Build the lexer to tokenize C source code" why = "Parser needs a stream of tokens, not raw characters" how = "Hand-written scanner with keyword trie, handles preprocessor directives" backup = "Fall back to regex-based tokenizer if performance is acceptable" [context] inputs = "C source code as string or file path" outputs = "Iterator of Token structs with location info" dependencies = [] tests = "Tokenize test files, compare against expected token sequences" </code></pre> A subtask file adds a file</code> field:</p> order = 1 what = "Define token types and structures" file = "src/lexer/token.rs" why = "All other lexer components depend on token definitions" how = "Enum for token kinds, struct for token with span and value" [context] inputs = "None - foundational types" outputs = "Token enum, TokenKind enum, Span struct" tests = "Unit tests for token construction and display" </code></pre> Planning to Execution Flow</h2> Here is the minimal end-to-end for a boring but real task: refactoring Rust error handling to use thiserror</code> crate. Replace manual impl Display</code> with derive macro. Update all error construction sites.</p> lok spec "Refactor error types to use thiserror crate. Replace manual Display impls with derive macro. Update all error construction sites." </code></pre> Output:</p> .arf/specs/ roadmap.arf 01-add-dependency/spec.arf 02-refactor-errors/spec.arf 02-refactor-errors/01-lexer-error.arf 02-refactor-errors/02-parser-error.arf 03-update-callsites/spec.arf </code></pre> Review the roadmap and specs. If the plan looks wrong, edit the .arf</code> files or regenerate. Once satisfied:</p> lok implement .arf/specs/ </code></pre> Agents read each spec and implement the changes directly. Each agent works on its assigned file according to the spec. The boundary between planning and execution is the review gate - you decide when to run lok implement</code> after reviewing the specs.</p> Why This Matters</h2> The spec files are ARF</a> format. That means they're structured, parseable, and auditable. When you review a spec, you're reviewing the plan before any code exists. If the approach is wrong, you catch it here, not after 10,000 lines of generated code.</p> The subtask breakdown is what enables parallel execution. Once you have specs for 01-token.arf</code>, 02-cursor.arf</code>, 03-scanner.arf</code>, and 04-keywords.arf</code>, different agents can work on different files simultaneously. They're not stepping on each other because each owns their file.</p> The pattern is recursive. lok spec</code> on a project gives you steps. Each step has subtasks. If a subtask is still too big, you could spec it again. Same process, different scale.</p> The spec format enforces three invariants:</p> Serializable plans</strong>: Every decision is written down in parseable TOML. You can diff plans, version them, replay them.</li> Attributable actions</strong>: Each spec names the file it will modify or create. No agent can touch code without a spec that declares intent.</li> Human intervention points</strong>: Spec generation is separate from execution. You review the plan before any code changes happen.</li> </ol> These are not optimizations. They are constraints that prevent the system from becoming a black box.</p> Human in the Loop by Design</h2> The separation between lok spec</code> and execution is not a temporary limitation. It is the core design. The system does not "learn" to skip human review or "graduate" to autonomous operation.</p> Every phase boundary requires explicit human approval:</p> Spec generation produces files you review before execution starts</li> Execution runs subtasks but does not merge or deploy results</li> Integration is a separate manual step</li> </ul> This is not because the LLMs are not capable enough. It is because software built by delegation requires inspection and veto power at decision boundaries. The moment you remove that, you have an agent that makes choices you cannot audit until after the damage is done.</p> Single Backend Fallback</h2> If you only have one backend configured, lok spec</code> skips the multi-model consensus and just asks that backend to plan and spec directly. You still get the structured output, just without the debate.</p> lok spec --backend claude "Build a REST API" </code></pre> The value of multi-backend consensus is catching blind spots. One model might over-engineer the auth system while another keeps it simple. Synthesis finds the middle ground. But if you're just exploring or don't have multiple backends set up, single-model works fine.</p> Token Conservation</h2> The multi-agent pattern has a cost: API calls. Four backends generating roadmaps is four API calls. Synthesis is another. Spec generation is another. Subtask generation is one per step.</p> For a 7-step project, that's roughly: 4 (roadmaps) + 1 (synthesize) + 1 (specs)</p> 7 (subtasks) = 13 API calls. Not cheap if you're using expensive models.</li> </ul> But here's the key: every backend's contribution gets used. We're not querying four models and throwing away three responses. We're synthesizing all four into something better than any single response.</p> This is the rule I've been following: if you fire off multiple agents, they must debate or synthesize. Never query N backends just to pick one.</p> What's Next</h2> The specs exist. The next step is execution: read the specs, assign agents to subtasks, run them in parallel, integrate the results. That is a bigger piece of machinery, but the foundation is here.</p> For now, lok spec</code> gives you a structured plan that multiple models have agreed on. Review it, tweak it if needed, then start building with confidence that the architecture makes sense. The system does not get smarter by hiding decisions from you. It gets more useful by making decisions inspectable.</p> The source is at github.com/ducks/lok</a>.</p> Previous: Part 4: The Self-Healing Loop</a></p> cfgs.dev: A Directory for Developer Setups Unknown — Tue, 03 Feb 2026 00:00:00 +0000 Every developer eventually builds a setup they are proud of. Not because it is perfect, but because it is earned - shaped by years of work, mistakes, migrations, and small personal decisions.</p> The problem is discovery. These hard-won configurations are scattered across GitHub repos, half-documented READMEs, gists, and blog posts. You can find them if you already know what to search for. But browsing? Exploring what tools people actually use together? That is hard.</p> cfgs.dev</a> exists to fix that gap.</p> It is not a new config system. Not a dotfile manager. Not a package manager. It is a directory - a browsable index of how developers actually work, across tools, operating systems, and philosophies.</p> Think of it like browsing other developers' desks. You can see what tools they use, how they configure them, and what their workflow looks like. Then follow the link to their actual dotfiles repo to see the details.</p> What cfgs.dev is</h2> cfgs.dev scans GitHub repos and extracts what tools people use. Not just "this repo has Neovim" but "this repo uses Neovim with lazy.nvim, gruvbox, lualine, telescope, and nvim-cmp."</p> An entry is simple: a username, a link to the dotfiles repo, and a structured breakdown of what the scanner found. Anyone can submit any public repo - the owner can later claim it by logging in. You can browse by category (editors, terminals, window managers) or by specific tool. Want to see how people configure Hyprland? There's a page for that.</p> The detection is declarative. Each tool has a JSON config that specifies file patterns to match and content to extract:</p> { "name": "Neovim", "patterns": ["nvim/init.lua", ".config/nvim/*/.lua"], "contentFlags": { "pluginManager": { "lazy.nvim": ["lazy.nvim", "folke/lazy"], "packer": ["packer.nvim", "wbthomason/packer"] }, "theme": { "gruvbox": ["gruvbox"], "tokyonight": ["tokyonight"] } } } </code></pre> When the scanner finds a matching file, it checks the content for these patterns. First match wins per category. The result is a structured view of what the config actually contains.</p> Deep Detection</h2> The latest version goes deeper on Neovim specifically. It now detects 14 categories of config details:</p> Distribution (LazyVim, AstroNvim, NvChad)</li> Plugin manager (lazy.nvim, packer, vim-plug)</li> LSP setup (nvim-lspconfig, coc.nvim)</li> Completion (nvim-cmp, coq, deoplete)</li> Statusline (lualine, lightline, airline)</li> File explorer (nvim-tree, neo-tree, oil.nvim)</li> Fuzzy finder (telescope, fzf-lua)</li> Theme (gruvbox, tokyonight, catppuccin, etc.)</li> And more</li> </ul> The tricky part was handling multi-file configs. A typical Neovim setup has init.lua</code> that just requires other files, with the actual plugin configs in lua/plugins/.lua</code>. The scanner now merges details from all matching files instead of stopping at the first match.</p> Badges</h2> You can embed your setup in your README:</p> ![setup](https://cfgs.dev/api/badge/yourusername) </code></pre> This returns a shields.io style badge showing your top tools. There are options for filtering by category and changing the style.</p> What cfgs.dev is not</h2> Not a dotfile manager (use chezmoi, Stow, dotter, or bare git repos)</li> Not a package manager (use Nix, Homebrew, or your distro's package manager)</li> Not enforcing standards or best practices (your config, your choices)</li> Not replacing existing tools (it points to them, does not replace them)</li> </ul> What Works</h2> The declarative detector system is nice. Adding a new tool is just appending to a JSON file. No TypeScript, no build step, no tests to write. The refactor from code-based detectors to config-based ones removed 455 lines.</p> Browse-by-tool is useful for discovery. Instead of searching through random repos, you can see "here are 47 people using Helix" and look at their configs.</p> What Doesn't</h2> Scanning requires cloning repos locally, which takes time. A shallow clone of a typical dotfiles repo is fast, but large repos or slow connections can timeout. I cache scan results so subsequent visits are instant.</p> Detection accuracy varies. Simple tools are easy (if kitty.conf</code> exists, they use Kitty). Complex tools with many config locations are harder. Neovim alone has like 6 different places people put their config.</p> The data model is flat right now. There's no way to express relationships like "this person switched from packer to lazy.nvim" or "these configs are forks of each other." That might be interesting but it is a lot more complexity.</p> What's Next</h2> Multi-tool filtering. Right now you can browse by single tool, but "show me users with both Neovim and Kitty" isn't possible yet.</p> Similar setups. If you use Neovim with these 5 plugins, here are other people with similar configs. This requires some fuzzy matching logic but the data is there.</p> Better search. Right now it's browse-only. Being able to search by tool combinations, categories, or specific plugins would be useful.</p> If you have a dotfiles repo, add it. Anyone can submit any public dotfile repo - no login required. Paste the URL and the scanner does the rest. If you are the owner, you can log in with GitHub to claim your entry and update it later. The more setups in the index, the more useful it becomes as a living map of real developer workflows.</p> cfgs.dev</a> \| GitHub</a></p> ARF: Structured Reasoning for AI Agents Unknown — Mon, 02 Feb 2026 00:00:00 +0000 The Problem with Prompts</h3> The deeper I get into building with LLMs, the more I realize the "chat prompt" model works but could be better.</p> When you give an agent an unstructured prompt, it runs with it. Sometimes brilliantly. Sometimes it hallucinates a photographer named "Chris Lawton" because it couldn't parse a webpage and decided to make something up instead of saying "I don't know." The lack of structure means the agent decides what matters, what to skip, and what to invent.</p> This is fine for casual Q&A. It falls apart when you're building tools that need to be auditable, reviewable, or predictable.</p> From lok to ARF</h3> I've been building lok</a>, an LLM orchestration tool that runs multi-step workflows across different backends. One thing became clear: the more structure I added, the better the results.</p> Workflows with explicit steps, defined inputs, and expected outputs work. Workflows that just say "figure it out" produce garbage as often as gold.</p> This led to a question: what if we standardized how agents communicate their reasoning? Not just "here's my answer" but "here's what I'm doing, why I'm doing it, how I plan to do it, and what I'll do if it fails."</p> The result is ARF (Agent Reasoning Format), a simple spec for structured agent reasoning.</p> The Format</h3> ARF records are TOML files with required and optional fields:</p> what = "Add retry logic to API client" why = "Transient failures causing user-visible errors" how = "Exponential backoff with 3 retries, circuit breaker after 5 failures" backup = "Revert to synchronous error handling if latency increases" timestamp = "2026-02-02T15:14:32Z" commit = "8ae882e6" </code></pre> Two fields are required:</p> what</strong>: The concrete action being taken</li> why</strong>: The reasoning behind the approach</li> </ul> Two fields are recommended:</p> how</strong>: Implementation details</li> backup</strong>: Rollback plan if it fails</li> </ul> The backup field is the interesting one. Forcing agents to declare a rollback plan before acting means they have to think about failure modes. It's the difference between "I'll refactor this function" and "I'll refactor this function, and if tests fail I'll revert to the original implementation."</p> Storage: Orphan Branches</h3> ARF records need to live somewhere. The options were:</p> Git notes (invisible, sync friction)</li> Nested repo (coordination overhead)</li> Orphan branch (separate history, same repo)</li> </ol> I ran a lok debate</a> across four LLM backends to evaluate the tradeoffs. All four converged on orphan branches.</p> The approach uses git worktrees to mount an orphan branch at .arf/</code>:</p> your-repo/ ├── .arf/ # Mounted worktree (arf branch) │ └── records/ │ └── 8ae882e6/ # Records by commit SHA │ └── claude-20260202-151432.toml ├── .git/ └── src/ </code></pre> Records are organized by commit SHA. When you record reasoning, it links to the commit you're working on. The .arf/</code> directory is gitignored from the main branch but has its own history on the orphan branch.</p> This keeps reasoning history completely separate from code history. You can push, pull, and sync reasoning records without touching your main branch.</p> The CLI</h3> The reference implementation is a Rust CLI:</p> # Initialize ARF tracking arf init # Record reasoning for current work arf record --what "Add graph command" \ --why "Need unified view of git history with reasoning" # View reasoning log arf log # Combined visualization arf graph </code></pre> The arf graph</code> command shows git commits alongside their reasoning records:</p> Git + ARF History: ├─● 8ae882e Add diff command with ARF reasoning context │ └─ what: Add diff command │ why: Combine git diff with ARF reasoning for full context review │ how: Shows reasoning header then git show output ├─● 5604413 Add graph command for unified git+arf visualization │ └─ what: Add graph command │ why: User requested visualization combining git commits with reasoning │ how: Matches commit SHAs to .arf/records/ directories ├─● 8ec6c98 Add ARF CLI reference implementation │ └─ what: Implement ARF CLI v0.1 │ why: Need reference implementation for spec │ how: Rust CLI with init/record/log/sync commands └─● 3384a83 Initial ARF spec v0.1 </code></pre> The arf diff</code> command shows a single commit with reasoning context:</p> ═══════════════════════════════════════════════════════════════ Commit: 8ae882e Add diff command with ARF reasoning context ═══════════════════════════════════════════════════════════════ REASONING: what: Add diff command why: Combine git diff with ARF reasoning for full context review how: Shows reasoning header then git show output ─────────────────────────────────────────────────────────────── CHANGES: src/main.rs \| 118 +++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) </code></pre> This is "review the reasoning, not just the diff."</p> Why This Matters</h3> The shift happening in AI tooling is from unstructured to structured. Chat interfaces are training wheels. Production systems need:</p> Declared intent</strong>: What are you trying to do?</li> Explicit reasoning</strong>: Why this approach?</li> Failure planning</strong>: What if it breaks?</li> Audit trails</strong>: What happened and why?</li> </ul> ARF is one piece of this. It's not a replacement for git commit messages or PR descriptions. It's a parallel track for capturing reasoning that doesn't belong in code history but shouldn't be lost.</p> When an agent makes a change, the diff shows what changed. The ARF record shows why that approach was chosen over alternatives, what tradeoffs were considered, and what the rollback plan is.</p> Using It</h3> The spec and CLI are on GitHub: github.com/ducks/arf</a></p> Install with Cargo:</p> cargo install --git https://github.com/ducks/arf </code></pre> The format is intentionally minimal. Four fields, two required. Easy to generate, easy to parse, easy to extend.</p> If you're building agent tooling and want structured reasoning, try it out.</p> I Built a Robot to Help Me Understand People Unknown — Sat, 31 Jan 2026 00:00:00 +0000 I am good with machines and bad with people.</p> This is not false modesty. I can trace a request through twelve microservices and find the one misconfigured timeout. I can read a stack trace and know which library is lying. I can debug race conditions that only happen on Tuesdays.</p> But ask me to read a room? To pick up on what someone is really saying in a meeting? To notice when a coworker is frustrated before they explicitly say so? That is where I struggle.</p> Writing Is Easier</h2> I do better with written communication. Forum posts, Slack messages, pull request descriptions. When people write, they leave a trail I can actually follow. I can re-read it. I can search it. I can take my time.</p> In person, the signal moves too fast. By the time I have processed what someone said, we have moved on. I miss the subtext because I am still working on the text.</p> This is probably why I ended up in infrastructure. Machines do not have subtext. A 502 error is a 502 error.</p> Graham Duncan's Question</h2> A coworker recently wrote about Graham Duncan's framework for evaluating people. I had never heard of it, so I did some research. Duncan is an investor known for his approach to assessing people. His core question is:</p> "What's going on here, with this human?"</p> Not "are they qualified?" or "do they have the right experience?" but something deeper. What patterns show up in how they communicate? What do they care about? How do they handle disagreement? What are they not saying?</p> Duncan's framework breaks this down into dimensions:</p> Self-awareness and blind spots</li> Hidden motivations and fears</li> How they respond to stress and uncertainty</li> Contextual fit (right person, wrong role?)</li> </ul> I realized this is exactly what I struggle to do in real-time with coworkers. But what if I could do it asynchronously, with written artifacts, with a machine's help?</p> The Data Is Already There</h2> At Discourse, we use our own product internally. Years of forum posts, technical discussions, weekly updates, casual banter. A written record of how people think, communicate, and collaborate.</p> This is the kind of data I can actually work with.</p> So I built a tool. It pulls someone's forum activity, reads through their posts, and generates a structured evaluation. Communication style. Areas of expertise. How they handle disagreement. Patterns that emerge over time.</p> It is not a replacement for actually talking to people. But it gives me a starting point. A cheat sheet for understanding someone before I walk into a 1:1 or try to give feedback.</p> What It Actually Produces</h2> The output is a structured report:</p> Executive summary (what stands out about this person?)</li> Core strengths with evidence from actual posts</li> Growth areas, framed constructively</li> Communication profile (tone, clarity, patterns)</li> Collaboration dynamics (how do they work with others?)</li> Representative quotes that capture their voice</li> Discussion prompts for 1:1s</li> </ul> That last section is the most useful for me. Specific questions I can ask based on what someone has actually written about. Not generic "how's it going?" but "you mentioned being frustrated with X last month, how's that going?"</p> The Uncomfortable Part</h2> There is something uncomfortable about using a machine to understand people. It feels like cheating. Or like admitting a deficiency that maybe I should just work on directly.</p> But I have been "working on it directly" for decades and I am still bad at it. At some point you have to accept your constraints and build around them.</p> I use a calendar because I cannot remember appointments. I use a todo list because I cannot hold tasks in my head. I use version control because I cannot trust myself to not break things.</p> Why not use a tool to help me understand people?</p> Not a Replacement</h2> This does not replace actual human interaction. It is prep work. The same way you might review someone's recent commits before a code review, or skim their last few PRs before a 1:1.</p> The conversations still happen. The relationship still matters. I just show up slightly less clueless about what is going on with this human.</p> Try It</h2> The tool is open source if you want to try it:</p> claude plugin marketplace add ducks/person-eval claude plugin install person-eval@person-eval --scope user </code></pre> Then in Claude Code:</p> /person-eval username https://your-discourse-site.com </code></pre> Or with a timeframe for yearly reviews:</p> /person-eval username https://your-discourse-site.com 2025 </code></pre> It requires the discourse-mcp server to be configured, which gives Claude Code access to Discourse data.</p> The Irony</h2> The irony is not lost on me. I built a machine to help me understand humans because I understand machines better than humans.</p> But maybe that is fine. We all have different strengths. Mine happen to involve making robots do things. If I can make a robot help me be a better coworker, that seems like a reasonable trade.</p> The goal is not to replace human connection with machine analysis. The goal is to show up more prepared, more aware, more able to actually connect when the moment comes.</p> I am still bad with people. But I am getting better at compensating for it.</p> Lok Part 4: The Self-Healing Loop Unknown — Wed, 28 Jan 2026 00:00:00 +0000 Last time I showed lok finding 25 bugs in itself and creating GitHub issues automatically. Today it fixed one of those bugs, submitted a PR, and then found a real bug in Discourse that I just pushed upstream.</p> Agentic Workflows</h2> The missing piece was letting lok actually do things, not just talk about them. I added a few fields to the workflow TOML:</p> [[steps]] name = "fix" backend = "claude" apply_edits = true verify = "cargo build" prompt = """ Fix this issue. Output JSON: {"edits": [{"file": "src/main.rs", "old": "...", "new": "..."}], "summary": "..."} """ [[steps]] name = "commit" shell = "git add -A && git commit -m '{{ steps.fix.summary }}'" depends_on = ["fix"] </code></pre> Three new things:</p> shell</code> runs a command instead of querying an LLM</li> apply_edits</code> parses JSON from the LLM and patches files</li> verify</code> runs after edits to make sure they work</li> </ol> The {{ steps.fix.summary }}</code> bit extracts a field from the JSON output. You can also do {{ arg.1 }}</code> for positional arguments, so lok run fix-issue 42</code> passes 42 into the workflow.</p> Lok Fixes Itself</h2> Issue #25</a> was about a redundant Clone</code> implementation. The Delegator</code> struct already derives Clone, but there was a manual impl at the bottom of the file doing the same thing.</p> I ran the fix workflow:</p> lok run fix-issue 25 </code></pre> It analyzed the issue, generated an edit to delete the redundant impl, applied it, ran cargo build</code> to verify, committed with a message based on the fix summary, pushed the branch, and opened a PR.</p> The whole loop took maybe 30 seconds. I reviewed the diff, looked reasonable, merged it.</p> Finding Bugs in Discourse</h2> Feeling confident, I pointed lok at the main Discourse codebase:</p> lok hunt ~/discourse/discourse </code></pre> Both Codex and Claude found issues. Most were minor (confusing patterns, style things) but two stood out:</p> A chat job with a TODO saying "delete after 2025-01-01" that was still there in January 2026. Pure dead code.</p> </li> A bug in the thread serializer. It had this pattern:</p> </li> </ol> @opts[:include_thread_original_message].presence \|\| true </code></pre> The problem is .presence</code> on false</code> returns nil</code>. So if you explicitly pass include_thread_original_message: false</code>, it gets converted to nil</code>, then \|\| true</code> kicks in, and your option is ignored.</p> One controller was passing false</code> and getting true</code> back. Nobody noticed because the behavior difference is subtle, but it was definitely wrong.</p> I created two PRs: #37333</a> #37334</a></p> The Vision</h2> The pieces are coming together for a fully autonomous loop:</p> lok hunt --issues</code> finds bugs and creates GitHub issues</li> lok run fix-issue 42</code> analyzes, fixes, verifies, commits, opens PR</li> lok run review-pr 43</code> has multiple backends review the diff</li> If they agree, merge</li> </ol> Humans become exception handlers. You get pinged when the LLMs disagree or flag something they are not confident about. Otherwise the codebase quietly improves itself.</p> We are not there yet. The fix workflow needs better error recovery, the review workflow needs the debate mode integrated, and I want confidence scores on the merge decision. But the foundation is solid.</p> What's Next</h2> Honestly, I'm not 100% sure. I plan to just keep using it and adding/fixing things that I want or need. Stay tuned to see how the project evolves.</p> Next stop: unknown. But the tracks are laid.</p> Previous: Part 3: Dogfooding and Code Review</a></p> Lok Part 3: Dogfooding and Code Review Unknown — Tue, 27 Jan 2026 00:00:00 +0000 Part 2 ended with two promises: parallel workflow execution and dead code cleanup. Both happened. But the more interesting development was lok creating GitHub issues for bugs it found in itself.</p> Hunt with Issues</h2> The lok hunt</code> command scans for bugs using multiple LLM backends. The new --issues</code> flag takes it further: parse the findings and create GitHub issues automatically.</p> lok hunt --issues # Find bugs, create issues lok hunt --issues -y # Skip confirmation prompt lok hunt --issues --issue-backend gitlab # Force GitLab instead of GitHub </code></pre> The implementation auto-detects whether to use gh</code> (GitHub CLI) or glab</code> (GitLab CLI) by checking the git remote URL:</p> fn detect_from_remote(dir: &Path) -> Option<Self> { let output = Command::new("git") .args(["remote", "get-url", "origin"]) .current_dir(dir) .output() .ok()?; let url = String::from_utf8_lossy(&output.stdout).to_lowercase(); if url.contains("github.com") { Some(IssueBackend::GitHub) } else if url.contains("gitlab.com") \|\| url.contains("gitlab.") { Some(IssueBackend::GitLab) } else { // Fall back to checking which CLI is installed // ... } } </code></pre> Self-hosted GitLab instances work too (the gitlab.</code> check catches gitlab.mycompany.com</code>).</p> Lok Reviews Itself</h2> The real test: run lok hunt --issues -y</code> on the lok repository itself.</p> $ lok hunt --issues -y Task: hunt Find bugs and code issues ================================================== [errors] === CLAUDE === 1. Unchecked path canonicalization* - `src/main.rs:271` - Uses `unwrap_or_else` to silently fall back on failure - Backends expecting absolute paths may behave unexpectedly 2. Unvalidated PR URL parsing - `src/main.rs:1320-1323` - No validation that URL has enough path segments - Malformed URLs like `https://github.com/foo` will panic ... === CODEX === 1) src/cache.rs:121 — `read_to_string(...).ok()?` silently drops IO errors 2) src/workflow.rs:241 — `find(...).unwrap()` can panic on duplicate steps ... [perf] === CLAUDE === 1. O(n×m) consensus checking - `src/debate.rs:176-189` 2. Regex compiled per interpolation call - `src/workflow.rs:282-294` ... === CODEX === 1. `src/workflow.rs:89` — Linear `.find` over steps, O(n^2) with many steps 2. `src/workflow.rs:279` — Regex recompiled on every `interpolate` call ... [dead-code] === CLAUDE === 1. src/backend/mod.rs:1-9 - Bedrock module feature-gated but never enabled 2. src/cache.rs - `Cache::clear()` method defined but never called ... </code></pre> Both backends found real issues. Claude and Codex agreed on several (the regex recompilation, the O(n^2) workflow lookups) and each caught things the other missed.</p> Then the issues got created:</p> ================================================== issues: Creating GitHub issues in ducks/lok Found 25 potential issues: 1. src/cache.rs:121 — silently drops IO errors 2. src/workflow.rs:241 — find(...).unwrap() can panic 3. Regex compiled per interpolation call ... Creating issue: src/cache.rs:121... ✓ https://github.com/ducks/lok/issues/1 Creating issue: src/workflow.rs:241... ✓ https://github.com/ducks/lok/issues/2 ... Creating issue: src/spawn.rs:381-384... ✓ https://github.com/ducks/lok/issues/25 ✓ Created 25 issues </code></pre> 25 GitHub issues from a single command. The tool found bugs in itself and opened tickets to track them. Each issue body includes the full finding context and which backend reported it.</p> PR Review</h2> The lok pr</code> command reviews GitHub pull requests:</p> lok pr 123 # Current repo lok pr owner/repo#123 # Specific repo lok pr https://github.com/o/r/pull/123 # From URL </code></pre> It fetches PR metadata and diff via gh</code>, constructs a review prompt, and sends it to the configured backends. Feedback is organized by severity (critical, important, minor, nitpick).</p> The value is having it as a single command instead of copy-pasting diffs into chat windows. Run lok pr</code> on your own PRs before requesting review. It catches the obvious stuff so human reviewers can focus on architecture.</p> Explain Mode</h2> The lok explain</code> command explains codebases:</p> lok explain # Current directory lok explain /path/to/project # Specific project lok explain --focus auth # Focus on specific aspect </code></pre> It gathers context automatically: README, package manifests (Cargo.toml, package.json, etc.), and a two-level directory tree. Then asks the backend to explain purpose, architecture, key files, and entry points.</p> The --focus</code> flag is useful for large codebases. Instead of explaining everything, ask specifically about auth, database access, or API structure.</p> lok explain ~/work/discourse --focus "background jobs" </code></pre> Context Detection</h2> Part 2 mentioned false positives from lok flagging N+1 queries in codebases that use auto-eager-loading. Context detection fixes this.</p> Lok scans for framework and tooling markers before constructing prompts:</p> pub struct CodebaseContext { pub detected_language: Option<String>, pub is_rails: bool, pub has_goldiloader: bool, pub has_bullet: bool, pub has_brakeman: bool, // ... } </code></pre> When running N+1 detection on a Rails app with Goldiloader, the prompt includes:</p> Note: This codebase uses Goldiloader for automatic eager loading. Many apparent N+1 patterns may be handled automatically. Focus on cases where Goldiloader wouldn't help.</p> </blockquote> This reduced false positives significantly. Check what lok detects with:</p> lok context . </code></pre> Parallel Workflows</h2> Steps without dependencies now run in parallel:</p> [[steps]] name = "patterns" backend = "codex" prompt = "Find code patterns" [[steps]] name = "dead-code" backend = "codex" prompt = "Find dead code" # These two run in parallel (no dependencies) [[steps]] name = "synthesize" backend = "claude" depends_on = ["patterns", "dead-code"] prompt = "Combine: {{ steps.patterns.output }} {{ steps.dead-code.output }}" </code></pre> For workflows that hit multiple backends, this cuts total time significantly. A three-backend scan that took 15 seconds sequentially now takes 6 seconds.</p> Diff Review</h2> lok diff</code> reviews local changes before committing:</p> lok diff # Staged changes lok diff --unstaged # All uncommitted changes lok diff main..HEAD # Branch vs main lok diff HEAD~3 # Last 3 commits </code></pre> Same idea as PR review, but catches issues before they become PR comments.</p> The Pattern</h2> A few days in, a usage pattern has emerged:</p> Exploratory work</strong>: Let Claude Code call lok ask</code> with different backends as needed. The LLM decides when to get second opinions.</p> </li> Repeatable analysis</strong>: Define workflows in TOML. Run with lok run</code>. Parallel execution makes multi-backend scans fast.</p> </li> Code review</strong>: lok diff</code> before committing, lok pr</code> before requesting review. Catches obvious issues early.</p> </li> Bug tracking</strong>: lok hunt --issues</code> to find bugs and create tickets in one command.</p> </li> </ol> Lok isn't trying to replace your LLM session. It's a tool your LLM session can use. The orchestration intelligence stays in the conductor (Claude, GPT, whatever you're chatting with). Lok just provides the interface to multiple specialized backends.</p> What's Next</h2> Those 25 issues on the lok repo need fixing. The O(n^2) workflow lookups and regex recompilation are the most impactful. The silent error swallowing in the cache layer should probably at least log warnings.</p> The PR review could be smarter about large diffs. Right now it truncates at 50k characters. Chunking with overlap would preserve context better.</p> And the issue creation could get smarter about deduplication. Right now it dedupes by title within a single run, but doesn't check for existing open issues with similar titles.</p> The source is at github.com/ducks/lok</a>.</p> Previous: Part 2: Workflows and Local LLMs</a> \| Next: Part 4: The Self-Healing Loop</a></p> Lok Part 2: Workflows and Local LLMs Unknown — Sun, 25 Jan 2026 00:00:00 +0000 Since introducing Lok</a>, two features emerged from actual use: local LLM support via Ollama, and a declarative workflow engine. Both solve real problems I hit while using the tool.</p> Ollama: Local LLMs Without the API Tax</h2> Cloud APIs are great until they're not. Rate limits, quota exhaustion, latency spikes, privacy concerns. Sometimes you just want to run a model locally and not worry about any of that.</p> Ollama runs LLMs on your machine via a simple HTTP API. Lok now supports it as a first-class backend:</p> # ~/.config/lok/lok.toml [backends.ollama] enabled = true command = "http://localhost:11434" model = "llama3.2" </code></pre> lok ask --backend ollama "Explain this function" </code></pre> The implementation is straightforward. Ollama exposes a /api/chat</code> endpoint that accepts JSON. No CLI binary to shell out to, no stdout parsing. Just HTTP.</p> async fn chat(&self, prompt: &str) -> Result<String> { let request = ChatRequest { model: self.model.clone(), messages: vec![ChatMessage { role: "user".to_string(), content: prompt.to_string(), }], stream: false, }; let response = self.client .post(format!("{}/api/chat", self.base_url)) .json(&request) .send() .await?; // Parse response... } </code></pre> When to use Ollama:</strong></p> Privacy-sensitive codebases that can't hit external APIs</li> Avoiding rate limits during intensive analysis sessions</li> Cost control (no per-token billing)</li> Offline development environments</li> </ul> Trade-offs:</strong></p> Slower than cloud APIs on most hardware</li> Model quality depends on what you can run locally</li> Requires Ollama running as a daemon</li> </ul> In practice, I use Ollama for synthesis steps where I'm combining outputs from faster cloud models. The final summarization doesn't need to be fast, it needs to be private and reliable.</p> Workflows: Declarative Multi-Step Pipelines</h2> Single-shot LLM calls are useful, but real analysis often requires multiple passes. First a fast scan, then a deep investigation, then synthesis. Doing this manually means copy-pasting outputs between commands.</p> Workflows solve this by defining multi-step pipelines in TOML:</p> # ~/.config/lok/workflows/security-review.toml name = "security-review" description = "Multi-pass security review with synthesis" [[steps]] name = "initial-scan" backend = "codex" prompt = "Find obvious security issues: injection, auth bypass, hardcoded secrets" [[steps]] name = "deep-audit" backend = "claude" depends_on = ["initial-scan"] prompt = """ Review these findings and investigate deeper: {{ steps.initial-scan.output }} """ [[steps]] name = "synthesize" backend = "ollama" depends_on = ["initial-scan", "deep-audit"] prompt = """ Combine into a prioritized report: Initial: {{ steps.initial-scan.output }} Deep: {{ steps.deep-audit.output }} """ </code></pre> Run it with:</p> lok run security-review </code></pre> The output:</p> Running workflow: security-review Multi-pass security review with synthesis ================================================== [step] initial-scan ✓ (2.3s) [step] deep-audit ✓ (8.1s) [step] synthesize ✓ (4.2s) ================================================== Results: [OK] initial-scan (2.3s) Found 5 potential issues: 1. src/api/auth.rs:45 - SQL string interpolation ... [OK] deep-audit (8.1s) Investigated the SQL interpolation finding... ... [OK] synthesize (4.2s) ## Security Review Summary ### Critical (1) - SQL injection in auth.rs... </code></pre> Variable Interpolation</h3> The {{ steps.NAME.output }}</code> syntax passes previous step outputs into subsequent prompts. The workflow engine does a simple regex replacement before sending the prompt to the backend.</p> This is the key feature that makes workflows useful. Without it, you'd need manual copy-paste between steps. With it, you can build arbitrary pipelines where each step builds on previous results.</p> Dependency Resolution</h3> Steps declare dependencies with depends_on</code>. The engine performs a topological sort to determine execution order. Steps without dependencies can run in parallel (though the current implementation runs sequentially for simplicity).</p> [[steps]] name = "patterns" backend = "codex" prompt = "Find code patterns" [[steps]] name = "dead-code" backend = "codex" prompt = "Find dead code" [[steps]] name = "synthesize" backend = "claude" depends_on = ["patterns", "dead-code"] prompt = """ Combine findings: Patterns: {{ steps.patterns.output }} Dead code: {{ steps.dead-code.output }} """ </code></pre> The first two steps have no dependencies, so they could run concurrently. The third step waits for both to complete before running.</p> Conditional Execution</h3> Steps can include a when</code> clause for conditional execution:</p> [[steps]] name = "emergency-fix" backend = "claude" depends_on = ["scan"] when = "steps.scan.output contains 'critical'" prompt = "Propose immediate fixes for critical issues..." </code></pre> If the condition isn't met, the step is skipped with a [skip]</code> message. This keeps workflows from doing unnecessary work.</p> Workflow Discovery</h3> Workflows are loaded from two locations:</p> .lok/workflows/</code> in the current directory (project-local)</li> ~/.config/lok/workflows/</code> (global)</li> </ul> Project-local workflows override global ones with the same name. This lets you define team-wide workflows globally while allowing project-specific overrides.</p> lok workflow list </code></pre> Available workflows: security-review (global) Multi-pass security review with synthesis 3 steps code-quality (global) Multi-backend code quality analysis 3 steps rails-audit (local) Rails-specific security checks 4 steps </code></pre> The Plugin System Realization</h2> Here's the thing I didn't plan: workflows are plugins.</p> When you define a workflow, you're creating a reusable command. lok run security-review</code> isn't calling a built-in feature. It's loading a TOML file and executing it. The "plugin" is just configuration.</p> This means:</p> No compilation needed to add new capabilities</li> Share workflows by copying TOML files</li> Customize existing workflows without touching Rust code</li> Version control your workflows alongside your code</li> </ul> A future lok workflow install</code> could fetch workflows from URLs:</p> lok workflow install https://example.com/rails-audit.toml lok run rails-audit </code></pre> The plugin system is the workflow system. No separate concepts needed.</p> The Real Conductor: Your LLM Session</h2> Here's the pattern that actually works best: use your existing LLM as the conductor, and call lok as a tool.</p> I run Claude Code as my daily driver. When I need multi-model analysis, I don't switch to lok conduct</code>. I just ask Claude to use lok:</p> Me: Find performance issues in this codebase Claude: [runs: lok ask --backend codex "Find N+1 queries and performance issues"] Claude: I found 3 N+1 queries in the controllers. Let me get a second opinion on the caching strategy... Claude: [runs: lok ask --backend gemini "Review caching approach in lib/cache.rb"] Claude: Based on both analyses, here's what I'd prioritize... </code></pre> The LLM session becomes the orchestration layer. It sees results, reasons about them, decides when to query other backends. No need for lok to implement its own multi-round conversation loop.</p> This works because lok is just a command. It doesn't try to be a chat interface or maintain conversation state. It does one thing: send a prompt to backends and return results. The intelligence stays in the LLM that's already running.</p> The workflow engine complements this. For repeatable multi-step analysis, define a workflow. For exploratory work where you need to reason about intermediate results, let your LLM call lok directly.</p> Putting It Together</h2> Here's my actual workflow for auditing a new codebase:</p> Me: Audit this codebase for security issues Claude: [runs: lok run security-review] Claude: The workflow found 5 issues. The SQL interpolation in auth.rs looks serious. Let me investigate... Claude: [runs: lok ask --backend gemini "Is the SQL in auth.rs:45 exploitable?"] Claude: Gemini confirms it's exploitable. I'll draft a fix... </code></pre> Workflows handle the repeatable multi-step analysis. Claude handles the reasoning and follow-up questions. Lok is just the interface to multiple backends. Each layer does what it's good at.</p> What's Next</h2> The dead code that lok hunt</code> found in its own codebase still needs cleanup. There's also the question of parallel step execution in workflows, which would make multi-backend pipelines faster.</p> But the core loop is solid: define workflows in TOML, run them with one command, get multi-model analysis without the manual coordination tax.</p> The source is at github.com/ducks/lok</a>.</p> Previous: Introducing Lok</a> \| Next: Part 3: Dogfooding and Code Review</a></p> I Don't Type Every Word You Read Unknown — Sun, 25 Jan 2026 00:00:00 +0000 Most modern work is already mediated by machines. Writing is just late to admit it.</p> Commerical pilots rarely fly planes by hand anymore. Chip designers do not solder transistors. Photographers do not grind their own lenses. Infrastructure engineers rarely flip physical switches in a datacenter.</p> In all of these fields, the work did not disappear. It moved upstream.</p> Writing is undergoing the same shift.</p> Where the Work Actually Is</h2> I do not type every word you read here.</p> That does not mean this writing is automated, synthetic, or detached from real experience. It means the locus of effort has changed.</p> The work now lives in:</p> deciding what is worth saying</li> knowing when something is wrong</li> recognizing when a paragraph feels hollow</li> choosing what to delete</li> setting constraints</li> maintaining direction</li> </ul> The model generates text. I decide what survives.</p> That distinction matters.</p> How I Actually Write Now</h2> Most posts start the same way they always have: with a thought that will not leave me alone.</p> Sometimes it comes from building something. Sometimes from frustration. Sometimes from noticing the same pattern repeat across tools, systems, or conversations.</p> I outline roughly. I write fragments. I ask an LLM to help me move past blank-page friction, not to decide what I believe.</p> I frequently discard its output entirely.</p> I interrupt it mid-paragraph when it drifts. I reframe prompts when the tone is wrong. I delete sections that feel technically correct but experientially false.</p> The process is not faster because I think less. It is faster because I spend less time fighting inertia.</p> Delegating Friction, Not Thinking</h2> This is the part people often get backwards.</p> I am not delegating authorship. I am delegating friction.</p> The same way a pilot delegates routine control to an autopilot in order to focus on situational awareness, failure modes, and judgment.</p> Automation does not reduce responsibility. It increases expectations.</p> When something goes wrong, there is still a human in the loop. There always is.</p> Is This Still Worth Reading?</h2> That is the question people tend to circle without asking directly.</p> If a post reflects real experience, real constraints, and real judgment, I do not care which tool helped shape the sentences.</p> Authenticity does not come from keystrokes. It comes from context.</p> You can feel the difference between writing that emerged from lived systems and writing that emerged from nowhere. Tools do not erase that distinction.</p> They amplify it.</p> Writing Did Not End. It Moved.</h2> We already accept this shift everywhere else.</p> We do not demand that pilots prove their worth by flying without instruments. We do not ask engineers to manage infrastructure without automation. We do not measure photographers by how manual their camera is.</p> We judge outcomes, judgment, and reliability.</p> Writing is no different.</p> The work did not disappear. It moved.</p> And learning where it lives now is part of the craft.</p> Introducing Lok: A Local Multi-LLM Orchestration Control Plane Unknown — Sat, 24 Jan 2026 00:00:00 +0000 Large language models are getting better, but they're also getting more specialized. Some are fast and direct for pattern matching. Others are slower but excel at deep, multi-step reasoning. If you work on real codebases, you've probably felt the pain: no single model is "best" for every task, and switching between tools manually is a constant tax.</p> That's the problem Lok solves.</p> The Brain That Controls the Arms You Already Have</h2> Lok is a local orchestration layer that coordinates multiple LLM backends through one control plane. It wraps existing CLIs like OpenAI's Codex and Google's Gemini, treating them as pluggable backends with a unified interface.</p> The key insight: model choice isn't a preference anymore. It's part of the engineering workflow. When your toolchain includes multiple LLMs, you need orchestration.</p> lok hunt . # Bug hunt with smart backend selection lok audit . # Security audit lok team "analyze" # Coordinated multi-model analysis lok debate "async?" # Let the models argue lok spawn "task" # Parallel agents on subtasks </code></pre> ┌─────────────┐ │ USER │ │ (task) │ └──────┬──────┘ │ ▼ ┌──────────────────────────────────────────┐ │ CONDUCTOR (BRAIN) │ │ │ │ • Analyze task complexity │ │ • Break into parallel subtasks │ │ • Assign backends via delegator │ └──────────────────┬───────────────────────┘ │ ┌────────────────────────┼────────────────────────┐ │ │ │ ▼ ▼ ▼ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ AGENT 1 │ │ AGENT 2 │ │ AGENT 3 │ │ "frontend"│ │ "backend" │ │ "database"│ │ [CODEX] │ │ [GEMINI] │ │ [CODEX] │ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │ │ │ │ ══ PARALLEL EXECUTION ══ │ │ │ │ └────────────────────────┼────────────────────────┘ │ ▼ ┌──────────────────────────────────────────┐ │ SUMMARIZATION PHASE │ │ │ │ • Collect all agent outputs │ │ • Report success/failure per agent │ │ • Aggregate into final summary │ └──────────────────────────────────────────┘ </code></pre> Mode Comparison</h2> Mode</th> Backends Used</th> Execution</th> Use Case</th></tr></thead> smart</td> 1 (best fit)</td> Single call</td> Fast, targeted tasks</td></tr> team</td> 1-3</td> Sequential</td> Analysis + optional peer review</td></tr> debate</td> 2+</td> 3 rounds</td> High-stakes decisions</td></tr> spawn</td> 2-4</td> Parallel</td> Complex tasks with subtasks</td></tr> </tbody></table> Smart Delegation: The Right Tool for the Job</h2> Not every task requires the most expensive, reasoning-heavy model. Conversely, complex security audits shouldn't be handled by a model optimized for speed.</p> Lok's delegator (src/delegation.rs</code>) routes tasks based on keyword matching and task classification:</p> N+1 queries, code smells, dead code</strong>: fast, pattern-matching models (Codex, Claude Haiku)</li> Security audits, architecture reviews</strong>: thorough, investigative models (Gemini, o1)</li> General questions</strong>: whatever's available (first responsive backend)</li> </ul> The routing logic is straightforward: task descriptions are tokenized and matched against known patterns. If the task contains "security", "audit", "vulnerability", it routes to investigative models. If it contains "find", "search", "pattern", it routes to fast models. No ML involved - just conditional routing based on task characteristics.</p> lok smart "Find N+1 queries" # Routes to Codex lok smart "Security audit" # Routes to Gemini lok suggest "Find SQL injection" # Shows routing decision without running </code></pre> When routing fails</strong>: If the chosen backend is unavailable, Lok falls back to the next-best available backend. If all backends fail, you get a clear error message listing what's offline.</p> Debate Mode: Built-In Skepticism</h2> Single-model answers are often too confident. Debate mode turns that into a feature by making backends disagree on purpose.</p> In lok debate</code>, each backend responds in multiple rounds. They see each other's answers and can challenge them. Round 1 is initial positions. Round 2 is responses to each other's positions. Round 3 is final synthesis by a judge model that weighs all perspectives.</p> lok debate "What's the best way to handle auth?" </code></pre> How synthesis works</strong>: The judge model receives all responses with their round numbers and prompts: "Given these competing perspectives, identify points of agreement, highlight unresolved disagreements, and synthesize a final recommendation that acknowledges tradeoffs."</p> This catches two failure modes:</p> False confidence</strong>: A single model confidently recommending an antipattern</li> Blind spots</strong>: One model missing a constraint that another catches</li> </ul> The cost is 3x the API calls and 2-4x the latency. Use it for decisions where being wrong is expensive.</p> Team Mode: Coordinated Analysis</h2> Team mode combines smart delegation with optional debate. It orchestrates the backends like a small group:</p> Choose the best available backend for the task</li> If debate is enabled, ask others to review or challenge</li> Synthesize a final result</li> </ol> lok team "Analyze this codebase for issues" lok team --debate "Should we use async here?" </code></pre> This gives you both the speed of a model that's good at the task and the rigor of peer review. In practice, it feels like having a lead engineer and two reviewers that don't get tired.</p> Spawn Mode: Parallel Agent Execution</h2> Spawn takes the coordination further. Instead of routing a single task to the best backend, it breaks a complex task into parallel subtasks and runs multiple agents simultaneously.</p> lok spawn "Build a todo app with frontend and backend" </code></pre> The flow:</p> Plan</strong>: An LLM breaks the task into 2-4 independent subtasks</li> Delegate</strong>: Each subtask gets assigned to the best available backend</li> Execute</strong>: All agents run in parallel with shared context</li> Summarize</strong>: Results are collected and aggregated</li> </ol> You can also specify agents manually:</p> lok spawn "Build an app" \ --agent "api:Build REST endpoints" \ --agent "ui:Build React components" \ --agent "db:Design the schema" </code></pre> This is the conductor pattern in CLI form. A brain that plans, delegates to specialized workers, and synthesizes results. The same pattern that makes human teams effective, applied to LLM orchestration.</p> The Naming Story</h2> "Lok" has two meanings, both relevant.</p> Locomotive</strong> (Swedish/German: lokomotiv). Lok has a conduct</code> command, and the metaphor is intentional: a conductor sends trained models down the tracks. The pun on "trained" models is deliberate.</p> Sanskrit/Hindi लोक</strong> ("world" or "people"), as in Lok Sabha, the People's Assembly. Lok's philosophy is a collection of agents working together, not a single monolithic mind.</p> The name captures both the engineering (orchestration, routing, coordination) and the philosophy (collective intelligence, multiple perspectives).</p> Configuration: Encode Your Team's Knowledge</h2> Lok works out of the box, but gets more powerful with lok.toml</code>:</p> [tasks.hunt] description = "Find bugs and code issues" backends = ["codex"] prompts = [ { name = "n+1", prompt = "Search for N+1 query issues..." }, { name = "dead-code", prompt = "Find unused code..." }, ] [tasks.audit] description = "Security audit" backends = ["gemini"] prompts = [ { name = "injection", prompt = "Find SQL injection..." }, { name = "auth", prompt = "Find auth bypass..." }, ] </code></pre> This isn't just configuration. It's a way to encode your team's knowledge about which model to trust for what. Tasks become repeatable workflows, not one-off experiments.</p> Why This Matters</h2> We're moving away from the era of "Prompt Engineering" and into the era of Flow Engineering. The quality of an AI output is no longer determined solely by how clever your prompt is, but by the architecture of the workflow that processes it.</p> By formalizing these flows into a CLI tool, Lok brings determinism and reliability to AI interactions:</p> Higher signal, lower noise</strong>: Smart delegation keeps the right model on the right task</li> Built-in skepticism</strong>: Debate and team modes catch errors and broaden coverage</li> Parallel execution</strong>: Spawn mode runs multiple agents simultaneously, turning sequential workflows into concurrent ones</li> Repeatable workflows</strong>: Tasks like lok hunt</code> become part of your engineering rhythm</li> Local control plane</strong>: No hidden SaaS layer, no opaque routing. You can see and customize how it chooses backends</li> </ol> Before and After: A Real Example</h2> Without Lok:</strong></p> # Manual workflow for finding Rails performance issues $ claude "Find N+1 queries in app/controllers" # Review output, switch tools $ gemini "Are there better caching strategies?" # Manually synthesize both answers # Total time: 5-10 minutes of context switching </code></pre> With Lok:</strong></p> # Single command, automatic backend selection and synthesis $ lok team --debate "Analyze Rails app for performance issues" # Codex finds N+1 queries (fast, pattern-matching) # Gemini suggests caching strategies (thorough, investigative) # Judge model synthesizes into prioritized action items # Total time: 2 minutes, no context switching </code></pre> The value isn't just speed - it's that you get both the exhaustive pattern matching and the strategic recommendations in one pass, with built-in skepticism from debate mode catching false positives.</p> Getting Started</h2> # Check what backends you have lok doctor # Ask all backends lok ask "Find performance issues" # Let them debate lok debate "Best approach for caching?" # Smart routing lok smart "Find N+1 queries" # Parallel agents lok spawn "Build a REST API with tests" </code></pre> Lok doesn't replace your LLMs. It coordinates them. That means you keep the tools you already trust and add orchestration on top.</p> Performance characteristics</strong>: Smart routing adds ~50-100ms overhead for task classification. Debate mode runs 3 rounds sequentially, so expect 3x the single-model latency. Spawn mode runs agents in parallel, so wall-clock time is determined by the slowest agent, not the sum of all agents.</p> The source is at github.com/ducks/lok</a>. It's Rust, it's fast, and it's the brain that makes your AI arms work together.</p> Next: Part 2: Workflows and Local LLMs</a></p> How Jennifer Aniston and Friends Cost Us 377GB and Broke ext4 Hardlinks Unknown — Fri, 23 Jan 2026 00:00:00 +0000 Intro</h2> It started with backup issues. Sites with hundreds of gigabytes of uploads were running out of disk space during backup generation. One site had 600+ GB of uploads and the backup process kept dying.</p> While looking into reliable large backups, we discovered something wild in one of those sites: the actual unique content was a fraction of the reported size. They were storing the same files over and over again, each with a different filename. The duplication was absurd.</p> So we shipped an optimization. Detect duplicate files by their content hash, use hardlinks instead of downloading each copy. I wrote some new tests, they all passed, it got approved and merged. But unfortunately, a fix like this is kind of hard to actually fully test.</p> Then someone ran it on a real production backup and hit a filesystem limit I didn't know existed. The culprit? A single reaction GIF, duplicated 246,173 times.</p> The Problem</h2> Discourse has a feature called secure uploads. When a file moves between security contexts (say, from a private message to a public post), the system creates a new copy with a randomized SHA1. The original content is identical, but Discourse treats it as a new file.</p> This happens constantly with reaction GIFs and popular images. Users share them across posts, embed them in PMs, repost in different categories. Each context creates another copy.</p> This is mostly fine for normal operation. But for backups, it's a disaster.</p> One customer had 432 GB of uploads. Unique content? 26 GB. The rest was duplicates. A 16x inflation factor, all going into the backup archive.</p> The Fix</h2> The fix seemed straightforward. Discourse tracks the original content hash in original_sha1</code>. During backup:</p> Group uploads by original_sha1</code></li> Download the first file in each group</li> Create hardlinks for the duplicates</li> </ol> Hardlinks point multiple filenames to the same data on disk. GNU tar preserves them, so the archive stores the data once. Download 26 GB, archive 26 GB, everyone wins.</p> def process_upload_group(upload_group) primary = upload_group.first primary_filename = upload_path_in_archive(primary) return if !download_upload_to_file(primary, primary_filename) # Create hardlinks for all duplicates in this group upload_group.drop(1).each do \|duplicate\| duplicate_filename = upload_path_in_archive(duplicate) hardlink_or_download(primary_filename, duplicate, duplicate_filename) end end </code></pre> The hardlink_or_download</code> method falls back to downloading if the hardlink fails:</p> def hardlink_or_download(source_filename, upload_data, target_filename) FileUtils.mkdir_p(File.dirname(target_filename)) FileUtils.ln(source_filename, target_filename) # Create hardlink increment_and_log_progress(:hardlinked) rescue StandardError => ex # Fallback: download if hardlink fails log "Failed to create hardlink, downloading instead", ex download_upload_to_file(upload_data, target_filename) end </code></pre> Shipped it and got positive feedback.</p> The Limit</h2> A colleague then used the new version to run a backup on a large site. The logs looked great:</p> 53000 files processed (25 downloaded, 52975 hardlinked). Still processing... 54000 files processed (25 downloaded, 53975 hardlinked). Still processing... ... 64000 files processed (25 downloaded, 63975 hardlinked). Still processing... 65000 files processed (25 downloaded, 64975 hardlinked). Still processing... Failed to create hardlink for upload ID 482897, downloading instead Failed to create hardlink for upload ID 457497, downloading instead Failed to create hardlink for upload ID 867574, downloading instead </code></pre> At 65,000 hardlinks, it started failing. Turns out ext4 has a limit: roughly 65,000 hardlinks per inode. One file can only have 65,000 names pointing to it.</p> The fallback worked and it didn't fail completely. The backup finished. But instead of one download for all 246,173 duplicates, we got one download plus ~181,000 fallback downloads after hitting the limit.</p> Still better than 246,173 downloads. But not the win I expected.</p> The GIF</h2> So what file had 246,173 copies?</p> Upload.where(original_sha1: '27b7a62e34...').count => 246173 Upload.where(original_sha1: '27b7a62e34...').first.filesize => 1643869 </code></pre> 1.6 MB. Duplicated a quarter million times. That's 377 GB of backup bloat from a single image.</p> And then I saw what it was...</p> </p> A reaction GIF. Used constantly in posts, PMs, everywhere. Each use in a different security context creates a new copy. 246,173 copies of Rachel from Friends doing a happy dance.</p> One GIF broke the hardlink limit.</p> The Math</h2> Without deduplication: 246,173 downloads, 377 GB transferred.</p> With deduplication (hitting limit): ~4 downloads, ~6.4 MB transferred.</p> The filesystem limit turned my "download once" into "download four times." I can live with that.</p> The Fix for the Fix</h2> My first instinct was to track hardlink counts and proactively rotate before hitting the limit. But a colleague pointed out the flaw: we have no idea what filesystem is being used. ext4 has one limit, XFS another, ZFS another. Picking a magic number is fragile.</p> Better approach: let the filesystem tell us when we've hit the limit.</p> def create_hardlink(source_filename, upload_data, target_filename) FileUtils.mkdir_p(File.dirname(target_filename)) FileUtils.ln(source_filename, target_filename) source_filename rescue Errno::EMLINK # Filesystem hardlink limit reached - copy and use as new primary FileUtils.cp(source_filename, target_filename) target_filename rescue StandardError => ex download_upload_to_file(upload_data, target_filename) source_filename end </code></pre> When Errno::EMLINK</code> fires, we already have the file locally. No need to re-download. Just copy it and use the copy as the new primary for subsequent hardlinks. Works on any filesystem, no configuration needed.</p> What I Learned</h2> Filesystems have opinions. ext4's hardlink limit exists to prevent certain classes of bugs and attacks. It's not arbitrary.</p> The fallback saved the feature. Without graceful degradation, that backup would have failed entirely. Instead it completed, just slower than optimal.</p> Production always finds the edge cases. 246,000 copies of one file is absurd. But absurd things happen at scale.</p> A few concrete takeaways:</p> Test for failure modes, not just success paths. The hardlink fallback was built-in from the start, but I never expected to actually need it.</li> Optimizations that reduce work by 16x still need to handle edge cases. A 99.998% improvement with graceful degradation beats a 100% improvement that crashes.</li> Track filesystem-level constraints early. Hardlink limits, inode counts, path lengths - these are real operational boundaries, not theoretical concerns.</li> </ul> And now I know Jennifer Aniston can stress-test infrastructure.</p> Links</h2> Discourse PR #37261</a> - The backup deduplication fix</li> Discourse PR #37293</a> - The hardlink limit fix</li> </ul> The Unholy Trinity: Nix Shells, SSH Config, and Claude Code Unknown — Wed, 21 Jan 2026 00:00:00 +0000 I wrote about using Claude Code for daily development</a> a few months ago. That post was about workflow and mindset. This one is about infrastructure.</p> Turns out, the real multiplier isn't how you prompt the AI. It's what you let it touch.</p> The Problem With AI Coding Assistants</h2> Most AI coding tools work in a sandbox. They can read your code, suggest changes, maybe run a linter. But the moment you need to actually test something, build something, deploy something? You're back to copy-pasting commands.</p> "Here's how you'd run the tests" is not the same as running the tests.</p> Claude Code is different because it has shell access. It can run commands, read output, iterate. But that only matters if the environment is set up for it.</p> Nix Shells: Run Anything, Anytime</h2> Every project I work on has a shell.nix</code>. When Claude needs to run something, the command is:</p> nix-shell --run "bundle exec rspec" </code></pre> That's it. No "first install Rust nightly, then set up ALSA, then configure pkg-config paths." The shell.nix declares everything. Claude doesn't need to know how to set up a Rust audio environment. It just needs to know nix-shell</code>.</p> Here's what my shelltrax</a> shell looks like:</p> { pkgs ? import <nixpkgs> {} }: let rust-overlay = import (builtins.fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz"); pkgs' = import <nixpkgs> { overlays = [ rust-overlay ]; }; rust = pkgs'.rust-bin.nightly.latest.default; in pkgs'.mkShell { buildInputs = with pkgs'; [ rust rust-analyzer pkg-config alsa-lib openssl gcc ]; } </code></pre> Claude can run tests, build releases, check for warnings. All without me explaining how to install Rust nightly or configure audio libraries.</p> The pattern works everywhere. Rust project? nix-shell --run "cargo test"</code>. Ruby project? nix-shell --run "bundle exec rspec"</code>. Node? Same deal. The AI doesn't need to understand package managers. It just needs one command that always works.</p> SSH Config: The Revelation</h2> I've had SSH config set up for years. Host pond</code> instead of typing IPs, key-based auth, the usual. Standard stuff for anyone who manages servers.</p> Host pond HostName 199.68.196.244 User ducks IdentityFile ~/.ssh/pond_ed25519 </code></pre> What I hadn't considered: Claude can use it too.</p> I was debugging why my analytics service was down. Normally I'd open another terminal tab, SSH in, check logs, come back and describe what I found. The usual dance.</p> Instead, on a whim, I just asked Claude to check the logs. And it did.</p> ssh pond "journalctl -u goatcounter -n 50" </code></pre> It found the error, suggested the fix, and I approved the command to restart the service. I never left the conversation.</p> That was the moment it clicked. My SSH config wasn't just for me anymore. Any host I can reach, Claude can reach. Any command I can run remotely, Claude can run remotely.</p> The Combination</h2> Here's where it gets interesting. These two things compound.</p> Locally, nix-shell means Claude can build, test, and run anything in any of my projects. Remotely, SSH config means Claude can check, restart, and deploy anything on my servers.</p> The AI goes from "helpful for writing code" to "helpful for everything."</p> Example from this week: I was debugging why a webhook wasn't firing. Claude:</p> Read the local webhook handler code</li> SSH'd to the server to check the logs</li> Found the error (SSL cert issue on callback URL)</li> Suggested the fix</li> I approved, it deployed</li> SSH'd back to verify the fix worked</li> </ol> That's five context switches I didn't have to make. Five terminal tabs I didn't have to open. And I stayed focused on understanding the problem instead of typing commands.</p> What This Enables</h2> With proper setup, Claude becomes useful for:</p> Local development</strong> - Run tests, check linting, build assets. Not "here's how to run tests" but actually running them and reading the output.</p> Server management</strong> - Check service status, read logs, restart processes. Actual ops work, not just suggesting commands.</p> Debugging across boundaries</strong> - Read local code, check remote logs, correlate the two. The AI can see both sides of the problem.</p> Deployments</strong> - On my NixOS server, nixos-rebuild switch</code> is the entire deploy process. Claude can run it.</p> The Trust Question</h2> "But do you really want AI SSH'd into your production server?"</p> Fair question. My answer: it's my personal VPS running hobby projects. The worst case is I rebuild it from my NixOS config. If this were production infrastructure at work, I'd be more careful.</p> But for personal stuff? The productivity gain is massive. And honestly, Claude is less likely to rm -rf /</code> than I am after a long day.</p> Setting It Up</h2> If you want to try this:</p> 1. Create shell.nix files for your projects</strong></p> Even a minimal one helps:</p> { pkgs ? import <nixpkgs> {} }: pkgs.mkShell { buildInputs = with pkgs; [ ruby nodejs yarn ]; } </code></pre> 2. Set up SSH config with key auth</strong></p> Host myserver HostName your.ip.here User youruser IdentityFile ~/.ssh/your_key </code></pre> 3. Tell Claude about it</strong></p> In your CLAUDE.md or context file:</p> "Use nix-shell --run</code> for commands in projects with shell.nix"</li> "SSH host myserver</code> is available for server operations"</li> </ul> That's it. Now your AI assistant has actual hands instead of just a mouth.</p> The Multiplier Effect</h2> Good tools multiply your output. AI is a good tool. But AI with proper environment access? That's a different category.</p> I'm not faster because the AI writes better code. I'm faster because the AI can actually verify what it writes. It can run tests, check logs, and iterate without me being the middleman.</p> The unholy trinity: Nix makes everything reproducible. SSH makes everything reachable. Claude ties it together.</p> Set up your environment right, and AI coding assistants stop being a novelty. They become infrastructure.</p> Letting AI Pick the Project Unknown — Mon, 19 Jan 2026 00:00:00 +0000 With the rise of AI and LLMs, a common theme has been "don't let the machine do the thinking". The argument is we simply become expensive copy and pasters. And while I mostly agree, I was curious.</p> Well, I tried an experiment today. Instead of coming to Claude Code with a specific task, I asked: "Based on everything you know, what would you build? Create a repo, use whatever language you want, document it along the way."</p> No constraints. No requirements. Just: build something.</p> What It Chose</h2> Claude chose to build why</code>, a CLI tool for code archaeology. The pitch:</p> I spend so much of my time helping people understand codebases, and the hardest question is always "why was this decision made?" The answer is scattered across git blame, old PRs, commit messages, issue trackers, maybe a Slack thread somewhere that's now lost.</p> </blockquote> The tool points at a file or line range and synthesizes a narrative: who introduced this code, when, what commits modified it, what issues and PRs are referenced, what type of changes they were (bug fix, feature, security patch).</p> why app/models/user.rb --range 100-150 </code></pre> The Story ========= This code was first introduced by Jeff Atwood on 2020-05-22. The initial commit said: "Revert 'Merge branch master'" Since then, it has been modified 5 time(s): * FIX: do not send rejection emails to auto-deleted users (#12160) by Arpit Jalan Type: Bug fix * SECURITY: Limit name field length of TOTP authenticators by OsamaSayegh Type: Security </code></pre> The Process</h2> What struck me was how Claude approached it. It started by reasoning about what problems it encounters repeatedly. Not what would be cool to build, but what it genuinely wished existed.</p> Then it moved fast. Within minutes: Rust project scaffolded, git blame parsing working, commit categorization logic, GitHub API integration. It tested on its own source code, then on Discourse (a large real-world codebase I work on).</p> When I suggested adding Discourse as a context source (we use it for work discussions), it designed a pluggable trait system:</p> #[async_trait] pub trait ContextSource: Send + Sync { fn name(&self) -> &str; fn detect_references(&self, text: &str) -> Vec<Reference>; async fn fetch_reference(&self, reference: &Reference) -> Result<Option<ContextItem>>; async fn search(&self, query: &str) -> Result<Vec<ContextItem>>; fn is_available(&self) -> bool; } </code></pre> GitHub and Discourse implementations, easy to add more. The architecture emerged naturally from the feature request.</p> The Tangents</h2> We went down a few rabbit holes. I mentioned that real context often lives in Slack threads that never got linked to the code. Claude immediately saw the harder problem: semantic search across communication history, not just following explicit links.</p> It outlined what that would require: embeddings, RAG pipelines, LLM synthesis. Then it asked the right question: "Worth building? Or is this scope creep from a useful simple tool into a research project?"</p> We also briefly explored turning it into an MCP server so Claude could call it during conversations. Another good idea, but another scope expansion.</p> I kept pulling back to "what's actually useful now" and Claude adjusted. No ego about its ideas. Just: "Good call. Let me clean up and commit."</p> What I Learned</h2> A few observations from this experiment:</p> First, the AI had genuine preferences. It didn't pick something random or impressive-sounding. It picked a tool that would help it do its job better. There's something interesting about that.</p> Second, the iteration loop was fast. Feature idea to working code in minutes. Not because the code was simple, but because there was no translation layer. Claude understood what it wanted and knew how to build it.</p> Third, scope management mattered. Left unchecked, we could have spent hours on semantic search and MCP servers. The human role was less about technical direction and more about "is this the thing we're building right now?"</p> The Tool</h2> why</code> is at github.com/ducks/why</a>. Rust, MIT licensed, about 900 lines. It actually works.</p> Whether I'll use it daily, I don't know. But it exists because I asked an AI what it would build if it could build anything, and it had an answer.</p> From Bash Scripts to NixOS: Real Declarative Infrastructure on a VPS Unknown — Sun, 18 Jan 2026 00:00:00 +0000 In my previous post</a>, I described running infrastructure with systemd services and bash scripts. It worked, but the update script kept growing with edge cases.</p> # This kept getting longer safe_download() { ... } update_goatcounter() { # Download binary # Stop service # Run migrations # Start service } # Repeat for each service... </code></pre> Every service needed special handling. GoatCounter needed database migrations. Scrob had "text file busy" errors. Downloads could 404 and block everything.</p> Three weeks in, the update script was 300+ lines with \|\| true</code> scattered everywhere.</p> I wasn't managing infrastructure declaratively. I was writing imperative bash scripts to approximate declarative config.</p> The Inevitable Upgrade</h2> I already use NixOS for local development. My laptop runs it. My dev environments are nix-shell. I know how good it is for reproducibility.</p> The bash script approach was always temporary. I knew I'd migrate to NixOS eventually - I just wanted to get the services running first, understand what they needed, then declare it properly.</p> But after three weeks of bash edge cases, "eventually" became "now."</p> Creating pond-nix</h2> I created a new repo called pond-nix</code> with NixOS configuration for the same services:</p> # configuration.nix { imports = [ ./services/gitea.nix ./services/goatcounter.nix ./services/woodpecker.nix ./services/scrob.nix ./services/caddy.nix ]; networking = { hostName = "pond"; useDHCP = false; interfaces.ens3.ipv4.addresses = [{ address = "199.68.196.244"; prefixLength = 24; }]; defaultGateway = "199.68.196.1"; nameservers = [ "176.10.124.177" "176.10.124.136" ]; firewall.allowedTCPPorts = [ 22 80 443 ]; }; users.users.ducks = { isNormalUser = true; extraGroups = [ "wheel" ]; openssh.authorizedKeys.keys = [ "ssh-ed25519 AAAAC3... ducks@pond" ]; }; security.sudo.wheelNeedsPassword = false; } </code></pre> Each service gets its own module:</p> # services/goatcounter.nix { config, pkgs, ... }: { systemd.services = { goatcounter-jg = { description = "GoatCounter - stats.jakegoldsborough.com"; after = [ "network.target" ]; wantedBy = [ "multi-user.target" ]; serviceConfig = { ExecStart = "${pkgs.goatcounter}/bin/goatcounter serve -listen localhost:8081 -tls none -db sqlite+/var/lib/goatcounter-jg/goatcounter.db"; User = "goatcounter"; WorkingDirectory = "/var/lib/goatcounter-jg"; Restart = "always"; }; }; # ... other instances }; } </code></pre> No update scripts. No migrations to remember. Nix handles dependencies, service ordering, and restarts.</p> The Installation Challenge</h2> Installing NixOS on a VPS remotely is risky. Get the network config wrong and you're locked out.</p> The nixos-infect Trap</h3> My first thought was nixos-infect</code> - a script that converts an existing Linux system to NixOS in-place. Seems clever, right?</p> Maybe too clever?</p> I tried it on a fresh Arch install. The script started building, then hit an error:</p> swapon: /tmp/nixos-infect.swp: Invalid argument </code></pre> The problem:</strong> On Linux, /tmp</code> is mounted as tmpfs - a RAM-based filesystem. nixos-infect tried to create a 1GB swap file in RAM</em>. That's like trying to extend your RAM by using... RAM.</p> I patched the script to use /root/tmp</code> instead:</p> curl -o nixos-infect.sh https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect sed -i 's\|mktemp /tmp/\|mktemp /root/tmp/\|g' nixos-infect.sh mkdir -p /root/tmp NIX_CHANNEL=nixos-24.05 bash nixos-infect.sh </code></pre> This time it worked! The build completed, the system rebooted...</p> And I was locked out.</p> nixos-infect generated a config, but with no console password and broken SSH access. I could see the NixOS login screen through the console, but couldn't log in. SSH timed out.</p> Lesson learned:</strong> In-place conversions are clever until they're not. When you're remote, clever is dangerous.</p> The ISO Approach</h3> I wiped the VPS and started over with the NixOS installation ISO.</p> Step 1: Mount the ISO</strong></p> Downloaded the NixOS 25.11 minimal ISO</a> and mounted it through Fornex's control panel, then I rebooted the VPS.</p> Step 2: Set up networking</strong></p> The installer gives you a root shell with no password. But before anything else, networking:</p> # Check interface name (mine was ens3, not eth0!) ip addr # Configure static IP ip addr add 199.68.196.244/24 dev ens3 ip link set ens3 up ip route add default via 199.68.196.1 echo "nameserver 176.10.124.177" > /etc/resolv.conf # Test it ping -c 2 google.com </code></pre> Step 3: Enable SSH</strong></p> passwd root # Set a temporary password systemctl start sshd </code></pre> Now I could SSH in from my local machine and use a proper terminal instead of the janky web console.</p> Step 4: Partition the disk</strong></p> GPT with GRUB needs a BIOS boot partition:</p> parted /dev/vda -- mklabel gpt parted /dev/vda -- mkpart primary 1MB 512MB # BIOS boot parted /dev/vda -- mkpart primary 512MB 100% # Root filesystem parted /dev/vda -- set 1 bios_grub on mkfs.ext4 /dev/vda2 mount /dev/vda2 /mnt </code></pre> The first partition stays unformatted - GRUB just needs it for bootloader code.</p> Step 5: Generate and customize config</strong></p> nixos-generate-config --root /mnt nano /mnt/etc/nixos/configuration.nix </code></pre> Key settings:</p> { boot.loader.grub.enable = true; boot.loader.grub.device = "/dev/vda"; networking = { hostName = "pond"; useDHCP = false; interfaces.ens3 = { # Not eth0! ipv4.addresses = [{ address = "199.68.196.244"; prefixLength = 24; }]; }; defaultGateway = "199.68.196.1"; nameservers = [ "176.10.124.177" "176.10.124.136" ]; firewall.allowedTCPPorts = [ 22 80 443 ]; }; users.users.ducks = { isNormalUser = true; extraGroups = [ "wheel" ]; openssh.authorizedKeys.keys = [ "ssh-ed25519 AAAAC3... ducks@pond" ]; }; security.sudo.wheelNeedsPassword = false; services.openssh = { enable = true; settings = { PasswordAuthentication = false; PermitRootLogin = "prohibit-password"; }; }; } </code></pre> Step 6: Install</strong></p> nixos-install # Set root password when prompted reboot </code></pre> After reboot, unmount the ISO through the control panel.</p> Step 7: SSH in with your user</strong></p> ssh ducks@199.68.196.244 </code></pre> It worked. NixOS booted, networking was correct, SSH keys worked. No lockouts.</p> Deploying the Real Config</h2> Now that NixOS is installed, time to deploy pond-nix:</p> # Clone your config git clone https://git.jakegoldsborough.com/ducks/pond-nix.git cd pond-nix # Deploy it (automatically fetches hashes, copies files, and builds) make install </code></pre> The Makefile handles everything: fetching binary hashes for packages, copying config files to /etc/nixos/</code>, and running nixos-rebuild</code>. One command builds and activates all services: Gitea, GoatCounter, Woodpecker, Scrob, Caddy. Everything starts declaratively.</p> If something breaks:</p> sudo nixos-rebuild switch --rollback </code></pre> One command. Back to the previous working state.</p> Migrating the Data</h2> With NixOS running and services configured, time to migrate data from the old server (burrow). I wrote a migration script to handle this:</p> # scripts/migrate-from-burrow.sh #!/usr/bin/env bash # 1. Stop services on pond (avoid database corruption) ssh pond 'sudo systemctl stop scrob goatcounter-jg gitea' # 2. Back up databases from burrow ssh burrow 'sudo tar czf /tmp/goatcounter-backups.tar.gz /var/lib/goatcounter-' ssh burrow 'sudo tar czf /tmp/gitea-backup.tar.gz /var/lib/gitea' ssh burrow 'sudo -u postgres pg_dump scrob \| gzip > /tmp/scrob-db.sql.gz' # 3. Copy to local machine (keep backups!) scp burrow:/tmp/.tar.gz burrow:/tmp/.sql.gz /tmp/backups/ # 4. Copy to pond and restore scp /tmp/backups/ pond:/tmp/ ssh pond 'cd /tmp && sudo tar xzf goatcounter-backups.tar.gz -C /' ssh pond 'cd /tmp && sudo tar xzf gitea-backup.tar.gz -C /' ssh pond 'gunzip < /tmp/scrob-db.sql.gz \| sudo -u postgres psql scrob' # 5. Fix permissions ssh pond 'sudo chown -R goatcounter:goatcounter /var/lib/goatcounter-' ssh pond 'sudo chown -R gitea:gitea /var/lib/gitea' # 6. Start services ssh pond 'sudo systemctl start goatcounter-jg gitea scrob' </code></pre> Run it:</p> ./scripts/migrate-from-burrow.sh </code></pre> All data migrated: Git repositories, analytics databases, scrobble history. Everything preserved.</p> Updating DNS</h2> Final step: point DNS to the new server. I use name.com's API:</p> # scripts/update-dns.sh export NAMECOM_USERNAME="your_username" export NAMECOM_TOKEN="your_api_token" ./scripts/update-dns.sh </code></pre> The script updates specific service A records to pond's IP (199.68.196.244):</p> code.jakegoldsborough.com</code> → Gitea</li> ci.jakegoldsborough.com</code> → Woodpecker</li> stats.jakegoldsborough.com</code> → GoatCounter</li> scrob.jakegoldsborough.com</code> → Scrob API</li> ui.scrob.jakegoldsborough.com</code> → Scrob UI</li> stats.date-ver.com</code> → GoatCounter</li> stats.gnarlyvoid.com</code> → GoatCounter</li> </ul> DNS propagates in a few minutes. Test with dig</code>:</p> dig code.jakegoldsborough.com +short # 199.68.196.244 </code></pre> Once DNS updates, Caddy automatically provisions Let's Encrypt certificates for all domains. No manual cert management needed.</p> What Changed</h2> Before (burrow-systemd):</strong> - 300+ lines of bash scripts - Manual version checking - Special migration handling per service - "Text file busy" errors - Download failures blocking other updates - \|\| true</code> everywhere</p> After (pond-nix):</strong> - Declarative config in Nix - nixos-rebuild switch --upgrade</code> updates everything - Migrations run automatically (defined in service modules) - Atomic updates - One command rollback</p> Service Updates</h2> With systemd + bash:</p> sudo ./bin/update check # Check for updates sudo ./bin/update apply # Apply them # Hope nothing breaks </code></pre> With NixOS:</p> cd pond-nix git pull make install </code></pre> That's it. Pull the latest config, and the Makefile handles the rest: updating hashes, testing the config, and deploying atomically. If anything fails, the old generation still works.</p> The Tradeoff</h2> NixOS has a learning curve. Nix expressions are different from bash scripts.</p> But once you understand it, everything clicks: - System is reproducible - Updates are atomic - Rollbacks are instant - Configuration is versioned in git</p> No more "it works on my machine". The configuration is</em> the machine.</p> Was It Worth It?</h2> My update script was approaching 500 lines with safe_download()</code>, per-service migration logic, and error handling for every edge case.</p> Now it's ~500 lines of readable Nix across multiple modules. But those lines are: - Declarative - Type-checked - Composable - Reproducible</p> The difference: With bash, I was writing procedures</em>. With Nix, I'm declaring state</em>.</p> That's real declarative infrastructure.</p> Links</h2> pond-nix</a></li> nixos-infect</a></li> NixOS Manual</a></li> Previous post: Running Infrastructure with Systemd</a></li> </ul> Building Embedded Discourse Comments with Rust and WASM Unknown — Wed, 14 Jan 2026 00:00:00 +0000 I built an embedded comment widget that lets you add Discourse-powered comments to any static site with a single script tag. No iframe, no build step, just drop it in and it works.</p> <script src="https://unpkg.com/discourse-comments/dist/discourse-comments.min.js"></script> <discourse-comments discourse-url="https://forum.example.com" topic-id="123"> </discourse-comments> </code></pre> The widget fetches comments from a Discourse topic, renders them with a clean UI, and lets authenticated users post replies and like posts. All in a 725KB bundle with the WASM runtime inlined.</p> You can see the code here: discourse-comments on GitHub</a></p> Why Build This?</h2> Discourse has had an embedding feature for years, but it uses iframes. Iframes work, but they come with baggage: height management issues, styling isolation, auth cookie problems, SEO invisibility, accessibility complications. It's 2026 and we have web components, Shadow DOM, and ES modules. We can do better.</p> I wanted to see if a standalone component talking directly to Discourse's REST API could provide a cleaner experience. And I wanted an excuse to push some Rust into the browser.</p> The Stack</h2> The widget is built in three layers:</p> discourse-api-rs</a></strong> - A Rust client library for Discourse's API, compiled to WASM with wasm-bindgen</li> discourse-comments</a></strong> - A TypeScript web component that uses the WASM client</li> esbuild bundler</strong> - Inlines the WASM as base64 so the whole thing is a single file</li> </ol> The Rust layer handles HTTP requests, JSON parsing, and the OAuth flow. The TypeScript layer handles DOM rendering and user interactions. The bundler glues it together into a drop-in script.</p> The Hard Part: OAuth</h2> Getting read-only comments working was straightforward. The Discourse API is well-documented and predictable. But letting users post comments required authentication.</p> Discourse supports User API Keys, which are perfect for third-party clients. The flow works like this:</p> Generate an RSA key pair in the browser</li> Redirect to Discourse with the public key</li> User approves the app</li> Discourse encrypts an API key with the public key</li> Redirect back with the encrypted payload</li> Decrypt the payload with the private key</li> Store the API key for future requests</li> </ol> Sounds simple but there were issues.</p> The Base64 Whitespace Problem</h3> Discourse returns the encrypted payload as base64 in a query parameter. My code called atob(payload)</code> to decode it.</p> Problem: Discourse includes newlines in the base64 encoding. atob()</code> chokes on whitespace.</p> Fix: Strip whitespace first: payload.replace(/\s/g, '')</code>.</p> The RSA Padding Problem</h3> WebCrypto only supports RSA-OAEP for encryption/decryption. Discourse historically used PKCS1 padding, which WebCrypto can't handle.</p> Turns out Discourse added OAEP support in December 2025 (PR #36592). You pass padding=oaep</code> in the OAuth request and it encrypts with OAEP instead. But if your Discourse instance is older than that, you're stuck.</p> This one cost me hours of debugging before I found the version requirement.</p> The Like Button</h2> Once posting worked, adding likes was straightforward. The Discourse API has POST /post_actions</code> to like and DELETE /post_actions/:id</code> to unlike.</p> The UI shows a heart icon that toggles between outline (not liked) and filled (liked). Clicking it calls the API and updates the count. Nothing fancy, but it makes the widget feel more interactive.</p> One gotcha: you can't like your own posts. Discourse returns 403. I added a check to hide the like button on posts where yours: true</code>.</p> The Bundle</h2> Getting this to work as a single script tag required some bundler gymnastics. The WASM client needs its binary loaded somehow. Options:</p> Fetch it from a URL at runtime (requires hosting the .wasm file)</li> Inline it as base64 in the JavaScript bundle</li> </ol> I went with option 2. The esbuild plugin intercepts the WASM import, reads the binary, base64-encodes it, and injects code that decodes and instantiates it at runtime.</p> const wasmBuffer = fs.readFileSync(wasmPath); const wasmBase64 = wasmBuffer.toString('base64'); // In the bundle: const bytes = Uint8Array.from(atob(wasmBase64), c => c.charCodeAt(0)); await WebAssembly.instantiate(bytes, imports); </code></pre> This adds ~500KB to the bundle (the WASM binary), but eliminates the need for any separate file hosting. One script tag, everything works.</p> The Community Response</h2> I shared this experiment internally. The response was encouraging but also clarifying. Some on the core team pushed back on the WASM approach, preferring to stay within the existing Ember/Rails stack. Ember recently added support for rendering components to a DOM without spinning up an entire application instance, which could serve the same use case without introducing a new runtime.</p> I get it. Maintaining a Rust/WASM layer alongside an existing codebase adds complexity. But an "ever moving API target" concern feels overstated. This is a REST API with stable endpoints for fetching topics, creating posts, and liking. Compare that to AI integrations that build on LLM APIs from multiple vendors with breaking changes every few months.</p> The iframe suggestion also came up. That feels like a step backward. We have better tools now.</p> What I Learned</h2> WASM is production-ready.</strong> The toolchain (wasm-pack, wasm-bindgen) just works. Cross-compiling Rust to run in browsers isn't experimental anymore.</p> OAuth in the browser is tricky.</strong> The combination of cross-origin redirects, browser storage limitations, and encryption requirements creates a lot of edge cases. Test with real redirects, not just mocked flows.</p> Experiments spark conversations.</strong> Even if the official team goes a different direction, building a working prototype moved the discussion forward. Sometimes the value of an experiment is proving that a use case matters, not necessarily that your implementation is the right one.</p> Try It</h2> The widget works today with any Discourse instance running December 2025 or later (for the OAEP OAuth support).</p> discourse-comments on GitHub</a></li> discourse-api-rs on GitHub</a></li> npm package</a></li> </ul> Running VPS Infrastructure with Systemd Unknown — Sat, 10 Jan 2026 00:00:00 +0000 I run all my personal infrastructure on a single VPS using systemd services instead of Docker. No containers, no orchestration, just systemd units and bash scripts.</p> Why Not Docker?</h2> Docker is fine, but for a single VPS it felt like overhead. I wanted something simpler and built-in. I initially started with Docker but was constantly hitting networking issues with services communicating.</p> Systemd already handles process supervision, logging, and restarts. Why add another layer?</p> What's Running</h2> The VPS hosts:</p> Gitea</strong> - Git hosting at code.jakegoldsborough.com</li> Woodpecker CI</strong> - Continuous integration (idle for now)</li> Scrob</strong> - Music scrobbling server (see previous post</a>)</li> GoatCounter</strong> (3 instances) - Analytics for multiple sites</li> Caddy</strong> - Reverse proxy with automatic HTTPS</li> PostgreSQL</strong> - Shared database for Gitea, Woodpecker, and Scrob</li> </ul> Everything runs as dedicated system users with systemd units managing their lifecycle.</p> How It Works</h2> Caddy (reverse proxy + TLS) \| +-- code.jakegoldsborough.com -> Gitea (port 3000) +-- ci.jakegoldsborough.com -> Woodpecker (port 8000) +-- scrob.jakegoldsborough.com -> Scrob (port 3002) +-- ui.scrob.jakegoldsborough.com -> Scrob UI (static files) +-- stats.jakegoldsborough.com -> GoatCounter (port 8081) +-- stats.date-ver.com -> GoatCounter (port 8082) +-- stats.gnarlyvoid.com -> GoatCounter (port 8083) </code></pre> Each service runs as a systemd unit. Caddy handles TLS termination and proxies requests to the appropriate backend.</p> The Repository Structure</h2> The entire setup lives in a git repo called burrow-systemd</code>:</p> burrow-systemd/ ├── systemd/ # Service unit files │ ├── gitea.service │ ├── woodpecker-server.service │ ├── scrob.service │ ├── goatcounter-.service │ └── caddy.service ├── config/ # Service configurations │ ├── Caddyfile │ ├── gitea/app.ini │ ├── woodpecker/server.env │ └── scrob/scrob.env └── bin/ # Deployment scripts ├── bootstrap # Initial setup ├── deploy # Update and restart ├── update # Check and apply updates └── backup # Backup databases </code></pre> Configuration is declarative. Change a config file, commit, push, pull on the VPS, run ./bin/deploy</code>, done.</p> Bootstrap Script</h2> The bootstrap script sets up everything from scratch:</p> Installs packages (Caddy, PostgreSQL)</li> Downloads service binaries (Gitea, GoatCounter, Woodpecker)</li> Creates system users (gitea</code>, goatcounter</code>, scrob</code>, etc.)</li> Initializes PostgreSQL databases</li> Generates secure passwords and tokens</li> Copies config files from templates</li> Installs systemd service files</li> </ol> Run once on a fresh VPS:</p> sudo ./bin/bootstrap </code></pre> It generates a .env</code> file with all secrets and database passwords. This file is git-ignored and stays on the server.</p> Deploy Script</h2> The deploy script handles updates and restarts:</p> Updates configuration files (substitutes passwords from .env</code>)</li> Copies service files to /etc/systemd/system/</code></li> Reloads systemd</li> Creates databases if they don't exist</li> Enables and restarts all services</li> Checks service status</li> </ol> After changing config locally:</p> git add config/Caddyfile git commit -m "Update reverse proxy config" git push # On VPS cd ~/dev/burrow-systemd git pull sudo ./bin/deploy </code></pre> The deploy script is idempotent. Run it as many times as you want.</p> Service Updates</h2> Updates are automated via the update script. It checks GitHub releases for all services and downloads new binaries when available:</p> # Check what needs updating sudo ./bin/update check # Apply all updates sudo ./bin/update apply # Update specific service sudo ./bin/update apply gitea </code></pre> The script compares installed versions against the latest GitHub releases. If an update is available, it downloads the new binary, stops the service, replaces the binary, and restarts the service.</p> Scrob migrations run automatically on startup via sqlx::migrate!()</code>.</p> Simple and explicit.</p> Database Strategy</h2> PostgreSQL is shared across Gitea, Woodpecker, and Scrob. Each service gets its own database and user with limited permissions.</p> GoatCounter uses SQLite because each instance is independent. Three separate SQLite databases, three separate systemd units, three separate ports.</p> No database clustering, no replication, no complexity. Daily backups via cron are enough for my use case.</p> What Works</h2> Single command deployment (./bin/deploy</code>)</li> Automated binary updates (./bin/update</code>)</li> Centralized logging via journalctl</li> Automatic HTTPS via Caddy + Let's Encrypt</li> Service isolation via systemd users</li> Declarative config in git</li> Low memory footprint (no container runtime)</li> </ul> What Doesn't</h2> Can't easily move to a different host (not portable like containers)</li> Service isolation is weaker than containers</li> Harder to test locally (no docker-compose equivalent)</li> </ul> Security Model</h2> Each service runs as a dedicated system user</li> PostgreSQL only listens on localhost</li> TLS handled by Caddy (reverse proxy)</li> Secrets stored in .env</code> (git-ignored, mode 600)</li> No rate limiting (future work)</li> </ul> All services bind to localhost and are only accessible via Caddy's reverse proxy. The VPS firewall blocks everything except 80, 443, and SSH.</p> Reflections</h2> The best part is the simplicity. No Docker networking, no volume mounts, no image building. Just systemd units, config files, and bash scripts.</p> When something breaks, journalctl -u <service></code> shows exactly what went wrong. No container layers to debug.</p> The tradeoff is portability. This setup is tied to the specific VPS and filesystem layout. Migrating to a new server means running bootstrap again and restoring database backups.</p> For my use case, that's fine. I'm not running a multi-tenant SaaS. I'm hosting services for myself.</p> That's enough.</p> Links</h2> burrow-systemd</a></li> Scrob blog post</a></li> Gitea</a></li> Woodpecker CI</a></li> GoatCounter</a></li> Caddy</a></li> </ul> Building Scrob: A Self-Hosted Music Scrobbling Server Unknown — Fri, 02 Jan 2026 00:00:00 +0000 I wanted to track what music I listen to without sending that data to Last.fm. Part privacy preference, part self-hosting habit.</p> So I set up scrob</a> - a self-hosted scrobbling server that tracks my listening history and makes it shareable.</p> </p> </p> How It Works</h2> Scrob is a REST API server with a separate static UI:</p> Music Player (shelltrax, etc.) \| v [POST /scrob] with Bearer token \| v Scrob API (Axum + Rust) \| v PostgreSQL (scrobbles + users) \| v Scrob UI (static Svelte site) \| v Public profile: ui.scrob.example.com/username </code></pre> The server authenticates clients via Bearer tokens, stores scrobbles in Postgres, and serves stats via REST endpoints. The UI is a static site that fetches data from the API.</p> Public Profiles</h2> The interesting part was adding public user profiles. Like Last.fm, I wanted people to be able to share their music taste via a URL: ui.scrob.jakegoldsborough.com/username</code></p> This required:</p> New public API endpoints (/users/:username/recent</code>, /users/:username/top/artists</code>, /users/:username/top/tracks</code>)</li> Privacy controls (users are public by default, can opt-in to private)</li> URL-based routing in the Svelte app</li> </ul> The privacy model is simple: a boolean is_private</code> column in the users table. Public endpoints check the flag and return 403 if private. Users can toggle it via /settings/privacy</code>.</p> Security Model</h2> Scrob uses token-based authentication:</p> Login with username/password to get a Bearer token</li> All scrobble submissions require Authorization: Bearer <token></code></li> Tokens are stored in the database with revocation support</li> Passwords are hashed with bcrypt</li> </ul> TLS is expected to be handled by a reverse proxy (Caddy, nginx, etc.). The server itself runs over HTTP.</p> Rate limiting is not currently implemented. Future work.</p> The Stack</h2> Backend</strong>: Rust + Axum + PostgreSQL + sqlx</p> Frontend</strong>: Svelte 5 + Vite + TypeScript</p> Client</strong>: Shelltrax</a> (my terminal music player)</p> Infrastructure</strong>: Systemd services on a VPS, no Docker</p> Scrob is straightforward. It's an API server that receives scrobble data, stores it in Postgres, and serves it back via REST endpoints. The UI is a static site that shows your listening history.</p> Try It</h2> If you want to run your own scrob instance:</p> Prerequisites: Rust 1.82+, PostgreSQL 12+, reverse proxy for TLS</li> Clone repo and build: cargo build --release</code></li> Set DATABASE_URL</code> environment variable</li> Migrations run automatically on first startup via sqlx::migrate!()</code></li> Create a user with ./scripts/bootstrap.sh</code></li> Start UI (separate repo: scrob-ui) or use API directly</li> </ul> See the README</a> for full details.</p> sqlx and Offline Query Caching</h2> Scrob uses sqlx</code> for compile-time checked SQL queries. This is great for type safety but annoying for CI: you need a database to compile.</p> The solution is cargo sqlx prepare</code> which generates a .sqlx/</code> cache of query metadata. Then CI can build with SQLX_OFFLINE=true</code> without needing Postgres.</p> The problem: running cargo sqlx prepare</code> manually is tedious. You need to spin up Postgres, run migrations, prepare the cache, tear it down.</p> I automated it with a Makefile:</p> prepare: @docker run postgres:16-alpine (port 5433) @Wait for postgres @cargo sqlx migrate run @cargo sqlx prepare @docker rm postgres </code></pre> Now make prepare</code> handles everything. One command, query cache updated.</p> Dev Tooling</h3> The prepare target must be rerun whenever you:</p> Add or modify SQL queries in the codebase</li> Create new migrations</li> Change database schema</li> </ul> Without updating .sqlx/</code>, CI builds fail with query verification errors. The cache is committed to git, so offline builds work without a live database connection.</p> Deployment</h2> The deployment setup is declarative:</p> Migrations live in the scrob repo</li> On startup, scrob automatically detects and runs new migrations via sqlx::migrate!()</code></li> The deploy script checks GitHub releases for new versions and only downloads if there's an update</li> Systemd restarts the service after updating the binary</li> </ul> No manual migration management. No separate migration runner. Single source of truth.</p> What Works</h2> Scrobbling from Shelltrax to the API</li> Public profile pages with recent scrobbles and top stats</li> Privacy toggle (public by default, opt-in private)</li> Automated migrations on startup</li> Version-aware deployment script</li> </ul> What Doesn't</h2> No album stats yet (just artists and tracks)</li> No client/player tracking (can't tell if you scrobbled from Shelltrax vs another client)</li> Limited metadata (no album art, genre tags, etc.)</li> UI is functional but basic</li> </ul> Reflections</h2> The best part of this project was the deployment automation. The make prepare</code> command and the version-checking deploy script make updates trivial. Push a tag, wait for CI, run sudo ./bin/deploy</code>, done.</p> Scrob isn't trying to compete with Last.fm's features... yet. It's a simple, self-hosted alternative that does one thing: tracks what you listen to and makes it shareable.</p> That's enough for now.</p> Links</h2> scrob (backend)</a></li> scrob-ui (frontend)</a></li> My public profile</a></li> </ul> 2025 - A Review Unknown — Wed, 31 Dec 2025 00:00:00 +0000 2025 Yearly Recap</h1> A Year of Building, Shipping, and Showing the Work</h2> 2025 was the year things stopped being ideas in progress and started becoming systems with gravity. Across code, writing, travel, and creative work, the through-line was consistency: small, composable pieces that add up to something durable.</p> The pace was intentional. Ship in public. Measure lightly. Let curiosity decide what compounds.</p> Open Source and Engineering</h2> This was a deeply technical year, but not driven by framework churn. It was about foundations.</p> Continued deep investment in Rust, especially for CLI and TUI tooling</li> Multiple self-authored tools reached real usability: Static resume generation</li> Budgeting and finance tooling</li> Audio and scrobbling infrastructure</li> </ul> </li> Strong preference for: Plain data formats</li> Deterministic builds</li> Git as a source of truth</li> </ul> </li> Clear move away from "just ship JSON" toward intentional data modeling</li> </ul> Alongside that:</p> Declarative systems (NixOS, Docker Compose, reproducible infra)</li> CLI-first design, with UI as a layer rather than a dependency</li> Energy-aware and sustainability-minded technical choices</li> </ul> A recurring pattern this year: build tools you actually want to use, then refine them until they feel obvious.</p> Writing, Blogging, and Metrics</h2> In 2025, the blog stopped feeling like a side project and started acting like a signal.</p> Consistent long-form technical writing</li> Multi-part series and deep dives</li> Willingness to publish unfinished thinking and iterate publicly</li> </ul> The results were quiet but meaningful:</p> Organic traffic from multiple search engines</li> Readers arriving via GitHub, chat tools, and RSS</li> Early signs of compounding interest rather than spikes</li> </ul> Metrics stayed in their place: feedback, not validation.</p> Travel and Perspective Shifts</h2> Travel this year was less about movement and more about recalibration.</p> Time spent in Europe, especially Central Europe, reinforced:</p> A preference for walkable cities</li> Public transit that works</li> Slower, more deliberate daily rhythms</li> </ul> It also sharpened longer-term thinking around relocation, digital-nomad feasibility, and how much infrastructure is actually needed to live well.</p> This wasn't escapism. It was alignment.</p> Disc Golf, Outdoors, and Sustainability</h2> Disc golf remained a grounding constant.</p> Not just as a hobby, but as:</p> A recurring design constraint (maps, data, APIs)</li> A sustainability touchstone</li> A reminder that systems should work outside, not just on screens</li> </ul> The focus subtly shifted from collecting and optimizing toward understanding spaces:</p> Courses as designed environments</li> Flow, access, and maintenance</li> How technology can support, not dominate, physical experiences</li> </ul> Creative Work Beyond Code</h2> 2025 also made room for making things with your hands.</p> Pottery experiments</li> Tufting and material exploration</li> Visual identity and logo work</li> </ul> These fed back into engineering work by reinforcing:</p> Process over output</li> Material constraints</li> Iteration without metrics</li> </ul> That cross-pollination showed up everywhere.</p> Career and Direction</h2> Professionally, this was a year of alignment.</p> The focus moved further toward:</p> Open-source adjacent work</li> Tooling that empowers communities</li> Infrastructure that disappears when it works</li> </ul> Rather than chasing titles or hype, the emphasis stayed on:</p> Taste</li> Maintainability</li> Systems that still make sense six months later</li> </ul> The result was confidence rooted in practice, not positioning.</p> The Shape of Things Going Forward</h2> If 2024 was about exploration, 2025 was about integration.</p> There is now:</p> A coherent technical stack</li> A public body of work</li> Clear values around sustainability, simplicity, and ownership</li> </ul> Most importantly, the year ends with momentum that feels calm rather than frantic.</p> That is the kind that lasts.</p> Building LLM-TUI: Never Lose Context Again Unknown — Tue, 16 Dec 2025 00:00:00 +0000 I am loving CLI agentic LLM apps except for one thing... and that's losing context.</p> You're working on a feature. You've shown the AI five files. You've explained your architecture. You're making progress. Then Claude crashes. Or you switch to a different project.</p> When you come back tomorrow, you start over. Re-explain everything. Re-share the files. Re-establish context.</p> I was taking daily notes but I got tired of that. So I built llm-tui.</p> It's a terminal interface for AI chat, but that's not the main feature. The main feature is it remembers. File context persists across sessions. Tool results get cached. You can close it, come back a week later, and pick up exactly where you left off.</p> What It Does</h2> You launch it, pick a model, and chat. But the devil's in the details.</p> Multi-Provider Support</strong></p> Switch between Ollama (local models on your machine), Claude API (Anthropic's hosted models), and AWS Bedrock (Claude via AWS). One interface, multiple backends.</p> Tool System</strong></p> When using Claude or Bedrock, the AI can Read files, Write files, Edit existing code, search with Glob and Grep, and run Bash commands. All sandboxed to your home directory. Every tool execution requires confirmation (y/n/q).</p> File Context Persistence</strong></p> Files read during a session get cached. When you reopen that session later, those files are already loaded. The AI remembers what it was looking at.</p> Session Management</strong></p> Create named sessions, organize them by project, rename and delete them. SQLite storage means everything persists and loads instantly.</p> Vim Keybindings</strong></p> Modal editing. Normal mode for navigation, insert mode for typing, command mode for session management. j/k to scroll, i to insert, Esc to escape. Feels natural.</p> Token Tracking</strong></p> Real-time display of token usage (Tokens: 1250/200000). When conversations get long, automatic context compaction kicks in at 75% capacity. Old messages get summarized, recent ones stay intact.</p> Why I Built It</h2> Context loss kills productivity. You're building a feature, the AI understands your codebase, and then you lose it all. Browser tabs close. Sessions expire. You switch projects and forget to save the conversation.</p> Starting over means minutes of setup every time. Copy file contents. Explain your architecture again. Re-establish what the AI already knew.</p> I needed persistence. Sessions that survive restarts. File context that doesn't disappear. A tool that picks up where you left off without re-explaining everything.</p> And I wanted control over which model handles the task. Local models for quick iteration. Claude when I need reasoning. Bedrock for AWS work. One interface, no lost context when switching.</p> The Tool System</h2> Context persistence only works if the AI can actually interact with your files. Browser-based chat requires copying code back and forth. Every file you want the AI to see means another copy-paste. Every change it suggests means manually applying edits.</p> The tool system fixes this. When using Claude or Bedrock, the AI can Read files, Write files, Edit code, search with Glob and Grep, and run Bash commands. All sandboxed to your home directory with explicit confirmation.</p> When the AI wants to read a file, it calls the Read tool. You see: Read /home/user/project/foo.rs? (y/n/q)</code>. Same for writes and edits. You approve or reject each action.</p> The key part: tool results get cached per session. If the AI reads config.toml</code>, that result stays in the session history. Next time you open that session, it already knows what was in that file. No re-reading. No re-explaining. The context persists.</p> The Future Is Weird</h2> As you can probably tell, I love and prefer open source software. Unfortunately, Claude does not fall into that category so I could not look at it for inspiration. So, I tried a wild idea. I simply asked Claude how it's tools worked and what the API response looked like. And you know what, it worked! I had Claude help me basically rebuild it's tools by internal reflection. The future is a trip, man.</p> Session Management</h2> This is where context persistence actually lives. Each session is a separate context with its own history, files, and conversation state. Work on multiple projects without mixing contexts. Switch between them without losing anything.</p> :new my-feature # New session with custom name :project discourse-yaks # Set current project :rename better-name # Rename current session </code></pre> Sessions are stored in SQLite at ~/.local/share/llm-tui/sessions.db</code>. Close the app, come back tomorrow, and every session is exactly as you left it. The AI still has all the files loaded. The conversation picks up mid-thought.</p> You can even load context from other sessions with :load session-name</code>. Pull in file context from a different project without manually re-sharing everything.</p> Provider Management</h2> Switch providers with a command:</p> :provider ollama # Local models :provider claude # Claude API (requires ANTHROPIC_API_KEY) :provider bedrock # AWS Bedrock (requires AWS credentials) </code></pre> The models screen (press 3</code>) shows all available models across all providers. Installed Ollama models marked with [installed]</code>. Current active model marked with [current]</code>.</p> You can download Ollama models directly from the TUI. Navigate to a non-installed model, hit Enter, and it pulls from the Ollama library. One keypress.</p> Automatic Context Compaction</h2> Long conversations hit context window limits. Most chat interfaces handle this by truncating old messages. You lose the early context that established your architecture decisions and project structure.</p> llm-tui summarizes old messages instead of dropping them. At 75% capacity, it sends old messages to the LLM for summarization. The summary replaces the original messages, keeping under 500 tokens. Recent messages (default: 10) always stay uncompacted.</p> You keep the context. The AI still knows what happened at the start of the conversation. You just use fewer tokens to maintain it.</p> The Stack</h2> Written in Rust. The UI is built with ratatui (terminal UI library). SQLite for storage via rusqlite and crossterm for terminal handling.</p> Three API clients: reqwest for Ollama's HTTP API, anthropic-sdk-rust for Claude, and AWS SDK for Bedrock.</p> Tool execution uses ripgrep (grep crate) for fast content search, glob for pattern matching, and walkdir for file traversal.</p> Built my own vim-navigator-rs library for the modal keybindings. Normal, insert, and command modes with proper vim-style navigation.</p> Configuration</h2> Config file at ~/.config/llm-tui/config.toml</code>:</p> autosave_mode = "onsend" # disabled/onsend/timer ollama_model = "llama2" ollama_context_window = 4096 claude_model = "claude-3-5-sonnet-20241022" claude_context_window = 200000 bedrock_model = "us.anthropic.claude-sonnet-4-20250514-v1:0" bedrock_context_window = 200000 autocompact_threshold = 0.75 # Compact at 75% capacity autocompact_keep_recent = 10 # Keep last 10 messages uncompacted </code></pre> Autosave modes: disabled (manual :w</code> only), onsend (save immediately when sending messages), or timer (save every N seconds).</p> Auto-start Ollama if not running (configurable). Set default provider. Pick your context window sizes.</p> Roadmap</h2> Still building. Next up:</p> OpenAI API integration</li> Setup wizard for API keys</li> Daily notes integration (load from my claude-notes directory)</li> Search functionality across sessions</li> Session export</li> Code block syntax highlighting</li> </ul> Final Thoughts</h2> Browser-based chat interfaces are fine for casual use. But when you're deep in development work, context loss becomes the bottleneck. Re-explaining architecture. Re-sharing files. Starting conversations from scratch.</p> llm-tui fixes that. Sessions persist. File context survives restarts. You pick up exactly where you left off. The AI remembers what it knew yesterday.</p> JOBL and SRG: Building Resume Tools I Actually Want to Use Unknown — Sun, 14 Dec 2025 00:00:00 +0000 After getting laid off from my last job, I told myself I would keep my resume updated and my options open. Then we had layoffs at Discourse. Nothing like watching coworkers lose their jobs to remind you that stability is an illusion and preparation matters.</p> I have been in a spec and tool building mood lately anyway. Something about the uncertainty makes me want to build things I can control. JOBL and SRG fit that mood perfectly.</p> The Problem</h2> I needed to update my resume. The last version was a LibreOffice doc. It was a pain in the ass. The formatting was fragile. One change and the whole thing shifted. Exporting to PDF was a gamble. And I could not version control it properly because it was a binary blob.</p> What I wanted: plain text I can edit in vim, version control in git, and generate HTML and PDF programmatically.</p> So I built it.</p> JOBL: A TOML Resume Format</h2> JOBL is a strict TOML-based resume format. The file extension is .jobl</code> and the structure is simple:</p> [person] name = "Jake Goldsborough" headline = "Infrastructure Engineer" email = "jake@example.com" location = "Portland, OR" summary = "Backend systems and deployment automation." [skills] Languages = ["Ruby", "Rust", "JavaScript"] Infrastructure = ["Docker", "Kubernetes", "NixOS"] [[experience]] title = "Software Engineer" company = "Discourse" start = "2025-06" end = "current" summary = "Infrastructure team, backend systems, deployment tooling." highlights = [ "Built postgres-manager HTTP service replacing MessageBus pub/sub", "Reduced duplicate operations and improved operational visibility" ] [[projects]] name = "Transit Tracker" url = "https://github.com/ducks/discourse-transit-tracker" summary = "Live departure board plugin for Discourse showing real-time transit arrivals" [[education]] degree = "BS Computer Science" institution = "State University" start = "2016" end = "2020" </code></pre> TOML is human readable. You can edit it in any text editor. Comments are supported. Syntax errors fail fast at parse time. Version control works perfectly because it is plain text.</p> Why TOML Instead of JSON or YAML</h2> JSON is for machines. Writing nested structures by hand is miserable. No comments. Trailing commas break everything. It is data interchange format, not a human authoring format.</p> YAML has too many footguns. Indentation matters. Multiple ways to express the same thing. The Norway problem (NO gets parsed as boolean false). Anchors and references add complexity I do not need.</p> TOML is boring in the best way. One obvious way to express each type. Strict validation. Native Rust support via serde. No surprises.</p> The Parser: Strict Validation</h2> JOBL uses a two phase validation approach:</p> Parse TOML into generic Value to catch unknown keys</li> Deserialize into typed structs for field validation</li> </ol> This catches typos immediately. If you write titel</code> instead of title</code>, you get an error with the exact path: experience[0].titel: unknown field</code>.</p> The parser collects multiple errors instead of failing fast. When you have five typos, you see all five at once instead of fixing them one at a time.</p> pub fn parse_file(path: &Path) -> ValidationResult<JoblDocument> pub fn parse_str(input: &str) -> ValidationResult<JoblDocument> </code></pre> Simple API. File or string in, validated document or errors out.</p> No Version Field</h2> I originally included a jobl_version</code> field in documents. Then I removed it.</p> Docker recently dropped version fields from their configs. The library version determines what spec you support. Simpler for users. They do not maintain a version field. The parser handles compatibility.</p> You can always add versioning later if you need it. Start simple.</p> SRG: Static Resume Generator</h2> JOBL handles data. SRG handles rendering.</p> srg --input resume.jobl --out dist --template minimal </code></pre> Reads your JOBL file, generates dist/index.html</code> and dist/resume.pdf</code>. Single binary. No dependencies except Chrome for PDF generation.</p> The HTML is self contained with embedded CSS. Email it. Put it on a static host. It just works.</p> PDF Generation: Headless Chrome</h2> I was skeptical about using headless Chrome for PDF generation. It seemed heavy and finicky. I've tried an HTML -> PDF method before with less than ideal results. But it works incredibly well.</p> The HTML you write is the PDF you get. Print media queries work exactly as expected. Local fonts load synchronously. No layout rewriting needed.</p> let pdf_data = tab.print_to_pdf(Some(PrintToPdfOptions { landscape: Some(false), display_header_footer: Some(false), // No browser artifacts print_background: Some(true), // Keep CSS backgrounds scale: Some(1.0), paper_width: Some(8.5), paper_height: Some(11.0), // ... margins, etc })) </code></pre> Alternative was native Rust PDF libraries like printpdf. That means manually positioning every element. Reimplementing layout logic. Maintaining two rendering paths (HTML and PDF).</p> Headless Chrome means one rendering path. CSS does the work. The PDF matches the HTML perfectly.</p> Layout System: Structure Without HTML</h2> Users should not need to write HTML to customize their resume. But they should be able to control structure and formatting.</p> The layout system is a simple DSL:</p> person name headline email experience title company start " - " end highlights education degree institution start " - " end </code></pre> Section names at indent level 0. Field names at level 2. Order matters.</p> Quoted strings are literals. Unquoted words are field names. Mix them:</p> person name "at" email "Location:" location experience start " - " end </code></pre> Renders as:</p> Jake Goldsborough at jake@example.com Location: Portland, OR 2025-06 - current </code></pre> The layout file controls what shows and in what order. The template (minimal, professional, etc) controls CSS styling. Separation of concerns.</p> Why Build This</h2> Practical answer: I needed to update my resume and existing tools did not fit how I work.</p> Real answer: building tools gives me a sense of control when everything else feels uncertain. Layoffs happen. Companies change. Markets shift. But code I write is mine. Specs I design are mine. Tools I build solve problems exactly how I want them solved.</p> This is not about resume formats. This is about responding to uncertainty by building something you own completely.</p> Current Status</h2> Both projects are functional and tested:</p> JOBL: 7 unit tests, strict validation, clean error messages</li> SRG: layout system with quoted strings, PDF generation working, 15 total tests</li> Combined: about 1800 lines of Rust, all passing tests</li> </ul> Documentation sites are up at https://jobl.dev</a> (plain HTML, no build step, Gruvbox theme with dark/light toggle).</p> Source is on GitHub if you want to look:</p> github.com/ducks/jobl</a></li> github.com/ducks/srg</a></li> </ul> Skin Shedding, Not Bikeshedding Unknown — Sun, 23 Nov 2025 00:00:00 +0000 Snakes shed their skin. They outgrow it, slough it off, and keep moving. They're still the same snake, just with a fresh layer, ready for whatever comes next.</p> I've been thinking about that lately.</p> This whole reflection started because I caught myself in yet another argument where nobody was building anything.</p> The Bikeshed Problem</h2> There's this concept in software development called bikeshedding. The term comes from an example about a fictional committee reviewing plans for a nuclear power plant. They breeze through the complex reactor design but spend hours debating the color of the bike shed. Why? Because everyone understands bike sheds. Everyone has opinions about paint.</p> In code, bikeshedding looks like endless debates about tab width, framework choices, naming conventions. Arguments about the "right way" to do things that could be resolved by just trying something and seeing if it works.</p> I've spent too much time in those debates.</p> The Weight of Being Right</h2> Here's what I've learned: arguing about code is exhausting. Not the technical discussions about trade-offs or the collaborative problem-solving. I mean the arguments. The "this is the only correct approach" discussions. The debates where everyone digs in and nobody builds anything.</p> I've been part of teams where every PR becomes a referendum on architectural philosophy. Where suggesting a different approach gets met with resistance before anyone's even tried it. Where the discussion thread is longer than the code changes.</p> It's draining. And worse, it's a trap. Because when you're arguing about whether to use Tool A or Tool B, you're not actually learning which one works better for your specific use case. You're just... arguing.</p> The Freedom of Not Knowing</h2> The truth is, half the time we don't know what will work until we try it. We think we do. We have intuitions, experience, opinions. But software is weird. Context matters. What worked great on one project might be wrong for another.</p> So instead, I just try things.</p> Not recklessly. Not without thought. But when faced with two reasonable approaches, instead of spending hours debating the merits, I'll pick one and build it. See how it feels. See where it breaks. See what I learn.</p> And you know what? Sometimes the "wrong" choice teaches me more than the "right" one would have.</p> Shedding Skin</h2> This is where the snake metaphor comes back. Shedding skin isn't about becoming a different snake. It's about not being constrained by what fit before.</p> For the most part, I'm the same developer I was six months ago. Same skills, same values, same approach to problem-solving. But I'm not carrying around the weight of old arguments anymore. I'm not defending approaches I used on past projects just because I invested ego in them.</p> I can use SQLite on one project and Postgres on another. I can use React here and Svelte there. I can experiment with different state management approaches and see what actually works instead of what I think should work.</p> The skin shedding isn't about the technology. It's about letting go of needing to be right before I've tried anything.</p> What This Looks Like</h2> Practically, this means:</p> Build small experiments. Don't debate for hours about whether approach A or B is better. Spend 30 minutes trying A and see how it feels. Then try B. Now you have actual data instead of theoretical arguments.</p> Ship things that might not be perfect. Perfect is the enemy of learning. Ship something that works, see how it breaks in the real world, iterate. You'll learn more in a week of production use than a month of pre-planning.</p> Change your mind without drama. "We're using X" doesn't have to be a permanent commitment. If it's not working, you can try Y. This isn't failure, it's iteration.</p> Judge by outcomes, not aesthetics. Code that's a bit messy but works reliably is better than code that's architecturally pure but brittle. The goal is to solve problems, not win style points.</p> All of this beats spending three hours arguing about the hypothetical failure modes of something nobody has tested.</p> The Meta Lesson</h2> Here's the thing: this post is about code, but it's not really about code. It's about how we approach problems when we don't know the answer yet.</p> Do we lock ourselves into positions before we have evidence? Do we defend our intuitions as if they're facts? Do we mistake confidence for correctness?</p> Or do we stay curious? Do we try things? Do we update our beliefs when we learn new information?</p> The snake sheds its skin because it has to. It's grown too big for the old one. We can do the same. We can outgrow old arguments, old certainties, old ways of working that don't serve us anymore.</p> We're still the same developers. We're just not trapped by what we thought we knew before we tried it.</p> Try It and See</h2> Last week, instead of debating the limitations of someone else's critique, I just built the tool I wished we had.</p> Next time you're in a debate about the "right" way to do something, ask yourself: would it be faster to just try it?</p> Not everything, of course. Some decisions are expensive to reverse. But a lot of what we argue about? It's just bike sheds. We could build both sheds, paint them different colors, and actually see which one we like better.</p> That's skin shedding. Letting go of the need to be right about things you haven't tried yet. Staying light, staying curious, staying open to learning from the next thing you build.</p> The old skin doesn't fit anymore. Time to shed it and keep moving.</p> Date-Ver: A Formal Spec for Date-Based Versioning Unknown — Sat, 15 Nov 2025 00:00:00 +0000 Yesterday I published yaml-janitor</a> using date-based version numbers like 20251115</code>. The version number is the release date. Automatic, meaningful, no decisions needed.</p> Then I realized there's no formal specification for this. Semantic versioning has semver.org</a> with strict rules and RFC 2119 language. Calendar versioning has calver.org</a>, but that's just a pattern guide, not a spec.</p> So I built date-ver</a>.</p> What It Is</h2> date-ver is a formal spec for date-based version numbers. Instead of 1.2.3</code> or 2.0.0</code>, you use 20251116</code>, 202511</code>, or 2025</code>.</p> The idea is simple: your version number is when you released, not what changed. Works great for applications, utilities, and distributions where users care about freshness over compatibility.</p> Why It Exists</h2> Projects have been using date-based versions forever. Ubuntu does 24.04</code> and 24.10</code>. yaml-janitor uses 20251115</code>. But without a formal spec, everyone makes up their own rules.</p> Questions that needed answers:</p> Can you mix formats? (Yes: 2024</code> → 202505</code> → 20250601</code> is valid)</li> Multiple releases per day? (Sequence numbers: 20251116.1</code>, 20251116.2</code>)</li> Pre-releases? (Use your separator: 20251116.alpha.1</code> or 2025-11-15-rc-2</code>)</li> Separators allowed? (Yes: 20251116</code> = 2025.11.16</code> = 2025-11-16</code>)</li> </ul> date-ver answers all of these with proper RFC 2119 language.</p> The Separator Decision</h2> Ubuntu uses dots (24.04</code>). yaml-janitor uses nothing (20251115</code>). Some projects use hyphens or slashes. Rather than force everyone to change, date-ver allows any single-character separator as long as you're consistent throughout the entire version string similar to regex.</p> Valid:</p> 20251116</code> (no separator)</li> 2025.11.16</code> (dots throughout)</li> 2025-11-16</code> (hyphens throughout)</li> 2025/11/16</code> (slashes throughout)</li> 20251116.alpha.1</code> (dots for everything)</li> 2025-11-15-rc-2</code> (hyphens for everything)</li> </ul> Invalid:</p> 2025.11-16</code> (mixed separators in date)</li> 20251116-alpha.1</code> (mixing none with hyphen and dot)</li> </ul> Pick one separator and stick to it. All separator styles are equivalent. To compare versions, strip separators and compare digits. Simple.</p> Pick Your Precision</h2> Projects choose their granularity:</p> Year: 2025</code></li> Year-month: 202511</code> or 2025.11</code></li> Year-month-day: 20251116</code> or 2025.11.16</code></li> </ul> More specific = higher precedence: 2025 < 202501 < 20250101</code></p> Start with yearly versions and switch to monthly or daily whenever. No breaking changes, just more precision when you need it.</p> When to Use It</h2> Good fit:</p> Applications with regular releases</li> Operating systems and distributions</li> Tools where freshness matters</li> Internal utilities</li> </ul> Bad fit:</p> Libraries where compatibility matters</li> APIs with semver expectations</li> Projects with strict dependency contracts</li> </ul> Need to signal breaking changes? Use semver. Need to signal release timing? Use date-ver.</p> Building It</h2> Wrote the spec following semver's structure:</p> Summary</li> Introduction</li> Numbered rules with RFC 2119 language</li> FAQ</li> Examples</li> </ul> Built a website with GitHub Pages, Gruvbox colors, and automatic dark mode. The spec itself uses date-ver 20251115</code> (it originally said 1.0.0</code> which was pretty ironic).</p> That's It</h2> date-ver exists. The spec is done, the domain is live, and the website is up at date-ver.com</a>.</p> Ubuntu is officially valid date-ver. So is yaml-janitor. Any project using date-based versions can point to the spec now.</p> Maybe it catches on. Maybe it doesn't. Either way, there's a formal answer when someone asks "why are your versions dates?"</p> The version is the release date. That's date-ver.</p> Full spec: date-ver.com</a> Source: GitHub</a> (CC BY 4.0)</p> Building yaml-janitor: Solving the Comment Preservation Problem Unknown — Fri, 14 Nov 2025 00:00:00 +0000 For the past five years, there's been an intermittent problem at work: sometimes, when editing YAML configuration files with automated tools, comments get destroyed. The comments contain critical context like why certain values exist or what not to change, so losing them causes real problems when trying to maintain infrastructure configuration.</p> A coworker tried to solve this in 2021 by building tooling around psych-pure, a pure Ruby YAML parser that can preserve comments. But psych-pure wasn't stable enough at the time, so the project stalled.</p> Fast forward to 2025, and I happened to be looking through devops topics and stumbled upon this one. This seemed like the perfect opportunity to revisit the comment preservation problem.</p> The Initial Validation</h2> I started by writing a simple validation script using psych-pure to check if our production YAML files could survive a round-trip: load the file, dump it back out, and verify the semantics stayed the same.</p> require 'psych/pure' yaml_content = File.read('config.yml') loaded = Psych::Pure.load(yaml_content, comments: true) dumped = Psych::Pure.dump(loaded) # Verify semantics match original_data = Psych::Pure.load(yaml_content) dumped_data = Psych::Pure.load(dumped) if original_data == dumped_data puts "✅ Semantics preserved" else puts "❌ MISMATCH" end </code></pre> I ran this against 1,736 production YAML files across two repositories. The good news: no corrupt YAML! Most files validated successfully, with only a handful failing due to using patterns that are technically invalid per the YAML spec (though the C implementation of Psych accepts them anyway).</p> Building yaml-janitor</h2> With validation working, I built a proper linter around psych-pure. The key challenge was that while psych-pure preserves comments when loading, its built-in dump function doesn't give enough control over formatting. I needed custom formatting rules like consistent indentation and compact array notation.</p> Here's what yaml-janitor fixes:</p> # Before: mixed indentation, explicit array format config: # Database settings database: host: localhost port: 5432 features: - name: caching enabled: true # After: consistent indentation, compact arrays config: # Database settings database: host: localhost port: 5432 features: - name: caching enabled: true </code></pre> The solution was to build a custom emitter that walks the loaded data structure and outputs formatted YAML while preserving all comments:</p> class Emitter def initialize(node, config) @node = node @config = config @output = [] end def emit emit_comments(get_comments(@node, :leading), 0) emit_document(@node) @output.join("\n") + "\n" end def emit_mapping(hash, indent) entries = hash.respond_to?(:psych_keys) ? hash.psych_keys.map { \|pk\| [pk.key_node, pk.value_node] } : hash.to_a entries.each_with_index do \|(key, value), index\| emit_comments(get_comments(key, :leading), indent) key_str = scalar_to_string(key) case value when Hash, Array @output << "#{' ' * indent}#{key_str}:" emit_node(value, indent + indentation) else value_str = scalar_to_string(value) @output << "#{' ' * indent}#{key_str}: #{value_str}" end emit_comments(get_comments(key, :trailing), indent) end end end </code></pre> This gave me complete control over formatting while preserving every comment. The emitter handles:</p> Consistent indentation (2 or 4 spaces)</li> Compact array format (dash on same line as first key)</li> Comment placement (leading and trailing)</li> Blank lines between top-level sections</li> </ul> Production Testing</h2> I tested yaml-janitor on a production file with mixed 2-space and 4-space indentation:</p> # Backup original cp pipeline.yaml /tmp/pipeline_backup.yaml # Fix with yaml-janitor yaml-janitor --fix --indentation 2 pipeline.yaml # Verify semantics preserved ruby -ryaml -e " orig = YAML.load_file('/tmp/pipeline_backup.yaml') fixed = YAML.load_file('pipeline.yaml') puts orig == fixed ? '✅ Semantics preserved' : '❌ MISMATCH' " # Output: ✅ Semantics preserved </code></pre> The fix worked perfectly. Consistent indentation, all comments preserved, and semantics verified to be identical.</p> Configuration System</h2> I added a configuration file system so teams can standardize their YAML formatting:</p> # .yaml-janitor.yml indentation: 2 line_width: 80 sequence_indent: false rules: consistent_indentation: enabled: true multiline_certificate: enabled: true </code></pre> The CLI supports both config files and command-line overrides:</p> yaml-janitor --config .yaml-janitor.yml files/.yml yaml-janitor --fix --indentation 2 config.yml </code></pre> Publishing to RubyGems</h2> Once the linter was working, I published it to RubyGems so anyone could use it. I set up automated publishing with GitHub Actions and RubyGems trusted publishing (no API keys needed):</p> name: Publish to RubyGems on: push: tags: - 'v' jobs: publish: runs-on: ubuntu-latest permissions: contents: read id-token: write steps: - uses: actions/checkout@v4 - uses: ruby/setup-ruby@v1 with: ruby-version: '3.3' bundler-cache: true - uses: rubygems/release-gem@v1 </code></pre> The release process is now fully automated:</p> Update version number (date-based: YYYYMMDD)</li> Run bundle install</code> to update lockfile</li> Commit and push to main</li> Create and push tag: git tag v20251113 && git push origin v20251113</code></li> GitHub Actions automatically publishes to RubyGems</li> </ol> Results</h2> yaml-janitor is now published and available on RubyGems:</p> gem install yaml-janitor yaml-janitor --help </code></pre> Production validation results:</p> Scanned 1,736 YAML files</li> Found 0 corrupt files</li> Fixed widespread formatting inconsistencies</li> Preserved all comments during fixes</li> </ul> People are already using it to lint their YAML configurations.</p> The Five-Year Solution</h2> The problem my coworker identified in 2021 is finally solved. Teams can now safely automate YAML editing without losing critical context in comments. The infrastructure was already there, it just needed psych-pure to stabilize and someone to finish building the tooling.</p> yaml-janitor is open source and available on GitHub</a> and RubyGems</a>. If you've ever had to choose between manual YAML editing and losing your comments, check it out.</p> Like a Pig in Shit: Why I Love AI "Slop" Unknown — Sat, 08 Nov 2025 00:00:00 +0000 I've shipped more projects in the last three months than I did in the previous year. Are they all perfect? No. Are they all polished production-grade code? Hell no. Do I care? Not even a little bit.</p> I'm having the time of my life building whatever idea pops into my head, and AI is the reason I can actually finish things instead of just thinking about them.</p> And look, shipping isn't everything. Sometimes the best code never sees the light of day. Sometimes you build something just to learn, or just because it sounds fun. But there's something deeply satisfying about making things that actually work - even if they're just for you.</p> What I've Been Building</h2> In the last few months alone:</p> vimdeck.nvim</a></strong>: Markdown presentations in Neovim using Treesitter</li> mdpreview.nvim</a></strong>: Live markdown preview in a split window</li> discourse-yaks</a></strong>: Virtual currency system for forum posts</li> discourse-transit-tracker</a></strong>: Turn forums into live departure boards</li> discourse-invite-stats</a></strong>: Invite reporting and analytics plugin</li> shelltrax</a></strong>: TUI music player in Rust (my daily driver now)</li> Plus a handful of smaller tools and fixes</li> </ul> Some of these are polished. Some are "good enough for me." All of them work. All of them solve real problems I had. And I built most of them in a day or two.</p> The "Slop" Criticism</h2> There's this narrative that AI-generated code is "slop." Low quality, generic, copy-pasted garbage that's polluting the internet. And sure, that exists. That existed before AI when people would blindly copy from Stack Overflow. But the criticism misses something important:</p> When you're building for yourself, "slop" doesn't matter.</p> I'm not pushing half-baked code to production systems. I'm not claiming my afternoon projects are enterprise-ready. I'm building tools that solve my problems, learning by doing, and having fun.</p> If the markdown preview plugin has rough edges, who cares? It works for me. If the presentation tool doesn't handle every edge case, so what? It renders my slides.</p> The "slop" criticism only matters when you're shipping garbage and calling it gold. When you're building for yourself? Ship it, iterate, move on.</p> What's Actually Happening</h2> Here's what working with AI looks like for me:</p> I have an idea. "I want to do presentations in Neovim." Instead of spending a week researching markdown parsers and figlet integration and buffer management, I describe what I want and start building.</p> The AI suggests approaches. Some work. Some don't. We iterate. I learn what Treesitter can do. I understand how Neovim's highlight system works. I see patterns I wouldn't have thought of.</p> A few hours later, I have a working plugin.</p> Is it perfect? No. Did I learn a ton? Yes. Can I actually use it? Absolutely.</p> The Joy of Building</h2> What the critics miss is how much fun this is.</p> I used to have a backlog of ideas that never got built. "Someday I'll make that." "That would be cool but it's too much work." "I don't have time to learn X framework."</p> Now? I just build it.</p> Want to visualize invite relationships as an ASCII tree? Build it. Want live transit departures in a forum? Build it. Want to fix a bug in a YAML parser? Build it and submit the fix upstream.</p> The barrier between "I wish this existed" and "I built this" has collapsed. And that's incredible.</p> But Is It Actually Good Code?</h2> Sometimes yes, sometimes no. And that's fine.</p> The Ruby psych-pure bug fix</a> I submitted? That's good code. Full test coverage, proper edge case handling, clean implementation. It's going into a production library.</p> The transit tracker</a>? It works, handles 500k+ MTA stop times, and has solid patterns for data downloading and parsing. Could the UI be more polished? Sure. But it does what I need and I learned a ton building it.</p> The key is knowing the difference. When it matters, I put in the work. When it's just for me, I ship it and move on.</p> The Real Productivity Hack</h2> Working with AI isn't about replacing thinking. It's about spending your brain cycles on the interesting problems instead of the boring setup work.</p> I don't want to spend three hours setting up test infrastructure. I want to spend three hours solving the actual problem. AI handles the grunt work. I handle the decisions.</p> You Can Vibe and Still Be Productive</h2> Here's the thing: you can have fun, move fast, and still produce quality work. It's not either/or.</p> I'm "vibing out" projects. Building whatever sounds interesting. Shipping fast. And yet:</p> The code works</li> The tests pass</li> The bugs get fixed</li> The upstream contributions get merged</li> </ul> You can be a pig in shit and still do good work. The slop is the medium, not the output.</p> The Gatekeeping Problem</h2> A lot of the "AI slop" criticism is just gatekeeping in disguise.</p> "Real programmers don't use AI." "You're not actually learning." "This is ruining software quality."</p> Meanwhile, I'm shipping. Learning by building. Contributing to open source. Having fun.</p> The gatekeepers can argue about the "right way" to write code. I'm too busy building things.</p> What Actually Matters</h2> At the end of the day, here's what matters:</p> Does it work?</li> Did you learn something?</li> Are you having fun?</li> </ul> If the answer to those three questions is yes, then it doesn't matter if someone on Twitter thinks your code is "slop."</p> You're building. They're complaining. You win.</p> Like a Pig in Shit</h2> So yeah, I'm rolling around in the AI slop. Building projects at a pace I never could before. Shipping tools that solve real problems. Learning by doing instead of just reading about it. Old me would think I was full of shit if I tried explaining this.</p> Call it slop if you want. I'm too busy having the time of my life to care.</p> The pig pen is the place for me.</p> vimdeck.nvim: Markdown Presentations in Neovim Unknown — Fri, 07 Nov 2025 00:00:00 +0000 I live in the terminal and Neovim. We have been discussing lightning talks at work, so I wanted a way to present using both. The original vimdeck</a> used to work perfectly, but it's a Ruby script that doesn't seem to work with Neovim.</p> So I rewrote it from scratch using Treesitter and Lua (and Claude).</p> What It Does</h2> You write your presentation in markdown. Separate slides with horizontal rules (---</code>). Run :Vimdeck</code> and you get a fullscreen presentation with:</p> ASCII art headers (h1 and h2 use figlet)</li> Syntax highlighted code blocks</li> Clean list rendering with bullets</li> Blockquote formatting</li> Keyboard navigation (Space/PageDown, Backspace/PageUp, q to quit)</li> </ul> </p> </p> Why Rewrite It?</h2> The original vimdeck was solid for Vim, but it was not working for me in Neovim. Adding to that, it felt like it could be done in a better, more native way. The current Vimdeck was:</p> External Ruby script (dependency management)</li> Generated temp files for each slide</li> Custom shell wrapper for keybindings</li> redcarpet gem for markdown parsing</li> </ul> Neovim has Treesitter built-in. Lua is native. Why shell out to Ruby and manage temp files when you can parse and render everything directly?</p> The Approach</h2> Parser</strong> (lua/vimdeck/parser.lua</code>): Uses Treesitter to parse markdown buffers. Queries for headings, code blocks, lists, quotes, paragraphs. Splits content into slides on horizontal rules (thematic breaks).</p> local query = vim.treesitter.query.parse('markdown', [[ (thematic_break) @separator (atx_heading) @heading (fenced_code_block) @code (list_item) @list_item (block_quote) @quote (paragraph) @paragraph ]]) </code></pre> For each captured node, extract the text and metadata (heading level, code language, etc.). Group elements into slides based on separators.</p> Renderer</strong> (lua/vimdeck/renderer.lua</code>): Takes parsed slides and renders them to buffer lines with highlight instructions.</p> Headers get piped through figlet for ASCII art (h1 uses standard font, h2 uses small). Lists get bullet points. Blockquotes get vertical bars. Code blocks get syntax highlighting via Treesitter string parsers.</p> Navigation</strong> (lua/vimdeck/navigation.lua</code>): Opens slides in a new tab, sets up keybindings, manages state. Updates the buffer content and applies highlights when switching slides.</p> Technical Bits</h2> Treesitter Integration</strong>: The markdown parser exposes node types like atx_heading</code>, fenced_code_block</code>, list_item</code>. Each node has position info (start/end row/col) and can extract text with vim.treesitter.get_node_text()</code>.</p> Getting clean text required helper functions. List items include the markdown markers (- item</code>), so we traverse child nodes to skip list_marker</code> nodes and extract just the content. Same for blockquotes (strip ></code> markers) and code blocks (strip fence markers).</p> Heading Levels</strong>: Treesitter gives you atx_heading</code> nodes. To determine level, check for child nodes like atx_h1_marker</code>, atx_h2_marker</code>, etc.</p> function M.get_heading_level(heading_node) for child in heading_node:iter_children() do if child:type() == 'atx_h1_marker' then return 1 end if child:type() == 'atx_h2_marker' then return 2 end -- ... end return 1 end </code></pre> Duplicate Elements</strong>: Initial implementation captured both list_item</code> nodes and paragraph</code> nodes inside them. Rendering each element separately meant lists showed up twice. Fix: check node ancestry and skip paragraphs that are children of list items or blockquotes.</p> Newline Flattening</strong>: vim.api.nvim_buf_set_lines()</code> requires each array element to be a single line. Figlet output and some text processing can embed \n</code> characters. Solution: scan lines before setting buffer content and split any with embedded newlines.</p> What It Supports</h2> All heading levels</strong> (h1-h6). h1 and h2 get ASCII art via figlet if available. h3-h6 render as plain text with style options such as box, dashed, or underline.</p> Code blocks</strong> with language-specific syntax highlighting. The renderer creates a Treesitter string parser for the code content and applies highlight queries.</p> Lists</strong> render with bullet points (</code>). Blockquotes</strong> render with vertical bars (┃</code>).</p> </p> Per-Presentation Configuration</h2> YAML frontmatter lets you configure individual presentations without changing global settings. Add frontmatter at the start of your markdown:</p> --- wrap: 80 center_horizontal: true margin: 3 use_figlet: false header_style: "underline" --- # First Slide </code></pre> The wrap</code> option automatically wraps long paragraphs to the specified width. Perfect for prose-heavy slides where you don't want to manually hard-wrap text. Write flowing paragraphs in your markdown source and let vimdeck handle the layout.</p> Header styles provide alternatives to figlet ASCII art. Options include underline</code> (single/double lines), box</code> (Unicode box drawing), double</code> (double-line boxes), and dashed</code> (dotted underlines). All use Unicode characters for clean terminal rendering.</p> Frontmatter parsing uses a simple YAML parser (20 lines of Lua) that handles basic key-value pairs. Supports booleans, numbers, and strings. The frontmatter config merges with global config, so you only override what you need.</p> Installation</h2> Using lazy.nvim:</p> { 'ducks/vimdeck.nvim', cmd = { 'Vimdeck', 'VimdeckFile' }, opts = { use_figlet = true, center_slides = true, } } </code></pre> Requires figlet for ASCII art headers:</p> # macOS brew install figlet # Arch Linux sudo pacman -S figlet # NixOS pkgs.figlet </code></pre> And markdown Treesitter parsers:</p> :TSInstall markdown markdown_inline </code></pre> Usage</h2> Write your presentation:</p> # First Slide Content here --- ## Second Slide More content --- ### Code Example ```lua function hello() print("Hello!") end ``` </code></pre> Open in Neovim and run :Vimdeck</code>. Navigate with Space/PageDown for next slide, Backspace/PageUp for previous, q to quit.</p> Differences From Original</h2> The original vimdeck was a Ruby script. This is a native Neovim plugin.</p> No external dependencies (besides figlet for ASCII art)</li> No temp files</li> Treesitter parsing instead of redcarpet</li> Dynamic rendering instead of static file generation</li> Works with Neovim's highlight system directly</li> </ul> Things To Remember</h2> Treesitter is powerful</strong>: The markdown parser handles all the edge cases (nested lists, multi-line quotes, code fence detection). Using the query system is cleaner than regex parsing.</p> Node traversal matters</strong>: Getting clean text from Treesitter nodes requires understanding the tree structure. List items have marker nodes, code blocks have fence nodes, quotes have paragraph children. Walking the tree to extract just content nodes is necessary.</p> Lua quirks</strong>: Coming from Ruby, easy to forget not</code> instead of !</code>, ~=</code> instead of !=</code>, ..</code> for string concatenation, 1-indexed tables.</p> Code</strong>: github.com/ducks/vimdeck.nvim</a></p> Invite Tree to Invite Stats - How A Simple Tree Flourished Into A Full Moderation Plugin Unknown — Wed, 05 Nov 2025 00:00:00 +0000 Recently, I wrote about building a Discourse plugin that visualizes invite relationships as an ASCII tree. Clean, simple, Lobsters-inspired. I thought I was done.</p> Then I kept thinking about it.</p> Back in 2017, someone on Meta asked about tracking referrals and invites</a>. People wanted to know who was inviting quality members and who was creating moderation work. The Gamification plugin tracks invite counts, but that's just quantity. What about quality?</p> If you're running an invite-only community, you care about accountability. Who's inviting spam accounts? Who's inviting people who get immediately suspended? Which inviters have consistently good judgment?</p> The tree visualization was neat, but it wasn't answering those questions.</p> What Changed</h2> I added moderation metrics to every user in the tree. Now you see:</p> Suspended users (🚫)</li> Silenced users (🔇)</li> Users with agreed flags (⚠️3)</li> Quality scores for people who invited others</li> </ul> Then I built an accountability report that sits above the tree. It shows inviters who meet certain criteria:</p> Invited 3 or more problematic users</li> Have less than 70% invite success rate with 5+ invites</li> </ul> The tree is still there, but it's no longer the main feature. It's supporting evidence for the accountability data.</p> The Rename</h2> At this point, the plugin wasn't really about the tree anymore. It was about invite statistics and quality tracking. The tree was just one way to display the data.</p> So I renamed it: discourse-invite-tree</code> became discourse-invite-stats</code>.</p> Renaming a plugin mid-development is annoying. You have to update:</p> Repository name</li> Plugin metadata</li> All Ruby class names</li> All JavaScript component names</li> All CSS classes</li> All translation keys</li> All site setting names</li> The symlink in your Discourse plugins directory</li> The remote URL in git</li> </ul> But the name needs to match what the thing actually does. A plugin called "invite tree" that's primarily focused on moderation accountability is misleading.</p> Making It Configurable</h2> The hardcoded thresholds (3 bad invites, 70% quality score, 5 minimum invites) worked for my mental model, but different communities have different standards.</p> So I added site settings:</p> invite_stats_problematic_threshold</code>: How many bad invites trigger a flag</li> invite_stats_quality_threshold</code>: What percentage is acceptable</li> invite_stats_min_invites_for_quality</code>: Minimum invites before scoring applies</li> invite_stats_flags_threshold</code>: How many agreed flags mark someone as problematic</li> </ul> I converted the template to a proper Glimmer component class so I could inject siteSettings</code> and compute the threshold description dynamically. Now when an admin changes the thresholds in settings, the UI updates to match.</p> </p> No more hardcoded magic numbers. If your community runs strict moderation and wants to flag anyone with 2 bad invites, you can do that. If you're more lenient and only care about people with 5+ bad invites, that works too.</p> Things to Remember</h2> Scope creep isn't always bad. I started with "show me who invited whom" and ended up with "help me identify problematic inviters." The tree visualization is still there, but it's not the point anymore.</p> Sometimes you need to keep iterating. The first version was fine. The second version is actually useful.</p> Check it out: discourse-invite-stats on GitHub</a></p> Visualizing Discourse Invite Trees Unknown — Mon, 03 Nov 2025 00:00:00 +0000 I built a small Discourse plugin that shows who invited whom in your community. It displays the invite relationships as an ASCII tree, similar to how Lobsters</a> shows their user invites.</p> </p> The tree shows usernames, join dates, and how many people each user has invited. Users without an inviter (founding members or self-signups) appear at the root level, with their invite chains nested below.</p> The plugin works great with Discourse's native invite-only mode. If you enable invite-only registration, the tree visualization lets you see exactly how your community has grown through invites over time.</p> Back in 2017, someone on Meta asked about tracking referrals and invites</a>. People were using Data Explorer with custom SQL queries to see this data. This plugin makes it visual and accessible at /invite-tree</code>.</p> The implementation is straightforward: a recursive SQL query builds the tree from Discourse's native invite tables, and a Glimmer component renders it with monospace font and tree characters. The whole thing is about 600 lines.</p> I kept it minimal and hackable. No complex features, just a clean tree that adapts to your theme. If you want to customize how it looks or what it shows, the code is easy to modify.</p> Check it out: discourse-invite-tree on GitHub</a></p> Shelltrax Part 2: Footer, Tests, and CI Unknown — Wed, 29 Oct 2025 00:00:00 +0000 In Part 1</a>, I built the core of shelltrax</p> a TUI music player in Rust. It had library navigation, file browsing, audio playback, and a footer with song info and status. One big problem though, the footer would stop updating after the first song and I really wanted to fix that.</li> </ul> This post covers three improvements: implementing a proper footer with playback progress, adding unit tests for the tricky bits, and setting up CI to keep code quality high.</p> Running With A Limp</h2> The footer existed from early on (progress bar, time display, track info), but it had a critical bug: when autoplay advanced to the next track, the progress bar wouldn't reset. It would either keep counting from where the previous song left off, showing wrong times and eventually overflowing past 100% or it would just reset back to 0 and not progress. Whatever it did, it didn't work.</p> The bug was in play_next_track()</code>. It would set playback_start</code> and current_track</code>, but it wouldn't reset paused_duration</code> or paused_at</code>. If you paused the first song for 30 seconds, that 30 seconds would carry over to every subsequent song, throwing off the footer display completely.</p> Consolidation: begin_playback()</h2> The solution was extracting the timer reset logic into a dedicated method:</p> pub fn begin_playback(&mut self, track: &LibraryTrack) { self.current_track = Some(track.clone()); self.playback_start = Some(Instant::now()); self.paused_duration = Duration::ZERO; self.paused_at = None; self.playback_duration = track.duration.unwrap_or(0); } </code></pre> Now play_next_track()</code> calls begin_playback()</code> instead of manually setting fields. This ensures all timing state resets properly when advancing to the next song, whether manually or via autoplay.</p> Implementation: Tracking Time Correctly</h2> The app needs to track multiple timing values:</p> pub struct App { pub playback_start: Option<Instant>, pub playback_duration: u64, pub paused_at: Option<Instant>, pub paused_duration: Duration, // ... other fields } </code></pre> When a song starts, we record playback_start</code>. When the user pauses, we record paused_at</code>. When they unpause, we add the pause duration to paused_duration</code> and clear paused_at</code>.</p> The footer calculation looks like this:</p> let elapsed = if let Some(paused_at) = app.paused_at { paused_at.duration_since(start) } else { now.duration_since(start) }; let adjusted = elapsed.saturating_sub(app.paused_duration); </code></pre> If currently paused, elapsed time is frozen at the pause moment. Otherwise, it's the time since playback started. Then we subtract all the accumulated pause time to get the actual playback position.</p> The saturating_sub</code> is important. Without it, if paused_duration</code> somehow exceeded elapsed</code> (race condition, clock skew, whatever), you'd get an underflow panic. saturating_sub</code> clamps to zero instead.</p> Layout: Three Lines of Footer</h2> The footer uses a vertical layout with three lines:</p> let layout = Layout::default() .direction(Direction::Vertical) .constraints([ Constraint::Length(1), // Progress bar Constraint::Length(1), // Time display Constraint::Length(1), // Track info ]) .split(inner); </code></pre> Line 1 is a Gauge</code> widget showing the ratio of elapsed to total time. Line 2 shows MM:SS / MM:SS</code>. Line 3 shows Artist - Title - Album</code>.</p> The progress bar ratio:</p> let ratio = if total.as_secs_f64() > 0.0 { adjusted.as_secs_f64() / total.as_secs_f64() } else { 0.0 }; </code></pre> Clamp it to 1.0</code> max so the gauge doesn't overflow if the elapsed time somehow exceeds the track duration (can happen with malformed metadata).</p> Testing: What Actually Needs Tests?</h2> I'm not a fan of testing UI rendering code. It's tedious, fragile, and doesn't catch the bugs that matter. What I do test is the state management logic that the UI depends on.</p> For shelltrax, the critical logic is:</p> Playback state transitions (playing, paused, stopped)</li> Time tracking during pause/unpause cycles</li> Library state management (artist/album hierarchy)</li> </ul> I added two test modules: one in app.rs</code> for playback logic, one in library.rs</code> for library state.</p> Testing Playback State</h3> Four tests in app.rs</code>:</p> test_begin_playback_resets_timers:</strong></p> #[test] fn test_begin_playback_resets_timers() { let mut app = App::new(); app.playback_start = Some(Instant::now()); app.paused_duration = Duration::from_secs(10); app.paused_at = Some(Instant::now()); let track = create_test_track("test", 180); app.begin_playback(&track); assert!(app.playback_start.is_some()); assert_eq!(app.paused_duration, Duration::ZERO); assert!(app.paused_at.is_none()); } </code></pre> When starting a new track, all the timing state should reset. If it didn't, the footer would show stale pause data from the previous song.</p> test_toggle_pause_accumulates_paused_duration:</strong></p> #[test] fn test_toggle_pause_accumulates_paused_duration() { let mut app = App::new(); let start = Instant::now(); app.paused_at = Some(start); app.paused_duration = Duration::from_secs(5); app.toggle_pause(); // Unpause std::thread::sleep(Duration::from_millis(100)); app.toggle_pause(); // Pause again assert!(app.paused_at.is_none()); assert!(app.paused_duration > Duration::from_secs(5)); } </code></pre> This test verifies that pausing multiple times accumulates the total paused duration. The sleep</code> is gross but necessary to test time-based logic without mocking the clock (which would require dependency injection, which is overkill for a hobby project).</p> Testing Library State</h3> Six tests in library.rs</code> covering the artist/album/track hierarchy:</p> test_add_tracks_creates_structure:</strong></p> #[test] fn test_add_tracks_creates_structure() { let mut lib = LibraryState::new(); let tracks = vec![ create_test_track("Artist A", "Album 1", "Track 1", 1), create_test_track("Artist A", "Album 1", "Track 2", 2), create_test_track("Artist B", "Album 2", "Track 3", 1), ]; lib.add_tracks(tracks); assert_eq!(lib.artists.len(), 2); assert_eq!(lib.artists[0].name, "Artist A"); assert_eq!(lib.artists[0].albums.len(), 1); assert_eq!(lib.artists[0].albums[0].tracks.len(), 2); } </code></pre> This validates the library builds the correct tree structure when adding tracks. If the grouping logic broke, you'd end up with duplicate artists or albums in the wrong places.</p> test_visible_tracks_for_album:</strong></p> #[test] fn test_visible_tracks_for_album() { let mut lib = LibraryState::new(); lib.add_tracks(vec![ create_test_track("Artist", "Album 1", "Track 1", 1), create_test_track("Artist", "Album 1", "Track 2", 2), create_test_track("Artist", "Album 2", "Track 3", 1), ]); lib.selection = Some(LibrarySelection::Album { artist_index: 0, album_index: 0, }); let tracks = lib.visible_tracks(); assert_eq!(tracks.len(), 2); assert_eq!(tracks[0].title, "Track 1"); assert_eq!(tracks[1].title, "Track 2"); } </code></pre> The visible_tracks</code> method returns different results depending on whether an artist or an album is selected. This test ensures album selection filters correctly.</p> CI: Keeping Code Quality High</h2> GitHub Actions makes CI trivial for Rust projects. The workflow file:</p> name: test on: push: branches: [main] pull_request: branches: [main] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: install rust uses: dtolnay/rust-toolchain@stable with: components: clippy - name: cache dependencies uses: actions/cache@v4 with: path: \| ~/.cargo/bin/ ~/.cargo/registry/index/ ~/.cargo/registry/cache/ ~/.cargo/git/db/ target/ key: ${{ runner.os }}-cargo-${{ hashFiles('/Cargo.lock') }} - name: install system dependencies run: \| sudo apt-get update sudo apt-get install -y libasound2-dev - name: run tests run: cargo test --verbose - name: run clippy run: cargo clippy -- -D warnings </code></pre> The important bits:</p> Dependency caching:</strong> Without caching, every CI run would download and compile all dependencies from scratch. With caching, subsequent runs reuse compiled dependencies, dropping build time from several minutes to under 30 seconds.</p> System dependencies:</strong> The audio libraries (cpal, rodio) need ALSA headers to compile. libasound2-dev</code> provides those on Ubuntu.</p> Clippy with -D warnings</code>:</strong> This flag treats all warnings as errors. It's strict, but it keeps code quality high. If clippy suggests a fix, you either apply it or add an explicit #[allow(...)]</code> annotation explaining why you're ignoring it.</p> Results</h2> The footer works. Tests pass. CI keeps the codebase clean. Shelltrax now feels like a real music player instead of a tech demo.</p> Running cargo test</code> shows 10 passing tests:</p> running 10 tests test app::tests::test_begin_playback_resets_timers ... ok test app::tests::test_toggle_pause_accumulates_paused_duration ... ok test app::tests::test_toggle_pause_cycles_state ... ok test app::tests::test_toggle_pause_sets_paused_at ... ok test library::tests::test_add_tracks_creates_structure ... ok test library::tests::test_toggle_expanded ... ok test library::tests::test_track_by_path_finds_track ... ok test library::tests::test_track_by_path_returns_none_for_missing ... ok test library::tests::test_visible_tracks_for_album ... ok test library::tests::test_visible_tracks_for_artist ... ok test result: ok. 10 passed; 0 failed; 0 ignored; 0 measured </code></pre> And cargo clippy</code> stays green with zero warnings.</p> What's Next?</h2> The core functionality is solid, but there are still features I want:</p> config system</li> seeking</li> better metadata handling</li> vi keybindings</li> </ul> But for now, shelltrax does what I needed it to do: play music in the terminal with a proper UI that shows what's happening.</p> Code</strong>: github.com/ducks/shelltrax</a></p> Replacing MessageBus Pub/Sub with REST APIs: Fixing Production Outages Unknown — Mon, 27 Oct 2025 00:00:00 +0000 We're converting one of our infrastructure services from MessageBus pub/sub to a synchronous REST API. This isn't a protocol change or upgrade - both architectures use HTTP. This is about replacing fire-and-forget asynchronous messaging with request/response patterns that provide immediate feedback.</p> The control plane manages hundreds of Discourse forums across multiple data centers. It needs to orchestrate PostgreSQL user and database creation across these distributed clusters.</p> The Problem</h2> Our postgres-manager</code> service handles PostgreSQL user and database lifecycle for Discourse hosted sites. It was built using ServiceSkeleton</code>, a Ruby framework for message-driven services, subscribing to MessageBus channels for commands.</p> MessageBus uses HTTP long-polling for pub/sub messaging. Publishers send messages to channels, subscribers open long-lived HTTP connections and wait for messages to arrive. It works well for many use cases, but we've hit two critical problems:</p> No feedback mechanism. When the control plane published a message like "create database for site X", it had no way to know if the operation succeeded or failed. The message was sent and forgotten.</p> </li> Message replay on restarts. MessageBus keeps a backlog of messages. When postgres-manager restarts, it replays unacknowledged messages, causing duplicate operations. We've had multiple production outages from databases being recreated or users being decommissioned twice.</p> </li> </ol> The message replay issue is the immediate trigger, but the lack of feedback is the underlying architectural problem. We need synchronous request/response patterns with immediate success/failure feedback.</p> The Solution: REST API with Request/Response</h2> We're converting postgres-manager to a Sinatra HTTP service that responds synchronously to requests. Instead of subscribing to MessageBus channels, it will expose REST endpoints:</p> POST /databases</code> - Create database and user</li> DELETE /databases/:username</code> - Decommission database</li> POST /users</code> - Create user (triggers sync)</li> DELETE /users/:username</code> - Decommission user</li> POST /sync</code> - Sync all databases/users from control plane</li> </ul> Each endpoint will return an immediate response with proper HTTP status codes: 200 for success, 401 for auth failures, 400 for bad parameters, 500 for server errors.</p> Implementation</h2> Before: ServiceSkeleton with MessageBus</h3> The old implementation used ServiceSkeleton to subscribe to MessageBus:</p> message_bus = MessageBus::HTTPClient.new( config.control_plane_base_url, headers: { "Discourse-Access-Token" => config.control_plane_token } ) message_bus.subscribe(config.message_bus_channel) do \|message\| case message["type"] when "create_user", "create_db", "sync" sync when "decommission_db" decommission_db(message["dbname"]) when "decommission_user" decommission_user(message["username"]) end end </code></pre> The control plane would publish messages:</p> PostgresManagerPublisher.create_db(owner, cluster_name) # Fire and forget - no response </code></pre> After: Sinatra HTTP Service</h3> The new implementation uses Sinatra with proper HTTP patterns:</p> before do return if ["/health", "/metrics"].include?(request.path_info) auth_header = request.env["HTTP_AUTHORIZATION"] if !auth_header \|\| !auth_header.start_with?("Bearer ") halt 401, json(error: "Unauthorized", code: "AUTH_REQUIRED") end token = auth_header.sub("Bearer ", "") if token != config[:api_key] halt 401, json(error: "Unauthorized", code: "INVALID_TOKEN") end end post "/databases" do body = parse_json_body cluster = body["cluster"] username = body["username"] if cluster != config[:container_name] halt 400, json( error: "Cluster mismatch", code: "CLUSTER_MISMATCH", expected: config[:container_name], received: cluster ) end sync json( status: "success", message: "Database sync completed", cluster: cluster ) end delete "/databases/:username" do username = params["username"] decommission_db(username) json( status: "success", message: "Database decommissioned", username: username ) end </code></pre> The control plane will make HTTP requests and get immediate responses:</p> PostgresManagerHttpClient.create_db(owner, cluster_name) # Returns { "status" => "success", "message" => "..." } # Or raises PostgresManagerError on failure </code></pre> HTTP Client with Proper Error Handling</h2> The new HTTP client provides clear error handling:</p> class PostgresManagerHttpClient class PostgresManagerError < StandardError; end class PostgresManagerTimeout < PostgresManagerError; end class PostgresManagerAuthError < PostgresManagerError; end def self.create_db(owner, cluster_name) call_postgres_manager( cluster_name: cluster_name, method: :post, path: "/databases", body: { cluster: cluster_name, username: owner, action: "create" } ) end private def self.call_postgres_manager(cluster_name:, method:, path:, body: nil) api_key = ENV["POSTGRES_MANAGER_API_KEY"] raise "POSTGRES_MANAGER_API_KEY not configured" if !api_key base_url = ENV["POSTGRES_MANAGER_BASE_URL"] \|\| "http://postgres-manager-#{cluster_name}:9105" uri = URI("#{base_url}#{path}") http = Net::HTTP.new(uri.host, uri.port) http.open_timeout = 5 http.read_timeout = 30 request = case method when :post then Net::HTTP::Post.new(uri) when :delete then Net::HTTP::Delete.new(uri) end request["Authorization"] = "Bearer #{api_key}" request["Content-Type"] = "application/json" request.body = body.to_json if body begin response = http.request(request) case response.code.to_i when 200..299 return nil if response.body.to_s.empty? JSON.parse(response.body) when 401 raise PostgresManagerAuthError, "Authentication failed: #{response.body}" when 400..499 raise PostgresManagerError, "Client error (#{response.code}): #{response.body}" when 500..599 raise PostgresManagerError, "Server error (#{response.code}): #{response.body}" end rescue Net::OpenTimeout, Net::ReadTimeout raise PostgresManagerTimeout, "Request timed out for #{uri}" rescue Errno::ECONNREFUSED raise PostgresManagerError, "Connection refused to #{uri}" end end end </code></pre> Testing Strategy: Unit and Integration Tests</h2> The HTTP service has a test suite with 54 tests covering both unit and integration testing:</p> Unit Tests (16 tests, no PostgreSQL required)</h3> Unit tests use WebMock to stub external dependencies:</p> it "makes POST request to /databases with correct parameters" do stub_request(:post, "#{base_url}/databases") .with( body: { cluster: "flex001", username: "example", action: "create" }.to_json, headers: { "Authorization" => "Bearer test-api-key" } ) .to_return( status: 200, body: { status: "success", message: "Database sync completed" }.to_json ) result = PostgresManagerHttpClient.create_db("example", "flex001") expect(result["status"]).to eq("success") end </code></pre> These tests run fast (under 1 second) and validate HTTP client logic, metrics tracking, and configuration handling without requiring PostgreSQL.</p> Integration Tests (38 tests, with real PostgreSQL)</h3> Integration tests use Docker to automatically start/stop PostgreSQL and test real database operations:</p> it 'creates database and user' do multisite_config = { "example" => { "username" => "example", "password" => "test123", "database" => "example_discourse" } } stub_request(:get, "http://mothership.test/api/multisite_config?container_name=test-cluster") .to_return(status: 200, body: JSON.dump(multisite_config)) result = sync.perform # Verify in actual PostgreSQL sync.database.with_db('postgres') do \|db\| user_result = db.exec_params('SELECT usename FROM pg_user WHERE usename = $1', ['example']) expect(user_result.ntuples).to eq(1) db_result = db.exec_params('SELECT datname FROM pg_database WHERE datname = $1', ['example_discourse']) expect(db_result.ntuples).to eq(1) end end </code></pre> Idempotency Tests</h3> Critical tests verify the service handles message replay scenarios that caused production outages:</p> it 'handles rapid duplicate creates (race condition simulation)' do threads = 2.times.map do Thread.new do begin database.create(test_db, test_user) rescue PG::DuplicateDatabase # Expected - one thread wins, other gets duplicate error end end end threads.each(&:join) # Verify only one database created database.with_db('postgres') do \|db\| result = db.exec_params('SELECT datname FROM pg_database WHERE datname = $1', [test_db]) expect(result.ntuples).to eq(1) end end </code></pre> These tests validate that calling create operations multiple times (as happens during message replay) doesn't cause crashes or duplicate resources.</p> Migration Strategy</h2> We can't switch all clusters at once. The migration strategy:</p> Deploy HTTP version alongside MessageBus - Run both in separate containers</li> Test HTTP version manually - Verify endpoints work, check metrics</li> Switch control plane to HTTP - Deploy control plane changes, monitor logs</li> Clean up MessageBus - Stop old containers, remove environment variables</li> </ol> Both services can run simultaneously during migration, and rollback is just reverting the control plane code and restarting services.</p> Expected Results</h2> No more duplicate operations from message replay</li> Immediate visibility into success/failure</li> Proper error handling with retries</li> Easy to test with curl or standard HTTP tools</li> Can be load balanced through standard proxies</li> Standard HTTP monitoring and metrics</li> </ul> Outcomes</h2> Fire-and-forget messaging has hidden costs. The lack of feedback makes debugging production issues extremely difficult. We don't know if operations fail until customers complain.</p> </li> Message replay is a feature until it's a bug. MessageBus's backlog replay is useful for reliable message delivery, but causes havoc when operations aren't idempotent.</p> </li> Different HTTP patterns, same protocol. Both MessageBus (HTTP long-polling) and our REST API use HTTP for transport, but serve fundamentally different communication patterns. MessageBus uses HTTP to implement pub/sub messaging (asynchronous, one-to-many), while REST implements request/response (synchronous, one-to-one). The choice isn't HTTP vs something else - it's choosing the right messaging pattern for your use case.</p> </li> Testing gets easier with simpler patterns. The old MessageBus setup requires a full environment. The HTTP version can be tested with simple request/response stubs.</p> </li> </ol> Summary</h2> This migration will take our infrastructure service from fire-and-forget messaging to synchronous request/response patterns. The expected result: no more duplicate operations, immediate feedback on success/failure, and much simpler debugging. Sometimes the solution isn't choosing new technology - it's choosing the right pattern for your use case.</p> Current Status</h2> The HTTP service implementation is complete and tested:</p> Modular architecture with 6 separated modules (Config, Database, User, Client, Sync, Metrics)</li> Test suite (16 unit tests, 38 integration, all passing)</li> RuboCop clean (zero offenses)</li> Security fixes (parameterized queries, retry limits)</li> GitHub Actions CI configured and passing</li> </ul> The service is production-ready and awaiting deployment to test clusters. Once validated with real PostgreSQL operations and monitored for stability, we'll proceed with gradual rollout to production infrastructure.</p> Building The Guest Spot: Part 2 - Two Refactors Unknown — Sun, 26 Oct 2025 00:00:00 +0000 In Part 1</a>, I built an Instagram-style showcase using a custom GuestSpotPost</code> model. It worked. But it also meant maintaining a parallel data structure instead of leveraging what Discourse already provides.</p> This post covers two major refactors: first from custom models to Discourse Topics, then from custom feed infrastructure to plugin outlets. Each time, less code gave me more features.</p> Why Refactor?</h2> The custom model approach had problems:</p> Duplicate logic: Comments, moderation, spam protection already exist for Topics</li> Extra maintenance: Every time Discourse updates, potential breakage</li> Missing features: No native file upload, no revision history, no trust levels</li> More code: Separate serializers, separate permissions, separate everything</li> </ul> Discourse Topics already have everything we need:</p> First post holds the caption and images</li> Title can be auto-generated</li> Categories handle public vs private</li> Pinning is built-in</li> Commenting works out of the box</li> </ul> The showcase is just a custom view of Topics in the "Public Feed" category.</p> The Refactor</h2> Backend Changes</h3> Deleted the entire GuestSpotPost</code> model and migrations. Instead, the controller now works with Topics:</p> # app/controllers/guest_spot/posts_controller.rb def index category_id = CategoryHelper.public_feed_category_id topics = Topic .where(category_id: category_id) .where(deleted_at: nil) .includes(:user, posts: :uploads) .order(created_at: :desc) .limit(50) pinned_topics = Topic .where(category_id: category_id) .where(deleted_at: nil) .where.not(pinned_at: nil) .includes(:user, posts: :uploads) .order(created_at: :desc) render json: { posts: serialize_data(topics, GuestSpotPostSerializer), pinned: serialize_data(pinned_topics, GuestSpotPostSerializer) } end </code></pre> The serializer extracts what we need from Topics:</p> # app/serializers/guest_spot_post_serializer.rb class GuestSpotPostSerializer < ApplicationSerializer attributes :id, :user_id, :username, :caption, :image_urls, :created_at, :pinned def caption object.first_post&.raw \|\| "" end def image_urls object.first_post.uploads.map { \|upload\| UrlHelper.absolute(upload.url) } end def pinned object.pinned_at.present? end end </code></pre> Caption is the post content. Images come from uploads. Pinned status is the native pinned_at</code> field.</p> Creating Posts</h3> Instead of GuestSpotPost.create</code>, we use TopicCreator</code>:</p> def create category_id = CategoryHelper.public_feed_category_id title = "@#{current_user.username} - #{Time.now.to_i}" topic_creator = TopicCreator.new( current_user, Guardian.new(current_user), category: category_id, title: title, raw: params[:caption] \|\| "" ) topic = topic_creator.create render_serialized(topic, GuestSpotPostSerializer) end </code></pre> Auto-generated titles keep them unique. The caption goes in the first post's raw content. Image uploads attach automatically through Discourse's existing upload system.</p> Frontend Changes</h3> Frontend barely changed. The serializer provides the same JSON structure, so components worked as-is. The only update was changing @post.id</code> to reference topic IDs instead of custom model IDs.</p> What This Got Us</h3> The refactor from custom models to Topics gave us:</p> Comments work natively (no custom implementation)</li> Moderation tools work (flags, hiding, deleting)</li> File uploads work (native uploader)</li> Revision history works (edit tracking)</li> Trust levels work (spam protection)</li> All for free, by using what Discourse already provides</li> </ul> But I still had a custom feed with its own routes, controllers, and serializers. That was the next problem to solve.</p> Going Native: Deleting the Custom Feed</h2> In Part 1, I built a custom GuestSpotPost</code> model. Then I realized that was overkill and refactored to use Discourse Topics. But I kept the custom feed with its own routes, controllers, and serializers.</p> After implementing that custom feed, I realized there was an uncomfortable disconnect. Users would browse an Instagram-style feed, click a post, and suddenly land in Discourse's standard topic view. The context switch was jarring.</p> The question became: why maintain a custom feed at all? If the custom model was unnecessary, maybe the custom feed was too.</p> Discourse already has everything we need:</p> Category pages show topic lists</li> Category permissions control who can post and who can view</li> Native pinning highlights featured content</li> Theme system allows extensive visual customization</li> </ul> Instead of maintaining a parallel feed system, we could just make the Public Feed category look great using plugin outlets.</p> The Deletion</h3> I deleted the entire custom feed infrastructure:</p> Removed (1,078 lines)</strong>:</p> Custom feed routes and controllers (guest_spot/feed_controller.rb</code>, guest_spot/posts_controller.rb</code>)</li> Custom post serializer (guest_spot_post_serializer.rb</code>)</li> All custom Ember components (guest-spot-feed.gjs</code>, guest-spot-post-card.gjs</code>)</li> Custom route definitions and templates</li> Multiple initializers for hiding UI elements</li> </ul> Added (264 lines)</strong>:</p> Single plugin outlet connector: assets/javascripts/discourse/connectors/topic-list-item/guest-spot-item.gjs</code></li> CSS Grid layout for responsive cards</li> </ul> Net result: 814 fewer lines of code.</p> Plugin Outlets: The Right Pattern</h3> Discourse provides plugin outlets - extension points where plugins can inject custom HTML. There are two types:</p> Regular outlets</strong> inject content but Discourse still renders the default elements. Wrapper outlets</strong> completely replace the template.</p> I used the topic-list-item</code> wrapper outlet to completely replace how topics display in the Public Feed category:</p> import Component from "@glimmer/component"; import avatar from "discourse/helpers/avatar"; import replaceEmoji from "discourse/helpers/replace-emoji"; import formatDate from "discourse/helpers/format-date"; export default class GuestSpotItem extends Component { get isPublicFeed() { return this.args.outletArgs?.topic?.category?.slug === "public-feed"; } get truncatedExcerpt() { const excerpt = this.args.outletArgs?.topic?.excerpt \|\| ""; if (excerpt.length <= 50) { return excerpt; } return excerpt.substring(0, 50) + "..."; } <template> {{#if this.isPublicFeed}} <td class="topic-list-data guest-spot-card"> <div class="guest-spot-author"> <a href="/u/{{this.args.outletArgs.topic.creator.username}}"> {{avatar this.args.outletArgs.topic.creator imageSize="medium"}} <span class="username"> {{this.args.outletArgs.topic.creator.username}} </span> </a> </div> <div class="guest-spot-image"> <a href={{this.args.outletArgs.topic.url}}> <img src={{this.args.outletArgs.topic.image_url}} alt="" /> </a> </div> <div class="guest-spot-excerpt"> {{replaceEmoji this.truncatedExcerpt}} </div> <div class="guest-spot-metadata"> <div class="meta-item"> Views: {{this.args.outletArgs.topic.views}} </div> <div class="meta-item"> Replies: {{this.args.outletArgs.topic.posts_count}} </div> <div class="meta-item"> Posted: {{formatDate this.args.outletArgs.topic.createdAt leaveAgo=true}} </div> </div> </td> {{else}} {{@default}} {{/if}} </template> } </code></pre> The component checks if we're in the public-feed category. If yes, render the custom card layout. If no, render the default ({{@default}}</code>).</p> CSS Grid for Responsive Layout</h3> Instead of JavaScript handling the layout, CSS Grid does all the work:</p> .category-public-feed { .topic-list { display: grid; grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); gap: 1.5rem; @media (max-width: 480px) { grid-template-columns: 1fr; } tr.topic-list-item { display: flex; flex-direction: column; border-radius: 8px; overflow: hidden; background: var(--primary-very-low); transition: transform 0.2s; &:hover { transform: translateY(-2px); } } } } </code></pre> On mobile, it collapses to a single column. On tablet and desktop, it flows naturally based on available space.</p> </p> </p> Discovery Process</h3> Finding the right plugin outlet took some research. I used rg</code> to search Discourse core for available outlets:</p> rg "PluginOutlet" app/assets/javascripts/discourse/app/components/ \ \| grep topic-list </code></pre> Found several candidates:</p> topic-list-before-link</code> - Injects before the title link (still renders default content)</li> topic-list-after-title</code> - Injects after the title (still renders default content)</li> topic-list-item</code> - Wrapper outlet (replaces entire template)</li> </ul> The wrapper outlet was key. Regular outlets would have shown both my custom card and the default topic row, creating duplicate content.</p> What Works Now</h3> The native approach gives us:</p> Comments work out of the box (no custom implementation needed)</li> All Discourse features work (moderation, flags, bookmarks, etc.)</li> 814 fewer lines of code to maintain</li> Better mobile support (Grid automatically adapts)</li> No custom API (no serializers, controllers, or routes)</li> Pin/unpin still works (using Discourse's native pinning)</li> </ul> The showcase is now just "a really nicely styled Discourse category" instead of "a custom app built on top of Discourse."</p> Vibe Coding: Pros and Cons</h2> This project is a perfect example of "vibe coding" - building something by feel, iterating quickly, and learning what works through trial and error.</p> I started with a custom model because that felt right. Then I realized Topics already did everything I needed. I built a custom feed because I wanted full control. Then I realized plugin outlets gave me that control without the maintenance burden.</p> The downside</strong>: I went too fast and tried too much. Each iteration meant throwing away code. The custom model, the custom feed infrastructure - all that work ended up deleted. If I'd researched Discourse patterns first, I could have gone straight to the plugin outlet approach.</p> The upside</strong>: I learned way more by doing it wrong first. I understand why wrapper outlets exist, because I felt the pain of duplicate content with regular outlets. I understand why Discourse's native features are powerful, because I tried to rebuild them and saw how much work that is.</p> Fast iteration meant I could course-correct. I wasn't six months into building a custom ORM before realizing Topics existed. I was a few days in, so refactoring didn't hurt. The velocity of vibe coding let me try ideas, see them fail, and pivot quickly.</p> The final result is simple and maintainable. It took three iterations to get there, but each iteration taught me something. Now I know how to not do things, which is just as valuable as knowing how to do them.</p> The code is on GitHub: discourse-guest-spot</a></p> Building The Guest Spot: Part 1 - My First Community Unknown — Sat, 25 Oct 2025 00:00:00 +0000 I'm not exactly a social butterfly. I can enjoy small groups of like minded people talking about our interests but small talk really drains me. I'm much happier with a computer, book, or just sitting out in the woods.</p> Since joining Discourse a few months ago, I've been learning the platform by building weird experiments. A transit departure board. A virtual currency system. Tools that push Discourse in directions it wasn't designed for. But they've all been technical exercises. Solo projects. Learning by doing, but doing alone.</p> The Guest Spot is different. This is my first time helping build something for an actual community of people. Real artists who will (hopefully) use this thing. Not just me poking at APIs and seeing what breaks.</p> It's exciting. And a little terrifying.</p> How The Idea Evolved</h2> The original concept was simple: a private forum for tattoo artists. A place where people in the industry could talk shop, share techniques, discuss challenges. No clients. No tourists. Just professionals.</p> But then I started thinking about how artists actually share their work. Instagram. Almost every tattoo artist is on Instagram. It's where they build their portfolio, attract clients, establish their style. But they don't own any of it. The algorithm decides who sees their posts. Instagram decides what gets buried or promoted. If Instagram changes the rules or shuts down tomorrow, years of work disappears.</p> What if artists could have both? A professional forum for discussion and a public showcase for their work. Same platform, same data, but they own it all. No algorithm deciding what gets seen. No corporate platform that could pull the rug out.</p> That's when the concept clicked: build the Instagram-style feed as the front door, with the private forum as the main room. Artists get a beautiful public portfolio plus a real community space. All on infrastructure they control.</p> What Is The Guest Spot?</h2> The result: an Instagram-style public showcase for tattoo artists, powered by Discourse.</p> Artists can post photos of their work in a clean, visual feed. Pinned posts appear in a horizontal carousel at the top. Recent work flows down below in a responsive grid. Click any image and you get a full detail page with all the context.</p> And if you've been vetted, behind the public feed is a private, invite-only Discourse forum. The showcase is the front door. The forum is where the real community happens. Artists can discuss techniques, share experiences, ask questions. It's gated access because tattoo culture values quality and trust.</p> Think of it as Instagram's visual presentation meets forum depth, with Discourse handling both sides.</p> Why Discourse Makes Sense Here</h2> Discourse isn't Instagram. It's not designed to be a photo showcase. But it has everything we need to build one:</p> Custom fields store image URLs and captions. Categories and tags organize content. The permission system handles public showcase vs private forum.</p> Most importantly, Discourse is built for communities. The forum infrastructure is already there. We're just adding a pretty front door.</p> And unlike Instagram, artists own everything. The database, the images, the content. They can export it all. No algorithm. No corporate overlord. Just their work, on their terms.</p> What I've Built So Far</h2> Backend is straightforward Rails stuff:</p> GuestSpotPost</code> model with image URLs (stored as arrays), captions, and pinned status</li> Migrations for the database schema</li> Controllers that handle CRUD operations and serve JSON to the frontend</li> Serializers that package post data with user info</li> </ul> Frontend is where it gets interesting. Modern Discourse uses Glimmer components, which are Ember's latest component format. Template and logic live in the same .gjs</code> file:</p> export default class GuestSpotPostCard extends Component { get firstImage() { return this.args.post.image_urls?.[0]; } <template> <LinkTo @route="guest-spot-post" @model={{@post.id}} class="guest-spot-post-card"> {{#if this.firstImage}} <img src={{this.firstImage}} alt={{@post.caption}} class="post-image" /> {{/if} <div class="post-meta"> <div class="post-author"> {{avatar @post.user imageSize="small"}} <span class="username">{{@post.user.username}}</span> </div> {{#if @post.caption}} <p class="post-caption">{{@post.caption}}</p> {{/if}} {{#if @post.pinned}} <span class="pinned-badge">Featured</span> {{/if}} </div> </LinkTo> </template> } </code></pre> The card is a link. Click it, you go to the full post page. The whole thing is wrapped in a LinkTo</code> component so the entire card is interactive.</p> The Feed Page</h2> </p> Two sections: pinned posts in a horizontal carousel, recent posts in a responsive grid.</p> The carousel uses CSS flexbox with scroll-snap-type: x mandatory</code> so it feels smooth on mobile. On phones, each card takes up 80% of the viewport width. On tablets, 250px. On desktop, 300px. Pure CSS, no JavaScript.</p> The grid uses CSS Grid with auto-fill</code> and minmax()</code>:</p> .posts-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(250px, 1fr)); gap: 1.5rem; @media (max-width: 768px) { grid-template-columns: repeat(auto-fill, minmax(150px, 1fr)); gap: 1rem; } @media (max-width: 480px) { grid-template-columns: 1fr; gap: 0.75rem; } } </code></pre> On phones, we force a single column so cards stay large enough to see the artwork clearly. On tablets and desktops, it flows naturally based on available space.</p> The Post Page</h2> </p> Click any card and you get the full post view. It's designed to let the artwork breathe while keeping all the important context visible.</p> The layout is simple:</p> Back link at the top (returns to feed)</li> Full-size image(s) with object-fit: contain</code> so nothing gets cropped</li> Artist info (avatar + username)</li> Full caption with preserved line breaks</li> Pinned badge if applicable</li> </ul> Images are wrapped in a card design with rounded corners and subtle shadow. On mobile, padding reduces and max image height adjusts so everything fits nicely on smaller screens. The whole page uses the same responsive breakpoints as the feed (768px for tablets, 480px for phones).</p> All contained in a centered column with max-width of 900px. Clean, focused, lets the work be the star.</p> Hiding the Sidebar</h2> Guest Spot has its own route at /guest-spot</code>. But Discourse has a persistent sidebar. For a public showcase, that doesn't make sense. Artists posting work shouldn't see forum navigation.</p> First attempt: route lifecycle hooks.</p> export default class GuestSpotFeedRoute extends DiscourseRoute { activate() { super.activate(...arguments); const appController = this.controllerFor("application"); appController.set("showSidebar", false); document.body.classList.add("guest-spot-page"); } deactivate() { const appController = this.controllerFor("application"); appController.set("showSidebar", true); document.body.classList.remove("guest-spot-page"); super.deactivate(...arguments); } } </code></pre> This hides the sidebar. But the hamburger button (.header-sidebar-toggle</code>) stays visible. Users can toggle it back. Not ideal.</p> CSS didn't work. Setting controller properties didn't work. So I got pragmatic: DOM manipulation via an initializer.</p> export default { name: "hide-sidebar-toggle-on-guest-spot", initialize() { withPluginApi("0.8", (api) => { api.onPageChange((url) => { const toggle = document.querySelector(".header-sidebar-toggle"); if (toggle) { if (url.startsWith("/guest-spot")) { toggle.style.display = "none"; } else { toggle.style.display = ""; } } }); }); }, }; </code></pre> Is it hacky? Yes. Does it work? Also yes. Sometimes pragmatic beats perfect.</p> Mobile Responsive</h2> Mobile-first isn't just a buzzword here. It's critical. Tattoo artists live on their phones. They're checking Instagram between clients, browsing artist portfolios while waiting for appointments, posting fresh work right after finishing a piece. If this doesn't work perfectly on a phone, it doesn't work at all.</p> The entire layout is mobile-first. Every component has media queries for tablet and phone breakpoints.</p> Carousel cards shrink to 80% viewport width on phones so you can see part of the next card (scroll hint). Grid forces a single column on small screens so cards don't get comically tiny. Post detail pages reduce padding and image heights so everything fits nicely without excessive scrolling.</p> All CSS. No JavaScript calculating widths or handling resize events. The browser does the work, which means it's fast and doesn't drain battery with constant calculations.</p> What's Next</h2> This is Part 1. We've got the public showcase working. But there's more to build:</p> Post creation UI (artists need to upload images and write captions)</li> Admin controls (pin/unpin posts from the feed)</li> User profile pages (view all posts by a specific artist)</li> Comments system integration (if we want interaction on posts)</li> </ul> But most importantly: actually launching this for a real community. Getting feedback from artists. Seeing if this makes sense to people who aren't me.</p> That's the scary part. Building code is easy. Building for people? That's where it gets real.</p> Part 2 will cover the creation flow and admin tools. Stay tuned.</p> If you want to see the code, it's on GitHub: discourse-guest-spot</a></p> How I'm Using Claude Code for Daily Development Work Unknown — Fri, 24 Oct 2025 00:00:00 +0000 I've been using Claude Code for a few months now as my primary development assistant. Not as a replacement for thinking, but as a way to move faster on the boring stuff while keeping the interesting problems for myself.</p> What It's Actually Good At</h2> The Grunt Work</h3> Testing infrastructure is where Claude shines. Today, I needed to test SMTP error logging improvements. Instead of manually setting up mail-relay-simulator</a>, configuring different failure scenarios, and writing test cases, I described what I needed and got a complete Ruby script that:</p> Manages docker-compose lifecycle</li> Switches between 4 test scenarios (auth failures, wrong credentials, etc.)</li> Writes proper config files with correct syntax</li> Handles cleanup</li> </ul> The script works. It's maintainable. It saved me 2-3 hours of tedious setup work.</p> Research and Discovery</h3> "Find all the places in this codebase where we do X" - this is tedious grep work that Claude excels at. It can search, cross-reference, and explain patterns without me needing to open 20 files.</p> Example: When investigating AWS SDK credential chain bugs, I had Claude trace through the entire credential provider chain, find where it was failing, and document the root cause. That kind of code archaeology is perfect for AI assistance.</p> Documentation</h3> Writing test results documentation, commit messages, technical proposals - Claude can take my rough notes and produce clean markdown that I'd never bother writing myself. The writeup exists because the AI made it low-effort, not because I suddenly got better at documentation.</p> Where It Could Improve</h2> Understanding Intent</h3> If I'm not specific about what I want, Claude will give me something that technically works but misses the point. Example: I asked for markdown rendering in Neovim. Got three different failed attempts at split-window rendering before I just said "fuck it, just hard-wrap at 80 characters."</p> The AI doesn't know when to stop. It will keep trying increasingly complex solutions when the answer is "do less."</p> Production Debugging</h3> When real production issues happen, Claude's knowledge cutoff and lack of access to live systems means it's guessing. I can describe symptoms and it'll suggest things to check, but it's not replacing actual debugging experience.</p> Knowing What It Doesn't Know</h3> The worst thing Claude does is hallucinate with confidence. It'll make up photographer names for Unsplash images when WebFetch fails to parse the page. It'll suggest APIs that don't exist. It'll confidently explain behavior that's completely wrong.</p> You have to verify everything. Trust but verify isn't optional.</p> How I Actually Use It</h2> 1. Explicit Context</h3> I maintain a CONTEXT.md file with my preferences:</p> Code style (no emoji, wrap at 80 chars, prefer if !</code> over unless</code>)</li> Project patterns (date-based versioning, git workflow preferences)</li> Common pitfalls (Ruby openssl gem vs extension, Discourse auth patterns)</li> </ul> This cuts down on back-and-forth. Claude knows I want --no-ff</code> merges without me explaining it every time.</p> 2. Incremental Validation</h3> I don't let Claude write 500 lines without checking. Small changes, validate, next change. When it starts going off track, I stop and correct immediately.</p> If tests fail, I read the error myself. If code looks weird, I ask "why did you do it this way?" and often realize there's a better approach.</p> 3. Use It For What It's Built For</h3> Good uses:</p> File operations (read, edit, search)</li> Repetitive code changes</li> Documentation generation</li> Test script creation</li> Config file management</li> </ul> Bad uses:</p> Anything requiring judgment calls</li> Performance optimization without profiling</li> Security-sensitive code review</li> "Just make it work" prompts</li> </ul> 4. Keep Notes</h3> I have Claude maintain daily notes of what we worked on. Not as todo tracking, but as a context refresh. When I come back tomorrow, I can read yesterday's notes and pick up where we left off.</p> The notes also catch when Claude forgets something or contradicts earlier decisions.</p> The Workflow</h2> Typical session:</p> Me</strong>: "I need to test SMTP error logging with mail-relay-simulator"</li> Claude</strong>: Reads existing code, finds simulator location, proposes script structure</li> Me</strong>: "Yeah but make it modular, don't hardcode paths"</li> Claude</strong>: Updates script with env var + path discovery</li> Me</strong>: Runs script, hits error</li> Claude</strong>: "That error means X, here's the fix"</li> Me</strong>: Applies fix, tests, moves on</li> </ol> It's not magic. It's a very fast junior developer who never gets tired but also never learns from mistakes unless you tell it explicitly.</p> The Trap</h2> The trap is letting the AI do your thinking. It's really easy to just accept the first solution that looks reasonable. But "looks reasonable" and "is correct" aren't the same thing.</p> I caught Claude trying to use Dir.chdir</code> in a script today. RuboCop flagged it as not thread-safe. The "correct" solution was system(..., chdir: path)</code>. Claude didn't know that until the linter told it.</p> If I'm not reading the code and understanding the changes, I'm just a very expensive copy-paste machine.</p> Should You Use It?</h2> If you're junior: Maybe not yet. You need to build pattern recognition before you can effectively verify AI output. You won't know when it's bullshitting.</p> If you're mid-level: Useful for grunt work, but keep it on a short leash. You should be reading and understanding every change.</p> If you're senior: This is productivity steroids. You already know what good code looks like. AI just makes it faster to write.</p> Final Thoughts</h2> Claude Code isn't replacing developers. It's replacing the boring parts of development. The parts where you know exactly what needs to happen but it's going to take an hour of tedious typing.</p> I'm not using less brain power. I'm using it on the problems that actually matter instead of fighting with test harness boilerplate.</p> That's the win.</p> Building Yaks: A Virtual Currency System for Discourse (Part 4: Custom Titles and Earning System) Unknown — Sun, 19 Oct 2025 00:00:00 +0000 Part 1</a> covered the backend architecture, Part 2</a> covered topic pinning and expiration, and Part 3</a> covered topic boosting and custom avatar flair. This post covers two more major features: custom user titles and the automatic earning system.</p> Custom User Titles</h2> Custom titles let users spend Yaks to set a custom title displayed next to their username throughout the forum. Unlike Discourse's built-in title system (which is tied to badges and trust levels), Yak titles are purely cosmetic and time-limited.</p> </p> The Challenge: Serializer Discovery</h3> The first attempt seemed straightforward: override the title</code> field in the user serializers. But after implementing it, the title showed in user cards and profiles but not next to posts. Why?</p> Discourse uses different serializer methods for different contexts:</p> title</code>: Used in user cards, profiles, group member lists</li> user_title</code>: Used specifically in PostSerializer</code> for post display</li> </ul> This makes sense from an architecture perspective. Posts need their own serializer method because they serialize the user as a nested object, not as the main object.</p> The Solution: Override Both</h3> The fix required overriding both serializer methods across multiple serializers:</p> # For user cards, profiles, groups [:post, :user_card, :post_action_user, :user_name, :group_post_user, :group_user, :hidden_profile].each do \|serializer_name\| add_to_serializer(serializer_name, :title) do title_data = object.custom_fields["yak_features"]&.dig("title") if title_data && title_data["enabled"] title_data["text"] else object.title end end end # For post display (critical!) add_to_serializer(:post, :user_title) do user = object&.user return nil unless user title_data = user.custom_fields["yak_features"]&.dig("title") if title_data && title_data["enabled"] title_data["text"] else user.title end end </code></pre> In PostSerializer</code>, object</code> is a Post, so we access the user via object.user</code>. In user-focused serializers, object</code> is the User directly.</p> The Frontend Modal</h3> </p> The custom title modal is straightforward:</p> @tracked customTitle = ""; get characterCount() { return this.customTitle.length; } get isOverLimit() { return this.characterCount > 50; } get canApply() { return this.customTitle.trim().length > 0 && !this.isOverLimit && this.currentUser.yak_balance >= this.cost; } </code></pre> Live preview, character counter, balance check. The modal shows exactly what the title will look like before spending Yaks.</p> The Earning System</h2> This was the most complex feature to implement. Users needed a way to earn Yaks by contributing to the community, with anti-gaming measures built in.</p> Requirements</h3> From the start, the requirements were clear:</p> Be modular (database-driven, not hardcoded)</li> Rate limiting (can't spam posts to farm Yaks)</li> Trust level requirements (new accounts can't abuse it)</li> Content length minimums (beyond Discourse's defaults, prevent low-effort farming)</li> </ol> Database Schema</h3> Instead of hardcoding earning rules in the service, we made them database-driven:</p> create_table :yak_earning_rules do \|t\| t.string :action_key, null: false t.string :action_name, null: false t.text :description t.integer :amount, null: false, default: 0 t.integer :daily_cap, null: false, default: 0 t.integer :min_trust_level, null: false, default: 0 t.boolean :enabled, null: false, default: true t.jsonb :settings, default: {} t.timestamps end </code></pre> Seeded with four default rules:</p> Post Created</strong>: 2 Yaks, 20/day cap, TL1+, 20 character minimum</li> Topic Created</strong>: 5 Yaks, 10/day cap, TL1+, 50 character minimum</li> Post Liked</strong>: 3 Yaks, 30/day cap, TL1+</li> Solution Accepted</strong>: 25 Yaks, no cap, TL1+</li> </ol> The settings</code> jsonb column allows flexible per-rule configuration like content length minimums without schema changes.</p> Service Layer</h3> YakEarningService</code> handles all validation and awarding logic:</p> def self.award(user:, action_key:, related_post: nil, related_topic: nil) rule = YakEarningRule.get_rule(action_key) return false if !rule # Check trust level requirement return false if user.trust_level < rule.min_trust_level # Check minimum content length if applicable if rule.min_length > 0 content = related_post&.raw \|\| related_topic&.first_post&.raw \|\| "" return false if content.length < rule.min_length end # Check daily cap if rule.has_daily_cap? earned_today = get_daily_earning_count(user, action_key) return false if earned_today >= rule.daily_cap end # Award the Yaks wallet = YakWallet.find_or_create_by(user: user) YakTransaction.create!( user: user, yak_wallet: wallet, amount: rule.amount, transaction_type: "earn", description: "Earned from: #{rule.action_name}", related_post: related_post, related_topic: related_topic, ) wallet.update!(balance: wallet.balance + rule.amount) # Publish balance update to frontend MessageBus.publish("/yak-balance/#{user.id}", { balance: wallet.balance }, user_ids: [user.id]) true end </code></pre> The service returns a boolean so we can track success/failure in logs.</p> Rate Limiting Implementation</h3> Daily caps are enforced by counting today's transactions:</p> def self.get_daily_earning_count(user, action_key) wallet = YakWallet.find_by(user: user) return 0 if !wallet rule = YakEarningRule.find_by(action_key: action_key) return 0 if !rule start_of_day = Time.zone.now.beginning_of_day YakTransaction .where(yak_wallet: wallet) .where(transaction_type: "earn") .where("description LIKE ?", "Earned from: #{rule.action_name}") .where("created_at >= ?", start_of_day) .count end </code></pre> Single query per award attempt. Could be cached if it becomes a bottleneck, but the query is fast.</p> Event Hooks</h3> Discourse provides events for all the actions we care about:</p> DiscourseEvent.on(:post_created) do \|post, opts, user\| next if post.post_type != Post.types[:regular] next if post.deleted_at.present? next if post.hidden next if !post.user YakEarningService.award( user: post.user, action_key: "post_created", related_post: post, related_topic: post.topic, ) end DiscourseEvent.on(:like_created) do \|post_action\| post = post_action.post next if !post next if post.deleted_at.present? next if post.hidden next if post.user_id == post_action.user_id # No self-likes YakEarningService.award( user: post.user, action_key: "post_liked", related_post: post, related_topic: post.topic, ) end </code></pre> We also hook topic_created</code> and accepted_solution</code> (from the discourse-solved plugin, if installed).</p> Real-Time Balance Updates</h3> The original implementation had a problem: after earning Yaks, the user menu still showed the old balance. Page refresh required.</p> The fix uses MessageBus, Discourse's real-time messaging system:</p> Backend</strong>: Publish when balance changes</p> MessageBus.publish("/yak-balance/#{user.id}", { balance: wallet.balance }, user_ids: [user.id]) </code></pre> Frontend</strong>: Subscribe and update</p> const messageBus = container.lookup("service:message-bus"); messageBus.subscribe(`/yak-balance/${currentUser.id}`, (data) => { currentUser.set("yak_balance", data.balance); }); </code></pre> Now when you create a post, the balance in your user menu updates instantly. No polling, no page refresh.</p> Bugs Fixed</h2> Some bugs were discovered during manual testing. All three would have been caught immediately by integration tests.</p> Bug 1: Event Hook User Parameter</h3> The Discourse event signature includes a user</code> parameter:</p> DiscourseEvent.on(:post_created) do \|post, opts, user\| </code></pre> The first implementation used that parameter directly:</p> YakEarningService.award(user: user, ...) </code></pre> But that user</code> parameter is nil. The actual user must be accessed via post.user</code>. The test would have failed immediately with "User can't be blank".</p> Bug 2: Topic.raw Doesn't Exist</h3> Content length validation tried to access topic.raw</code>:</p> content = related_post&.raw \|\| related_topic&.raw \|\| "" </code></pre> But topics don't have a raw</code> field. Only posts do. The fix:</p> content = related_post&.raw \|\| related_topic&.first_post&.raw \|\| "" </code></pre> A test creating a topic would have crashed with "undefined method `raw' for Topic".</p> Bug 3: Missing User in Transaction</h3> YakTransaction</code> has a belongs_to :user</code> association, which validates presence by default in Rails. But we weren't passing it:</p> YakTransaction.create!( yak_wallet: wallet, amount: rule.amount, ... ) </code></pre> Should be:</p> YakTransaction.create!( user: user, yak_wallet: wallet, amount: rule.amount, ... ) </code></pre> Any test attempting to create a transaction would have failed validation.</p> A New Basic Test Suite Structure</h2> The test suite covers all validation paths:</p> RSpec.describe YakEarningService do describe ".award" do it "awards Yaks for valid post by TL1 user" do post = Fabricate(:post, user: user, raw: "This is a test post...") result = YakEarningService.award( user: post.user, action_key: "post_created", related_post: post, related_topic: post.topic, ) expect(result).to eq(true) expect(user.reload.yak_balance).to eq(2) end it "does not award Yaks to TL0 user" do post = Fabricate(:post, user: tl0_user, raw: "...") result = YakEarningService.award( user: post.user, action_key: "post_created", related_post: post, ) expect(result).to eq(false) expect(tl0_user.reload.yak_balance).to eq(0) end it "respects daily cap" do rule = YakEarningRule.find_by(action_key: "post_created") # Create posts up to daily cap rule.daily_cap.times do post = Fabricate(:post, user: user, raw: "...") YakEarningService.award(user: post.user, ...) end # Next post should fail due to cap post = Fabricate(:post, user: user, raw: "...") result = YakEarningService.award(user: post.user, ...) expect(result).to eq(false) end end end </code></pre> Tests force you to think about edge cases: trust levels, content length, daily caps, disabled rules.</p> Admin UI</h2> </p> The admin UI shows all earning rules in a table:</p> Action name and description</li> Amount of Yaks awarded</li> Daily cap (or "No limit")</li> Minimum trust level</li> Enabled status</li> </ul> Architecture Wins</h2> Database-Driven Configuration</strong>: No code changes needed to adjust earning amounts or daily caps. Just update the database.</p> Event-Driven</strong>: Loosely coupled. The earning system doesn't need to know about post creation internals, just subscribes to events.</p> Real-Time Updates</strong>: MessageBus makes instant balance updates trivial. Six lines of code for publish and subscribe.</p> Proper Service Layer</strong>: Business logic lives in YakEarningService</code>, not scattered across controllers and models.</p> Full Audit Trail</strong>: Every earning action creates a transaction record with type, amount, description, and related post/topic. Complete history.</p> Performance Considerations</h2> Single Query for Rate Limiting</strong>: The daily count query is simple and fast. Could be cached if it becomes a bottleneck.</p> No N+1 Queries</strong>: Balance updates happen during the transaction creation, no separate queries.</p> MessageBus Efficiency</strong>: Only publishes to the specific user who earned Yaks. Not broadcasting to everyone.</p> Indexed Properly</strong>: Transactions table has indexes on yak_wallet_id</code>, transaction_type</code>, and created_at</code> for the daily count query.</p> What's Left</h2> The plugin is now feature-complete for the MVP:</p> Wallet system with transaction logging</li> Multiple purchasable features (post highlighting, topic boosting, custom flair, custom titles)</li> Expiration system (features automatically expire)</li> Earning system (users earn Yaks by contributing)</li> Admin UI (view stats, packages, features, earning rules)</li> Real-time updates (no page refresh needed)</li> </ul> Remaining work:</p> Payment integration (Stripe or similar) for purchasing Yak packages</li> Guardian authorization checks (ensure users can only spend their own Yaks)</li> More earning actions (first reply, helpful flags, etc.)</li> Admin edit functionality for earning rules</li> Production monitoring and adjustment based on real usage</li> </ul> Lessons Learned</h2> Serializers Are Powerful</strong>: Understanding Discourse's serializer architecture unlocks a lot of customization possibilities.</p> MessageBus Is Handy</strong>: Real-time updates are easy with MessageBus, yet some plugins don't use it.</p> Database-Driven Config Is Worth It</strong>: The upfront effort to make earning rules configurable pays off in flexibility.</p> Event Hooks Are Reliable</strong>: Discourse's event system is solid. Events fire consistently and provide the data you need.</p> Conclusion</h2> Building a virtual currency system is teaching me a lot about Discourse's architecture. Serializers, custom fields, MessageBus, service objects, event hooks - all pieces that work together to create a cohesive plugin.</p> The earning system was the most complex feature, but also the most rewarding. Watching a user create a post and seeing their balance update instantly, knowing that every piece of the system is working together (event hooks, service validation, database transactions, MessageBus publishing, frontend subscription) - that's satisfying.</p> The full source code is available at github.com/ducks/discourse-yaks</a>. If you're building a Discourse plugin and want to see how all these pieces fit together, the repo should be a useful reference.</p> Next up: Payment integration and production deployment. Stay tuned for Part 5.</p> Building Yaks: A Virtual Currency System for Discourse (Part 3: Advanced Features) Unknown — Sat, 18 Oct 2025 00:00:00 +0000 Part 1</a> covered the backend architecture and Part 2</a> covered topic pinning and the expiration system. This post covers two more complex features: topic boosting (pinning topics globally with visual highlighting) and custom avatar flair (letting users customize their forum identity).</p> Topic Pin vs Topic Boost</h2> The plugin has two topic pinning features with different scopes:</p> Topic Pin</strong>: Pins a topic to the top of its category only. The topic stays at the top of the category page but doesn't appear across other categories. No visual highlighting.</p> Topic Boost</strong>: Pins a topic globally across all categories AND adds a colored border to make it stand out in topic lists. Much more visibility, costs more Yaks.</p> This post focuses on topic boost, the more powerful and visually striking feature.</p> Topic Boost: Making Threads Stand Out</h2> Topic boost is a premium feature that pins a topic globally (across all categories) and adds a colored border to make it stand out in topic lists.</p> </p> Backend: Leveraging Discourse APIs</h3> Discourse has native topic pinning built in. The API is straightforward:</p> topic.update_pinned(status, global, pinned_until) </code></pre> Parameters:</p> status</code>: true to pin, false to unpin</li> global</code>: true for global pin (all categories), false for category only</li> pinned_until</code>: timestamp as string (not Time object)</li> </ul> The service implementation for topic boost:</p> when "topic_boost" duration = feature.settings["duration_hours"]&.hours \|\| 72.hours related_topic.update_pinned(true, true, duration.from_now.to_s) current_features = related_topic.custom_fields["yak_features"] \|\| {} current_features["boosted"] = { enabled: true, color: feature_data[:color] \|\| "gold", applied_at: Time.zone.now.to_i, } related_topic.custom_fields["yak_features"] = current_features related_topic.save_custom_fields </code></pre> This does two things:</p> Pins the topic globally for 72 hours using Discourse's native pinning</li> Stores visual customization data (color choice) in topic custom fields</li> </ol> Frontend: Value Transformers</h3> To apply CSS classes to boosted topics in topic lists, we use Discourse's value transformer API. This is the modern replacement for the deprecated widget decorators.</p> api.registerValueTransformer("topic-list-item-class", ({ value, context }) => { const topic = context?.topic; if (topic?.yak_features?.boosted?.enabled) { value.push("yak-boosted-topic"); const color = topic.yak_features.boosted.color \|\| "gold"; value.push(`yak-color-${color}`); } return value; }); </code></pre> The transformer receives a value</code> array and adds CSS classes based on the topic's custom fields. Optional chaining (?.</code>) prevents errors if the data is missing.</p> We also apply styling to the first post in boosted topics:</p> const topic = helper.getModel().topic; const topicYakFeatures = topic?.yak_features; const isFirstPostInBoostedTopic = post.post_number === 1 && topicYakFeatures?.boosted?.enabled; if (isFirstPostInBoostedTopic) { article.classList.add("yak-boosted-topic-post"); const color = topicYakFeatures.boosted.color \|\| "gold"; article.classList.add(`yak-color-${color}`); } </code></pre> This gives visual consistency. The colored border appears both in topic lists and on the opening post.</p> Avoiding N+1 Queries</h3> When adding custom field serialization, you must tell Discourse to preload the data to avoid N+1 query warnings:</p> TopicList.preloaded_custom_fields << "yak_features" if TopicList.respond_to?(:preloaded_custom_fields) </code></pre> Without this, accessing topic.custom_fields["yak_features"]</code> in serializers triggers a database query for every topic in the list. With preloading, all custom fields load in a single query.</p> Pin Auto-Dismiss Behavior</h3> Discourse has built-in pin dismissal behavior. When a user visits a pinned topic, Discourse creates a TopicUser</code> record with cleared_pinned_at</code> timestamp. For that user, the topic shows as unpinned.</p> This is intentional design to prevent banner blindness. The topic stays pinned for everyone else, but individual users can dismiss it after viewing. The colored border remains visible to all users regardless of pin state.</p> CSS Variables for Theme Customization</h3> Originally, colors were hardcoded:</p> .yak-boosted-topic.yak-color-gold { border-color: #ffd700; background: rgba(255, 215, 0, 0.1); } </code></pre> This made it difficult for theme authors to customize colors. The fix was CSS variables:</p> :root { --yak-color-gold: #ffd700; --yak-color-gold-bg: rgba(255, 215, 0, 0.1); --yak-color-blue: #4169e1; --yak-color-blue-bg: rgba(65, 105, 225, 0.1); // ... } .yak-boosted-topic.yak-color-gold { border-color: var(--yak-color-gold); background: var(--yak-color-gold-bg); } </code></pre> Now theme authors can override colors without modifying plugin code:</p> :root { --yak-color-gold: #ff9900; --yak-color-gold-bg: rgba(255, 153, 0, 0.15); } </code></pre> Custom Avatar Flair: User Identity</h2> Avatar flair is the small badge that appears next to a user's avatar. Normally it's set at the group level (moderators get one badge, admins get another). The custom flair feature lets individual users choose their own icon and color scheme for 30 days.</p> </p> The Challenge: Integrating with Existing Components</h3> Discourse has an existing UserAvatarFlair</code> component that reads flair data from serializers. The component expects certain fields (flair_group_id</code>, flair_url</code>, flair_bg_color</code>, etc.) and renders accordingly.</p> Initially, I tried using widget decorators to inject custom data. This hit deprecation warnings. The modern pattern is overriding serializer fields directly.</p> Serializer Override Pattern</h3> Instead of decorating components, we override the serializer methods:</p> [:post, :user_card, :post_action_user].each do \|serializer_name\| add_to_serializer(serializer_name, :flair_url) do user = serializer_name == :post ? object.user : object flair = user.custom_fields["yak_features"]&.dig("flair") if flair && flair["enabled"] flair["icon"] # Return icon name like "rocket" or "crown" else user.flair_group&.flair_icon \|\| user.flair_group&.flair_upload&.url end end end </code></pre> This checks user custom fields first. If yak custom flair is present, return that data. Otherwise, fall back to group flair.</p> Similar overrides for flair_bg_color</code>, flair_color</code>, and flair_name</code>. This pattern works across all serializers (post, user card, action user) without touching the component.</p> The flair_group_id Problem</h3> The UserAvatarFlair</code> component has an early return:</p> if (!user \|\| !user.flair_group_id) { return; // No flair rendered } </code></pre> Users with custom flair but no group flair would fail this check. The component would exit early and never render anything.</p> The fix was setting a dummy marker value:</p> add_to_serializer(serializer_name, :flair_group_id) do user = serializer_name == :post ? object.user : object flair = user.custom_fields["yak_features"]&.dig("flair") if flair && flair["enabled"] -1 # Dummy value to pass existence check else user.flair_group_id end end </code></pre> With flair_group_id</code> set to -1</code>, the component passes the existence check. It then finds flair_url</code> is set (to the icon name) and renders the custom flair.</p> Frontend: Icon and Color Picker</h3> </p> The flair modal presents three selection grids:</p> const ICONS = ["star", "heart", "fire", "bolt", "gem", "crown", "rocket", "trophy"]; const BG_COLORS = ["#ffd700", "#4169e1", "#dc143c", "#32cd32", "#9370db", "#ff8c00"]; const TEXT_COLORS = ["#ffffff", "#000000", "#ffd700"]; </code></pre> Users click icons to select one, then choose background and text colors. A live preview shows the combination:</p> <div class="flair-preview"> <span class="user-flair" style={{this.previewStyle}}> {{d-icon this.selectedIcon}} </span> </div> </code></pre> The preview updates reactively as selections change. Once the user confirms, the modal sends the choices to the backend, which stores them in user custom fields.</p> Making Feature Cards Clickable</h3> On the wallet page, custom flair is the only feature that needs a modal (icon/color picker). Other features just need a color picker, which is handled inline.</p> To make the custom flair card clickable, we split the template:</p> {{#if (eq feature.id "custom_flair")}} <div class="feature-card clickable" {{on "click" this.openFlairModal}}> {{! card content }} </div> {{else}} <div class="feature-card"> {{! card content }} </div> {{/if}} </code></pre> Only the custom flair card gets the click handler. Other cards remain static. This avoids passing undefined</code> callbacks to the {{on}}</code> helper.</p> What's Next</h2> The plugin now has:</p> Post highlighting (colored borders)</li> Topic pinning (category-only)</li> Topic boosting (global pin + highlight)</li> Custom avatar flair (user identity)</li> </ul> Still to implement:</p> Post pinning (pin individual post to top of topic)</li> Post boosting (increase visibility in feeds)</li> Earning system (auto-reward quality posts)</li> Guardian authorization (permission checks)</li> Admin dashboard improvements</li> </ul> The earning system is the next major piece. Right now, users can only spend Yaks. They need ways to earn them through quality contributions, not just purchases.</p> Code is on GitHub: ducks/discourse-yaks</a></p> Building Yaks: A Virtual Currency System for Discourse (Part 2: Features and Expiration) Unknown — Fri, 17 Oct 2025 00:00:00 +0000 In Part 1</a>, I covered the backend architecture for Yaks: wallets, transactions, and the service layer. The database models were in place, but the system could only apply one feature (post highlighting) and had no way to clean up expired features.</p> Part 2 covers:</p> Implementing topic pinning (our second feature)</li> Refactoring the service layer to be truly modular</li> Building an expiration system with background jobs</li> Starting the admin configuration UI</li> </ul> </p> </p> Topic Pinning</h2> Topic pinning lets users spend Yaks to pin their topic to the top of its category for a configurable duration. This uses Discourse's native pinning mechanism, but requires currency to access.</p> Why This Feature Matters</h3> Forums prioritize content by recency. Older discussions get buried. Topic pinning gives users a way to temporarily boost visibility for important discussions without needing moderator intervention.</p> The constraint is time. After the configured duration expires, the pin is removed and the topic returns to normal sorting.</p> The Service Architecture Problem</h3> When implementing topic pinning, I hit an architectural issue. The existing YakFeatureService.apply_feature</code> method was post-centric:</p> def self.apply_feature(user, feature_key, related_post, feature_data: {}) # ... validation logic ... feature_use = YakFeatureUse.create!( user: user, yak_feature: feature, related_post: related_post, # Always requires a post feature_data: feature_data ) end </code></pre> This design assumed every feature applies to a post. But topic pinning applies to a topic, not a post. I could hack around it by passing related_post.topic</code>, but that's wrong. The service should support both contexts.</p> Looking at the implementation, the issue was clear. The service wasn't modular at all. It was built for posts and only posts. Adding topic support meant refactoring the core design.</p> Refactoring the Service</h3> The fix was adding support for both posts and topics:</p> # Old (post-centric) def self.apply_feature(user, feature_key, related_post, feature_data: {}) # New (modular, all keyword) def self.apply_feature( user:, feature_key:, related_post: nil, related_topic: nil, feature_data: {} ) </code></pre> Now the service accepts either a post or a topic (or neither, for user-level features like custom flair). Making all parameters keyword arguments forces explicit call sites, which prevents mistakes when you have multiple optional params.</p> Validation got context-specific methods:</p> def self.can_apply_to_post?(feature_key, post, user) return false if post.trashed? \|\| post.deleted_at.present? return false if post.user_id != user.id # Check for existing active feature !YakFeatureUse.exists?( user: user, yak_feature: YakFeature.find_by(feature_key: feature_key), related_post: post, expires_at: Time.zone.now..Float::INFINITY ) end def self.can_apply_to_topic?(feature_key, topic, user) return false if topic.closed \|\| topic.archived return false if topic.user_id != user.id # Check for existing active feature !YakFeatureUse.exists?( user: user, yak_feature: YakFeature.find_by(feature_key: feature_key), related_topic: topic, expires_at: Time.zone.now..Float::INFINITY ) end </code></pre> This pattern will scale. When we add user-level features (custom flair), we'll add can_apply_to_user?</code> without touching the core service logic.</p> Integrating with Discourse's Topic Pinning</h3> Discourse has built-in topic pinning. The Topic</code> model has an update_pinned</code> method:</p> duration = feature.duration_hours.hours topic.update_pinned(true, false, duration.from_now.to_s) </code></pre> Three parameters:</p> pinned</code> - Enable or disable the pin</li> global</code> - Pin globally (across all categories) or just in this topic's category</li> pinned_until</code> - When to automatically unpin (must be a string timestamp)</li> </ol> The third parameter is critical. It must be a string, not a Time object. This caught me during implementation:</p> # Wrong (creates YakFeatureUse but topic doesn't actually pin) topic.update_pinned(true, false, feature.duration_hours.hours.from_now) # Correct topic.update_pinned(true, false, feature.duration_hours.hours.from_now.to_s) </code></pre> The feature use was being created, the Yaks were being deducted, but the topic wasn't pinning. The issue was the timestamp format. update_pinned</code> silently fails if you pass a Time object instead of a string.</p> Expiration System</h2> Features need to expire. Each feature has a configurable duration stored in the database. We need a way to clean up expired features and undo their effects.</p> The Architecture</h3> The system has three parts:</p> Regular Job</strong>: ExpireYakFeature</code> - Handles a single expiration</li> Scheduled Job</strong>: CleanupExpiredYakFeatures</code> - Finds expired features and queues regular jobs</li> Service Method</strong>: YakFeatureService.expire_feature</code> - Business logic for expiration</li> </ol> The primary expiration mechanism runs at creation time. When a feature use is created, the expiration job is scheduled to run exactly when it expires:</p> def self.apply_feature(...) feature_use = YakFeatureUse.create!(...) if feature_use.expires_at Jobs.enqueue_at(feature_use.expires_at, :expire_yak_feature, feature_use_id: feature_use.id) end # ... end </code></pre> This is efficient. No polling. The job runs exactly when needed.</p> The Scheduled Job</h3> Runs hourly to find expired features:</p> module Jobs class CleanupExpiredYakFeatures < ::Jobs::Scheduled every 1.hour def execute(args) expired_features = YakFeatureUse .where("expires_at IS NOT NULL AND expires_at <= ?", Time.zone.now) .where(expired: false) expired_features.find_each do \|feature_use\| Jobs.enqueue(:expire_yak_feature, feature_use_id: feature_use.id) end { processed: expired_features.count } end end end </code></pre> It queries for expired features (where expires_at</code> is in the past) and queues a job for each one.</p> This hourly cleanup job is a safety net. If the server restarts before a scheduled job runs, or if something goes wrong with job scheduling, the cleanup job catches it. It's backup, not the primary mechanism.</p> Why find_each</code> instead of each</code>? Performance. find_each</code> loads records in batches (1000 by default) instead of loading everything into memory. If you have 10,000 expired features, each</code> would load all 10,000 at once. find_each</code> loads 1000, processes them, loads the next 1000.</p> The Regular Job</h3> Processes one expiration:</p> module Jobs class ExpireYakFeature < ::Jobs::Base def execute(args) feature_use = YakFeatureUse.find_by(id: args[:feature_use_id]) return unless feature_use YakFeatureService.expire_feature(feature_use) end end end </code></pre> Why a separate job? Fault tolerance. If one expiration fails (database error, bug in the expiration logic), it doesn't stop the others from processing.</p> The Service Method</h3> Handles the business logic:</p> def self.expire_feature(feature_use) feature_key = feature_use.yak_feature.feature_key case feature_key when "post_highlight" remove_post_highlight(feature_use.related_post) when "topic_pin" unpin_topic(feature_use.related_topic) end feature_use.update!(expired: true) end private def self.remove_post_highlight(post) return unless post features = post.custom_fields["yak_features"] \|\| {} features.delete("highlight") if features.empty? post.custom_fields.delete("yak_features") else post.custom_fields["yak_features"] = features end post.save_custom_fields end def self.unpin_topic(topic) return unless topic topic.update_pinned(false, false, nil) end </code></pre> Expiration removes the visual effects and marks the feature use as expired.</p> Why mark as expired instead of deleting? Audit trail. Users can see their feature history. Admins can debug issues. Refunds are easier because you have the original feature use record.</p> Frontend Integration</h2> The frontend needed two things:</p> A "Spend Yaks" button on topics</li> Context-aware modal that shows appropriate features</li> </ol> Topic Footer Button</h3> Discourse has an API for adding buttons to topic footers:</p> import { withPluginApi } from "discourse/lib/plugin-api"; export default { name: "yak-topic-actions", initialize() { withPluginApi((api) => { api.registerTopicFooterButton({ id: "yak-spend", icon: "coins", label: "yaks.topic_action.spend", action() { const modal = getOwner(this).lookup("service:modal"); modal.show(SpendYaksModal, { model: { topic: this.topic, }, }); }, dropdown() { return this.site.mobileView; }, classNames: ["yak-spend"], dependentKeys: ["topic.closed", "topic.archived"], displayed() { return ( this.currentUser && this.topic.user_id === this.currentUser.id && !this.topic.closed && !this.topic.archived ); }, }); }); }, }; </code></pre> The displayed()</code> function controls visibility. The button only shows if:</p> User is logged in</li> User owns the topic</li> Topic isn't closed or archived</li> </ul> Context-Aware Modal</h3> The modal needed to work for both posts and topics:</p> export default class SpendYaksModal extends Component { get isPostContext() { return !!this.args.model.post; } get isTopicContext() { return !!this.args.model.topic && !this.args.model.post; } get postFeatures() { return this.allFeatures.filter((f) => f.category === "post"); } get topicFeatures() { return this.allFeatures.filter((f) => f.category === "topic"); } get availableFeatures() { if (this.isPostContext) return this.postFeatures; if (this.isTopicContext) return this.topicFeatures; return []; } } </code></pre> One modal, two contexts. The UI adapts based on whether you clicked "Spend Yaks" on a post or a topic.</p> Admin UI (In Progress)</h2> The final piece is admin configuration. Currently, features and purchase packages are hardcoded. They need to be editable in the UI.</p> Database-Backed Packages</h3> Created a yak_packages</code> table:</p> create_table :yak_packages do \|t\| t.string :name, null: false t.text :description t.integer :price_cents, null: false, default: 0 t.integer :yaks, null: false, default: 0 t.integer :bonus_yaks, null: false, default: 0 t.boolean :enabled, null: false, default: true t.integer :position, null: false, default: 0 t.timestamps end </code></pre> Price is stored as cents (integers) instead of dollars (floats) to avoid floating-point precision issues. A $5.00 package is 500 cents.</p> The model has helper methods:</p> class YakPackage < ActiveRecord::Base def total_yaks yaks + bonus_yaks end def price_usd price_cents / 100.0 end def price_usd=(usd) self.price_cents = (usd.to_f 100).to_i end end </code></pre> This lets you work in dollars in the UI but store as cents in the database.</p> CRUD Endpoints</h3> Added REST endpoints to the admin controller:</p> def packages packages = YakPackage.ordered render json: { packages: packages.map { \|p\| serialize_package(p) } } end def create_package package = YakPackage.new(package_params) if package.save render json: { package: serialize_package(package) } else render_json_error(package.errors.full_messages.join(", ")) end end def update_package package = YakPackage.find(params[:id]) if package.update(package_params) render json: { package: serialize_package(package) } else render_json_error(package.errors.full_messages.join(", ")) end end def delete_package package = YakPackage.find(params[:id]) package.destroy! render json: success_json end </code></pre> Standard Rails REST pattern. The admin can create, edit, and delete packages without touching code.</p> Admin UI Structure</h3> The UI follows Discourse's admin plugin pattern (inspired by the Chat plugin):</p> admin/assets/javascripts/discourse/ ├── routes/admin-plugins/show/discourse-yaks-management/ ├── controllers/admin-plugins/show/discourse-yaks-management/ ├── templates/admin/plugins/show/discourse-yaks-management/ └── initializers/yaks-admin-plugin-configuration-nav.js </code></pre> The structure creates tabs:</p> Settings</strong> - Site settings (automatic)</li> Management</strong> - Custom UI for packages, features, stats</li> </ol> The templates use Discourse's admin components:</p> <div class="admin-config-page"> <div class="admin-plugin-config-page"> <div class="d-page-header"> <div class="d-page-header__title-row"> <h1 class="d-page-header__title">Yak Management</h1> </div> <p class="d-page-header__description"> Manage your virtual currency system. Configure purchase packages and premium features. </p> </div> <div class="admin-plugin-config-page__content"> <!-- Tables for stats, packages, features --> </div> </div> </div> </code></pre> This matches Discourse's standard admin page structure. Using the framework's components ensures consistency with the rest of the admin area.</p> Current Status</h3> The admin UI backend is complete (CRUD endpoints, modals, tables), but the tab navigation isn't working yet. The Settings tab appears, but the Management tab doesn't. This is a routing issue, not a data issue.</p> The tables work when accessed directly. The functionality is there. The navigation just needs debugging.</p> What's Next</h2> The immediate task is fixing the admin UI tab navigation. Once that's working, admins will have full control over the system configuration:</p> Add/edit/delete purchase packages (price, Yak amounts, bonus structure)</li> Configure feature costs and durations (how many Yaks, how long they last)</li> View system statistics (total wallets, Yaks in circulation, active features)</li> </ul> After that:</p> Implement the earning system (reward quality posts based on configurable criteria)</li> Build the remaining features (post pin, post boost, custom flair)</li> Add purchase flow integration (Stripe for buying Yaks with real money)</li> </ul> The plugin is functional. Two features work end-to-end. The expiration system is running. The architecture is modular enough to add new features without major refactoring.</p> Part 3 will cover the earning system and completing the admin UI.</p> The code is on GitHub: ducks/discourse-yaks</a></p> ChatGPT assisted Changelog - 42/52 Unknown — Fri, 17 Oct 2025 00:00:00 +0000 AWS SDK Ruby contributions and follow-up</strong></p> You published Contributing to AWS SDK Ruby - Part 3</em>, which wrapped up your series about improving the Ruby AWS SDK. You mentioned the post got 3 boosts on Mastodon and linked to it from Hachyderm. We also talked briefly about your earlier PRs and how they connect -- adding a feature first, then fixing a bug.</p> Transit Tracker and Discourse experiments</strong></p> You released and shared Building a Live Transit Departure Board with Discourse</em>, a creative exploration of using Discourse for something non-forum-like. We talked about whether posting it on Discourse's official blog or community site would be weird, and you decided it'd actually fit since you work there. You also added screenshots later to make the post more engaging.</p> GoatCounter and analytics debugging</strong></p> You tried exporting page-view data from your self-hosted GoatCounter instance, but ran into a network failure while testing the API. You realized you might not have the admin section working yet. You also revisited an older issue about countries being listed twice in your data and looked at the GoatCounter repo to see why.</p> Personal tools and privacy</strong></p> We discussed private movement trackers for GrapheneOS, and you settled on PFA</em> as a lightweight way to track steps and distance without leaking data.</p> Side notes</strong></p> You mentioned two new blog posts being live -- Transit Tracker in Discourse</em> and Yak's Virtual Currency - Part 2</em> -- both updated with screenshots.</p> Building Slumprutt: A Random Route Generator in Under an Hour Unknown — Thu, 16 Oct 2025 00:00:00 +0000 I've wanted a random route generator for awhile now. My problem is I walk and bike the same routes over and over. My brain goes on autopilot. I wanted something that would throw me new routes to explore in my own neighborhood.</p> I wanted something simple: "Give me a random 5-mile loop from my house."</p> So I built it. With Claude Code's help, we went from idea to working app in under an hour.</p> The Name</h2> "Slumprutt" comes from Swedish "slumpmässig rutt" (slumpmässig = random or by chance, rutt = route), commonly shortened to just "slumprutt". Seemed fitting for a random route generator.</p> The Stack</h2> Backend</strong>: TypeScript + Node.js + Express</p> Frontend</strong>: Svelte + TypeScript + Leaflet</p> Routing</strong>: OSRM (Open Source Routing Machine)</p> Maps</strong>: OpenStreetMap</p> OSRM deserves special mention. It's a free public API that provides road-accurate routing with turn-by-turn directions. Incredibly fast (sub-second response times) and requires zero setup. Just hit their public endpoint and get back real routes that follow actual roads.</p> The Algorithm</h2> The core challenge was generating interesting random loops. Not just random waypoints, but routes that actually feel like purposeful walks or bike rides.</p> Here's what I landed on:</p> export function generateLoopWaypoints( start: Coordinate, targetDistanceKm: number, variationIndex: number = 0 ): Coordinate[] { // Use fewer waypoints (3-5) for longer segments const numWaypoints = Math.max(3, Math.min(5, 3 + variationIndex)); // Reduced multiplier to 0.6 to account for road routing overhead const baseRadius = targetDistanceKm / (2 * Math.PI) * 0.6; const waypoints: Coordinate[] = []; const latPerKm = 1 / 111; // 1 degree latitude ≈ 111km const lonPerKm = 1 / (111 * Math.cos((start.lat * Math.PI) / 180)); // Rotate each route by 120° to avoid overlap const primaryDirection = (variationIndex * (2 * Math.PI)) / 3; for (let i = 0; i < numWaypoints; i++) { const baseAngle = (i / numWaypoints) * 2 * Math.PI + primaryDirection; // More randomness for diverse paths const angleVariation = (Math.random() - 0.5) * 0.8; const angle = baseAngle + angleVariation; // More radius variation to explore different distances const radiusVariation = 0.5 + Math.random() * 1.0; const radius = baseRadius * radiusVariation; waypoints.push({ lat: start.lat + Math.sin(angle) * radius * latPerKm, lon: start.lon + Math.cos(angle) * radius * lonPerKm, }); } return waypoints; } </code></pre> Key design decisions:</p> Fewer waypoints</strong> (3-5 instead of 8+) means longer road segments and more interesting routes. Too many waypoints and you just walk back and forth.</p> </li> Smaller radius with overhead adjustment</strong> (0.6x) accounts for the fact that road routing adds significant distance compared to straight-line waypoints. Initially used 1.5x which resulted in 7-8 mile routes when requesting 1 mile.</p> </li> Directional rotation</strong> (120° per route) prevents all routes from heading in the same direction. Generate 3 routes and they'll spread out into different quadrants.</p> </li> More randomness</strong> (0.8 angle variation, 0.5-1.5 radius variation) creates diverse paths that explore different areas. This prevents multiple routes from clustering in the same locations.</p> </li> </ol> Then we feed those waypoints to OSRM, which turns them into actual road routes with turn-by-turn directions.</p> Challenges</h2> Distance Input Validation</h3> First issue: weird validation errors when changing distance inputs. I had step="0.1"</code> on both the miles and kilometers inputs. The problem: 3.2 miles converts to 5.1494888 km, which rounds to 5.15. The browser expected 5.1 or 5.2 (multiples of 0.1) and rejected 5.15.</p> Fix: step="any"</code> accepts any decimal value.</p> Map Not Visible</h3> Built the whole UI, ran it, and... no map. Just an empty space where the map should be.</p> The issue: CSS height inheritance. The map div had height: 100%</code> but its parent containers didn't have explicit heights. The fix required setting height on three elements:</p> :global(html), :global(body), :global(#app) { height: 100%; width: 100%; } </code></pre> This is a common Svelte gotcha when you want a full-viewport layout.</p> Routes Don't Follow Roads</h3> Initial implementation drew straight lines between waypoints. Routes went through buildings, parks, water. Not useful for actual navigation.</p> This is where OSRM saved the day. One API call with waypoints, get back actual road geometry:</p> const coords = route.points.map(p => `${p.lon},${p.lat}`).join(';'); const url = `https://router.project-osrm.org/route/v1/${profile}/${coords}?overview=full&geometries=geojson&steps=true`; const response = await fetch(url); const data = await response.json(); </code></pre> The steps=true</code> parameter gives you turn-by-turn directions too, which I added to the UI in collapsible sections under each route.</p> Boring Back-and-Forth Routes</h3> First test: "Walk this way, turn around, walk back." Technically a loop, but boring as hell.</p> The issue was too many waypoints creating short segments. The fix was the algorithm changes I mentioned earlier: fewer waypoints, larger radius, directional rotation. Now routes actually explore different areas instead of just oscillating.</p> TypeScript Across the Stack</h2> I initially questioned whether TypeScript was overkill for this project. Turns out it was perfect.</p> Shared types between frontend and backend caught so many potential bugs:</p> export interface Coordinate { lat: number; lon: number; } export interface GeneratedRoute { id: number; points: Coordinate[]; waypoints: Coordinate[]; isLoop: boolean; distance?: number; duration?: number; steps?: RouteStep[]; } </code></pre> When the backend returns GeneratedRoute[]</code>, the frontend knows exactly what shape to expect. No guessing, no runtime surprises.</p> Development Environment</h2> Created a Nix shell for reproducible development:</p> { pkgs ? import <nixpkgs> {} }: pkgs.mkShell { buildInputs = with pkgs; [ nodejs_22 typescript nodePackages.tsx ]; } </code></pre> Anyone can clone the repo, run nix-shell</code>, and have the exact same environment. No "works on my machine" issues.</p> Result</h2> The app works. You enter an address, pick a mode (walk/bike/car), set a distance, and hit generate. It shows you multiple random routes on an interactive map with turn-by-turn directions.</p> </p> </p> </p> </p> I've already used it to find new walking routes in my neighborhood.</p> Is it perfect? No, it's not. You will get routes that go down sketchy roads or routes that still go back and forth. But it was fun and it's helpful to me.</p> Try it yourself</strong>: github.com/ducks/slumprutt</a></p> What I Learned</h2> OSRM is incredible</strong> - Free, fast, accurate. No API key required. If you're building anything with routing, use OSRM.</p> </li> TypeScript prevents so many bugs</strong> - Especially for coordinate/route data that flows through multiple layers. Type errors at compile time beat runtime errors every time.</p> </li> Fewer waypoints make better routes</strong> - Counterintuitive, but 3-5 waypoints create more interesting loops than 8-10.</p> </li> Svelte's reactivity is clean</strong> - No useState/useEffect boilerplate. Just $: if (condition) { doThing() }</code> and it works.</p> </li> Building with AI is wild</strong> - Went from idea to working app in under an hour. Not just scaffolding, but a fully functional app with an interesting algorithm, API integration, and polished UI.</p> </li> </ol> AWS SDK Ruby Part 3: When "Working as Intended" Means "Broken by Design" Unknown — Tue, 14 Oct 2025 00:00:00 +0000 The Saga Continues</h3> If you've been following along (Part 1</a> and Part 2</a>), you know I've been on a journey fixing AWS SDK Ruby credential handling. First I added the missing credential_source = Environment</code> implementation, then I discovered it didn't actually work due to credential chain precedence issues.</p> After extensive testing and code analysis, I submitted PR #3303</a> with a fix. The maintainer initially responded positively:</p> "Hey, thanks for opening an issue. I believe you are correct and this is something we need to fix."</p> </blockquote> Great! But then...</p> The Reversal</h3> After I provided detailed testing comparing AWS CLI behavior, demonstrated the fix working in production, and showed exactly which code was unreachable due to the chain precedence, the maintainer walked it back:</p> "From what I understand, I think the default chain will try to resolve credentials as quickly as possible, so if environment variables are set it will use them directly instead of using them as a credential source. We try not to change the behavior of the default chain since returning credentials in a different order can break many customers."</p> </blockquote> And then closed both the issue and PR.</p> Why This Is Wrong</h3> 1. The Feature Is Completely Broken</strong></p> When you configure:</p> [default] role_arn = arn:aws:iam::123456789012:role/MyRole credential_source = Environment </code></pre> What happens?</p> env_credentials</code> (position 7) finds AWS_ACCESS_KEY_ID</code> and AWS_SECRET_ACCESS_KEY</code></li> Chain returns those credentials and stops</li> assume_role_credentials</code> (position 10) never executes</li> The role_arn</code> and credential_source</code> configuration is completely ignored</strong></li> </ol> The maintainer confirmed this: "All of the static_profile_</code> methods handle credentials resolution when a client is configured explicitly with a profile."</p> So the feature works... but only if you don't use the credential chain, which defeats the entire purpose of having a credential chain.</p> 2. The Code Contradicts Their Argument</strong></p> Look at shared_config.rb:392-400</code></a>:</p> def credentials_from_source(credential_source, config) case credential_source when 'Ec2InstanceMetadata' # ... when 'EcsContainer' # ... when 'Environment' creds = Credentials.new( ENV['AWS_ACCESS_KEY_ID'], ENV['AWS_SECRET_ACCESS_KEY'], ENV['AWS_SESSION_TOKEN'] ) creds.metrics = ['CREDENTIALS_ENV_VARS'] creds end end </code></pre> This code exists specifically to use environment variables as source credentials for role assumption. But the credential chain prevents it from ever executing when using the default profile.</p> 3. The Workaround Proves It's Broken</strong></p> The maintainer suggested: "if specifying the profile resolves your issue I would recommend doing that."</p> But that's not a solution, it's an admission the feature is broken. The credential chain exists so you DON'T have to explicitly pass profile:</code> parameters everywhere. Setting AWS_PROFILE=default</code> or using the default profile should work. That's the entire design philosophy.</p> 4. Who Would This "Break"?</strong></p> The maintainer worried about "breaking many customers." But let's think about this:</p> My fix only affects users who have both</strong> of these conditions:</p> A profile with role_arn</code> AND credential_source = Environment</code></li> Environment variables AWS_ACCESS_KEY_ID</code> and AWS_SECRET_ACCESS_KEY</code> set</li> </ul> If someone configures both, they're explicitly declaring: "use these environment variables AS SOURCE CREDENTIALS to assume this role."</p> Who would configure this and expect it to be ignored? That's not a customer being protected, that's a broken feature being excused.</p> What I Did Instead</h3> Since the AWS team won't fix the credential chain, I worked around it by explicitly passing the profile:</code> parameter to AWS SDK clients. This bypasses the broken credential chain entirely.</p> The approach is simple:</p> def aws_client_options opts = { region: config.region } # Explicitly pass profile if configured if config.profile.present? opts[:profile] = config.profile elsif config.access_key_id.present? && config.secret_key.present? opts[:access_key_id] = config.access_key_id opts[:secret_access_key] = config.secret_key end # Otherwise omit credentials, let SDK auto-discover opts end </code></pre> With AWS config:</p> [profile app-uploads] role_arn = arn:aws:iam::123456789012:role/AppUploads credential_source = Environment </code></pre> This works because explicitly passing profile:</code> to the SDK bypasses the broken credential chain and goes directly to the profile-based role assumption code. It's not fixing the SDK bug, but it enables working role assumption with temporary credentials instead of long-lived static keys.</p> What I Learned (The Hard Way)</h3> Open source maintainers aren't always right.</strong> Even when they're from AWS, even when they're maintaining critical infrastructure, they can make bad decisions.</p> Document your wins even when they don't get merged.</strong> This fix works in production. Other developers will hit this same issue. Having a public record of the problem and solution helps everyone.</p> The bug report itself has value.</strong> Even though they closed it, the issue and PR document exactly what's broken and why. Future developers will find it and understand they're not crazy. The feature really is broken.</p> The Bigger Picture</h3> This experience reminded me technical correctness doesn't always win.</p> I had:</p> Clear reproduction steps</li> Root cause analysis with line numbers</li> A working fix with tests</li> Production validation</li> Comparison with AWS CLI behavior</li> Maintainer acknowledgment that it was broken</li> </ul> And they still closed it.</p> Sometimes the politics of "don't change anything" beat "fix the broken feature." That's frustrating, but it's reality.</p> For Other Contributors</h3> If you hit this issue:</p> Yes, credential_source = Environment</code> is broken with the default credential chain</li> No, it's not you, it's the SDK</li> The workaround is explicitly passing profile:</code> to clients (or using source_profile</code> with plaintext keys)</li> Explicitly passing the profile parameter bypasses the broken chain and enables proper role assumption</li> </ol> For AWS maintainers reading this:</p> You have unreachable code in credentials_from_source</code></li> Your credential chain prevents documented features from working</li> "Breaking changes" is a poor excuse for not fixing broken features</li> The feature is already broken for everyone using default profiles</li> </ul> The End (For Now)</h3> This is where the story ends. I found a workaround, documented it for others, and moved on.</p> Sometimes that's all you can do. Sometimes "no" from maintainers means finding another path. Sometimes proving you're technically correct doesn't matter if the project isn't willing to fix their bugs.</p> But hey, at least the deployment works now. And maybe this blog series will help the next developer who hits this same wall and wonders why a documented feature doesn't actually work.</p> The adventure is over. The bug remains. The workaround persists.</p> Such is open source.</p> Building Yaks: A Virtual Currency System for Discourse (Part 1: Backend Architecture) Unknown — Sat, 11 Oct 2025 00:00:00 +0000 I'm building a virtual currency system for Discourse. Users earn and spend "Yaks" on premium post features like colored highlighting, pinned posts, and custom user flair.</p> </p> </p> This is Part 1 of a series documenting the development. This post focuses on the backend architecture. Future posts will cover the frontend UI, earning mechanisms, and feature implementations.</p> Why Yaks?</h2> The name works on two levels. First, "yak" as a verb means to talk or chat persistently. Forums are where people yak.</p> Second, "yak shaving" is programmer slang for doing a seemingly pointless series of tasks. Unfortunately, sometimes, talking (arguing) with people online can feel apparently useless. The name acknowledges that.</p> Why Virtual Currency?</h2> Forums have moderation tools and permission systems, but they're binary: you can do something or you can't. Virtual currency adds a middle layer where users can temporarily access premium features by spending earned currency.</p> The use cases:</p> Highlight important posts with colored borders</li> Pin your post to the top of a topic for 24 hours</li> Add custom flair next to your username</li> Boost your post in feeds and search results</li> </ul> These aren't permissions. They're temporary, purchasable upgrades.</p> The Data Model</h2> The system has four core models:</p> YakWallet</h3> Each user has a wallet that tracks their balance and lifetime totals:</p> class YakWallet < ActiveRecord::Base belongs_to :user has_many :yak_transactions validates :balance, numericality: { greater_than_or_equal_to: 0 } validates :lifetime_earned, numericality: { greater_than_or_equal_to: 0 } validates :lifetime_spent, numericality: { greater_than_or_equal_to: 0 } end </code></pre> The wallet is the source of truth for a user's currency. Every earn, spend, and refund goes through it.</p> YakTransaction</h3> Every balance change is logged. This creates an immutable audit trail:</p> class YakTransaction < ActiveRecord::Base belongs_to :user belongs_to :yak_wallet enum transaction_type: { earn: 0, spend: 1, refund: 2 } end </code></pre> Transactions include:</p> Amount (positive for earn/refund, negative for spend)</li> Type (earn, spend, refund)</li> Source (where it came from: stripe_purchase</code>, quality_post</code>, feature_post_highlight</code>)</li> Description (human-readable explanation)</li> Metadata (JSON field for additional context)</li> Related post/topic (if applicable)</li> </ul> Why log everything? Transparency. Users can see exactly where their Yaks went. Admins can debug balance issues. Refunds are straightforward because you have the original transaction ID.</p> YakFeature</h3> Features define what users can spend Yaks on:</p> class YakFeature < ActiveRecord::Base has_many :yak_feature_uses validates :feature_key, presence: true, uniqueness: true validates :cost, numericality: { greater_than: 0 } validates :category, inclusion: { in: %w[post user topic] } end </code></pre> Each feature has:</p> A unique key (post_highlight</code>, post_pin</code>)</li> Display name and description</li> Cost in Yaks</li> Category (post, user, topic)</li> Settings (duration, default values, constraints)</li> </ul> Currently implemented:</p> Post Highlighting</strong> (25 Yaks): Colored border and background (gold, blue, red, green, purple)</li> </ul> Planned features:</p> Post Pin</strong> (50 Yaks): Pin to top of topic for 24 hours</li> Custom Flair</strong> (100 Yaks): Custom text next to username for 30 days</li> Post Boost</strong> (30 Yaks): Priority in feeds for 72 hours</li> </ul> The cost is per feature, not per variation. Post highlighting costs 25 Yaks regardless of which color you choose.</p> YakFeatureUse</h3> When a user purchases a feature, we create a YakFeatureUse record:</p> class YakFeatureUse < ActiveRecord::Base belongs_to :user belongs_to :yak_feature belongs_to :yak_transaction belongs_to :related_post, class_name: "Post", optional: true belongs_to :related_topic, class_name: "Topic", optional: true scope :active, -> { where("expires_at IS NULL OR expires_at > ?", Time.zone.now) } end </code></pre> This tracks:</p> Who applied the feature</li> Which feature was applied</li> What post/topic it was applied to</li> When it expires (if applicable)</li> Feature-specific data (color choice, custom text, etc.)</li> </ul> The active</code> scope makes it easy to query currently active features and clean up expired ones.</p> The Service Layer</h2> Business logic lives in services, not controllers. Controllers handle HTTP, services handle business rules.</p> What Are Services?</h3> Discourse has a standardized service pattern using Service::Base</code>. Services define:</p> Contracts</strong>: Input validation using schemas</li> Policies</strong>: Preconditions that must be true</li> Steps</strong>: The actual execution flow</li> </ul> Example structure:</p> class MyService < Service::Base contract do attribute :user_id, :integer validates :user_id, presence: true end policy :user_exists step :do_work private def user_exists User.exists?(id: contract.user_id) end def do_work # actual logic end end </code></pre> This pattern separates validation, authorization, and execution. If the contract fails, the service returns an error before hitting any business logic. If a policy fails, execution stops.</p> YakFeatureService</h3> The Yaks plugin currently uses a simpler service pattern (a plain Ruby class with class methods) because the logic is straightforward. It could be refactored to Service::Base</code> if validation becomes more complex.</p> The service handles:</p> Validating the feature exists and is enabled</li> Checking the user can afford it</li> Checking the feature can be applied (no duplicate active uses)</li> Creating the transaction</li> Creating the feature use record</li> Applying the visual effects</li> </ol> def self.apply_feature(user, feature_key, related_post: nil, feature_data: {}) feature = YakFeature.enabled.find_by(feature_key: feature_key) return { success: false, error: "Feature not found" } unless feature return { success: false, error: "Insufficient balance" } unless feature.affordable_by?(user) wallet = YakWallet.for_user(user) transaction = wallet.spend_yaks( feature.cost, feature_key, "Applied #{feature.feature_name}", related_post_id: related_post&.id, metadata: feature_data ) return { success: false, error: "Insufficient balance" } unless transaction feature_use = YakFeatureUse.create!( user: user, yak_feature: feature, yak_transaction: transaction, related_post: related_post, expires_at: calculate_expiration(feature), feature_data: feature_data ) apply_feature_effects(feature_key, related_post, feature_data) { success: true, feature_use: feature_use, new_balance: user.yak_balance } end </code></pre> Why put this in a service instead of the controller? Because controllers should handle HTTP concerns (params, rendering, status codes). Business logic (validating affordability, deducting currency, applying effects) belongs in a service.</p> This makes testing easier. You can test the business logic without setting up HTTP requests. You can reuse the service from rake tasks, background jobs, or the Rails console.</p> The Double Balance Check</h3> Notice the service checks affordability twice:</p> # First check return { success: false, error: "Insufficient balance" } unless feature.affordable_by?(user) wallet = YakWallet.for_user(user) # Second check (wallet.spend_yaks returns nil if balance insufficient) transaction = wallet.spend_yaks(...) return { success: false, error: "Insufficient balance" } unless transaction </code></pre> Why check twice? Race conditions.</p> Between the first check and the actual spend, another request could deduct from the user's balance. Without the second check, you could end up with negative balances.</p> The first check is an optimization (fail fast before loading the wallet). The second check is correctness (verify balance inside the database transaction).</p> The wallet's spend_yaks</code> method uses ActiveRecord transactions:</p> def spend_yaks(amount, feature_key, description, options = {}) return nil if amount <= 0 \|\| balance < amount transaction do decrement!(:balance, amount) increment!(:lifetime_spent, amount) yak_transactions.create!(...) end end </code></pre> If the balance check fails inside the transaction, it returns nil</code> and nothing is deducted. This prevents concurrent requests from causing overdrafts.</p> Applying Features</h2> Features modify post custom fields:</p> def self.apply_feature_effects(feature_key, post, feature_data) current_features = post.custom_fields["yak_features"] \|\| {} case feature_key when "post_highlight" current_features["highlight"] = { enabled: true, color: feature_data[:color] \|\| "gold", applied_at: Time.zone.now.to_i } when "post_pin" current_features["pinned"] = { enabled: true, applied_at: Time.zone.now.to_i } end post.custom_fields["yak_features"] = current_features post.save_custom_fields end </code></pre> Custom fields are Discourse's way of extending models without migrations. The yak_features</code> field stores a JSON object with all active features on a post.</p> This data gets serialized to the frontend:</p> add_to_serializer( :post, :yak_features, include_condition: -> { object.custom_fields["yak_features"].present? } ) do object.custom_fields["yak_features"] end </code></pre> The frontend can then read post.yak_features.highlight.color</code> and apply the appropriate CSS.</p> Current State</h2> The backend is complete:</p> Wallet management with balance tracking</li> Transaction logging with full audit trail</li> Feature definitions with costs and durations</li> Service layer for applying features</li> Custom field serialization for the frontend</li> </ul> What's missing:</p> Frontend UI for viewing balance and purchasing features</li> Earning mechanisms (quality posts, admin grants, purchases)</li> Feature expiration cleanup job</li> Admin dashboard for managing features and viewing stats</li> </ul> Next Steps</h2> Part 2 will cover building the frontend UI: displaying the user's balance, browsing available features, and adding a "spend Yaks" button to posts.</p> Part 3 will cover earning mechanisms and the admin dashboard.</p> The code is on GitHub: ducks/discourse-yaks</a></p> ChatGPT assisted Changelog - 41/52 Unknown — Fri, 10 Oct 2025 00:00:00 +0000 This week centered on publishing, polishing, and reflecting on your Discourse work, with some light data analysis and side discussions along the way.</p> Blog and Writing</strong></p> You published "Building a Live Transit Departure Board with Discourse"</em>, a follow-up to your earlier post about your first Discourse core contribution. The piece explored how you built a live transit tracker plugin that reimagines Discourse as a real-time data board rather than a forum. You asked if posting it on the official Discourse blog would be weird, ultimately deciding it would make sense given your role there. You also asked if the piece itself was interesting -- it was, both technically and conceptually, tying in your love of open data and infrastructure with your day job.</p> Data and Analytics</strong></p> You dug into your GoatCounter analytics, examining visitor distribution across countries. After cleaning up duplicate entries, you found 37 unique countries</strong> represented, spanning six continents</strong> -- North America, South America, Europe, Asia, Africa, and Oceania. Europe and Asia were the strongest regions overall. The data was reformatted into a clean markdown table for future reference.</p> Open Source and Development</strong></p> You briefly noted another bug you found in the AWS SDK for Ruby, following your previous fix and contribution, reinforcing your growing involvement in that project's ecosystem.</p> Overall</strong></p> It was a quieter week but a meaningful one -- marked by the satisfaction of publishing a well-crafted post that blends creativity and engineering. The analytics work helped ground your readership data, while your continued OSS engagement kept your technical momentum going.</p> Building a Live Transit Departure Board with Discourse Unknown — Wed, 08 Oct 2025 00:00:00 +0000 I've been working at Discourse for a few months now, learning how flexible the platform is. It's a forum. It's designed for conversations. But what if we used it for something completely different?</p> Something like tracking flights and trains?</p> I wanted to learn more about Discourse by building something that felt real and that would force me into actual problems. Most importantly though, I wanted to build something that involves my interests and would be fun. I love transit infrastructure and open data so why not a transit tracker using free government feeds? I had this image in my head: those old split-flap airport departure boards, the ones that click and whir as letters rotate into place.</p> Photo by Amsterdam City Archives</a> on Unsplash</a></em></p> What if I could recreate that aesthetic, but powered by Discourse topics instead of actual flights?</p> You can see the result here: discourse-transit-tracker on GitHub</a></p> Why This Makes No Sense (And Why I Did It Anyway)</h2> Let's be clear: Discourse is not a transit tracking system</strong>. It's a forum platform built for human conversations, not GTFS feeds and real-time departure data.</p> But that's exactly what made it interesting.</p> Discourse topics are incredibly flexible. They have custom fields, tags, categories, and a robust permission system. If you squint hard enough, a flight departure is just a "post" with structured data. The departure time? A custom field. The status (on-time, delayed, departed)? A tag. The airline? Maybe a category.</p> It's ridiculous. But it could work</em>.</p> Learning with Claude Code</h2> I built this entire plugin using Claude Code, Anthropic's CLI tool. Not because I couldn't write it myself, but because I wanted to learn Discourse patterns while writing quality code from the start.</p> "Vibe programming" gets a bad rap. People hear "AI-assisted development" and think it's about blindly accepting generated code. But that's not how I used it. Claude Code became a learning tool. I'd describe what I wanted to build, Claude would suggest an approach using Discourse conventions, and I'd understand why those patterns exist.</p> This allowed me to learn the platform faster than reading docs alone would have taught me. I saw real implementations of custom fields, service objects, Ember components, and ActiveRecord patterns. And because Claude follows Discourse's style guide and architecture, the code I wrote actually fits the codebase.</p> This is what good AI-assisted development looks like: not replacing understanding, but accelerating it.</p> The Technical Stack</h2> The plugin integrates three data sources, each with its own challenges.</p> Amtrak (GTFS)</h3> I built an AmtrakGtfsService</code> that downloads Amtrak's GTFS feed (a ZIP file with CSVs), parses routes, stops, trips, and schedules, and creates departure topics with detailed stop information. No API key required.</p> The service:</p> Downloads and extracts GTFS.zip</code> from Amtrak's CDN</li> Parses routes.txt</code>, stops.txt</code>, trips.txt</code>, and stop_times.txt</code></li> For each trip in the next 24 hours, creates a topic with: All basic departure info as custom fields</li> A detailed stops array with lat/lon coordinates and times</li> A formatted schedule table as Post #2</li> </ul> </li> </ol> Running bin/rake transit_tracker:import_amtrak</code> processes ~2,300 trips and creates ~600 departure topics (many trips share the same departure, so they get merged).</p> The Problem: "Title has already been used"</strong></p> The first import run worked fine, processing ~2,300 trips and creating ~600 topics. But when I ran it again to test updates, I hit a wall:</p> Processing 340 trips... Created 1 topic Error: Title has already been used (339 times) </code></pre> Only 1 out of 340 trips succeeded on the second run. The rest failed.</p> Discourse requires unique topic titles. My title format was: "City of New Orleans to New Orleans at 19:05"</code>. Multiple different trains with the same route, destination, and departure minute produced identical titles.</p> My lookup strategy was to find topics by trip_id</code> + service_date</code> stored in custom fields. That worked fine when topics existed. But on subsequent runs, when a topic wasn't found by custom field (maybe the trip_id</code> changed), I'd try to create one, and Discourse would reject it because another train had already claimed that title.</p> The Fix: Fallback Lookup by Title</strong></p> The solution was to add a fallback lookup by title before trying to create:</p> # First, try to find by trip_id + service_date (the ideal natural key) topic = Topic.joins(:_custom_fields) .where(topic_custom_fields: { name: "transit_trip_id", value: attributes[:trip_id] }) .where(...) .first # If still no match, try to find by title to avoid duplicates if !topic title = build_title(attributes) category_id = determine_category(attributes[:mode]) topic = Topic.where(title: title, category_id: category_id).first if topic Rails.logger.info "[TransitTracker] Found existing topic by title, will update" is_new = false end end </code></pre> This way, if multiple trips share a title, they merge into the same topic and get updated instead of failing.</p> Result: 327 departures created, 0 errors</strong>. All trips within the 24-hour window imported successfully. The duplicate trips just update the same topic with fresh data.</p> NYC MTA Subway (GTFS)</h3> The NYC MTA subway system is massive. Their GTFS feed contains over 500,000 stop times covering weeks of schedules across dozens of routes.</p> My first approach was simple: import everything, just like I did with Amtrak. Parse the entire feed, create topics for every departure in the next 24 hours.</p> The Problem: 19GB of RAM</strong></p> I ran the import and watched my Rails process climb. 1GB. 5GB. 10GB. It kept going. By the time it finished parsing, it had consumed over 19GB of RAM</strong>.</p> Loading and processing 500k+ stop times to create 20,000+ Discourse topics consumed massive amounts of memory. At scale, big data creates big problems.</p> The Fix: Reduce the Time Window</strong></p> The fix? Reduce the import window from 24 hours to 6 hours:</p> # Only import departures within the next 6 hours dep_time = parse_gtfs_time(today, first_stop[:departure_time]) next if dep_time < now \|\| dep_time > (now + 6.hours) </code></pre> Result: ~5,000 topics instead of 20,000+, memory usage stayed under 2GB, and the board still shows plenty of departures. For a live departure board, you don't need train schedules from tomorrow anyway.</p> The final implementation includes official MTA line colors (red 1/2/3, green 4/5/6, yellow N/Q/R/W, etc.) and creates ~5,000 departure topics with complete schedules.</p> AviationStack API</h3> Tracks flight departures with gate assignments, delays, and code-share detection. Requires an API key from aviationstack.com</a>.</p> The Problem: Duplicate Code-Share Flights</strong></p> Multiple airlines sell seats on the same physical flight under different flight numbers. That's called code-sharing. So you might have AA123</code>, BA456</code>, and IB789</code> all referring to the exact same plane leaving from Gate E7 at 07:30.</p> At first, I tried to build my own detection using departure time + gate + destination as a natural key. But then I looked closer at the AviationStack API response and found it: a codeshared</code> field that tells you exactly which flight is the operating carrier.</p> The Fix: Use the API's Built-In Field</strong></p> # Handle code-share flights: use operating carrier as natural key codeshared = flight_info["codeshared"] if codeshared.present? # This is a marketing carrier selling seats on another airline's flight # Use the operating flight as trip_id so all code-shares merge operating_flight = codeshared["flight_iata"] \|\| codeshared["flight_icao"] trip_id = "#{operating_flight}-#{departure_info['scheduled']}" Rails.logger.info "[TransitTracker] Code-share detected: #{marketing_flight} operated by #{operating_flight}" else # Regular flight, use its own flight number trip_id = "#{flight_info['iata']}-#{departure_info['scheduled']}" end </code></pre> Why reinvent the wheel? The API already does the hard work of identifying code-shares. I just use the operating carrier's flight number as the trip_id</code>, and all marketing carriers automatically merge into the same topic.</p> Result: AA 1234 / BA 5678 / IB 789</code> displayed as one departure.</p> The Architecture</h2> Topics as Transit Legs</h3> Each flight (or train, or bus) is a Discourse topic. I created a TransitLeg</code> model that wraps Topic and handles all the custom fields:</p> transit_dep_sched_at</code> (scheduled departure time)</li> transit_dep_est_at</code> (estimated departure time for delays)</li> transit_route_short_name</code> (flight numbers)</li> transit_headsign</code> (destination)</li> transit_gate</code> / transit_platform</code> (where to board)</li> transit_dest</code> (airport code)</li> transit_stops</code> (JSON array of all stops with coordinates and times)</li> </ul> Tags handle the mode (flight</code>, train</code>, bus</code>) and status (status:scheduled</code>, status:delayed</code>, status:departed</code>).</p> Posts as Schedule Details</h3> Here's where using Discourse as the foundation really paid off.</p> When you click on a departure row, it expands to show the complete route schedule with all stops and arrival/departure times. But I didn't build a custom data structure for this. I used Discourse posts</strong>.</p> Each departure topic has:</p> Post #1</strong> (the OP): Basic departure info (route, times, gate)</li> Post #2</strong>: A markdown table with the complete schedule</li> Post #3+</strong>: Any delay notifications or status updates</li> </ol> When you expand a row, you're literally seeing the topic's replies rendered inline. It slides down with a smooth animation, showing the full schedule table styled to match the departure board aesthetic.</p> The schedule post looks like this:</p> ## 🚂 Complete Schedule Route: City of New Orleans Direction: Chicago \| Stop \| Arrival \| Departure \| \|---------------------------------------\|---------\|-----------\| \| New Orleans Union Passenger Terminal \| 12:45 \| 12:45 \| \| Hammond Amtrak Station \| 13:42 \| 13:45 \| \| McComb \| 14:30 \| 14:32 \| \| ... \| ... \| ... \| \| Chicago Union Station \| 08:15 \| 08:15 \| _Schedule times are in local timezone. This is the planned schedule and may be subject to delays._ </code></pre> It renders beautifully in the expanded row with the board's dark styling.</p> Why This Works Really Well</h3> Using posts instead of a custom schema means:</p> Update history is built-in</strong>. If a train gets delayed, we post an update and users see the entire timeline.</li> Moderation tools work</strong>. If there's bad data, moderators can edit posts using Discourse's existing tools.</li> Comments could work</strong>. Users could reply to departures (we don't allow this now, but the infrastructure is there).</li> No additional database tables</strong>. Posts are just posts, Discourse handles all the storage.</li> </ul> Screenshots</h2> Flights - Collapsed View</strong></p> </p> Flights - Expanded View</strong></p> </p> NYC Subway - Collapsed View</strong></p> </p> NYC Subway - Expanded View</strong></p> </p> Amtrak Trains - Collapsed View</strong></p> </p> Amtrak Trains - Expanded View</strong></p> </p> Bonus Tooling: Consistent Screenshots</h2> Getting these screenshots pixel-perfect required some tooling. I wanted to be able to:</p> Select a region once</li> Click things in the browser to expand/collapse</li> Take multiple screenshots of the exact same region</li> </ol> I built a Nix shell with Wayland screenshot tools (grim</code> + slurp</code>):</p> nix-shell ~/discourse/nix-shells/screenshot.nix screenshot-region flight-1.png # Select region once # Click to expand in browser screenshot-repeat flight-2.png # Same exact region </code></pre> The slurp</code> tool saves the region geometry, and screenshot-repeat</code> reuses it for perfect alignment across multiple screenshots.</p> Takeaways</h2> I learn best by writing real tools.</strong> Tutorial projects teach syntax, but they don't force you into the messy, real-world problems that make you actually understand a framework.</p> Discourse Topics Are More Flexible Than You Think</h3> Custom fields, tags, and categories gave me all the structured data I needed. Topics aren't just "posts". They're flexible containers for any kind of information.</p> Posts Are the Perfect Update Mechanism</h3> Instead of building a custom "updates" system with timestamps and status changes, I just used Discourse posts. When a delay happens, post an update. The topic becomes a living history of what happened to that departure.</p> Entity Resolution: Check Your Data Before Building Logic</h3> My first implementation created duplicate topics for every code-share flight. I started building my own deduplication logic using a natural key (departure time + gate + destination). But then I actually read the API response and found it: a codeshared</code> field that identifies which flights are the same. I was about to solve a problem the API had already solved for me.</p> GTFS Parsing Has Edge Cases</h3> GTFS times can exceed 24 hours (e.g., "25:30:00" means 1:30 AM the next day). ZIP files can have encoding issues. Stop sequences aren't always sequential. Real-world data is messy.</p> Performance Matters at Scale</h3> The MTA feed has 500k+ stop times. A 6-hour import window instead of 24 hours keeps memory usage reasonable and topic counts manageable (~5,000 instead of 20,000+).</p> Is This Practical?</h2> Probably not for real transit tracking. But it's a great example of pushing Discourse in unexpected directions to understand the platform deeply.</p> The same pattern (topics as structured data + posts as updates) could work for:</p> Package tracking (topics = packages, posts = scan events)</li> Server status boards (topics = servers, posts = incidents)</li> Deployment pipelines (topics = deploys, posts = stage completions)</li> Event schedules (topics = sessions, posts = time/room changes)</li> Support ticket boards (topics = tickets, expandable = full history)</li> </ul> The split-flap aesthetic is a bonus.</p> Try It Yourself</h2> The plugin is open source: ducks/discourse-transit-tracker</a></p> Clone it, run the Amtrak import (no API key required), and see what Discourse topics can become when you push them beyond forum discussions.</p> My First Official Contribution to Discourse Unknown — Mon, 06 Oct 2025 00:00:00 +0000 This past week marked a small but meaningful milestone for me - I submitted and merged my first pull request to the Discourse core project. The fix is simple but important: handle a nil</code> commit URL path in Admin::PluginsController</code>, preventing a 500 error in the plugins admin UI. (github.com</a>)</p> Debugging a random admin panel crash</h3> I've been at Discourse for about two and a half months now, and most of my work so far has been focused on internal tools and infrastructure rather than the main codebase itself. It's been a great way to learn how things fit together behind the scenes, but I've been itching to make a direct impact on the project that everyone actually sees and uses.</p> This PR was a small but deliberate step in that direction. I wanted to start contributing to the public codebase, not just to fix a bug, but to get more familiar with the patterns, tests, and expectations that make Discourse what it is. It's one thing to understand how we run it internally - it's another to touch the core code that powers thousands of communities around the world.</p> There's also a kind of quiet satisfaction in cleaning up a small edge case like this. It's the kind of detail that no one notices when it's working, but it makes the whole system sturdier. That's the kind of work I enjoy doing.</p> What the bug was, succinctly</h3> In lib/plugin/instance.rb</code></strong>, the method discourse_owned?</code> was calling .split</code> on parsed_commit_url.path</code> without checking if path</code> might be nil</code>.</li> In the scenario where a plugin has a commit URL parsed successfully but the path</code> is nil</code> (for example, plugins without a git remote configured), this led to a crash (HTTP 500) in /admin/plugins</code>.</li> My patch adds a nil</code> check: if parsed_commit_url.path</code> is nil</code>, the method returns false</code> (or skips the split) gracefully. I also added a test case to assert this behavior.</li> </ul> In short: prevent a rare but real crash, and make the behavior deterministic in that edge case.</p> How the review and merge went</h3> The PR moved relatively smoothly:</p> I opened the PR and described the bug and proposed patch.</li> The maintainers reviewed and approved it.</li> After passing all checks, the PR was merged into main</code>.</li> The branch was deleted afterward.</li> </ul> It was a small change - only +11 / -1 lines - but I made sure the fix was clean, covered by a test, and clearly explained. Small contributions like this build trust and open the door to more.</p> Takeaways</h4> Fixing something this small reminded me that even the simplest changes can improve confidence in a codebase. It also helped me see more of the moving parts that make Discourse work - how plugins tie in, how errors surface in the admin panel, and how tests are structured to catch regressions early.</p> It's easy to think of "first contributions" as symbolic, but what really mattered was understanding how to move through the process: spot an issue, confirm it, write a clean fix, explain it clearly, and see it merged. That flow is something I want to keep refining.</p> Going forward, I want to:</p> Explore other bug reports in Discourse (especially in plugins and the admin UI)</li> Take on slightly more complex patches (refactors, performance improvements, new features)</li> Use this experience to contribute in a modular, maintainable way</li> </ul> Going off the Rails on the AWS Credential Chain Unknown — Sat, 04 Oct 2025 00:00:00 +0000 The Plot Twist</h3> Remember that AWS SDK contribution</a> I wrote about? The one where I fixed missing credential_source = Environment</code> support? Well, turns out that was only half the story.</p> After my PR got merged and we updated our Discourse deployment to aws-sdk-core 3.233.0</code>, I was excited to finally see role assumption working. The missing credential source was fixed, our config looked perfect, and all the unit tests were passing.</p> But when I deployed it to our test cluster, I still got an error. It was a new error, but an error nonetheless. Instead of UnsupportedCredentialType</code>, I was now getting a permission denied error when trying to use AWS S3 operations.</p> The Real Problem</h3> Here's what was happening. I'd check the identity in our Rails console:</p> discourse(prod)> sts = Aws::STS::Client.new discourse(prod)> puts sts.get_caller_identity.arn arn:aws:iam::123456789012:user/MyUser </code></pre> That should have been showing an assumed role ARN like:</p> arn:aws:iam::123456789012:assumed-role/MyRole/session-name </code></pre> The SDK was still using environment variables directly instead of using them as source credentials to assume the configured role.</p> The Investigation (Round 2)</h3> Back to the AWS SDK source code, this time looking at credential_provider_chain.rb</code>. And there it was - a classic ordering problem:</p> def providers [ # ... other providers ... [:env_credentials, {}], # Position 7 ← Wins! # ... other providers ... [:assume_role_credentials, {}], # Position 10 ← Never reached ] end </code></pre> The credential chain finds AWS_ACCESS_KEY_ID</code> and AWS_SECRET_ACCESS_KEY</code> in position 7, returns those credentials immediately, and never reaches the role assumption logic at position 10.</p> But here's the thing - this isn't as simple as just moving assume_role_credentials</code> higher in the chain. That might break existing behavior for thousands of applications that rely on direct environment variable usage.</p> The Real Architecture Problem</h3> What should happen with this config:</p> [default] role_arn = arn:aws:iam::123456789012:role/MyRole credential_source = Environment role_session_name = test-session region = us-west-2 </code></pre> Expected flow:</strong></p> SDK sees role_arn</code> + credential_source = Environment</code></li> SDK uses AWS_ACCESS_KEY_ID</code>/AWS_SECRET_ACCESS_KEY</code> as source credentials</strong></li> SDK calls AssumeRole</code> with those source credentials</li> SDK returns assumed role credentials</strong></li> </ol> Actual flow:</strong></p> SDK finds AWS_ACCESS_KEY_ID</code>/AWS_SECRET_ACCESS_KEY</code> in environment</li> SDK returns those credentials directly (chain stops)</li> Role assumption config is never processed</li> </ol> The Contribution</h3> I filed Bug #3301</a> with:</p> Clear reproduction steps</li> Root cause analysis pointing to the specific code location</li> Expected vs. actual behavior with ARN examples</li> A workaround using source_profile</code> (though it requires plaintext keys)</li> </ul> The Response</h3> The AWS team's response was exactly what you hope for:</p> "Hey, thanks for opening an issue. I believe you are correct and this is something we need to fix. I need to confirm some details regarding AssumeRoleCredentials profile chaining with the team first and I'll keep you updated."</p> </blockquote> That's maintainer validation that this is a real architectural issue, not user error.</p> What I Learned (Again)</h3> Complex systems have complex bugs:</strong> My first fix solved the missing feature, but revealed a deeper architectural problem with credential chain precedence.</p> Sometimes the obvious fix isn't right:</strong> Moving assume_role_credentials</code> higher might seem simple, but it requires careful consideration of context and backward compatibility.</p> Good bug reports matter:</strong> Clear reproduction steps, root cause analysis, and concrete examples help maintainers understand and prioritize issues.</p> Persistence pays off:</strong> I could have stopped after the first fix and lived with workarounds. But pushing deeper led to identifying a more fundamental issue.</p> The Bigger Picture</h3> This experience reinforced something important about systems work: fixing one layer often reveals problems in the next layer down.</p> The first bug was a missing feature - straightforward to implement. The second bug is an architectural design issue that requires careful consideration of how credential resolution should work when role assumption is involved.</p> Both bugs are real, both needed fixing, and both will help developers who hit the same issues. But they required completely different approaches - one needed code, the other needed a thoughtful design discussion with the maintainers.</p> Status Update</h3> As of this writing, the AWS team is discussing the fix for the credential chain precedence issue. Our Discourse implementation is ready to go - we're just waiting on the upstream architectural fix.</p> Sometimes the best contribution you can make is clearly identifying and documenting a problem, even when the solution isn't obvious. That's exactly what happened here.</p> The Adventure Continues</h3> Read Part 3</a> to see how the maintainers responded to the bug report and the workaround I ended up implementing.</p> ChatGPT assisted Changelog - 40/52 Unknown — Fri, 03 Oct 2025 00:00:00 +0000 The week covered a mix of practical, technical, and personal topics.</p> Travel and Residency</h3> Discussions continued around moving to Czechia. You asked about employer documents, contracts, the passport biopage, tax implications, accommodation requirements, and realistic timelines for when you could start working from Prague. Flatio was identified as a likely short-term housing option.</p> Anki and Language Learning</h3> You set up an Anki deck for learning Czech. The focus was on the alphabet, pronunciation, and use of IPA symbols. We went through how to structure the deck, what templates should look like, and clarified things like vowel length.</p> NixOS and Framework Issues</h3> There were troubleshooting sessions with your Framework 16 and NixOS. Problems included the command key breaking after an RGB reset, the RGB matrix not working in Linux, and questions about whether this tied to a NixOS upgrade. We looked at inputmodule installation, what parts of /etc are declarative, and the Framework warranty/return policy.</p> Broader NixOS Community</h3> You asked about the NixOS steering committee drama and its connection to Anduril, looking for current context on community governance issues.</p> Practical Life Logistics</h3> A few everyday topics came up:</p> Steps for getting a car repaired after being rear-ended.</li> How to cancel a Moda healthcare plan.</li> Best backup plan when changing operating systems.</li> Selling an old car (1974 Ford Ranchero) in Portland, with estimates for repair or restoration and whether shops do at-home consultations.</li> </ul> Projects and Ideas</h3> You continued brainstorming unique Discourse plugin ideas. This included using Discourse to track flights, trains, or transit legs (with Prague trams as a test case) and asking about APIs and boilerplate plugin setup.</p> Miscellaneous</h3> GoatCounter analytics and why a single link share might register multiple views (including prefetching behavior).</li> Color distribution analysis on an uploaded image, with rotations and measurements.</li> iPad Mini use cases.</li> Services to help sell or donate items at home.</li> Shipping personal items from the US to Europe.</li> Kastaplast first run disc valuations and market prices, including Falk, Lots, Stål, Göte, Berg, and Reko.</li> </ul> Overall, the week balanced ongoing emigration planning and language study with NixOS troubleshooting, plugin experiments, and practical life logistics.</p> ChatGPT assisted Changelog - 36-39/52 Unknown — Fri, 26 Sep 2025 00:00:00 +0000 Travel and Prague notes</strong></p> A first Europe trip to Prague sparked a travel post and follow ups. Sections about the castle, tram lines 6 and 17, and Czech Cubism were drafted. Airport and TSA logistics were covered, including CT scanner lanes at PDX, KLM meal expectations, missed connection handling at AMS, and return routing via JFK. Mint Mobile's international pass proved sufficient for a week, with OsmAnd recommended for offline maps and Obtainium used to install apps without Play Store.</p> Czech visa preparation</strong></p> Residency planning continued. A rental listing in Holesovice prompted an email draft to the agent and an explanation of Czech 4+1 flat notation. Resources for US to CZ expats, the role of Flatio, timing without a fixed move date, and document prep were explored. An employer affidavit template was rewritten in plain text. Fingerprinting and FBI background check expectations were clarified. Czech terms like software engineer and contract types such as HPP were noted.</p> Cameras and creative gear</strong></p> Beginner travel camera options were compared: Nikon Z30 and Canon R50 kits versus the Ricoh GRIII for street and night work. Strengths, tradeoffs, and lens choices were outlined. For carry systems, compact bags and local stock for brands like WANDRD were discussed, with an eye toward minimal kits.</p> Discourse experiments and ideas</strong></p> A flurry of off label Discourse concepts landed, from non forum app patterns to playful ideas like Conway's Game of Life. Practicalities came up too: VPS disk pressure from journal files, running locally instead, and revisiting plugin basics. A specific plugin that tracks days until the next cake day was analyzed for implementation details and feasibility.</p> Desktop tooling and small wins</strong></p> On Wayland, grim plus wl copy needed an explicit MIME type to fix clipboard issues. A Nushell function location was clarified, and a prompt flow was added to optionally save screenshots after copying. Hyprland confirmations and UX touches resurfaced as blog worthy tips.</p> Selling, shipping, and decluttering</strong></p> Paths for selling a non running 1974 Ford Ranchero in Portland were mapped out: where to get initial consultations, rough cost expectations for engine checks and tune ups, and whether restoration would raise sale value. Services that help sell or donate household items were listed. Options for shipping personal goods from the US to Europe were compared at a high level.</p> Email deliverability and DNS</strong></p> Email headers were unpacked for a non technical audience. DKIM and DMARC were explained in plain terms, realistic DNS propagation timing was set, and common DMARC failure causes were reviewed. The idea of account warming was addressed with a pragmatic lens. Header domains and alignment details were parsed from sample Authentication Results lines.</p> Disc golf market checks</strong></p> Kastaplast first run prices were researched with a focus on Falk, Lots, Stal, and Gote. Market ranges, recency caveats, and condition effects were noted. A correction landed for the Reko mix, with early plastics clarified. A well used FR Berg valuation was discussed with realism about wear and ceiling prices.</p> Personal finance and admin</strong></p> 401k choices were outlined: cash out implications, rollovers to IRAs, and how a move abroad intersects with taxes and planning. Help from fiduciary advisors and any digital nomad friendly country programs were surveyed at a high level.</p> Logos, apps, and posts</strong></p> A map based Loop Finder app concept took shape using Vue, with local GraphHopper via Docker Compose to remove API key friction. Zola templating for shared resume layouts was explored. A prior post on typing Swedish with a US keyboard kept attracting search traffic.</p> Housekeeping on the site</strong></p> Styling for headings aimed at mobile readability while respecting an 80 char column. Prior weekly summaries stayed the model: plain text markdown, no fancy chars, prose first, and wrapped lines. Future posts were queued from several threads above, especially Prague transport notes, Hyprland prompts, and the email DNS explainer.</p> First time in Europe: One week in Prague Unknown — Tue, 16 Sep 2025 00:00:00 +0000 A Country Boy Goes to Europe</h3> This past week was the annual global meetup for Discourse</a>, the company I recently joined. I was lucky enough to get hired right before the planning cutoff date, and they were very generous to include me so early in my tenure. That inclusion made me feel valued and trusted. This year the meetup was held in Prague, Czech Republic. I was excited because I have never been out of North America.</p> Initial Leg and a Missed Connection in Amsterdam</h3> The trip started with a flight from Portland to Amsterdam. It was pretty smooth, even if long. The only real issue was that the flight arrived late. On top of that, the passport control line in Amsterdam may have been the longest line I have ever seen in an airport. Those two things combined forced me to miss my connecting flight to Prague. Luckily I was flying KLM, which is very good about rebooking a new flight when it is their fault.</p> I had to do A LOT</strong> of walking and waiting, but I got rebooked and made it to my new flight.</p> Meeting My New Coworkers</h3> For all the excitement, I was nervous too. I am introverted, and walking into a room of about 70 people I did not know was daunting. I am not great at introducing myself and I do not feel "important" enough to assume people want to meet me. I was not the only first timer, but I was by far the newest hire.</p> Prague Castle</h3> Prague Castle is not a single building as much as it is a hilltop campus of courtyards, churches, palaces, and gardens.</p> St. Vitus Cathedral</h4> Although I am anti-religion, I can appreciate the architecture of old world churches. Pictures cannot do this building justice. The height, beauty, and aging are things you just have to see in person.</p> </p> </p> Golden Lane (Zlatá ulička)</h4> This pocket street sits between the Bílá Tower and Daliborka Tower. The tiny, colorful houses were built into the castle fortifications around the end of the 16th century and stayed lived in up to the Second World War. Several of the homes now show period interiors that trace everyday life on the lane across five centuries.</p> House No. 22 is the best known stop. Franz Kafka stayed here for a time during the First World War. Facades were repainted in the 1950s following designs by Jiří Trnka, which is part of why the lane looks so storybook today.</p> Climb the steps at House No. 12 to the terrace above Daliborka. The round tower dates to 1496 and served as a prison until 1781. You will see notes about the knight Dalibor of Kozojedy, the tower's first recorded inmate.</p> The Castle Proper (Old Royal Palace)</h4> The Old Royal Palace centers on Vladislav Hall: huge, yet surprisingly open. The broad Riders' Staircase was built so horsemen could enter, which says a lot about the space's ambitions. Outside, the courtyards do the real work of the visit: sit, watch the guard change, and let the pace reset. On the south side, terraces step down toward the river with quiet garden paths and big sky views.</p> </p> Public Trams-it</h3> Prague's tram network is part moving museum, part everyday superpower.</p> A quick history:</p> 1875: horse trams debut in Prague</li> 1891: inventor František Křižík launches the first electric tram (Letná)</li> 1962: the Tatra T3, the red cream classic, begins service and becomes a design icon still seen today</li> 2010s to current: 100% low floor Škoda 15T ForCity sets the modern standard</li> </ul> I caught almost every ride at Veletržní palác, a 2 minute walk from Mama Shelter. Lines 6</strong> and 17</strong> stop here, so I could either hug the river or cut across town without thinking too hard. Daytime trams run about every 8 to 20 minutes, so it felt like show up and go.</p> Tram 6</h4> Line 6 connects Nádraží Holešovice to Kubánské náměstí, which makes it a useful cross town link if you are moving between Holešovice, the center, and Vršovice. Daytime trams in Prague typically run every 8 to 20 minutes, so you can treat both 6 and 17 like show up and go service.</p> Tram 17</h4> Line 17 hugs the Vltava for long stretches, so it is the easy, scenic way to glide past Národní divadlo, Staroměstská, Výtoň, and the riverfront. It links the north (Vozovna Kobylisy) with the south (Sídliště Modřany and Libuš). If you want a view rich ride, sit by the window on this one.</p> Czech Cubist Museum at The House of the Black Madonna</h3> Czech Cubism did not stop at the canvas. It leapt into architecture, furniture, and everyday objects. One of the movement's showpieces is located at The House at the Black Madonna, which was built in 1911 to 1912 and designed by Josef Gočár. It was a Cubist designed department store turned cultural landmark of Old Town. Today it hosts The Museum of Czech Cubism and a restored Grand Cafe Orient.</p> </p> </p> </p> </p> Permanent Souvenirs</h3> I decided to get a couple permanent souvenirs in the form of tattoos while there.</p> </p> Tattoo by Dario Kristoffersen</a> at One Love Tattoo</a>. Prague, 2025.</em></p> </p> Tattoo by Tarlito</a> at One Love Tattoo</a>. Prague, 2025.</em></p> Summary and Reflection</h3> This was honestly the best trip of my life. I absolutely loved Prague and that old European energy. There was something different in the air. To me, it feels like a smaller, older New York City.</p> I loved it so much that I have already started a checklist for a digital nomad work visa. I could see going back for longer periods to visit and work. I regret not going to the transit museum, so that is high on the list for the next visit.</p> Děkuji, že jste si to přečetli.</p> Reverse Engineering A Unique Data Structure - Part 3, Course & Course Details Unknown — Wed, 03 Sep 2025 00:00:00 +0000 Second part of the series, Search, can be found here: Search for Places and Courses</a></p> In the previous two posts, we learned how to GET</code>, scrub, and parse Courses</code> data, as well as how to use the search endpoint for Places</code> and Courses</code>.</p> Viewing a Specific Course</h4> In this post, we will build on the previous data and show how to find the endpoint for a specific course and drill down into more data. We'll focus on the courseDetails</code>, using the beloved Maple Hill as our example:</p> { "_id": "M6vT9WAEmtFKRFr2v", "name": "Maple Hill", "ratingCount": 10064, "ratingAverage": 4.899286515846228, "locationText": "Leicester, MA", "courseId": 1523, "shortId": "lCej", "highlights": [ { "score": 2.803980588912964, "path": "name", "texts": [ { "value": "Maple", "type": "hit" }, { "value": " ", "type": "text" }, { "value": "Hill", "type": "hit" } ] } ], "searchScore": 15.834041595458984, "autocompleteScore": 16.079005921251294 } </code></pre> The URL for a course will be a slugified course name, plus the shortId</code>. For Maple Hill, this URL is: https://myfrisbee.com/courses/maple-hill-lCej.data</code></p> Based on observation, spaces become dashes, and special characters are removed when generating the slug.</p> For example, Keith L. Christner Family DG Course becomes keith-l-christner-family-dg-course.</p> Inspecting the Data</h4> The response from this endpoint is massive</strong>--so much so that Firefox truncates it in the Network tab. I had to use curl and save the file locally just to inspect it.</p> Again, we are greeted by a large array of mixed types. The more I'm reading and learning, it seems like this may not actually be done for any kind of obfuscation, but for performance or a client side hydration strategy. The response is very large but it's a full page of data and probably replaces multiple API calls.</p> This time, the response goes even deeper: it includes a schema map of schema maps, where keys don't point directly to data, but to other schema maps that must be resolved first.</p> "routes/courses/$slug/index", { "_3": 143 }, { "_144": 145, "_335": 336, "_343": 344, "_24719": 24720, "_24957": 24958, "_25013": 25014, "_25150": 25151, "_25410": 25411, "_25435": 25436, "_25481": 25482, "_25513": -7, "_25514": 25515 }, </code></pre> The second object is just full of references to other references. If you follow each one of those schema maps, we can sometimes get the location of each field's key and value. Often times, there are just more schema maps to follow. Here is a small snippet:</p> "smartLayouts": [345, 3534, 12323, 13767, 14131, 14506, 19520, 22543], "classicLayouts": [24721], "reviews": [24959, 24981, 24992, 25002], "photos": [25015, 25083, 25097, 25107, 25128], "nearbyCourses": [25152, 25226, 25280, 25344], </code></pre> Going to array[345]</code>, we get this:</p> { "_66": 346, "_84": 85, "_347": 348, "_349": 350, "_72": 3505, "_3506": 195, "_3507": 3508, "_147": 256, "_3509": 3510, "_3511": 3512, "_3513": 3514, "_3515": 3516, "_3517": 3518, "_104": 3519, "_167": 3520, "_3521": 131, "_3522": 320, "_3523": 3524, "_3525": 3526, "_3527": 2679, "_3528": 679, "_3529": 3530, "_396": 3531 } </code></pre> Going to some of those references leads to actual data, but again, often times it's just more mappings.</p> Now that it makes sense manually, let's write some code to do it programmatically.</p> At a high level, the flow is:</p> const schemaMap = resolveCourseSchemaMapSchema(data); const courseDetailsSchema = schemaMap.courseDetail; const courseDetails = resolveKeyAndValueNames(courseDetailsSchema, mockCourse); </code></pre> Break the big array down into a schema map of schema maps</li> Pass that courseDetailsSchema</code> and our original array to resolveKeyAndValueNames</code></li> </ol> Resolving a Course's Details Structure</h4> The function below does 3 important things:</p> finds our route key label. this key seems to precede the schema map.</li> follows the next pointer to the schema map schema map</li> passes that to resolveKeyAndValueNames</code> to resolve each set of key/values</li> </ul> export function resolveCourseSchemaMapSchema(data: any[]) { for (let i = 0; i < data.length - 2; i++) { const label = data[i]; const pointerMap = data[i + 1]; const schemaMap = data[i + 2]; if ( label === "routes/courses/$slug/index" && typeof pointerMap === "object" && typeof schemaMap === "object" && Object.keys(pointerMap).length === 1 ) { const pointerIndex = Object.values(pointerMap)[0]; const referencedMap = data[pointerIndex]; if (typeof referencedMap === "object") { return resolveKeyAndValueNames(referencedMap, data); } } } } </code></pre> That leaves us with a decoded schema object, where each field (like courseDetail</code>, reviews</code>, smartLayouts</code>) still contains schema references or arrays of indexes:</p> { courseDetail: { _66: 67, _68: 69, _146: 131, _147: 148, _72: 73, _149: 109, _150: 151, _152: 108, _84: 85, _153: 154, _96: 97, _155: 156, _158: 159, _160: 161, _162: 163, _164: 165, _102: 172, _110: 111, _130: 131, _174: 175, _176: 177, _180: 181, _184: 185, _56: 302, _303: 304, _305: 131, _132: 7, _133: 131, _306: 307, _308: 309, _310: 311, _312: 313, _314: 315, _316: 317, _318: 319, _134: 131, _323: 324, _328: 21, _329: 330, _331: 7, _332: 131, _333: 7, _334: 7 }, normalizedCourseTraffic: { _337: 338 }, smartLayouts: [ 345, 3534, 12323, 13767, 14131, 14506, 19520, 22543 ], classicLayouts: [ 24721 ], reviews: [ 24959, 24981, 24992, 25002 ], photos: [ 25015, 25083, 25097, 25107, 25128 ], nearbyCourses: [ 25152, 25226, 25280, 25344 ], nearbyStores: [ 25412, 25424 ], events: [ 25437, 25460, 25470 ], badges: [ 25483, 25494, 25498, 25500, 25505, 25506, 25508, 25509, 25511, 25512 ], globalLayoutAverages: undefined, userStatus: 'loggedOut' } </code></pre> Next is our core function. We take the courseDetail</code> schema map and pass it and our original data array to resolveKeyAndValueNames</code> to resolve the actual values.</p> /** * Resolves a schema map where both keys and values are index references into the data array. / export function resolveKeyAndValueNames(schema: Record<string, number>, data: any[]): Record<string, any> { const result: Record<string, any> = {}; for (const rawKey in schema) { const keyIndex = parseInt(rawKey.replace(/^_/, ""), 10); const valIndex = schema[rawKey]; const fieldName = data[keyIndex]; if (typeof fieldName !== "string") { throw new Error(`Expected string field name at index ${keyIndex}, got: ${typeof fieldName}`); } result[fieldName] = data[valIndex]; } return result; } </code></pre> We are now left with a nicely formatted and readable object of values:</p> { "_id": "M6vT9WAEmtFKRFr2v", "holeCount": 18, "isPay": true, "status": "Active", "name": "Maple Hill", "latitude": 42.276001, "website": "http://maplehilldiscgolf.com", "longitude": -71.895699, "courseId": 1523, "country": "United States", "availabilityStatus": "available", "landType": [157], "targetType": "basket", "targetTypeDescription": "Black Hole Portal, Black Hole Gravity Version 2", "availabilityTypeDescription": "Closed the Sunday before Thanksgiving to New Years for Christmas Tree Season. ", "conditions": { "_104": 166, "_167": -5, "_168": 169, "_170": 171 }, "location": { "_104": 105, "_106": 173 }, "shortId": "lCej", "hasBathroom": true, "propertyType": "dedicated", "activeTargetTypes": [178, 179], "activeTeeTypes": [182, 183], "layoutConfiguration": { "_186": 187, "_223": 224, "_251": 252, "_289": 290, "_299": 300, "_301": -5 }, "timezone": "America/New_York", "otherFees": "$5 Walker fee for those not playing", "isSmartLayoutEnabled": true, "hasDrinkingWater": false, "isDogFriendly": true, "amenitiesRating": 4.754434159544442, "designRating": 4.920076530755979, "sceneryRating": 4.923442842581462, "signageRating": 4.747814409366677, "teeRating": 4.882374770235053, "upkeepRating": 4.891556089317444, "difficultyBins": [320, 321, 322], "isCartFriendly": true, "contactInfo": { "_325": 326, "_327": 326 }, "accessTypeDescription": "", "accessibility": "notAccessible", "byob": false, "dedicatedTargets": true, "hasAvailabilityRestrictions": false, "underConstruction": false } </code></pre> Note: Some fields like conditions</code>, location</code>, and layoutConfiguration</code> are still partially encoded -- they contain their own schema maps or references that need to be decoded separately using resolveKeyAndValueNames</code>. We'll cover those in a future post when we dive deeper into layout and field-level data.</p> Summary</h4> In this post, we decoded the structure of MyFrisbee's courseDetails</code> payloads by:</p> Resolving the "routes/courses/$slug/index"</code> entry</li> Using resolveCourseSchemaMapSchema</code> to get a field-labeled schema</li> Running that through resolveKeyAndValueNames</code> to extract readable values</li> </ul> This pattern gives us a fully usable course object with real field names. While some nested fields (like conditions</code> or layoutConfiguration</code>) still require additional decoding, we now have the tools to confidently work with MyFrisbee's structured course data.</p> Next Time</h4> In the next post, we'll go one level deeper--resolving nested layout data like hole-by-hole distances and tee types.</p> Reverse Engineering A Unique Data Structure - Part 2, Search Unknown — Sat, 30 Aug 2025 00:00:00 +0000 First part of the series, Courses, can be found here: Courses</a></p> Search for Places</h4> In the first post in this series, we were able to parse and extract a list of Course</code> data. This is great, but we're simply getting back 20 random courses that might not mean anything to the end user. Lucky for us, there are a couple search options.</p> Going to https://myfrisbee.com/courses</a> and starting to type in the search box reveals some network calls:</p> /places/search?term=charlotte&limit=5</code></p> This is getting called for every character that is typed and should probably be debounced a little.</p> Anyway, from that call, we get some pretty well formed data instead of the index/schema map data like before. Here is one result:</p> { "_id": "NxHZZBpPjDnXHbbZg", "type": "city", "slug": "charlotte-nc", "name": "Charlotte", "country": "United States", "countryCode": "US", "admin1": "North Carolina", "city": "Charlotte", "location": [ -80.84313, 35.22709 ], "score": 98.75883083083083, "fullLocationText": "Charlotte North Carolina United States", "highlights": [ { "score": 1.4719792604446411, "path": "fullLocationText", "texts": [ { "value": "Charlotte North Carolina", "type": "hit" }, { "value": " United States", "type": "text" } ] } ], "autocompleteScore": 72.5995921895284 }, </code></pre> There seem to be a few options for type</code>.</p> city</li> admin1 (which appears to represent state in the US)</li> country</li> </ul> Now, you can take that slug</code> and plug it into the courses call:</p> /courses.data?placeId=charlotte-nc</code></p> See the first post</a> on how to parse and extract that data.</p> Search for Courses</h4> The Places endpoint was not the only one being hit though. When typing in the search box, you will also see this:</p> /api/courses/search?includeGenerallyUnavailableCourses=true&term=hornets nest&limit=5</code></p> Again, we get some pretty well formed data:</p> { "_id": "jJAW46X3WX8qT7mXR", "locationText": "Charlotte, VT", "ratingAverage": 3.4976632020706235, "courseId": 11220, "ratingCount": 239, "name": "Charlotte Beach", "shortId": "j04j", "highlights": [ { "score": 2.771970748901367, "path": "name", "texts": [ { "value": "Charlotte", "type": "hit" }, { "value": " Beach", "type": "text" } ] } ], "searchScore": 11.487470626831055, "autocompleteScore": 11.66234797214058 }, </code></pre> Next time I will show you how to take that data and get a specific Course</code> endpoint and data.</p> Another Way to Fuzzy Find Courses</h4> Not exactly a search but there appears to be at least one more way of fuzzy finding courses. The courses.data</code> endpoint can take another param called courseTerm</code>. The full URL would be:</p> /courses.data?courseTerm=charlotte</code></p> This will return course results with "Charlotte" in the name. I'm thinking this endpoint is there for list type pages and the search endpoint might just be for autocomplete drop downs.</p> Summary</h4> Showed how to search for places and courses</p> Plan for Next Time</h4> Drill down into specific course data</p> ChatGPT assisted Changelog - 35/52 Unknown — Fri, 29 Aug 2025 00:00:00 +0000 This week covered a mix of personal projects, resume updates, and site tweaks. On the budgeting front, cashctl planning continued, with refinements to the workflow around paydays, file naming, and how income gets assigned to periods. Simulated paycheck commands and outputs were discussed to bring the tool closer to being usable.</p> Work on the personal site also came up. A Zola question about sharing one resume template across multiple pages was raised, along with CSS improvements for headings that stay mobile friendly while keeping within an 80-character layout.</p> Resume polish was another theme. A contribution to the AWS SDK for Ruby was turned into a resume-style entry, with placement under the Discourse role considered for now. Additional feedback was asked for on how to position open source work.</p> The node-postgres-exporter project also got a GitHub star, and further improvements were considered, such as in-memory caching and local storage to smooth over network blips.</p> There was also some lighter talk--identifying a pine tree, considering Vermont properties, and chatting about power adapters and credit scores.</p> Overall, the week blended cashctl development, resume building, static site refinements, and a bit of infrastructure and personal exploration.</p> Reverse Engineering A Unique Data Structure - Part 1, Courses Unknown — Wed, 27 Aug 2025 00:00:00 +0000 Note: Real app name and URL have been replaced</strong></p> I am a very avid fan and player of disc golf.</p> Disc golf is basically the rules of golf but you're throwing a frisbee instead of hitting a ball. There are differences of course. We don't throw the disc into a hole in the ground, but the basic idea of starting in one place and getting an object to another remains the same. It's a beautiful sport that combines the mystique of physics and flight with the beauty and tranquility of nature. I get to take a hike and throw stuff through the woods, what's not to love? Like golf, there is a scoring system, and that's where "MyFrisbee" comes in.</p> "MyFrisbee" is a disc golf scoring app. You can search for courses, find leagues, and most importantly, keep score. It's a useful tool with one problem - there is no public API. I have seen this asked for publicly but MyFrisbee has shown no plans for this in the immediate future, and that's where I come in. I really like figuring out how things work.</p> Starting small</h4> This is the first real API I've tried reverse engineering so I wanted to start small. Some of the features of MyFrisbee are paid and only available in the app and I didn't want to dive into that just yet. There are parts of the service that are available on the website so I wanted to start there.</p> Courses</h4> The biggest feature of the free version of the app is probably the course directory so that's where I started.</p> https://myfrisbee.com/courses</a></p> Going directly to the courses URL, you can use the Developer Tools and the Network tab to already find some useful calls. The most important is a call to /__manifest</code>. This seems to strongly suggest at least the site is a Remix Run based app, also indicated by the p</code> parameters.</p> https://remix.run/</a></p> The full URL looks like this:</p> GET https://myfrisbee.com/__manifest?p=/courses&p=/courses/carey-park-disc-golf-course-e2a5&p=/courses/cheney-state-park-disc-golf-course-west-DnNL&p=/courses/chisholm-trail-3RqD&p=/courses/cowskin-mKI4&p=/courses/cowskin-west-MXwZ&p=/courses/dragon-disc-golf-course-ePkd&p=/courses/flying-bee-country-club-WOm5&p=/courses/garden-plain-city-park-dgc-dsry&p=/courses/helten-gardens-Bupy&p=/courses/keith-l-christner-family-dg-course-kLoh&p=/courses/lazys-links-1S2k&p=/courses/liberty-links-disc-golf-course-uwbs&p=/courses/linear-park-0KnA&p=/courses/llama-loop-qBK4&p=/courses/maize-south-dgc-0eco&p=/courses/newman-university-9Fmt&p=/courses/orchard-disc-golf-course-7F1E&p=/courses/prairie-winds-disk-golf-course-LiKg&p=/courses/quail-run-gFli&p=/courses/west-millbrook-dgc-tDG5&version=149b0717 </code></pre> While this does tell us a lot, it doesn't give us any real data. If we try changing filters, we see another useful call.</p> GET https://myfrisbee.com/courses.data?sortOrder=rating</code></p> Fore! Data incoming. While it's very, very</strong> obfuscated, you can see some real data in there.</p> We also can confirm our suspicions by looking at the response headers:</p> x-remix-response yes </code></pre> Most definitely a Remix based app.</p> Parsing The Data</h3> Looking at the data itself, it looks JSON-y, but when trying to parse it, we find it's corrupt and it fails. There are some foreign chars between two valid JSON arrays. This seems intentional as it's not breaking their site so they must know about it? Regardless, let's scrub that out.</p> This function takes our raw string and iterates over it creating a stack and checking for valid opening JSON brackets. When it finds an opening bracket, it pushes it to the stack, and when it finds a closing bracket, it pops one off. When the stack is empty, we know the JSON structure is complete.</p> export function extractJsonChunks(raw: string): any[] { const chunks: any[] = []; let i = 0; while (i < raw.length) { if (raw[i] === '[' \|\| raw[i] === '{') { const start = i; const stack = [raw[i]]; i++; while (i < raw.length && stack.length > 0) { if (raw[i] === '[' \|\| raw[i] === '{') { stack.push(raw[i]); } else if (raw[i] === ']' \|\| raw[i] === '}') { stack.pop(); } i++; } const chunk = raw.slice(start, i); try { chunks.push(JSON.parse(chunk)); } catch { // ignore invalid chunks } } else { i++; } } return chunks; } </code></pre> Inspecting The Data</h4> After successfully parsing the data, and there is a lot</strong> of it, we can take a better look at two very large arrays.</p> The first part of the first array is mostly config looking stuff - API tokens for various services and basic user settings like locale.</p> My interest is mostly in the actual data, which you can kind of see in the snippet below. These are items in the array, so you can tell the data is there but it's very confusing to read and code against. It would be easy to assume a key then a value but then you see things like price</code>, followed by status</code> and can tell price</code> is obviously missing a value.</p> "_id", "cxYvYpWXX66MoAG5f", "name", "Orchard Disc Golf Course", "headline", "Moderately wooded technical course, Par 54 unless hole 5 is in long., making that a par 4 hole. (course 55)", "longDescription", "18 holes, 1 tee for each hole, 2 basket locations for each hole, rotated regularly. ", "holeCount", 18, "price", "status", "Active", "website", "https://www.facebook.com/groups/270758746431057", </code></pre> Before any of that actual data, there is an array which didn't make much sense at first.</p> After some time digging and debugging (and a little help from ChatGPT), it clicked into place.</p> "courseResults", [ 73, 253, 305, 382, 451, 538, 598, 661, 718, 774, 821, 864, 919, 979, 1026, 1074, 1123, 1174, 1224, 1285 ], { "_74": 75, "_76": 77, "_78": 79, "_80": 81, "_82": 83, "_84": 21, "_85": 86, "_87": 88, "_89": 90, "_91": 92, "_93": 94, "_95": 96, "_97": 98, "_99": 100, "_101": 102, "_103": 104, "_105": 106, "_107": 108, "_109": 110, "_111": 112, "_113": 114, "_115": 116, "_117": 118, "_120": 121, "_122": 123, "_124": 125, "_126": 7, "_127": 128, "_129": 130, "_138": 139, "_143": 144, "_145": 146, "_162": 108, "_163": 164, "_165": 166, "_167": 168, "_56": 170, "_171": 172, "_221": 222, "_223": 125, "_224": 125, "_225": -5, "_226": 125, "_227": 228, "_230": 231, "_235": 21, "_236": 21, "_237": 7, "_238": 125, "_239": 7, "_240": 7, "_241": 7, "_242": 21, "_243": 7, "_244": 245, "_246": 247, "_252": -7 }, </code></pre> The first array, courseResults</code> is an index map telling us where in this giant array each result is. If could you look at the site where we found this URL, you would notice 20 courses in the UI - it just so happens that there are 20 items in that courseResults</code> array.</p> If you happen to check array[73]</code>, it's the following object from above and that turns out to be a schema map - saying that the field name at array[74]</code> is equal to whatever is at array[75]</code> and so on.</p> So, taking this further, the first result will have values in this giant array from 74</code> to 252</code>. If you notice in our index map array above, the second result will start at 253</code> so that makes perfect sense.</p> If you look at array[253]</code> you will find another schema index to indicate where to can find all the key value pairs for the 2nd result, which will actually start at array[254]</code>.</p> To summarize a bit on how this data is encoded:</p> The file contains multiple top-level JSON blocks, pasted together without separators</li> The structure includes: A top-level</strong> array of values (strings, numbers, objects)</li> An array named courseResults</code> that lists indices into that top-level array</li> A set of object maps</strong> (e.g. at index 73, 253, etc.) that map "key index" → "value index"</li> </ul> </li> </ul> Key Insight:</strong></p> The file is basically a compressed CSV, but:</p> Field names and field values are stored in different locations</strong></li> Object schema = { "_76": 77, "_78": 79 }</code> → "name"</code> is at 76, value is at 77</li> </ul> Putting It All Together</h4> After deciphering how to read the data manually, it was time to do it programmatically.</p> With the help of ChatGPT, I wrote a couple functions that would take our original data and format it down to something much more useable.</p> function findCourseResultIndices(data: any[]): number[] { for (let i = 0; i < data.length; i++) { if ( Array.isArray(data[i]) && data[i].every((v: unknown) => typeof v === 'number') && data[i - 1] === 'courseResults' ) { return data[i]; } } throw new Error('Could not find courseResults array'); } export function extractCourses(data: any[]): Record<string, any>[] { const schemaIndices = findCourseResultIndices(data); const courses: Record<string, any>[] = []; for (const schemaIndex of schemaIndices) { const schema = data[schemaIndex] as Record<string, number>; if (typeof schema !== 'object' \|\| Array.isArray(schema)) continue; const course: Record<string, any> = {}; for (const [rawFieldKey, valueIndex] of Object.entries(schema)) { const fieldKeyIndex = parseInt(rawFieldKey.replace(/^_/, ''), 10); const fieldName = data[fieldKeyIndex]; const value = data[valueIndex]; if (typeof fieldName === 'string') { course[fieldName] = value; } } courses.push(course); } return courses; } </code></pre> extractCourses</code> courses is a function that takes an array of any types.</p> First, it calls out to another function, findCourseResultIndices</code>. That function is iterating over the array, looking for another array of all numbers that is preceded by a string named courseResults</code> and returns it.</p> Then we take that list of indices back and iterate over it. For every index in that list, we build a schema of key value pairs and rebuild down into a simple Record</code>.</p> The result is something like this:</p> { _id: 'cxYvYpWXX66MoAG5f', name: 'Orchard Disc Golf Course', headline: 'Moderately wooded technical course, Par 54 unless hole 5 is in long., making that a par 4 hole. (course 55)', longDescription: '18 holes, 1 tee for each hole, 2 basket locations for each hole, rotated regularly. ', holeCount: 18, price: '', status: 'Active', website: 'https://www.facebook.com/groups/270758746431057', latitude: 38.0998054149767, longitude: -97.87738949287784, locationText: 'Hutchinson, KS', yearEstablished: 2018, courseId: 20619, ratingCount: 755, ratingAverage: 4.385343483628396, country: 'United States', countryCode: 'US', state: 'Kansas', city: 'Hutchinson', accessType: 'everyone', availabilityStatus: 'available', availabilityType: 'yearRound', landType: [ 226 ], targetType: 'basket', targetTypeDescription: 'DISCatcher Pro (28 chains)', hasBathroom: true, hasDrinkingWater: false, propertyType: 'mixedUse', conditions: { _146: 195, _196: 21, _197: 342, _199: 343 }, location: { _146: 166, _167: 345 }, shortId: '7F1E', topPhoto: { _74: 348, _242: 349, _244: 350, _246: 351, _248: 352, _250: 353, _252: 354, _254: 355 }, admin1Name: 'Kansas', worldRankingsRating: 86.11626662182661, activeTargetTypes: [ 340 ], activeTeeTypes: [ 259 ], timezone: 'America/Chicago', layoutConfiguration: { _127: 360, _134: 363, _139: 374, _155: 380, _162: 383 }, playFeeType: 'free', isCartFriendly: true, isDogFriendly: true, limitedAccessReason: undefined, isSmartLayoutEnabled: true, difficultyBins: [ 203 ], contactInfo: { _387: 388, _389: 388 }, accessTypeDescription: '', availabilityTypeDescription: '', byob: false, dedicatedTargets: true, hasAvailabilityRestrictions: false, isLocationPrivate: false, isStrollerFriendly: false, otherFees: '', underConstruction: false, accessibility: 'notAccessible', distanceFromSelectedPlace: { _206: 397, _208: 398 }, badgesInfo: undefined }, </code></pre> Voila! We have a well formed Course</code> object. If you look at fields like topPhoto</code>, it looks like the schema map field reference rabbit hole goes even deeper but that's for another post.</p> Summary</h4> In this post, we have:</p> Found URL for Courses</code></li> Scrubbed and extracted (broken) JSON from said URL</li> Discovered data included index and schema maps</li> Wrote functions to format data into useable object</li> </ul> Plan For Next Time</h4> Enable the user to search for a Place</code> and Courses</code>.</p> Contributing to the AWS Ruby SDK: When Documentation and Implementation Don't Match Unknown — Sat, 23 Aug 2025 00:00:00 +0000 The Problem</h3> I was working on some IAM role configuration at work when our Discourse deployment started failing with AWS credential errors. The error was frustrating because according to the AWS documentation, everything should have been working perfectly.</p> The deployment was trying to use credential_source = Environment</code> in the AWS config, which is a standard approach documented in the AWS CLI guide. But for some reason, the Ruby SDK wasn't picking up the credentials.</p> The Investigation</h3> Like any good debugging session, I started by tracing through the credential chain. The AWS Ruby SDK has a pretty clear credential resolution process, so I dug into the source code to see what was happening.</p> That's when I found something interesting: the AWS CLI documentation clearly shows Environment</code> as a supported credential source, but when I looked at the Ruby SDK implementation, that option was completely missing.</p> Here are the docs</a></p> Here's what I found in the SDK</a>:</p> case credential_source when 'Ec2InstanceMetadata' # ... implementation exists when 'EcsContainer' # ... implementation exists when 'Environment' # ... nothing here! end </code></pre> The CLI supports it, the documentation says it should work, but the Ruby SDK just... doesn't implement it.</p> The Solution</h3> This felt like a classic case where implementation lagged behind documentation. Since I needed this working for our deployment, I decided to contribute the missing functionality back to the project.</p> The fix was actually pretty straightforward once I understood the pattern:</p> when 'Environment' Aws::Credentials.new( ENV['AWS_ACCESS_KEY_ID'], ENV['AWS_SECRET_ACCESS_KEY'], ENV['AWS_SESSION_TOKEN'] ) </code></pre> I added comprehensive tests to make sure it worked correctly and that I wasn't breaking any of the existing 20,000+ tests in the project.</p> The Contribution</h3> https://github.com/aws/aws-sdk-ruby/pull/3283</a></p> Here's the thing - I don't really know Ruby that well. But the codebase was well-organized and the patterns were clear enough that I could understand what needed to happen.</p> I submitted the PR with:</p> The missing implementation</li> Proper test coverage</li> Clear documentation of what was being added</li> </ul> The Response</h3> The response from the AWS team was exactly what you hope for in open source:</p> "Hey, thanks for opening a PR. I agree that we should support this and I may make some changes to this PR as well."</p> </blockquote> That's maintainer gold right there - acknowledgment that the gap was real and willingness to collaborate on getting it merged.</p> What I Learned</h3> This whole experience reinforced a few things for me:</p> Documentation gaps happen: Even in well-maintained projects like the AWS SDKs, there can be mismatches between what's documented and what's implemented.</p> Don't let unfamiliar languages stop you: I was able to contribute meaningfully to a Ruby project despite not being a Ruby developer. Good code organization and clear patterns make this possible.</p> Small changes can have big impact: This was maybe 10 lines of actual code, but it unblocked our deployment and will help other developers who hit the same issue.</p> The Bigger Picture</h3> This kind of contribution is exactly why I love working as a generalist. Instead of saying "that's not my language" or "someone else should fix the AWS SDK," I could trace the problem to its source and ship a fix.</p> The best part? Our Discourse deployment should work now, and hopefully other developers won't hit this same roadblock in the future.</p> Update</h3> Since writing this, the change has been expanded with additional tests and approved by the maintainers</a>. It's really rewarding to see a small contribution grow into something that's now part of the SDK itself. This is a great reminder that even small fixes matter -- they can make life easier for the next developer who comes along.</p> The Saga Continues</h3> This turned out to be just the beginning. After getting the feature merged, I discovered it didn't actually work due to credential chain precedence issues. Read more in Part 2</a> and Part 3</a>.</p> ChatGPT assisted Changelog - 34/52 Unknown — Fri, 22 Aug 2025 00:00:00 +0000 This week balanced travel research, disc golf writing edits, technical debugging, and creative design work. On the travel side, questions came up about flying with money internationally and how ATM fees might look in the Czech Republic with an OnPoint credit union card. You also researched the best European power adapters, checking Wirecutter's recommendations for reliable options.</p> In Shelltrax, you continued to refine autoplay. The play_next_track</code> function was revisited to keep the footer showing artist and song info, just as before. The main issue left was that the progress bar didn't carry over correctly between tracks when autoplay advanced.</p> On the creative side, you explored what the Discourse logo might look like if it had aged 100 years, and separately, how it could be reimagined if the company had started as a penpal or letter-writing business. Both ideas fit into your broader exploration of branding experiments.</p> The Swedish (and some German) study streak has been extended to 239 days in a row.</p> Overall, the week tied together preparations for international travel, cleanup work on ongoing projects, and a mix of technical and creative problem-solving.</p> ChatGPT assisted Changelog - 32+33/52 Unknown — Sun, 17 Aug 2025 00:00:00 +0000 Early August Projects</strong></p> The first week of August was centered on your Node-postgres-exporter work. You finished the conversion to ESM and TypeScript and started thinking about next steps. Around the same time, you were also looking into writing a Nix package for Discourse, asking how to handle complex setups that involve databases and services.</p> System and Config Troubles</strong></p> A fair amount of time went into NixOS. You ran into an error with nixos-option</code> and flakes not being found in .config/nix</code>, and later were debugging Git commit signing issues (wrong email in the commit vs author fields). You also asked about forcing Git to use a certain SSH key or email per repo. Other NixOS topics included setting up Wi-Fi on your Framework 16, writing custom modules (like for Kolide), installing packages for Python and Ruby in nix-shell, and configuring Starship with Nushell.</p> Hardware and Devices</strong></p> You were troubleshooting Librewolf not showing your Bluetooth headset mic, plus issues with Wi-Fi and Ethernet modules on the Framework. There was also a question about pinentry not working with GPG on NixOS. On the hardware front, you asked about pixel misalignment on your monitor and learned about TCON as a possible cause.</p> Lifestyle and Planning</strong></p> You asked about FSAs and their use. Travel came up too, with your upcoming Europe trip and looking for the best power adapters (especially for the Czech Republic).</p> Blogging and Writing</strong></p> Your NixOS daily driver series continued, with a post on getting Wi-Fi working on the Framework 16. You considered what direction to take the next entry. You also asked for an intro/about section to describe yourself, condensing it down to 5 sentences. In parallel, you've kept up with weekly summaries and changelog-style posts.</p> Miscellaneous</strong></p> Other threads included practicing Terraform and Nomad, CSS layout questions, and making Hyprland keybinds prompt for confirmation before closing a window. On the wearable side, your PineTime step counter broke and you asked about firmware, Gadgetbridge, and even writing your own step-tracking app in Rust or Kotlin.</p> ChatGPT assisted Changelog - 31/52 Unknown — Fri, 01 Aug 2025 00:00:00 +0000 Nix package development</strong></p> We discussed writing a Nix package for a complex project with multiple resources, using the Discourse install-cloud guide as a template to structure derivations and manage dependencies cleanly.</p> NixOS Wi-Fi on Framework 16</strong></p> We troubleshooted nmcli reporting the Intel AX210 as DOWN, enabled wireless in configuration.nix, and resolved common pitfalls to bring up the wireless interface successfully.</p> Git commit signing</strong></p> We covered forcing Git to use a specific SSH key for a given repository, how to resign commits, and how to update the commit email so that signatures appear valid.</p> Hyprland keybinds</strong></p> We added a custom Hyprland keybind to close the active window with a confirmation dialog, and refined the yes/no prompts and dialog appearance for better usability.</p> Terraform and Nomad learning</strong></p> We explored practical resources--sample projects, tutorials, and sandbox environments--to build hands-on experience with Terraform and Nomad orchestration.</p> Bluetooth audio input</strong></p> We investigated why LibreWolf failed to detect a Bluetooth headset mic, including how to identify the board, check firmware versions, and verify driver support.</p> Email server on NixOS</strong></p> We outlined setting up a mail server on NixOS and using Caddy to automate TLS certificate issuance for secure SMTP and IMAP provisioning.</p> Privacy-focused smartwatches</strong></p> We reviewed open-source options like the PineTime, diagnosed step-counter failures, checked return policies, and sketched a plan for a Rust-based long- term step tracker integrated with Gadgetbridge.</p> Swedish Studies</strong></p> 221 days in a row on Babbel. Listened to audio books as well this week.</p> Hyprland Tricks - Close Window Keybind With Confirmation Window Unknown — Mon, 28 Jul 2025 00:00:00 +0000 By default, hyprctl dispatch killactive</code> will instantly close your focused window. If you're like me and have ever yanked a terminal or browser window when you weren't ready, this tiny script adds a "Yes/No" confirmation window using Wofi.</p> </p> Create the Script</h3> For me, I will be adding this to ~/dotfiles/hypr/scripts/hypr-confirm-close</code>.</p> #!/usr/bin/env bash # prompt "Close window?" with Yes/No via wofi choice=$(printf "Yes\nNo" \ \| wofi --dmenu --prompt="Close window?" --lines=5) [ "$choice" = "Yes" ] && hyprctl dispatch killactive </code></pre> Remember to make it executable. chmod +x ~/dotfiles/hypr/scripts/hypr-confirm-close</code></p> Bind the Key</h3> In your hyprland.conf</code>:</p> bind = $mod, q, exec, bash, ~/.config/hypr/scripts/hypr-confirm-close </code></pre> The filepath is different here because it will get copied from our ~/dotfiles</code> dir to the normal ~/.config</code> directory.</p> Reload:</p> hyprctl reload</code></p> Summary</h3> Now MOD+q</code> pops up a two-line menu and only when you select "Yes" will your window be closed.</p> NixOS as a daily driver or Zero to Nixty, part 9/? - Enabling Wi-Fi Unknown — Sun, 27 Jul 2025 00:00:00 +0000 I recently got a new Framework 16</a> (thanks Discourse!). In the previous post, we talked about encrypting the machine and refactoring our config into a modular layout. You can read about that and more in the NixOS As A Daily Driver</a> series.</p> Today I will be showing how I got Wi-Fi working because it did not work on NixOS by default. The Framework 16 ships with an Intel AX210 Wi-Fi module.</p> The Symptoms</h3> nmcli device status</code> shows my wlp2s0</code> as "DOWN"</li> ip link set wlp2s0 up</code> was not effective</li> nmtui</code> would show SSIDs but refused to connect</li> </ul> Steps To Fix</h3> Load the Intel driver</strong></p> The AX210 needs the iwlwifi</code> kernel module and firmware:</p> boot.kernelModules = [ "iwlwifi" ]; hardware.enableRedistributableFirmware = true; </code></pre> This ensures the driver is in my init-ramfs</code> and the firmware is present.</p> Explicitly define Wi-Fi backend</strong></p> networking.networkmanager.enable = true; networking.networkmanager.wifi.backend = "wpa_supplicant"; </code></pre> Full Minimal Config Snippet</h3> All in all, this is what I added:</p> # Load the Intel AX210 driver and firmware boot.kernelModules = [ "iwlwifi" ]; hardware.enableRedistributableFirmware = true; # Enable the wireless module and NM networking.networkmanager.enable = true; networking.networkmanager.wifi.backend = "wpa_supplicant"; </code></pre> Rebuild & Reboot</h3> Make sure all the new config will take hold by rebuilding and rebooting.</p> sudo nixos-rebuild switch sudo reboot now </code></pre> You can confirm everything worked by running: nmcli device status \| grep wlp2s0</code></p> Victory!</h3> After rebooting, my iwlwifi</code> driver loaded, wlp2s0</code> came up, and nmtui</code> was able to both see and connect to the SSIDs.</p> ChatGPT assisted Changelog - 30/52 Unknown — Fri, 25 Jul 2025 00:00:00 +0000 Tech</h3> Waybar network module</strong></p> Discussions on adding an ethernet or wifi status module to Waybar configuration for Hyprland in NixOS.</p> Nixvim branch specification</strong></p> Explored how to pin a specific branch in nixvim and how imports resolve relative paths in modular NixOS configs.</p> Kolide nix-agent on NixOS</strong></p> Reviewed non-flake-based Kolide agent setup, module imports, time zone settings, and troubleshooting import errors.</p> Responsive CSS patterns</strong></p> Covered CSS techniques for responsive background images and use of the :before</code> pseudo-element to style boxes.</p> TUI music player pause fix</strong></p> Debugged keybinding logic in the Rust TUI music player, refining toggle_pause behavior to eliminate extra keystrokes.</p> Arch Linux vs NixOS installation</strong></p> Compared archinstall features, encryption support, and filesystem choices (btrfs vs ext4); discussed backup and fallback strategies.</p> Wi-Fi and GPG in NixOS</strong></p> Troubleshooted wifi connections via NetworkManager, git commit email issues, and GPG pinentry failures in a NixOS environment.</p> SSH key management</strong></p> Advised on forcing Git to use specific SSH keys per repository and evaluated ed25519 as the default key type.</p> Starship prompt in NixOS and Nushell</strong></p> Installed and configured Starship in NixOS, and explored Nushell integration. Need to fix path in Nushell.</p> Python and Ruby in nix-shell</strong></p> Set up nix-shell with Python packages, managed Ruby gems, and fixed pinentry and gemdir errors within shellHook workarounds.</p> Personal</h3> First Week at Discourse!</strong></p> The onboarding process has been very smooth and everyone is very welcoming. I am excited about my future there.</p> Swedish</strong></p> 215 days in a row.</p> Today is my first day at Discourse! Unknown — Mon, 21 Jul 2025 00:00:00 +0000 Today I am joining Discourse</a> as a software engineer on the infrastructure team.</p> Who is Discourse?</h3> Discourse is the 100% open source discussion platform built for the next decade of the Internet. We make it easy to have meaningful conversations and collaborate anytime, anywhere.</p> </blockquote> We are the home of ~22k communities across 23 countries and 13 timezones.</p> Why Discourse?</h3> I'm excited about working at Discourse for a number of reasons really.</p> Most of my tech and programming focused life has revolved around open source software and it's always been a dream to get paid to work on an open source software project.</p> </li> It's a software engineer role on the infrastructure team. I was introduced to DevOps work at my last job and fell down the rabbit hole. I love config based workflows so things like IaC and NixOS have really clicked.</p> </li> The company as a whole. This kind of goes with number 1 but I feel very aligned with Discourse as a company. We work in an async format while being completely remote. The company is very transparent, inclusive, and let's be real, the benefits are great.</p> </li> </ol> I think this can be a very important and fulfilling chapter of my professional and personal life and I'm looking forward to making the internet a better place through open source software.</p> This is the second time now I've lost a job then found a much, much better one. I think this is a valuable lesson to try and remember if I'm in that situation again.</p> If Discourse sounds like the place for you, see if we're hiring: https://discourse.org/jobs</a></p> NixOS as a daily driver or Zero to Nixty, part 8/? - Modular Config Unknown — Sun, 20 Jul 2025 00:00:00 +0000 Check out the whole series here:</p> NixOS as a Daily Driver - Zero to Nixty</a></p> Intro</h3> Today is all about configuration and setting up our new encrypted machine. As I stated at the end of the previous post, this didn't go as smoothly as I was hoping.</p> My plan was to just use labels when setting up the filesystems so my same exact configuration could be copied around. This plan was short-sighted for a number of reasons but it was definitely not going to work after seeing what the basic configuration looked like after installing with encryption enabled. The LUKS device setup is more complex than the normal, unencrypted filesystem config. There may be a way to use labels here but I don't really want to mess with that right now. I have an encrypted machine that boots so I'm going to leave it that way.</p> Breaking Config Into Modules</h3> After some thinking and research, I decided to refactor the way I store the config. I had been wanting to modularize it a bit anyway, so what better time than now.</p> First, I broke my config up into some modules in a common</code> directory.</p> nixos/ ├── common │ ├── base.nix │ ├── desktop.nix │ ├── packages.nix │ ├── services.nix │ ├── uefi.nix │ └── users.nix </code></pre> Then, I created a hosts</code> directory that includes a file for each machine. That file imports these basic modules and adds anything host specific like hostname.</p> nixos/ ├── hosts │ ├── framework-personal.nix │ ├── framework-work.nix │ └── macbook.nix </code></pre> One of those files looks like this:</p> { ... }: { imports = [ ../common/base.nix ../common/users.nix ../common/desktop.nix ../common/packages.nix ../common/services.nix ]; networking.hostName = "macbook"; } </code></pre> Then I just update the /etc/nixos/configuration.nix</code> that was created for me and import that one module. One of those files looks like this:</p> { config, pkgs, ... }: { imports = [ ./hardware-configuration.nix ./hosts/macbook.nix ]; # Replace actual UUID below boot.initrd.luks.devices."$UUID".device = "/dev/disk/by-uuid/$UUID"; # Do not change this value unless you know what you are doing! # This value does not* affect the Nixpkgs version. It is used to determine # whether to enable software and configuration options that require backwards # compatibility with older NixOS releases. Changing it may result in a system # that cannot be upgraded or has other surprising consequences. system.stateVersion = "25.05"; } </code></pre> Complete New Machine Flow</h3> Now, my new machine flow looks something like this:</p> Install NixOS</p> </li> Boot up and open a dev shell:</p> nix-shell -p git rustup neovim</code></p> (We use git to check out config, rustup to install rust/dotter, and neovim for easier editing.)</p> </li> Check out my dotfiles through https for now. This way I don't need to create an SSH key and add it to Github yet:</p> git clone https://github.com/ducks/dotfiles.git</code></p> </li> Install latest Rust then dotter:</p> rustup install stable; cargo install dotter</code></p> </li> Checkout a new branch in my dotfiles dir and add a new host file</p> </li> Add a new local config for Dotter at</p> dotfiles/.dotter/local.toml</code></p> </li> Use the installed Dotter to deploy my dotfiles:</p> ~/.cargo/bin/dotter deploy</code></p> </li> Rebuild NixOS:</p> sudo nixos-rebuild switch</code></p> </li> Start Hypr:</p> Hyprland</code></p> </li> Celebrate! :tada:</p> </li> </ol> If everything went well, I am now sitting behind a duplicate of my other machines. This workflow might seem long but it really only takes 10-30 mins to do all this. It can obviously vary on your machine and build size. It's far easier than any other new machine flow I've tried. I've read about people using ansible to do this kind of thing but this just feels so clean and easy once you get around the rough edges.</p> I have executed this flow on 3 machines now and it's worked well. I had to make a few small changes like adding a ref</code> to a branch for NixVim, and I'm honestly not sure why that is. I don't think it has anything to do with my config as it was building before.</p> Summary</h3> In this post, I showed how I broke my NixOS config down into modules so they can be easily imported per host. I think this is a clean and reproducible way to store and share my NixOS config. I have all my base config in easy to use modules, then I can simply add any host specific setup to that single file.</p> Next Time</h3> At this point, things are feeling pretty good for my setup personally. I keep things pretty minimal so as long as I can navigate around with the correct keybinds and have basic tools like Nix/Neovim and Librewolf installed and setup, I'm mostly good to go. There are definitely some non-NixOS specific things I could pivot to to stick with the "Daily Driver" theme.</p> If you're reading this and have suggestions or you're curious about something, let me know: nixos@jakegoldsborough.com</a></p> ChatGPT assisted Changelog - 29/52 Unknown — Fri, 18 Jul 2025 00:00:00 +0000 NixOS Daily Driver and Dotfiles</h3> Continued refining NixOS setup and daily driver blog series</li> Modularized dotfiles using Dotter with template support</li> Adopted approach of letting NixOS generate base config, layering custom on top</li> Explored idea of a "LazyNix" dev toolkit using importable modules</li> Troubleshot and resolved GRUB and UEFI encryption setup issues</li> </ul> Framework Laptop and QMK Customization</h3> New laptop! Framework 16</li> Investigated Framework RGB keyboard and LED matrix customization</li> Confirmed QMK support and existence of Rust libraries (most tooling is in C)</li> Searched for examples and guides to interact with Framework's LED module</li> </ul> Task Management and Productivity Tools</h3> Looked into Rust-based TUI task managers like Taskwarrior</li> Reviewed Taskwarrior features like due dates, tags, and urgency scoring</li> Practiced adding and updating tasks with CLI syntax</li> </ul> Git and Hosting</h3> Managing personal site using two remotes, pushing to both for now</li> Long-term plan is to self-host once everything is working reliably</li> </ul> NixCon 2025 Planning</h3> Would like to attend NixCon in Rapperswil-Jona, Sept 5 to 7</li> </ul> Avatars and Stickers</h3> Tweaked Tux-human avatar</li> Looked for places to buy open source stickers that support the projects</li> </ul> Neovim, Fonts, and Waybar</h3> Set up Nixvim to remove trailing whitespace on save</li> Troubleshot font issue in WezTerm by refreshing font cache and restarting</li> Created toggleable Waybar for system stats using manual launch approach</li> </ul> Language Learning</h3> 210 days of Swedish in a row</li> Trying to pick some German back up for trip to Prague</li> </ul> NixOS as a daily driver or Zero to Nixty, part 7.5/? - Trial by Encrypted Fire Unknown — Sun, 13 Jul 2025 00:00:00 +0000 Intro</h3> So far in this series, we have:</p> installed NixOS</li> enabled a desktop environment</li> setup a user and some basic daily driving tools</li> added our config to version control</li> introduced NixVim, a declarative way to configure Neovim</li> learned about NixOS dev environments</li> </ul> Catch up here: NixOS Daily Driver series list</a></p> This post is a bit of a detour as we'll be completing a fresh reinstall to enable disk encryption. We will be getting back to our configuration soon though. The next post will show how to take our version controlled config and apply it to our new install.</p> Encryption</h3> But first, let's talk encryption. So far I have not been installing NixOS with the drive encrypted. I recently learned that my new job will require the machine used for work to have an encrypted drive. This is a good thing and I should have been defaulting to encrypting my drives. Even though it's good, it does add some complexity to our NixOS configuration. Because I was doing this for the first time, I decided to first test the encrypted installation on an old System76 netbook I have.</p> Manual Attempts with LUKS and LVM</h3> Initially I planned to just do this manually. I have installed NixOS manually every time so far, so I was hoping it would just be a few more steps. For the most part this was true, but I still ran into some issues.</p> To start, I used gparted</code>, mkfs</code>, and cryptsetup</code> to format the disk and create some LUKS</code> partitions.</p> Partitioning and LUKS encryption</h4> # Partition disk (example: /dev/sda) parted /dev/sda mklabel gpt parted /dev/sda mkpart ESP fat32 1MiB 512MiB parted /dev/sda set 1 boot on parted /dev/sda mkpart primary 512MiB 100% # Format boot partition mkfs.vfat -F32 /dev/sda1 # Encrypt root partition with LUKS cryptsetup luksFormat /dev/sda2 cryptsetup open /dev/sda2 cryptroot </code></pre> This all worked fine and I was able to set a password for the encrypted drive and then unlock it right after.</p> LVM</h4> Now use LVM to allow flexibility inside the encrypted container:</p> # Initialize LVM pvcreate /dev/mapper/cryptroot vgcreate vg /dev/mapper/cryptroot # Create logical volumes lvcreate -L 16G -n swap vg lvcreate -l 100%FREE -n root vg # Format filesystems mkfs.ext4 /dev/vg/root mkswap /dev/vg/swap </code></pre> Mounting for Installation</h4> Next was to mount our partitions for installation.</p> # Mount the root volume mount /dev/vg/root /mnt # Mount the EFI partition mkdir -p /mnt/boot mount /dev/sda1 /mnt/boot # Enable swap swapon /dev/vg/swap </code></pre> Configuration and Installation</h4> The next step was to generate the NixOS configuration for our mounted filesystem:</p> nixos-generate-config --root /mnt</code></p> When running this, NixOS will generate a basic configuration for you based on the disks you create and mount. This works well when creating an unencrypted drive and the boot, root, and swap partitions are all configured correctly. For whatever reason, the LUKS</code> devices do not get picked up by this. This means we'll have to manually update our configuration to include the LUKS</code> devices.</p> This is fine because from what I read in the docs, this isn't too complex. It should look something like this:</p> # Attempted configuration boot.initrd.luks.devices."cryptroot" = { device = "/dev/disk/by-uuid/XXXX"; }; </code></pre> The docs also mention adding a kernel module: boot.initrd.kernelModules = [ "cryptd" ];</code></p> After that, it was time to rebuild then reboot.</p> And, at first, success! During boot, I get asked for a password to open my encrypted drive.</p> But then... failure! The passphrase will not work. My first instinct was I fat fingered it but I tried multiple times and it would just not work.</p> Recovery</h4> Welp, time to boot into the live ISO again. I wanted to doublecheck all the config and make sure I didn't mess something up.</p> First, I needed to open the encrypted root partition: cryptsetup open /dev/sda2 cryptroot</code></p> This creates /dev/mapper/cryptroot</code> and gives access to what's inside.</p> Next, the volume groups needed activated:</p> vgscan vgchange -ay </code></pre> Then we mount some important directories:</p> mount /dev/vg/root /mnt mkdir -p /mnt/boot mount /dev/sda1 /mnt/boot </code></pre> Now, we'll use nixos-enter</code>. This gave me a shell inside the broken system -- same environment as if it had booted normally.</p> We can check our config files to make sure nothing looks off:</p> nano /etc/nixos/configuration.nix nano /etc/nixos/hardware-configuration.nix </code></pre> Unfortunately for me, I could not find anything wrong. In fact, I tried 3 fresh installs and could never get it working manually.</p> Graphical Installer</h3> After all that, I decided to just give up on the manual install and try the graphical installer. I should have probably started here but I didn't see a certain sentence in the wiki in time.</p> There are a few options for full disk encryption. The easiest way is to use the graphical installer and choose "encrypt" while doing the installation.</p> </blockquote> And ya know what, it was easy. So easy in fact, it worked the first time and I could instantly power up, enter my encrypted drive password, and be taken to the login console.</p> Outro</h3> This post was kind of a detour from the normal series as we reinstalled so we could encrypt the drive. In the next post, I will be going over how we can take the configuration we added to git in the previous posts and apply it to our new, freshly installed and encrypted system.</p> Spoiler: it does not go as smoothly as I had hoped.</p> ChatGPT assisted Changelog - 28/52 Unknown — Fri, 11 Jul 2025 00:00:00 +0000 20250704 - 20250711</h3> Cyberspace</h3> NixOS</h4> Published two posts in Daily Driver series. My late 2011 Macbook Pro running NixOs is already feeling ready for daily use really:</p> Part 5</a></li> Part 6</a></li> </ul> </li> Fighting encrypted disk installation. Installation seems fine but then I can't unlock drive to boot up.</p> </li> </ul> Meatspace</h3> Disc Golf</h4> Played Pier Park</li> Played Memorial Park</li> Published post about experience with UDisc regarding my open source library: Fairway Client Not Fair Enough</a></li> </ul> </li> </ul> Language Studies</h4> Swedish</strong></p> 204 day streak on Babbel. Did a few more lessons this week and not just review. Listened to some Radio Sweden på lätt Svenska (Radio Sweden in easy Swedish)</li> </ul> Czech/German</strong></p> I found out I'll be going to Prague in Sept so I may try to pick up a little Czech and brush up on German as many speak it there apparently.</li> </ul> Garden</h4> Harvested 3 squash</li> Blueberry bush is fruiting</li> Raspberry bush is flowering</li> Tomatoes are flowering/growing</li> New tomato and pepper starts are doing well</li> </ul> Music</h3> Listened to a lot of Top Dawg Entertainment this week - Kendrick Lamar, Ab-Soul, Doechii, Schoolboy-Q</li> </ul> NixOS as a daily driver or Zero to Nixty, part 6/? - Dev environment Unknown — Tue, 08 Jul 2025 00:00:00 +0000 Recap</h3> In the last post, we added some quality of life enhancements. This included key remapping and getting hypridle and hyprlock set up.</p> See that post here</a>.</p> Intro</h3> Today, I will be introducing NixVim</code> and show you how to set up some per-project development shells. The latter is a very powerful part of NixOS as you'll see.</p> NixVim</h3> NixVim is a project that lets you declaratively configure Neovim in Nix. No init.lua</code>, vimrc</code>, or plugin managers like Lazy or Packer.</p> It's part of a broader Nix-native ecosystem where tools, config, and dependencies are defined in one declarative, reproducible system.</p> I use and suggest this for a few reasons:</p> Fully Declarative Neovim Config</li> </ol> This means all your plugins, keymaps, etc are explicity defined. This will allow you to easily version it, share it, and reproduce it on another system.</p> Automatic Plugin Management</li> </ol> No need to install anything with a plugin manager or run :PackerInstall</code>, :LazySync</code> etc. When you build Nix, NixVim builds Neovim with all your plugins downloaded and ready.</p> Tight Integration with Nix packages</li> </ol> You can inherit pkgs to bring in dependencies like ripgrep</code>, lua-language-server</code>, or stylua</code> directly. No external npm</code>, cargo</code>, pip</code>, or language-specific managers needed.</p> Initial Config</h4> We are going to start small with our config and extend it further later.</p> { pkgs, ... }: { programs.nixvim = { enable = true; # Enable basic plugins plugins = { lualine.enable = true; # Statusline telescope.enable = true; # Fuzzy finder treesitter.enable = true; # Better syntax highlighting }; # Use a Gruvbox theme (optional) colorschemes.gruvbox.enable = true; # LSP support plugins.lsp = { enable = true; # Example LSP: Lua servers = { lua-ls.enable = true; } } # Keymap example keymaps = [ { mode = "n"; key = "<leader>ff"; action = "<cmd>Telescope find_files<CR>"; options = { desc = "Find files"; }; } ]; }; } </code></pre> Let's break this config down.</p> First, and most importantly, we enable Nixvim by setting programs.nixvim.enable</code> to true</code>. Then, we enable a few basic plugins through programs.nixvim.plugins</code>.</p> After that we enable the gruvbox</code> color scheme and setup some basic LSP support.</p> Finally, we setup a keymap for <leader>ff</code> that uses telescope</code> to find files.</p> nix-shell</code> - What is it?</h3> Now onto nix-shell</code>. nix-shell</code> is a tool that lets you temporarily enter a development environment defined by a Nix expression. Think of it as a lightweight, project-specific sandbox with all the tools and dependencies you need -- and nothing you don't. They are like Python virtual environments, but for any tool or language.</p> You can use nix-shell</code> to:</p> Spin up a shell with specific packages available</li> Test tools or languages without installing them system-wide</li> Set up consistent dev environments across machines or teams</li> </ul> Why Use It?</h4> If you've ever run into "works on my machine" issues, nix-shell</code> is the antidote. By declaring your environment as code, you get repeatable, deterministic setups every time -- no more dependency drift or missing tools.</p> It's also fantastic for trying out a new language or toolchain. Want to test something in Ruby, Rust, or Go? You can be up and running with just a few lines.</p> Example</h4> Here’s what a simple shell.nix</code> might look like for Rust development:</p> { pkgs ? import <nixpkgs> {} }: pkgs.mkShell { buildInputs = [ pkgs.rustc pkgs.cargo ]; } </code></pre> Run nix-shell</code> in that directory, and boom, you'll be dropped into a shell environment with rustc</code> and cargo</code> available but without being installed globally.</p> One-Off Shells</h4> In fact, you don't even need a shell.nix</code> file. You could run nix-shell -p nodejs</code> and you would be dropped into a shell with nodejs</code> installed locally, meaning it's not installed globally.</p> Overall, nix-shell</code> is one of the most powerful parts of Nix/NixOS.</p> Summary</h3> In this post, we have:</p> Enabled NixVim and set up a simple, usable Neovim config</li> Introduced nix-shell</code> and showed how it can be used to create temporary, repeatable dev environments</li> Explained how to launch one-off shells and why nix-shell</code> is so useful for development workflows</li> </ul> NixOS as a daily driver or Zero to Nixty, part 5/? - QoL enhancements Unknown — Mon, 07 Jul 2025 00:00:00 +0000 Recap</h3> In the last post, we successfully got our configuration stored in version control. This will make it very simple to pass our config around if needed. We also learned about Dotter, a dotfile configuration management tool, which we will be using again today.</p> See that post here</a></p> Intro</h3> Today, we will be covering a few quality of life enhancements. Those will include keyboard remapping and locking our screen after a certain amount of idle time.</p> Quality of life enhancements are things that while not strictly necessary, they make life much better.</p> Keyboard Remapping</h3> First, I'll show you how to remap keys. For me personally, this will include:</p> Caps Lock -> Esc when pressed</li> Caps Lock -> Control when held (and another key is pressed)</li> </ul> Caps Lock as Control when being held is a new change for me but I'm really enjoying it. It has opened up many more keybind options for me.</p> This remapping will be done using "Interception Tools"</p> Interception Tools</h4> Interception Tools</a> is a set of utilities to control and customize the behavior of keyboard input mappings.</p> It works at a lower level than tools like xcape</code> or xmodmap</code> which makes it one of the only options available for customizing keyboard behavior across X11, Wayland, and the Linux console.</p> Below is an example of mine. It's stored in ~/dotfiles/nixos/modules/interception-caps.nix</code>.</p> This config:</p> enables the services.interception-tools</code> module</li> adds a plugin called caps2esc</li> adds a udevmonConfig</code> file</li> </ul> { config, pkgs, ...}: let intercept = "${pkgs.interception-tools}/bin/intercept"; uinput = "${pkgs.interception-tools}/bin/uinput"; in { services.interception-tools = { enable = true; plugins = with pkgs; [ interception-tools-plugins.caps2esc ]; udevmonConfig = '' - JOB: "${intercept} -g $DEVNODE \| ${pkgs.interception-tools-plugins.caps2esc}/bin/caps2esc -m 1 \| ${uinput} -d $DEVNODE" DEVICE: EVENTS: EV_KEY: [KEY_CAPSLOCK, KEY_ESC] ''; }; } </code></pre> Let's breakdown what's happening here.</p> JOB</code> defines a processing pipeline for input events. Each matching device runs this chain of commands.</p> </li> ${intercept} -g $DEVNODE</code> reads events from the input device</p> intercept</code> is the main input capture tool</li> -g</code> ensures the device stays grabbed</li> </ul> </li> caps2esc -m 1</code> is what actually transform the Caps Lock input into our dual behavior</p> Tap/Press = Escape</li> Hold = Control</li> Note - Control is only emitted if another key is pressed. holding Caps Lock will not simply emit Control</li> </ul> </li> ${input} -d $DEVNODE</code> writes the transformed input back into the system using uinput</code> kernel device</p> </li> DEVICE</code> block filters which devices this pipelines applies to.</p> EV_KEY: [KEY_CAPSLOCK, KEY_ESC]</code> means this only runs for devices that emit Caps Locks or Escape key events</li> </ul> </li> </ul> In short, this config captures raw key events for Caps Lock and Escape, transforms them using the caps2esc plugin, and injects the new behavior back into the system -- all at a low level that works across Wayland, X11, and even TTYs.</p> The above is stored in a separate NixOS module and then imported in my main configuration:</p> imports = [ # Include the results of the hardware scan. /etc/nixos/hardware-configuration.nix /etc/nixos/modules/interception-caps.nix ]; </code></pre> Idle and Lock</h3> Next, we will set our machine up to first lock, then power the screen down after a certain amount of idle time.</p> This is done using Hyprland companion packages, hyprlock</code> and hypridle</code>.</p> You can install those by adding them to your package list:</p> environment.systemPackages = with pkgs; [ hypridle hyprlock ]; </code></pre> Hyperidle</h4> Save this config as: ~/dotfiles/hypr/hypridle.conf</code></p> Here is my current setup:</p> general { lock_cmd = hyprlock before_sleep_cmd = hyprlock after_sleep_cmd = hyprctl dispatch dpms on } listener { timeout = 300 on-timeout = hyprlock } listener { timeout = 330 on-timeout = hyprctl dispatch dpms off on-resume = hyprctl dispatch dpms on } </code></pre> This is telling hypridle</code> to run hyprlock</code> as the lock_cmd and right before sleep. Then after we wake, use hyprctl to turn the monitor back on.</p> Then we set up a few simple listeners. The first one is for 300 seconds (5 minutes) and simply runs hyprlock</code> on-timeout. Then, I have another for 330 seconds (5 minutes 30 seconds) that will shut my monitor off on-timeout, and turn it back on after resuming.</p> Reload hypr conf with hyprctl reload</code> and you should now have a functioning idle and lock screen.</p> Hyperlock</h4> Note: Hyprlock does not automatically create a config, and without one, hyprlock</code> will not render anything, meaning you will just see your screen, but it will be locked -- you will not be able to interact with it again until you enter your password and hit Enter.</p> We are also able to customize our lock screen some. This config will also live in the same directory as the other hyprland config files. ~/dotfiles/hypr/hyprlock.conf</code></p> Below is an example of mine. It looks similar to css styling but not exactly.</p> Here, I'm setting up a simple background color, an input field with a border, and a label that just outputs the time. I like to keep mine simple but you can add a background image, move the input box around, and do a lot more than I am.</p> You can find more in the docs here</a>. It covers all the available elements you can use to style your Hyprlock screen.</p> background { color = rgb(282828) # Gruvbox dark background blur_passes = 0 } input-field { font_color = rgb(ebdbb2) inner_color = rgb(282828) # Slightly lighter than background outer_color = rgb(928374) outline_thickness = 3 size = 500, 50 position = 0, -33% } label { text = cmd[update:1000] echo "<b><big> $(date +"%H:%M:%S") </big></b>" color = rgb(ebdbb2) font_size = 32 position = 0, 0 valign = center halign = center } </code></pre> After adding both files, remember to run dotter deploy</code>. This will add symlinks for our newly added files to our correct Hyprland config directory by default based on our Dotter config.</p> Fun Fact</h3> This post was written from NixOS!</p> Summary</h3> In this post, we have:</p> Configured some muscle memory engraved key remappings including: Caps Lock -> Esc when pressed</li> Caps Lock -> Control when held (and another key is pressed)</li> </ul> </li> Setup hypridle</code> to lock out computer after 5 minutes then turn the screen off 30 seconds after that.</li> Styled a simple hyprlock</code> screen that shows the time and an input box for our password</li> </ul> Next Time</h3> Next time will be all about development work. We will introduce Nixvim and nix shell</code>. Nix shells are development environments you can set up via config. They are very powerful and make developing on NixOS much easier.</p> Fairway Client Not Fair Enough for MyFrisbee Unknown — Sun, 06 Jul 2025 00:00:00 +0000 Takedown Request</h3> Recently, I've been writing about reverse engineering a unique data structure I found while investigating the UDisc web app. I also created a free and open source library called Fairway Client. It's a fair way for accessing UDisc's .data</code> endpoints - the same ones their own web app uses. These are public, unauthenticated endpoints available to any browser.</p> The only intent was curiosity and a belief in open, user-accessible data and software. People have asked for this kind of access before, and UDisc has repeatedly said no. So I decided to see for myself. The data was right there - how hard could it be?</p> Turns out, not very.</p> Much of this data is user-submitted</strong>, and in some cases, user-paid</strong>. UDisc does offer a CSV export, but come on - programming is about automation, not downloading spreadsheets.</p> I posted about my findings and tools on the UDisc forum. That didn't go well. First, I didn't realize posts were moderated so my comment never got posted and that's on me. Second, they weren't pleased. I received a sternly worded email asking me to remove both the blog series and the codebase.</p> I wasn't sure what to expect - but I was still disappointed. I was hoping for curiosity, maybe even appreciation. Instead, I got a takedown request.</p> They cited their ToS, but if offering a clean, read-only interface to user-owned public data violates the ToS, maybe it's the ToS that is wrong.</p> The the code is down. I will be obscuring the posts to not reveal details but I have spent time and effort on them so they will be staying up in some form.</p> It might be time to give disc golf metrix a shot: https://discgolfmetrix.com/</a></p> ChatGPT Changelog - 27/52 Unknown — Fri, 04 Jul 2025 00:00:00 +0000 NixOS & NixVim Work</h3> Fixed issues with interception</code> and remapping caps lock to esc on tap and ctrl on hold</li> Investigated how to migrate from LazyVim to NixVim in a non-flake setup and how to modularize configuration.</li> Installed Starship and worked through integration with Nushell on NixOS, resolving autocomplete issues related to Carapace and Fish.</li> PipeWire was installed and CLI methods for inspecting its settings were explored.</li> Requested a developer-friendly NixVim config with completions and LSP support for both Node.js and Rust.</li> Compared nix-shell and flakes, with interest in setting up per-project environments for tools like Zola, Node, and Rust.</li> </ul> UDisc Reverse Engineering</h3> Public GitHub repo and blog posts were removed following a takedown request from UDisc. Redacted versions will be reposted later.</li> </ul> Etsy and Woodworking</h3> Added chunky maple cooking utensil</li> Added 4 piece mixed hardwood coaster set</li> Working on utensil rest</li> Working on guitar body</li> </ul> Personal</h3> Swedish learning streak hit 198 days</li> Received an offer letter!</li> </ul> NixOS as a daily driver or Zero to Nixty, part 4/? - dotfile/config management Unknown — Fri, 27 Jun 2025 00:00:00 +0000 From TTY to Tiling</h3> In the last post, we enabled Hyprland and set it to run by default on login.</p> In this post, we will be taking a slight detour and will be going over how to manage your NixOS config in version control. This step might be overkill for some but it makes it so we can easily checkout our config on any machine and have a working NixOS install fairly quickly.</p> We will also cover a little Hyprland config at the end.</p> Introducing Dotter</h3> Dotter</a> is a dotfile manager and templater.</p> You have a repo of dotfiles and two main config files:</p> .dotter/global.toml</code></p> global config where you define "modules" and tell Dotter how to handle copying config.</li> commit to version control</li> </ul> .dotter/local.toml</code></p> Per machine file that tells dotter which config to load. The idea being you may have different config needs for linux, macos, or windows.</li> This file is not committed to git because local lets you switch configs per machine without affecting version control</li> </ul> Add a .gitignore</code> if not already present. Add a new line: .dotter/local.toml</code></p> After configuring everything, you simply run dotter deploy</code> and the config files are copied to the locations set in global.toml</code>.</p> It's a great project and I highly recommend it.</p> Moving NixOS Config to Dotfiles Repo</h3> The first thing we'll do is add a new directory in our dotfile repo. Then we'll need to open up our .dotter/global.toml</code> file and add our NixOS config paths. That looks like this for me:</p> [nixos.files] nixos = '/etc/nixos' </code></pre> In Dotter talk, this is setting up a "module" named nixos</code>. We are telling Dotter that this module's files will be located in the nixos</code> folder and need to be copied to /etc/nixos</code>.</p> Now you will need to move the current NixOS config from /etc/nixos/configuration.nix</code> to your new nixos</code> folder.</p> One other step will be to allow writes to your /etc/nixos</code> dir by running sudo chmod o+w /etc/nixos</code>.</p> One important configuration option to mention for Dotter is the default_target_type</code>. Because of the template functionality of Dotter, it can either physically copy your config, or simply create a symlink.</p> I prefer symlinks by default so I use this config option. In global.toml</code>, I set the following:</p> [settings] default_target_type = 'symbolic' </code></pre> More info about that can be found in the Dotter wiki</a>.</p> If you plan to use symlinks with Dotter, you will need to open up nixos/configuration.nix</code> and make the hardware-configuration.nix</code> import an absolute path instead of relative path.</p> Example:</p> # nixos/configuration.nix { config, pkgs, ... }: { imports = [ /etc/nixos/hardware-configuration.nix ]; } </code></pre> You will also need to add your .dotter/local.toml</code> file.</p> That will look something like this:</p> packages = [ 'cmus', 'git', 'hypr', 'nvim', 'nushell', 'starship', 'waybar', 'wezterm', 'wofi' ] </code></pre> This is telling Dotter which of the "packages" in your global.toml</code> should be copied. This helps allow us to define our complete config in one repo even if every host doesn't use every package. Each host will have a local.toml</code> that copies specific packages.</p> Now it's finally time to run dotter deploy</code>. This will do the important step of taking our local dotfiles and copying (or symlinking) to the dirs we specified. After running that command, you will see /etc/nixos/configuration.nix</code> is present again.</p> The moment of truth, time to rebuild. You can start by doing a dry run sudo nixos-rebuild dry-activate</code>. This will build the system and tell you what would happen. If that goes well, run sudo nixos-rebuild switch</code>. NixOS gives a lot of protection around broken config so it's unlikely anything should break here and if it does, there will be an error that tells you why.</p> Commit your configuration file and merge your branch back to main</code>.</p> Adding Hyprland Config to Dotfiles Repo</h3> We are now going to do the same with our Hyprland</code> config. The steps are pretty much the same minus some chmod</code> and file path updates.</p> First, create a new branch and check it out. Then we create a new directory that I simply called hypr</code>. Next, copy the current Hyprland</code> config from ~/.config/hypr</code> into this new dir.</p> Now we will need to add a little Dotter config:</p> [hypr.files] hypr = '~/.config/hypr' </code></pre> Again, in Dotter talk, we are creating a hypr</code> module. Then we tell Dotter that any files in our local hypr</code> dir need to be copied to ~/.config/hypr</code>.</p> Now it's time to run dotter deploy</code>. This will do the step of copying our local config to the correct path in ~/.config</code>.</p> Confirm that file got copied and then run hyprctl reload</code> to reload the hypr</code> config.</p> Congrats On Version Controlled Config</h3> Your dotfile repo should now look something like this:</p> dotfiles/ ├── .dotter/ │ ├── global.toml │ └── local.toml ├── hypr/ │ └── hyprland.conf └── nixos/ └── configuration.nix </code></pre> We have now added two sets of our config into version control. This will allow us to easily pass around our config to a new machine if needed, especially with NixOS and it's declarative config.</p> Next Time</h3> In the next post, I plan to get back to actually setting up NixOS for daily driver use. This will probably include some hypr</code> config and introducing Nixvim. Nixvim is a way to manage your neovim plugins in a NixOS-y way.</p> ChatGPT Changelog (fka Weekly Summary) - 26/52 Unknown — Fri, 27 Jun 2025 00:00:00 +0000 NixOS Workflow & Improvements</h2> Refined NixOS development workflow by exploring the use of nix-shell</code> and Flakes for environment isolation and reproducibility. Discussed how to structure shell files for separate projects (e.g. Rust/Zola vs. Node).</li> Discovered how tools like rustup</code> and volta</code> behave in Nix environments. You acknowledged that nix-shell</code> helps contain them safely, but the Nix-native approach may still be preferable long term.</li> Cleaned up a bug with nixvim</code> setup by updating to the latest version and resolving a plugin rename (coedium-vim</code> ➝ windsurf</code>).</li> Added Blueman via Nix, and experimented with different ways to start Waybar without tying up terminal (eventually using hyprctl dispatch exec</code>).</li> Successfully reversed trackpad scroll direction in Hyprland using overrides, and this worked well across setup.</li> </ul> GitVote & GPG Work</h2> Progressed gitvote</code> CLI and backend significantly: Implemented registration and GPG signature support.</li> Verified that voting model and simulation strategy still worked.</li> Explored commit signing, storing keys in-repo, and ensuring modular CLI support for different user flows.</li> </ul> </li> Began planning for how to handle edge cases like simultaneous votes and eventually tallying.</li> </ul> Blogging & Writing</h2> Continued work on NixOS daily driver series, planning to document how to set up Dotter and Hyprland cleanly from scratch before layering more config.</li> Reflected on privacy-focused analytics post, considering how to improve tracking and discussing stance on respecting blockers.</li> </ul> UDisc API & Wrapper Library</h2> Worked on orchestration pattern for the TypeScript UDiscAPI</code> class, ensuring everything flows through a clean and testable interface.</p> </li> Removed unnecessary loadFromFile</code> logic and moved toward using raw JSON inputs with explicit route extraction.</p> </li> Streamlined the construction flow:</p> const udisc = new UDisc(); const schemaMap = udisc.extractSchemaMap(raw); const eventListings = udisc.resolveKeyValuePairs('eventListing'); </code></pre> </li> </ul> Personal Progress</h2> Maintained streak of learning Swedish — now at 193 days in a row. Mostly review. Need to listen to more podcasts/books again.</li> Only played one round of disc golf this week</li> </ul> How I accidentally wrote my first Neovim plugin Unknown — Wed, 25 Jun 2025 00:00:00 +0000 Just Show Me The Code</h3> repo</a></p> The Problem</h3> There is a simple motion I use in Neovim often and I finally decided to do something about it.</p> That motion is breaking up single line imports into multiline imports.</p> Example:</p> This:</p> import { foo, bar, baz } from './utils';</code></p> Should become:</p> import { foo, bar, baz, } from './utils'; </code></pre> It's a tiny thing but something I do all the time in javascript, typescript, and rust. Even if it's less than 80 characters wide, I really like breaking multiple modules imports down to separate lines.</p> The First Approach: Regex (And Why It Worked)</h3> The very first version of Vandelay used simple Lua string matching:</p> local pattern = [[import%s{%s(.-)%s}%sfrom%s(.);]] local names, from = string.match(line, pattern) </code></pre> This captured two groups:</p> names</code> - the full list inside { ... }</code></li> from</code> - the source string</li> </ul> After capturing, it simply:</p> Split names</code> on commas into a table of individual imports</li> Trimmed whitespace</li> Reconstructed the formatted import line with newlines and indentation</li> </ul> Why It Worked</h4> The format of imports I wanted to modify was extremely predictable. I only cared about one specific form and I was only operating on one line at a time. Lua strings were simple and fast for this very specific case. This worked extremely well from the start and passed some simple tests that tests import structure.</p> Adding Treesitter (And Why It Didn't Work)</h3> I thought using Treesitter would make the plugin more robust. It sounded like a perfect fit: parse the full AST, extract imports properly, and avoid relying on fragile string patterns.</p> In practice, I quickly ran into problems:</p> Complex Treesitter queries for what seemed like simple tasks</li> Accidental full-line and full-file rewrites when I only wanted to touch one line</li> Query capture ordering issues that merged unrelated imports together</li> Inconsistent grammar across different Treesitter parser versions</li> Parser installation requirements that added more dependencies</li> Much more boilerplate code for very minimal benefit</li> </ul> Treesitter excels for full-file refactors, linters, or analysis tools. But for surgical, highly structured, one-line rewrites? It was overkill.</p> What I Learned</h3> Treesitter is powerful. But power doesn’t always equal simplicity</strong> — especially for narrowly scoped formatting tasks.</p> For this plugin, regex provided:</p> Faster iteration</li> Predictable behavior</li> No parser dependencies</li> Simple implementation</li> Easier testing</li> </ul> Sometimes simple string matching really is enough -- especially when your input format is highly constrained.</p> nvim-vandelay 1.0</h3> The end result became nvim-vandelay</code>.</p> A micro-plugin for formatting imports</li> Fully manual keybind control</li> Regex-powered single-line rewriting</li> Rust and JavaScript support out of the box</li> Fully tested via Plenary + CI</li> </ul> Here is another link to the repo: nvim-vandelay</a></p> Introducing Shelltrax - Or how I vibe programmed my way to a TUI music player Unknown — Tue, 24 Jun 2025 00:00:00 +0000 Shelltrax</h3> github</a></p> </p> I love the terminal and have dabbled in Rust since the very early days. I've been to 5 RustConfs, but my actual knowledge of Rust never really went past the basics. I come from a scripted language background, so while I understood</em> the ideas, I didn't really understand them in practice -- mostly because I hadn't personally suffered the pain points Rust tries to solve.</p> The only way for me to truly understand was to build something real. Not another tutorial. Not another toy example. Something I'd actually use.</p> cmus</h3> cmus</a> is a small, fast</em>, and powerful console music player for Unix-like operating systems and it's easily one of the apps I use most.</p> And like I mentioned above, I learn best by writing real tools so why not try to recreate one of my daily drivers? It seemed like the perfect mix of things to learn: input handling, TUI design, file scanning, metadata parsing, and real-time playback.</p> Stack and Structure</h3> I tried to keep the stack small, modern, and as "Rust-native" as possible:</p> ratatui</code> - TUI layout and rendering</li> crossterm</code> - keyboard input handling and terminal backend</li> walkdir</code> - recursive file scanning and directory walking</li> id3v2</code> and symphonia</code> - parsing audio metadata (ID3, Vorbis, FLAC, etc)</li> rodio</code> - audio playback</li> </ul> Together, these gave me a good spread of "real" Rust problems to tackle: filesystems, decoding binary formats, audio streaming, real-time UI state, and concurrency.</p> Interface Design</h3> From the start, I wanted it to feel very simple.</p> The interface is split into a few key views:</p> A library view</strong>, where I can browse artists, albums, and tracks</li> A file browser</strong>, which lets me scan new folders and import music to the library</li> A persistent footer</strong>, showing the current track, album, artist and a real-time progress bar while the song plays</li> </ul> Even building that much required learning how to manage state in a long-running TUI app, wire up input handling with crossterm</code>, and keep the UI responsive while streaming audio in the background.</p> What's Working</h3> Despite starting this as mostly an experiment to learn Rust, I now have a music player that:</p> Scans my local library for FLAC and MP3 files</li> Parses metadata (title, album, artist, album artist, etc) correctly using Symphonia</li> Sorts and groups tracks by album artist for proper browsing</li> Supports autoplay, automatically advancing to the next track</li> Displays a footer with current song info and a live progress bar</li> Supports pause and resume functionality with synchronized playback state</li> </ul> It's already become my daily music player, replacing cmus for my listening.</p> </p> Reflections</h3> The most valuable part of this project was finally experiencing what Rust is really trying to protect you from.</p> Shared state</strong>: Coordinating real-time playback state across multiple threads (UI thread, playback thread, decode thread) forced me to actually deal with ownership, borrowing, and synchronization directly.</li> Lifetimes</strong>: I finally had to understand where lifetimes mattered when dealing with borrowed references and streaming APIs.</li> Real-world edge cases</strong>: Dealing with weird metadata formats, malformed files, and partial decode failures showed me how fragile real-world data can be.</li> </ul> I've read about these things for years, but building Shelltrax forced me to feel the problems directly. That's what finally made the learning click.</p> Vibe programming</h3> There's a lot of discourse around "vibe programming" -- the idea of just writing code by intuition, following your gut, and iteratively figuring it out as you go. It sometimes gets a bad rap: "You're just hacking around without fully understanding the language or design."</p> But for me, vibe programming doesn't mean ignoring fundamentals. It means building something real, fast enough to stay motivated, but being careful enough to stop and actually understand why something works (or why it doesn't).</p> I could have read Rust books or done more exercises, but none of that would have taught me what happens when a real audio stream crosses threads and you forget to reset a state flag at just the right time. And I'll be honest, I didn't magically learn Rust completely and know how to handle every situation but I certainly have a much better idea than a few weeks ago.</p> Vibe programming can force you into real problems. If you stay curious and careful, those problems become extremely effective teachers.</p> Building a Fully Decentralized Voting System Using Just Git and Pull Requests Unknown — Mon, 23 Jun 2025 00:00:00 +0000 The Premise</h3> What if we could build a fully transparent, auditable, and tamper-evident voting system -- without any servers, centralized backend, or traditional databases?</p> The result is GitVote</strong> - a simple but powerful decentralized voting system that uses nothing but Git, pull requests, and a little bit of Rust.</p> Why Git?</h3> Git already gives us:</p> A fully distributed ledger</li> Immutable commit history</li> Branching and merging workflows</li> Forking for isolated participant actions</li> Cryptographic integrity through hashes and signatures</li> </ul> With all that, we're part of the way to a blockchain.</p> I wondered if I could build a voting system where Git itself is the storage layer, the consensus layer, and the audit trail.</p> The Design</h3> At a high level, GitVote works like this:</p> Proposals</strong> are created as dedicated Git branches</li> Votes</strong> are submitted as files inside pull requests.</li> Voter ID</strong> is tied to each voter's Git configuration (name and email)</li> Duplicate Voting</strong> is automatically prevented via CI checks</li> Immutable blocks</strong> are built from merged votes using deterministic hashing</li> Tally results</strong> can be generated entirely offline from the final ledger</li> </ul> There's no central database, API server, or backend. Everything happens inside of Git.</p> The Voting Flow</h3> Proposal Creation</h4> Each new proposal is created as a new Git branch, for example:</p> proposal/001-color-vote</code></p> A simple schema.json</code> file defines the allowed choices for that proposal:</p> { "allowed": ["blue", "purple", "green"] } </code></pre> Voter Submission</h4> Voters follow this flow:</p> Fork the governance repo</li> Clone their fork locally</li> Checkout the correct proposal branch</li> Run GitVote CLI tool to cast their vote: gitvote cast --choice purple</code></li> </ol> This will:</p> Write a new vote file into votes/</code> (one file per voter)</li> Commits the vote using their Git identity</li> Signs the commit (GPG coming soon)</li> Prepares the branch for submission</li> </ul> Push their branch back to their fork</li> Open a pull request into the upstream proposal branch</li> </ol> Vote Validation</h4> Every pull request triggers CI which runs: gitvote validate</code></p> This will validate:</p> The vote file format</li> Compliance with the allowed schema</li> No duplicate voters (one voter, one vote)</li> </ul> Invalid votes fail the CI and will not be merged</p> Merging & Chain Building</h4> Once a valid PR is merged, CI will automatically run: gitvote build-chain</code></p> This scans all merged vote files and creates an immutable hash-linked chain of blocks stored as plain JSON:</p> blocks/ block-0000.json block-0001.json ... </code></pre> Each block includes:</p> The vote choice</li> The voter identity</li> The original timestamp of the vote</li> The Cryptographic hash linking it to the previous block</li> </ul> Tallying Votes</h4> At any time, anyone can run: gitvote tally</code></p> This reads the blocks/</code> directory and generates a full tally of the current vote state:</p> Vote Tally: purple votes: 3 red votes: 2 Total unique voters: 5 </code></pre> No external system is needed to calculate the results — everything lives entirely inside Git.</p> The Tech Stack</h3> Rust for the core CLI, gitvote</code></li> Github Actions for CI validation and chain building</li> Git itself as the distributed backend</li> </ul> Security</h3> Voter ID is tied to each user's Git config (user.name</code> and user.email</code>)</li> CI fully enforces schema validation and prevents voter duplication</li> All votes are auditable forever via immutable commit history</li> The chain is fully deterministic and reproducible offline</li> The ledger can be archived back into main</code> for permanent recordkeeping</li> </ul> The Benefits</h3> Simplicity:</strong> No central server or complex infrastructure</li> Transparency:</strong> Every vote and rule is visible to all voters</li> Auditability:</strong> Anyone can verify the ledger at any time</li> Offline verifiability:</strong> The full vote chain is just a Git repo</li> </ul> Future Plans</h3> There are a number of interesting enhancements that could be made here I think:</p> GPG signature enforcement</li> Anonymous but verifiable voting via zero-knowledge proofs</li> Weighted or ranked ballots</li> Multi-proposal governance workflow</li> </ul> For now, GitVote is a minimal, functioning, fully decentralized voting system.</p> The Code/Demo</h3> You can find the CLI here: GitVote CLI</a></p> You can find a test governance repo here: gitvote-test</a></p> By going to actions</a>, you can see the various CI workflows that run during the voting process.</p> First, I submit a valid vote for purple</strong></li> Then, I attempt to vote again for green</strong>, which correctly fails due to duplicate voter prevention</li> Finally, I simulate a new voter by spoofing a different Git identity (via git config</code>), submit a vote for blue</strong>, and the vote passes validation</li> </ul> Closing Thoughts</h3> What originally started as an idea for "Gitcoin" and wanting to learn more about blockchains turned into a fully functional, fully auditable governance platform -- all built entirely on top of Git (and Rust).</p> It was pretty satisfying to turn pull requests, branch protections, and hash-linked commits into a simple, verifiable voting process.</p> The Accidental Complexity of Doing The Right Thing or The Pain of Setting Up Privacy-Focused Analytics (2025 Edition) Unknown — Sun, 22 Jun 2025 00:00:00 +0000 Introduction</h3> As I've mentioned in the past, I’ve been writing and blogging more, and I became curious if anyone was actually reading my posts.</p> Before I go any further, I need to make it clear that I am very privacy-focused. I hate logging, tracking, fingerprinting, or any kind of unnecessary data collection. A user’s data is theirs -- I have no interest in storing anything about them. I just want a basic count of which pages are being visited.</p> Naturally, I asked ChatGPT for recommendations based on my current setup.</p> I'm already using Caddy as my web server and TLS manager, so the first suggestion was straightforward: just enable HTTP access logs and analyze them.</p> Attempt 1: Server-side access logs (Caddy)</h3> The basic flow here would be:</p> enable http logs in Caddy</li> scrape log file</li> count requests as rough pageviews</li> </ul> In theory, this sounded perfect. I wasn’t looking for fancy dashboards or detailed metrics -- just simple counts of which pages were being hit. Plain log files should be more than enough.</p> Caddy, by default, doesn't actually log HTTP requests unless you configure it to. More surprisingly, in many builds of Caddy (especially those provided by package managers), the http.handlers.log</code> module isn’t even included.</p> At first I thought I was on the wrong version, but after some digging, I realized that full HTTP access logging in Caddy requires building your own custom binary with xcaddy</code></a> to enable the logging module. This felt like massive overkill for something as basic as HTTP request logging.</p> After trying multiple versions, failing to get access logs working, and realizing that Caddy’s modular architecture was actively getting in my way, I gave up on this approach.</p> I asked ChatGPT for other options.</p> Attempt 2: Goatcounter via Docker</h3> The next recommendation was to use a dedicated privacy-first analytics tool. Several good open-source options exist: GoatCounter</a>, Plausible, and Umami.</p> After doing a bit of research, GoatCounter stood out. It’s fully open-source, extremely privacy-focused, lightweight, and seems purpose-built for people like me who just want simple pageview counts without any tracking nonsense.</p> Even better, GoatCounter has Docker images available.</p> But of course — the Docker image that used to be hosted on Docker Hub was no longer available. The project had moved its images to GitHub Container Registry (GHCR), and GHCR was returning permission errors when I tried to pull the image anonymously. Apparently GHCR increasingly requires authentication even for public images, depending on Docker version, client configuration, and random GitHub API mood swings.</p> Attempt 3: Building my own Goatcounter Docker image</h3> After that, I decided to just build the image myself.</p> GoatCounter publishes a Dockerfile in the repo, so this should be straightforward:</p> git clone https://github.com/arp242/goatcounter.git docker build -t goatcounter:local . </code></pre> The Dockerfile requires Docker BuildKit support, and uses newer Dockerfile features like --exclude</code>, which aren't supported by Docker’s legacy builder. I had to enable BuildKit, but enabling BuildKit required docker-buildx</code>, which wasn’t installed by default on my Arch system.</p> Once I installed docker-buildx</code>, I ran the build again. This time, it started pulling Go modules but failed with timeouts halfway through the build.</p> I retried. And retried. BuildKit timeouts, network flakiness, CDN rate limiting -- you name it. What should have been a 30-second build turned into multiple rounds of fighting with Docker’s build system and Go’s module proxy ecosystem.</p> At this point, Docker was no longer simplifying anything — it was actively making everything worse.</p> Attempt 4: Running GoatCounter directly</h3> By this point I was fully in "I don’t even care anymore" mode.</p> GoatCounter is a Go program that ships prebuilt binaries. I could just download the standalone Linux binary and run it behind Caddy directly, without Docker at all.</p> Except even that wasn't as straightforward as it should have been.</p> The download URL on GitHub releases points to a gzip-compressed file. I accidentally downloaded it and tried running it directly without decompressing it first, leading to confusing shell errors ("command not found" as it tried to parse the binary as text). Once I properly decompressed it, I finally had a functioning ELF binary.</p> I ran goatcounter serve</code>, initialized the SQLite database, and got it fully running behind Caddy with one reverse proxy entry. TLS worked automatically, and finally, my simple analytics system was live.</p> Observations</h3> Docker was supposed to make self-hosting trivial. But broken registries, permission issues, changing build standards, and fragmented tooling made things much harder. Self-hosted projects often don't have the resources to maintain registry hosting, Docker images, and packaging across multiple platforms. The friction involved in doing things ethically discourages people from even trying privacy-respecting solutions.</p> It's no surprise so many people just give up and paste Google Analytics into their site -- it's not better technology, it's easier deployment.</p> Conclusions</h3> Privacy-first analytics tools absolutely exist — GoatCounter is an excellent project, and I’m very happy with it now that it’s running.</p> But the tooling friction creates artificial barriers that discourage adoption. Ironically, it's often easier to deploy privacy-invasive analytics than privacy-respecting ones.</p> There’s a huge opportunity here to improve the ecosystem:</p> Smarter build tooling</li> Better Docker automation</li> Easier packaging of self-hostable apps</li> (Maybe even a tool that turns install instructions into Dockerfiles automatically — but that’s a post for another day...)</li> </ul> If we want ethical software to be the default, we need to make it easier, not harder.</p> Edit (20250526)</h3> There IS</strong> a Docker Image</h4> Welp, naturally, after all of this — the registry issues, the broken builds, the manual binary install — I found out there is</em> a Docker image for GoatCounter:</p> arp242/goatcounter</a></p> (Yes, maintained by the actual author.)</em></p> Apparently I was just one docker pull</code> away the whole time.</p> :facepalm:</p> node-postgres-exporter — A Lightweight, Configurable PostgreSQL Prometheus Exporter Unknown — Fri, 20 Jun 2025 00:00:00 +0000 I’m releasing a small project I’ve been building:</p> node-postgres-exporter</code>, is a lightweight Prometheus exporter for PostgreSQL, written in Node.js.</p> The goal: build a fully configurable exporter that supports multiple databases, dynamic custom metrics, and solid production fault tolerance — while keeping the design modular and simple to operate.</p> There are excellent existing exporters in the ecosystem — but many of them require full privilege access, tightly coupled SQL views, or lack flexible multi-database support.</p> This exporter aims to solve a more targeted problem:</p> Support multiple independent PostgreSQL instances</li> Expose core database metrics (connections, size, etc.)</li> Allow fully configurable, per-database custom metrics via JSON</li> Provide basic fault isolation so partial database failures don't block full scrapes</li> Expose Prometheus-friendly endpoints with modern HTTP APIs</li> </ul> Key Features</h3> Node.js + Express based architecture</li> Uses pg</code></a> for database access via dedicated connection pools per database</li> Uses prom-client</code></a> for full Prometheus metric management</li> Simple configuration via JSON files (databases.json</code> and queries.json</code>)</li> API key authentication (Bearer token) for securing metrics endpoint</li> Graceful shutdown handling for safe database pool cleanup</li> Fully Dockerized with ready-to-run docker-compose</code> setup for local testing</li> Includes health endpoints: /healthz</code>, /readyz</code>, /livez</code>, /configz</code></li> </ul> Metric Types Supported</h3> PostgreSQL connection counts</li> Per-database size metrics</li> Custom query metrics with support for Gauge</code> and Counter</code> types</li> Exporter self-metrics: scrape duration, error tracking, scrape lockouts, etc.</li> </ul> Dynamic Query Configuration</h3> One of the core design goals for node-postgres-exporter</code> was flexibility without requiring code changes. To achieve this, all custom metric definitions are fully externalized via configuration files.</p> queries.json</code></p> Custom metrics are defined in a simple queries.json</code> file, allowing operators to add new metrics by writing plain SQL queries without modifying or redeploying the exporter. Each query entry includes:</p> name</code> – the Prometheus metric name</p> help</code> – description for the metric</p> type</code> – gauge or counter</p> labels</code> – array of columns to extract as metric labels</p> query</code> – the raw SQL statement to run against the target database</p> [ { "name": "active_users", "help": "Number of active users", "type": "gauge", "labels": ["status"], "query": "SELECT status, COUNT()::int FROM users GROUP BY status" } ] </code></pre> On each scrape, the exporter executes the configured queries, extracts label values from the row fields, and populates the Prometheus metric accordingly.</p> Fault Tolerance and Isolation</h3> Another design goal was to handle database failures gracefully. If one database becomes unavailable (network issue, restart, maintenance), the exporter:</p> Continues scraping all healthy databases</li> Exposes scrape success/failure per database as dedicated metrics (pg_scrape_success</code>)</li> Never fails the entire scrape due to single database issues</li> </ul> Internally, this is implemented using:</p> Promise.allSettled()</code> to concurrently scrape databases while isolating failures</li> Explicit error metric tracking</li> Per-database scrape duration timing</li> </ul> Example Use Case</h3> This design fits environments where:</p> You manage multiple distinct PostgreSQL instances</li> You have limited privilege access on some databases</li> You want metrics to be purely driven by SQL queries without deeper system integration</li> </ul> What it’s not trying to be</h3> A full replacement for highly privileged exporters like the canonical postgres_exporter</code></a></li> A deep SQL monitoring agent requiring superuser roles or heavy introspection</li> </ul> This exporter is intentionally simple, safe, and scoped</strong> — easy to audit and deploy.</p> Roadmap / Future Ideas</h3> There’s plenty of room for future enhancement:</p> Hot-reload support for queries and DB configs</li> JSON schema validation on configuration files</li> Cardinality protection on dynamic label sets</li> Additional metric types (Histogram</code>, Summary</code>)</li> Publish Docker images to container registries</li> Integration with secret management for DB credentials</li> </ul> Source Code</h3> Repo available here: https://github.com/ducks/node-postgres-exporter</a></p> A Side Benefit</h3> Although this started as part of an audition project, I ended up building something I’d absolutely consider productionizing for real-world use cases — and more importantly, something I can showcase as a clean systems-level engineering project.</p> ChatGPT Changelog (fka Weekly Summary) - 25/52 Unknown — Fri, 20 Jun 2025 00:00:00 +0000 Weekly Summary — 2025-06-13 to 2025-06-20</h2> Accomplishments</h3> Shelltrax TUI</h4> Continued refinement of Shelltrax (TUI music player).</li> Autoplay behavior adjustments: added logic to handle album track advancement.</li> Made progress on Symphonia integration for FLAC and seeking support.</li> </ul> open-udisc-api</h4> Further decoding work on Remix-style .data</code> format.</li> Continued schema-indexed record handling.</li> Published part 4 of your UDisc reverse engineering blog series.</li> Meta post idea evolving for later publication.</li> </ul> node-postgres-exporter</h4> Built a lightweight node-postgres-exporter</code></a> for Prometheus.</li> </ul> NixOS</h4> Ongoing modular NixOS configuration improvements.</li> TTY-first daily driver series is slowly building up. New post soon.</li> </ul> Swedish studies</h4> Hit 186 days in a row on Babbel.</li> Published “Typing Swedish with US Keyboard” blog post.</li> </ul> TODOs</h3> ShellTrax TUI</h4> Fix footer (currently doesn't update with next song, and progress is not perfect)</li> Fix broken metadata parsing</li> </ul> open-udisc-api</h4> Figure out what post 5 should be about</li> </ul> NixOS</h4> Write next post about hyprland and other config updates</li> </ul> Swedish studies</h4> Listen to more audiobooks this week</li> Do more than bare minimum reviews</li> </ul> ChatGPT Changelog (fka Weekly Summary) - 24/52 Unknown — Fri, 13 Jun 2025 00:00:00 +0000 Happy Friday the 13th!</h3> I have decided to slightly change up my personal weekly summary posts.</p> I have been using ChatGPT more and more and really find it to be an important tool. It saves me so much time with debugging error messages and digging through docs. It can also keep very good track of what I've been working on and thinking about. Because of this, I have decided to update the way I do the weekly summary. I am going to let ChatGPT generate a personal changelog of everything I have been working on. It's not perfect so I do have to edit it some but it still does a better job than I could ever do.</p> So with that, here is my weekly ChatGPT changelog:</p> Accomplishments (Since June 7)</h3> UDisc API / Blog Series</h4> Published Part 4 of the blog series: deep dive into smartLayouts</code> and holes</code>.</li> Improved deepHydrate</code>, began resolving issues with arrays of unresolved IDs.</li> Continued resolving schema-indexed keys (e.g. _254: 270</code>) for clarity.</li> Added blog link to open-udisc-api</code> README.</li> Cleaned up TypeScript types and debugged schema hydration logic.</li> </ul> Infra & DevOps</h4> Set up Gitea using a Linux service.</li> Implemented a Git pre-push hook to filter Zola drafts before publishing.</li> Decided to drop OpenAPI support for the current API project.</li> </ul> PostgreSQL Exporter</h4> Deployed a general-purpose PostgreSQL -> Prometheus exporter.</li> Added /metrics</code>, /livez</code>, /readyz</code>, and /configz</code> endpoints.</li> Configured basic token authentication.</li> Documented endpoints and auth in the README.</li> </ul> NixOS / Hyprland</h4> Diagnosed Hyprland reload issues involving exec-once</code> behavior.</li> Installed and confirmed use of: wezterm</li> dunst</li> hypridle</li> bibata-cursor-theme</li> </ul> </li> Explored xcursor previews and how to apply cursor themes via Nix.</li> Set up Waybar with Gruvbox-inspired CSS.</li> </ul> Miscellaneous</h4> Continued Swedish learning streak (currently 179+ days).</li> Expanded concept for a first-person disc golf course viewer.</li> Researched 360-degree and panoramic photo capture on Android/GrapheneOS.</li> </ul> To-Do / Improvements</h3> UDisc API + Blog</h4> Fix unresolved arrays in deepHydrate</code>, such as targetPositionLabels</code>.</li> Begin drafting a "meta" post summarizing the UDisc reverse-engineering series.</li> Write additional parts exploring fields like dogleg</code> or obLines</code>.</li> Explore creating a visualizer for hydrated course data.</li> </ul> Infra / Self-Hosting</h4> Document the Gitea systemd service setup.</li> Write a blog post about using Git hooks to manage Zola drafts.</li> </ul> NixOS / Hyprland</h4> Investigate why exec-once</code> commands don't rerun on hyprctl reload</code>.</li> Continue refining modular environment.systemPackages</code> layout.</li> Extend daily-driver blog series for NixOS on MacBook hardware.</li> </ul> Portfolio + Sharing</h4> Add README links or badges to published blog posts.</li> Write a post about decoding custom schema formats in APIs.</li> Share blog content on Hacker News, Lobsters, or relevant communities.</li> </ul> Typing åäö in Hyprland: A US, Mac-style Keyboard Guide Unknown — Thu, 12 Jun 2025 00:00:00 +0000 Intro</h3> As I've mentioned in the previous GPT Changelog nee Weekly Summary, I have been learning Swedish for over 6 months now. I'm getting pretty good at listening and reading, but I have been doing very little speaking and typing practice. I would like to change that by building muscle memory through proper Swedish typing.</p> Enabling in Hyprland</h3> Like many things in the Linux world, there is more than one way to do this. The easiest way would just be to use the GUI menu and add the keyboard. I would prefer to keep this declarative and inside some config files so it's more easily reproducible.</p> Instead, I will add some config to Hyprland to enable this. This config will:</p> enable the Swedish kb_layout</code></li> add the US variant for the Swedish layout</li> sets rctrl</code> as the key that toggles between layouts</li> sets ralt</code> as the modifier key for Swedish keys</li> </ul> input { kb_layout = us,se kb_variant = ,us kb_options = grp:rctrl_toggle,lv3:ralt_switch } </code></pre> Save the config and reload the hypr config: hyprctl reload</code></p> What is the US variant?</h3> Before testing it out, I should explain what the US variant is.</p> The Swedish (US)</strong> layout — sometimes referred to as "Swedish for US keyboards" — is a variant of the traditional Swedish keyboard layout that’s specifically designed for people using US physical keyboards</strong>. It allows you to type Swedish characters like å</code>, ä</code>, and ö</code> without rearranging the rest of your familiar QWERTY key positions.</p> This layout keeps the standard US punctuation and symbol positions intact</strong> — like /</code>, @</code>, ;</code>, and "</code> — while introducing the necessary Swedish characters via the Right Alt key</strong> (also called AltGr</code> in XKB terminology).</p> Unlike the default Swedish layout</strong>, which assumes a physical keyboard with keys labeled for Swedish (and repositions many punctuation marks), the Swedish (US)</strong> layout overlays the Swedish characters on a standard US keyboard. This makes it ideal for:</p> Swedish learners or expats using American keyboards</li> Developers or typists who need occasional access to å</code>, ä</code>, and ö</code></li> Anyone who doesn’t want to remap common keys like @</code>, \|</code>, or /</code></li> </ul> In practice, this means you keep your normal US key behavior, and just use Right Alt as a modifier</strong> to access Swedish characters:</p> Right Alt + w</code> = å</li> Right Alt + '</code> = ä</li> Right Alt + ;</code> = ö</li> </ul> And uppercase versions with Shift.</p> If you’re used to US QWERTY and want to type Swedish without sacrificing developer-friendly symbols, Swedish (US)</strong> is the best option available — and it integrates smoothly into Linux environments like Hyprland when configured correctly.</p> 🇸🇪 Swedish (US) Layout – Character Cheat Sheet</h3> Character</th> Key Combo</th> Notes</th> </tr> </thead> å</td> Right Alt + w</kbd></td> Lowercase å</td> </tr> Å</td> Right Alt + Shift</kbd> + w</kbd></td> Uppercase Å</td> </tr> ä</td> Right Alt + '</kbd></td> Apostrophe key</td> </tr> Ä</td> Right Alt + Shift</kbd> + '</kbd></td> Shift + Apostrophe</td> </tr> ö</td> Right Alt + ;</kbd></td> Semicolon key</td> </tr> Ö</td> Right Alt + Shift</kbd> + ;</kbd></td> Shift + Semicolon</td> </tr> </tbody> </table> Conclusion</h3> You should now have a working Hyprland config that will allow you to type Swedish on a Mac-style, US variant keyboard.</p> Weekly Summary - 23/52 Unknown — Sat, 07 Jun 2025 00:00:00 +0000 Accomplishments</h3> Reverse Engineering UDisc API</h4> Published Part 3 of blog series on Course</code> and CourseDetails</code> structure.</li> Drafted outline for Part 4, focused on smartLayouts</code> and hole</code> info.</li> Renamed resolveSchemaMap</code> to a clearer, more specific function name.</li> Improved nested hydration using deepHydrate</code> for decoding nested data.</li> Considered naming conventions like courseWithDetails</code> for client API.</li> Decided to provide a client library first, rather than a full backend.</li> </ul> TypeScript Module and Publishing</h4> Adopted YYYYMMDD</code> format for versioning with semantic meaning.</li> Resolved JSON parsing and bundling issues in the TypeScript setup.</li> Held off on publishing to npm, but prepared module for later release.</li> </ul> Static Site and Blogging</h4> Fixed insecure site warning by enabling HTTPS on GitHub Pages.</li> Designed favicons and tried different accent colors and sizes.</li> Planned a meta-post to tie the blog series together conceptually.</li> </ul> NixOS Daily Driver Series</h4> Published Part 3 of your NixOS daily driver blog series.</li> Started exploring ideas for better display managers like Lemurs.</li> </ul> Gitea Self-Hosting</h4> Setup Gitea as Linux service.</li> Resolved SSH cloning issues by switching to internal SSH service.</li> Researched CI/CD via Woodpecker</li> </ul> Swedish Language Learning</h4> Reached 179-day streak learning Swedish using Babbel.</li> </ul> To-Do / Next Steps</h3> UDisc Blog Series</h4> Write and publish Part 4 about smartLayouts</code>, holes</code>, and tees</code>.</li> Create a meta-post summarizing the series with internal references.</li> Explore building a schema or data visualizer for reader clarity.</li> </ul> open-udisc-api Module</h4> Prepare for npm publishing (README, exports</code>, format cleanup).</li> Write more Vitest-based tests using mock data to avoid real API calls.</li> Add inline documentation and usage examples to client methods.</li> </ul> NixOS Configuration</h4> Start Lemurs setup for display management.</li> Write Part 4 of the daily driver series covering service setup.</li> Explore modularizing environment.systemPackages</code> further.</li> </ul> Gitea Enhancements</h4> Consider automating deployment with Git hooks or CI.</li> </ul> Additional Ideas</h4> Write a short post explaining UDisc .data</code> format independently.</li> Research legality of wrapper libraries for non-public data APIs.</li> Consider writing a proxy or wrapper API as a hosted endpoint.</li> </ul> NixOS as a daily driver on a late 2011 Macbook Pro, part 3/? - user, WM, tools Unknown — Thu, 05 Jun 2025 00:00:00 +0000 Recap</h4> See Part 2</a> where I cover installation and basic configuration.</p> Outline</h4> Things we will be covering in this post:</p> adding a non-root user with sudo access</li> installing a window manager - Hyprland</li> installing some tools - neovim, git, waybar, wezterm</li> </ul> Install a Text Editor</h4> First things first, let's install a better text editor to make our configuration updating easier.</p> You will have to use nano</code> for this. Open /etc/nixos/configuration.nix</code> and add the following:</p> programs.neovim = { enable = true; defaultEditor = true; }; </code></pre> Use ctrl+o</code> then ctrl+x</code> to write and exit nano.</p> Then run nixos-rebuild switch</code>. NixOS will rebuild your config and return you to a terminal. You should now be able to start neovim by running nvim</code>.</p> Adding a User</h4> Now that we can edit files easier, let's add a non-root user.</p> users.users.disco = { isNormalUser = true; extraGroups = [ "wheel" # Allows sudo access "networkmanager" # Allows controlling network "audio" # Audio device access "video" # Video devices (e.g. backlight, GPU) "input" # For input devices like keyboard/mouse config ]; }; </code></pre> Again, save and exit and then rebuild:</p> nixos-rebuild switch</code></p> After successfully rebuilding, you will need to set a password for the new user. For me that's:</p> passwd disco</code></p> Then you can exit</code> and login as your new sudo accessible user.</p> Enable Network Tools</h4> This will enable tools like nmtui</code> to allow for easier network setup.</p> networking.networkmanager.enable = true;</code></p> Install a Window Manager and Daily Driver Tools</h4> I am using Hyprland</a>. Hyprland is a dynamic Wayland compositor that supports tiling, floating, and hybrid layouts.</p> Add the following to your /etc/nixos/configuration.nix</code>. This enables Hyprland along with XDG portals, which are required for features like file pickers, screen sharing, and communication between sandboxed apps (especially Flatpaks and browsers).</p> programs.hyprland.enable = true; xdg.portal = { enable = true; wlr.enable = true; extraPortals = [ pkgs.xdg-desktop-portal-hyprland ]; }; </code></pre> Before rebuilding this time though, we will also install some daily driver tools.</p> One reason for this is that Hyprland</code> uses the kitty</code> terminal by default.</p> Look for this line in your /etc/nixos/configuration.nix</code> file:</p> environment.systemPackages = with pkgs; [ </code></pre> You will likely find this commented out with wget</code> listed as a package.</p> Expand on that section so it becomes:</p> environment.systemPackages = with pkgs; [ kitty # needed by Hyprland by default wget hyprpaper # background utility for Hyprland hyprlock # screen lock utility for Hyprland librewolf # privacy focused browser based on firefox wofi # needed by Hyprland by default git waybar # status bar for Hyprland wezterm ]; </code></pre> Some tools like neovim</code> and hyprland</code> have official NixOS modules, which let you enable them declaratively using enable = true;</code>. Other tools (like git</code> or librewolf</code>) don’t have modules and should be added directly to environment.systemPackages</code>.</p> Now it's time to rebuild. Again, this is done by: sudo nixos-rebuild switch</code>.</p> You can now manually start Hyprland</code> by running: exec Hyprland</code></p> You will be greeted with nothing but a random wallpaper supplied by Hyprland.</p> A couple important default keybinds are:</p> SUPER + q - opens terminal</li> SUPER + r - opens wofi app runner</li> </ul> Starting Hyprland on Login</h4> Let's make Hyprland</code> start on login. Create a ~/.bash_profile</code> file if it doesn't exist and add this:</p> if [ -z "$DISPLAY" ] && [ "$(tty)" = "/dev/tty1" ]; then exec Hyprland fi </code></pre> Summary</h4> In this post, we have:</p> added a non-root user and set their password</li> installed a window manager, Hyprland</code>, and set it to start on login</li> installed multiple important daily driver tools like git and librewolf</li> </ul> Next Time</h4> In Part 4, we'll continue to configure Hyprland</code>: adding keybindings, wallpapers, waybar, and maybe even a lockscreen.</p> NixOS as a daily driver on a late 2011 Macbook Pro, part 2/? - Installation, Basic Configuration Unknown — Wed, 04 Jun 2025 00:00:00 +0000 See Part 1</a> where I cover why you would want to run NixOS as a daily driver.</p> In this post, we will cover installation on a personal machine and setting up a basic configuration file.</p> Just as a note, for this specific post I am using:</p> efi</li> minimal ISO</li> dd (tool to write ISO)</li> </ul> See https://nixos.org/manual/nixos/stable/#ch-installation</a> for a full installation guide.</p> Installation</h4> Because Nix and Nixpkgs can be installed on almost any Linux distro, it's possible to install NixOS from inside an existing Linux install. You can even install it in place on the same partition. https://nixos.org/manual/nixos/stable/#sec-installing-from-other-distro</a></p> We will keep it simple and focus on using an ISO on a USB drive.</p> ISO</h4> Go to https://nixos.org/download/#nixos-iso</a> to download the ISO of your choice. If you are a newer user, you should probably pick graphical as it will help guide you along. I have Linux experience so I will be using the minimal version.</p> Next, insert your USB drive and look for it using lsblk</code>. Make sure it's not mounted: sudo umount /dev/sdX</code>. Then use dd</code> to write the ISO to your drive:</p> sudo dd bs=4M conv=fsync oflag=direct status=progress if=<path-to-image> of=/dev/sdX</code></p> Now it's time to boot.</p> You will be greeted with nothing but a terminal. You will be automatically logged in as the nixos</code> user and have sudo access without a password.</p> Networking</h4> You will need a connection to the internet to download various things needed for the install. The easiest way is to just use a wired connection if possible. If you need wireless, it takes a little setup. The minimal installer does not ship with the correct firmware for my wireless card so I'm forced to use a wired connection. The wireless setup doesn't look difficult and instructions can be found here: https://nixos.org/manual/nixos/stable/#sec-installation-manual-networking</a></p> Partitioning and formatting</h4> The minimal NixOS install doesn't do any partitioning or formatting so that needs to be done manually.</p> First, you will need to partition:</p> Create a GPT partition table</li> </ol> parted /dev/sda -- mklabel gpt</code></p> Add the root partition. This will fill the disk except for the end part, where the swap will live, and the space left in front (512MiB) which will be used by the boot partition.</li> </ol> parted /dev/sda -- mkpart root ext4 512MB -8GB</code></p> Next, add a swap partition. The size required will vary according to needs, here a 8GB one is created.</li> </ol> parted /dev/sda -- mkpart swap linux-swap -8GB 100%</code></p> Finally, the boot partition. NixOS by default uses the ESP (EFI system partition) as its /boot</code> partition. It uses the initially reserved 512MiB at the start of the disk.</li> </ol> parted /dev/sda -- mkpart ESP fat32 1MB 512MB parted /dev/sda -- set 3 esp on </code></pre> Now, you need to format those partitions:</p> For initialising Ext4</code> partitions: mkfs.ext4</code>. It is recommended that you assign a unique symbolic label to the file system using the option -L label</code>, since this makes the file system configuration independent from device changes. For example:</li> </ol> mkfs.ext4 -L nixos /dev/sda1</code></p> For creating swap partitions: mkswap. Again it’s recommended to assign a label to the swap partition: -L label</code>. For example:</li> </ol> mkswap -L swap /dev/sda2</code></p> For creating boot partitions: mkfs.fat</code>. Again it’s recommended to assign a label to the boot partition: -n label</code>. For example:</li> </ol> mkfs.fat -F 32 -n boot /dev/sda3</code></p> Installation</h4> Mount the target file system on which NixOS should be installed on /mnt</code>, e.g.</li> </ol> mount /dev/disk/by-label/nixos /mnt</code></p> Mount the boot file system on /mnt/boot, e.g.</li> </ol> mkdir -p /mnt/boot mount -o umask=077 /dev/disk/by-label/boot /mnt/boot </code></pre> (optional) If your machine has a limited amount of memory, you may want to activate swap devices now (swapon device). The installer (or rather, the build actions that it may spawn) may need quite a bit of RAM, depending on your configuration.</li> </ol> swapon /dev/sda2</code></p> You now need to create a file /mnt/etc/nixos/configuration.nix</code> that specifies the intended configuration of the system. This is because NixOS has a declarative configuration model: you create or edit a description of the desired configuration of your system, and then NixOS takes care of making it happen.</p> The command nixos-generate-config</code> can generate an initial configuration file for you:</p> </li> </ol> nixos-generate-config --root /mnt</code></p> This command will also create a file at /mnt/etc/nixos/hardware-configuration.nix</code>. This includes important config for your filesystems among other things. While NixOS should handle this, it can't hurt to double check just to make sure things are defined correctly.</p> Most of the default config will be commented out, but a basic configuration.nix</code> file will look something like this:</p> { config, pkgs, ... }: { imports = [ ./hardware-configuration.nix ]; boot.loader.systemd-boot.enable = true; boot.loader.efi.canTouchEfiVariables = true; # Macbook Pro wireless firmware nixpkgs.config = { allowUnfree = true; }; services.openssh.enable = true; system.stateVersion = "25.05"; # Adjust to match your NixOS version } </code></pre> Note for UEFI users: You must select a boot-loader, either systemd-boot or GRUB. The recommended option is systemd-boot: set the option boot.loader.systemd-boot.enable</code> to true. nixos-generate-config</code> should do this automatically for new configurations when booted in UEFI mode.</p> Install! This step can take some time depending on your machine.</li> </ol> nixos-install</code></p> As the last step, nixos-install will ask you to set the password for the root user, e.g.</li> </ol> setting root password... New password: * Retype new password: * </code></pre> If everything went well, it's time to reboot</code>.</li> </ol> Summary</h4> That's it for this post and the installation and basic configuration of NixOS.</p> Next Time</h4> In the next installment, we'll create a non-root user, configure the Hyprland window manager, and install some key daily-driver tools including Neovim, Git, and LibreWolf.</p> How Vulfmon Inspired Me to Learn to Weave Unknown — Sat, 31 May 2025 00:00:00 +0000 Who is Vulfmon</h4> Vulfmon is the alter ego/moniker of Vulfpeck leader Jack Stratton. He sometimes shoots videos in a room with various art on the walls. In the video for Alone Again, Naturally</a>, I noticed a weaving that I loved:</p> </p> Lucky for me, I just happened to have access to a loom and yarn. Like any new skill, it was a bit awkward to start and honestly, my first one was rough. I stuck with it though and have made many better ones including six inspired by Vulfmon:</p> Vulfmon - gold 1</strong> </p> Vulfmon - gold, orange, brown 1</strong> </p> Vulfmon - green 1</strong> </p> Vulfmon - gold 2</strong> </p> Mini Vulfmon - purple 1</strong> </p> Mini Vulfmon - orange 1</strong> </p> Weekly Summary - 22/52 Unknown — Fri, 30 May 2025 00:00:00 +0000 Another pretty decent week. Mostly concentrated on job hunt and API inspection.</p> Things I did:</p> worked more on some API inspection. published two posts on it. working on lib. Part 1 - Courses</a></li> Part 2 - Search</a></li> </ul> </li> continued Swedish language studies - 172 days in a row</li> sent out 13 applications</li> </ul> Things that I didn't get to work on much:</p> rust</li> gitea server</li> nixos setup</li> rockpro64 setup</li> </ul> Deploying a Zola static site to a custom domain with Github Actions Unknown — Sat, 24 May 2025 00:00:00 +0000 As I've been searching for a new gig, I've gotten the urge to write a bit more about some of the stuff I'm up to to help make myself stand out. I really like using the fewest tools as needed so I knew a static site generator was what I wanted. I also like to use Rust based tools when possible.</p> Searching for Rust static site generators lead me to Zola</a>.</p> Some of the top advertised features are no dependencies, blazingly fast, and easy to use. Those sound great to me.</p> Set up Zola site</h3> While this isn't a few blown Zola tutorial, I did want to include a few things.</p> After installing Zola, you can simply run zola init myblog</code>.</p> You'll be asked a few questions and a base site will be setup for you.</p> ├── config.toml ├── content ├── sass ├── static ├── templates └── themes </code></pre> Without going too deep, your CommonMark pages will go in content</code>, Tera/HTML templates in templates</code>, and any css/js/images or other static content will go in static</code>.</p> SASS is enabled by default but can be disabled. I am not currently using SASS personally.</p> Running zola build</code> will build the site and output it a directory called public</code>.</p> Here is a link to a complete overview:</p> https://www.getzola.org/documentation/getting-started/overview/</a></p> Push to Github & Create Github Actions workflow</h3> After getting your content written, site styled, and ready for deployment, it's time to push to Github. Create a repo and push it to a main</code> branch (exclude the public</code> directory).</p> Next, we will setup the actual workflow to take our input files, setup zola, build the site, and commit it to the correct branch.</p> Create a file at .github/workflows/deploy.yml</code> and insert this:</p> name: Deploy Zola to GitHub Pages on: push: branches: [main] jobs: build-deploy: runs-on: ubuntu-latest steps: - name: Check out source uses: actions/checkout@v4 - name: Install Zola run: \| curl -L https://github.com/getzola/zola/releases/download/v0.20.0/zola-v0.20.0-x86_64-unknown-linux-gnu.tar.gz -o zola.tar.gz tar -xzf zola.tar.gz sudo mv zola /usr/local/bin/ - name: Build site run: zola build - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./public publish_branch: gh-pages force_orphan: true </code></pre> This setups up a workflow that:</p> watches for pushes to main branch</li> checks out the zola source and installs it</li> builds your site using zola build</li> uses github pages plugin to push public</code> output dir to a gh-pages</code> branch</li> </ul> You will also need to go to your repos settings and look for the actions section to enable write permissions.</p> Push this up and watch the build by going to your repo and clicking the "Actions" tab. You will see a workflow that you can click into and see build and deploy jobs.</p> If everything goes well, you can now visit your site by filling in your values:</p> https://${username}.github.io/${repo}</p> Add Custom Domain (optional)</h3> After you have the initial workflow working, you will need to configure some Github settings for a custom domain.</p> First, run echo "yourdomain.com" > static/CNAME</code> and commit this file. Next, go to your Github repo's "Pages" setting and add the domain name.</p> Configure DNS (optional)</h3> If using a custom domain, you will also need to setup DNS. Go to your domain settings and add 4 A records for Github pages:</p> A @ 185.199.108.153 A @ 185.199.109.153 A @ 185.199.110.153 A @ 185.199.111.153 </code></pre> Setup any subdirectories you might want.</p> You may need to give this step some extra time to update before you can see your new site at your custom URL. Other times it's nearly instant so your results may vary.</p> Profit</h3> That's basically it for a basic setup. You should now have a static site setup at a custom domain that gets automatically built by just pushing a branch.</p> While simple, this is a complete setup that let's you create and deploy content to your own URL with ease.</p> Weekly Summary - 21/52 Unknown — Fri, 23 May 2025 00:00:00 +0000 This has been a pretty productive week.</p> Things that were good:</p> RockPro64 boots again! Blog post coming...</li> continued Swedish language studies - 165 days</li> started work on some API inspection. Another blog post coming...</li> figured out nixos/hyprland boot issue</li> </ul> Things that could be better:</p> didn't work on much rust</li> can't get gitea ssh setup on VPS</li> broke wood router part so had to buy new one to work on utensil rest</li> </ul> NixOS as a daily driver on a late 2011 Macbook Pro, part 1/? - What and why? Unknown — Sun, 18 May 2025 00:00:00 +0000 First, it's worth explaining what NixOS is and why I or anyone would want to run it as a daily driver.</p> But even before diving into NixOS, we have to talk about Nix.</p> Nix</h3> Nix is a package manager that is purely functional and creates reproducible builds specified in the Nix Expression Language. Nix expressions are functions that take dependencies as arguments which creates a derivation</em> that specifies a reproducible build environment. Nix then stores the results of the build at unique address specified by a hash of the complete dependency tree. This is known as the Nix store and it's immutable which allows atomic upgrades, rollbacks, and simultaneous installations of packages with different versions.</p> NixOS</h3> NixOS is an operating system that is built on top of Nix and the idea of purely functional package management. Packages are never overwritten once built. If you change the Nix expression for a package, it will be rebuilt, and stored under a new address with a new hash, preventing interference with an old version.</p> NixOS takes this a step further and applies this to configuration. By building your entire system from a Nix expression, NixOS ensures that your old configuration is never overwritten which allows for easy rollbacks. One big caveat of this is the elimination of "global" directores such as /bin</code>, /lib</code>, /usr</code>, etc. All packages are kept in /nix/store</code> under a hashed address. (One exception is a symlink /bin/sh</code> to Bash in the Nix store). There is a /etc</code> for system-wide config but many of those files are symlinks to files in the Nix store.</p> Everything in NixOS is built by the Nix package manager. This includes the kernel, applications, system packages, and configuration.</p> To configure NixOS, you have a file at /etc/nixos/configuration.nix</code>. You will setup everything from your boot devices to what services you want to run.</p> Here is a minimal config that enables sshd:</p> { boot.loader.grub.device = "/dev/sda"; fileSystems."/".device = "/dev/sda1"; services.sshd.enable = true; } </code></pre> More on this later though.</p> Why?</h3> Now the whys. I think many of them speak for themselves but here are mine:</p> Rollbacks</strong></p> This one is very big especially when learning about a new, drastically different OS like Nix. Because old config is never overwritten, you can easily cause a breaking change without being worried about how to fix it (unless maybe it's bootloader related). In fact, old configs are listed in the boot menu.</p> Reproducible Build Configurations</strong></p> Kind of like a rollback but starting from scratch. You can take the configuration.nix</code> file, copy to another machine, rebuild, and you will have the same applications, services, and configuration as before.</p> Ad-hoc shell environments</strong></p> In a "Nix shell", you can use any program that is packaged with Nix without needing to install permanently.</p> For example, you can run nix-shell -p git neovim node</code> and you will be dropped into a shell with those applications installed. This may take some time depending on the applications installed.</p> It's a new way to think</strong></p> Honestly, I just like trying new stuff, especially when it's done in a new way. Linux has mostly been the same for a long time now, so it's refreshing to see a new way of doing it that also improves on an already solid OS. I also have really fallen in love with DevOps/IaC type of work, and NixOS definitely scratches that itch.</p> Next time</h3> In the next post, I will go over how to install NixOS and maybe a bit of the configuration.</p> Weekly Summary - 20/52 Unknown — Fri, 16 May 2025 00:00:00 +0000 I am starting a weekly summary/reflection series that will be a high level view of things I have worked on or fixed or just things I want to track or note.</p> Things I enjoyed:</p> deployed this site</li> got an old raspberry pi running again</li> started back into some rust learnings with blockchain, TUI, and MQTT hacking 1</a></sup> 2</a></sup> 3</a></sup></li> started working on a walnut utensil rest</li> applied to 10 jobs</li> </ul> Things I did not enjoy:</p> seemingly bricked my RockPro64 as it won't boot past a black screen. ordered an adapater to help debug at a lower level.</li> rejected from multiple jobs</li> felt very confused by some of the rust learnings. makes sense in pieces but hard to see as the whole picture just yet</li> confirmed old fitbit can't be flashed with any open source/non-fitbit software</li> </ul> ^1</sup>https://ratatui.rs/concepts/application-patterns/the-elm-architecture/</a></p> </div> ^2</sup>https://github.com/veeso/tui-realm/tree/main</a></p> </div> ^3</sup>https://github.com/bytebeamio/rumqtt</a></p> </div>

Auditing a Squarespace 7.0 site before migrating to 7.1

Unknown — Sat, 30 May 2026 00:00:00 +0000

A local non-profit put out a call for volunteers looking for a "front-end web developer consultant" for their Squarespace site, and I answered it. The presenting problem: they want to migrate from Squarespace 7.0 to 7.1 and figure out what to do about their members-only login area.</p>

Before any migration conversation, I wanted a real inventory of what's actually on the site. Squarespace's update tool</a> has documented limitations: a 100-page cap, no support for album pages, video blocks on gallery pages don't carry over, certain templates are ineligible. The tool itself will tell you if your site is ineligible when you try to run it. What it won't tell you is why</em>, by how much</em>, or which pages are the problem</em> in a form you can hand to a non-technical decision-maker.</p>

So I wrote a small Python script that does.</p>

The trick: ?format=json</code></h2>Every Squarespace page accepts a ?format=json</code> (or ?format=json-pretty</code>) query parameter that returns a structured representation of the page. It's documented on Squarespace's developer portal</a>, used internally by their iOS editor, and has been stable for years.</p> curl -sS "https://www.portlandbonsai.org/resources?format=json" | jq . </code></pre> You get 15 top-level keys per page. The interesting ones:</p> website</code> - site-wide identity (title, tagline, domain, language, social accounts)</li> websiteSettings</code> - configuration (business type, country, contact info)</li> collection</code> - the page itself (title, URL, page type, item count, updated date)</li> item</code> - populated only when the URL is an individual entry inside a collection (a single blog post, product, event item, etc.)</li> mainContent</code> - the rendered HTML body of the page</li> template</code> - which template the site is on</li> </ul> That item</code> field is what makes the audit tractable. Squarespace's 100-page cap only counts container</em> pages: layout pages, blog pages, gallery pages, store pages, event calendar pages. The individual items inside those collections (the blog posts, the products, the event entries) don't count. If you treat every URL in the sitemap as a "page," you'll wildly overcount and start fights that don't need to happen.</p> What the audit checks</h2> I encoded the documented limitations from Squarespace's update tool into a script:</p> Check</th> Why it matters</th></tr></thead> Container vs item count</td> Update tool refuses sites with more than 100 containers</td></tr> Album pages</td> Deleted by the update</td></tr> Gallery pages</td> Convert to layout pages; embedded videos are lost</td></tr> Share buttons</td> Not supported in 7.1</td></tr> Custom Adobe Typekit fonts</td> Not supported in 7.1</td></tr> Products per store page</td> Cap of 200 per store</td></tr> </tbody></table> The script crawls sitemap.xml</code>, hits ?format=json</code> for every URL, separates containers from items, and groups findings by severity (block / warn / info). Output is a markdown report you can read top to bottom.</p> What it found on the real site</h2> The site I was auditing has a public face of maybe 30 pages. The sitemap lists 489 URLs. After separating containers from items and tag/category views, the real eligibility count is 126</strong>, which is 26 over the cap.</p> Eligibility count - Container pages (count toward 100-page cap): 126 - Individual items (excluded from cap): 121 - Filter/tag views (excluded from cap): 243 - ❌ OVER the 100-page eligibility cap by 26. Containers by type - page: 76 - gallery: 45 - products: 3 - blog: 1 - events: 1 </code></pre> The story isn't the blog. The blog has one container page and 65 posts; none of that is a problem for the cap. The story is 45 gallery pages</strong> built up over a decade of convention photos, fall show photos, monthly meeting photos. Each gallery is a container, each one counts, and each one is a candidate for the "embedded videos won't survive" warning. Galleries plus the 76 plain pages already put the site over the cap before you even look at the rest.</p> This is the kind of detail you can't get from a casual click-through. The webmaster knew the blog was big but hadn't connected the gallery archive to the update tool's cap.</p> Without this audit, the conversation would have been:</p> "We'll run the update tool when you're ready." "The update tool refused." "Oh."</p> </blockquote> Instead, the conversation becomes:</p> "You're 26 pages over the eligibility cap. Most of the slack is in 45 gallery pages, many of which are show photos from 2016-2019 that probably don't need to stay live. Here are three ways to handle it."</p> </blockquote> That's the kind of pre-work that actually moves a project forward.</p> The script</h2> It's a single Python file, no dependencies beyond the stdlib. Crawls the public sitemap, fetches each page's JSON, runs the checks, emits markdown.</p> The full source is in a gist: sqsp-preflight.py</a>. About 400 lines. No setup. Run it as:</p> python3 sqsp-preflight.py https://example.com > report.md </code></pre> For a 30-page site it finishes in seconds. For a 489-URL site it takes a couple of minutes (one HTTP request per URL, no parallelism, good enough).</p> What it doesn't do</h2> A few things the audit can't see:</p> Members-only content.</strong> The crawler is unauthenticated. If a site has a member area with extra pages behind login, they're invisible.</li> Developer mode usage.</strong> Only the admin knows whether this is on.</li> Discontinued template detection.</strong> The template</code> field in the JSON is sparse. Cross-referencing against Squarespace's current supported-template list still needs a human eyeball.</li> Visual fidelity in 7.1.</strong> No tool can predict whether a 7.0 layout will look right in 7.1's Fluid Engine. That's why the update tool has a preview mode.</li> Sidebar navigation.</strong> I couldn't find a reliable signal in the JSON for this one.</li> </ul> The script's job is to surface the known unknowns</em> fast enough that the human can focus on the genuine judgment calls.</p> What this is and isn't</h2> It's not a migration tool. Squarespace's update tool is the migration tool. This is a preflight check</strong> that runs before you commit, surfaces the specific pages that drive eligibility, and produces a report a non-technical decision-maker can read. The update tool will tell you "no"; this tells you why and what to fix first.</p> It also isn't a project. I'm not going to maintain this as a package. Squarespace can change the JSON shape at any time and break it; the maintenance commitment isn't worth it. If you hit the same problem, fork the gist, adapt it to your site, throw it away after.</p> The actually-publishable thing here is the approach</em>: use ?format=json</code> to inventory the site, separate containers from items the way the update tool does, encode the documented limitations as checks, produce a markdown report. Anyone reading this should be able to recreate the script in an evening.</p> The bigger lesson</h2> Squarespace's docs tell you the limitations. The update tool tells you whether you qualify. Neither one hands you the punch list of which pages to deal with, in what order, and why</em>. That gap shows up over and over with hosted platforms: the docs describe the system, the tools enforce the rules, but nothing produces an actionable report against your specific site.</p> For any platform migration on any hosted product, the first useful piece of work isn't "start the migration." It's "audit the source against the destination's known constraints, in a form a human can act on." Sometimes that takes a script. Often a CLI plus an afternoon does it.</p> Building a Travel Itinerary Plugin Inside Discourse Unknown — Mon, 25 May 2026 00:00:00 +0000 I built a Discourse plugin that turns a category of topics into a chronological travel itinerary. One topic per trip, then a flight topic, a hotel topic, a note topic, all linked back to the trip. The plugin renders them on /itinerary as a clean list and per-trip timeline grouped by day.</p> You can see the result here: discourse-itinerary on GitHub</a></p> Why Discourse for This?</h2> Same reason I keep doing this: Discourse topics are extremely flexible, and seeing how far I can push them keeps teaching me the platform. A trip is just a topic. A flight is just a topic. The relationship between them is a custom field pointing at the parent trip. Everything else (permissions, search, edit history, who posted what, comments) comes for free.</p> That was the bet anyway. Reality had some opinions.</p> The Data Model</h2> After a couple of rewrites, the model settled at:</p> Category</strong> = "Itinerary". One per forum. Auto-created by the plugin on first boot, with a configurable site setting if the admin wants to point it at a different category.</li> Topic with itinerary_item_type = trip</code></strong> = a trip (the container).</li> Other itinerary topics</strong> = items (flight, train, hotel, event, transfer, note) that point at their parent trip via itinerary_parent_trip_id</code> on the topic's custom_fields.</li> </ul> Earlier versions used a tag (itinerary</code>) to mark which topics belonged to the plugin. That got dropped once itinerary_item_type</code> existed. The tag was load-bearing nostalgia, not real structure.</p> All metadata lives in topic_custom_fields</code>:</p> Field</th> Type</th> Example</th></tr></thead> itinerary_item_type</code></td> string</td> flight</code></td></tr> itinerary_parent_trip_id</code></td> integer</td> 123</code></td></tr> itinerary_starts_at</code></td> string</td> 2026-09-20T14:30</code></td></tr> itinerary_ends_at</code></td> string</td> 2026-09-21T09:15</code></td></tr> itinerary_origin</code></td> string</td> PDX</code></td></tr> itinerary_destination</code></td> string</td> MAD</code></td></tr> itinerary_location</code></td> string</td> Madrid</code></td></tr> itinerary_confirmation_code</code></td> string</td> ABC123</code></td></tr> itinerary_status</code></td> string</td> booked</code></td></tr> </tbody></table> Timestamps are stored as ISO-8601 strings, not DateTime. Lexical sorting on the raw column does the right thing for YYYY-MM-DDTHH:MM</code>, which means I never have to parse them on the database side.</p> The Plugin API Trapdoors</h2> Discourse plugins have a deceptively friendly API. You write a plugin.rb</code>, drop some assets under assets/javascripts/discourse/</code>, and things mostly work. Until they don't, and you have to figure out why.</p> Here are the ones that actually stopped me cold.</p> The route-map filename convention</h3> To register Ember client routes from a plugin, you put a file named <plugin-slug>-route-map.js</code> in assets/javascripts/discourse/</code>. Discourse scans requirejs.entries</code> for anything matching /route-map$/</code> and invokes its default export to build out the route tree.</p> I named the file correctly. The file loaded. The composer connector loaded. The route map itself never ran.</p> Turns out Ember resolves the actual route modules by name. With this route map:</p> export default function () { this.route("itinerary", function () { this.route("show", { path: "/:trip_id" }); }); } </code></pre> Ember will look for routes/itinerary/index.js</code> and routes/itinerary/show.js</code>. Not routes/itinerary-index.js</code> or routes/itinerary-show.js</code>, which is what I had originally. The dot in the route name becomes a path separator. I had copied the route map from discourse-cakeday but missed the nested directory convention for the route files.</p> You don't get an error for this. The route map just silently doesn't match anything client-side and the URL falls through to Rails.</p> Rails has to serve the HTML for an Ember route</h3> This was the big one. After fixing the route file paths, /itinerary</code> still 404'd. The error came from Rails, not Ember. The plugin had JSON routes:</p> Discourse::Application.routes.append do get "/itinerary/trips" => "itinerary#index", defaults: { format: :json }, constraints: { format: :json } get "/itinerary/trips/:id" => "itinerary#show", defaults: { format: :json }, constraints: { format: :json, id: /\d+/ } end </code></pre> But none of those match a browser request for GET /itinerary</code> (which wants HTML). Rails 404s, the browser never gets the Discourse app shell, Ember never loads, the route map never runs.</p> discourse-cakeday works because it mounts a full Rails Engine at /cakeday</code>, which catches the HTML request and serves the SPA bootstrap. Discourse plugins like discourse-invite-stats use the simpler pattern:</p> get "/itinerary" => "itinerary#page", constraints: { format: :html } get "/itinerary/*path" => "itinerary#page", constraints: { format: :html } </code></pre> With an action that just renders the empty layout:</p> def page render "default/empty" end </code></pre> The empty layout is the SPA bootstrap. Ember takes over from there.</p> I burned a couple of hours on this before searching for it. Sometimes the fastest way to debug a plugin is to read three other plugins that do the same thing.</p> Composer fields and Glimmer autotracking</h3> The composer panel for itinerary fields shows different inputs depending on the item type. Flight has origin and destination, hotel has location, note has neither. The conditional rendering was driven by getters:</p> get itemType() { return this.composer.itinerary_item_type; } get showsRoute() { return ["flight", "train", "transfer"].includes(this.itemType); } </code></pre> This silently broke. The user could pick "Flight" from the dropdown, but the route inputs never appeared. The dropdown's change handler was firing. The composer model was being updated. But the template never re-rendered.</p> The reason: this.composer.set("itinerary_item_type", value)</code> doesn't go through a @tracked</code> property. Glimmer's autotracking can't follow composer.set(...)</code> on non-tracked composer fields. The getter reads from the composer correctly the first time, then becomes a dead read.</p> Fix:</p> @tracked itemType; @action setItemType(e) { this.itemType = e.target.value || null; this.composer.set("itinerary_item_type", this.itemType); } </code></pre> Keep a local @tracked</code> copy of anything you read from the composer model in conditional getters. The composer side stays in sync via the .set()</code> call.</p> datetime-local silently drops half-filled values</h3> I had separate inputs for "Starts at" and "Ends at" with type="datetime-local"</code>. The user creates a flight, types a date, doesn't bother with the time, clicks save. The flight saves. The trip page shows "No items in this trip yet."</p> The flight was actually saved, just without itinerary_starts_at</code>. The TripItemFinder filters out items without a start time, so the flight existed in the DB but never reached the timeline.</p> Why? <input type="datetime-local"></code> doesn't fire input</code> or change</code> until both the date and time portions are populated. A half-filled value is "invalid" to the browser, and you get nothing.</p> I split the field into a <input type="date"></code> plus an optional <input type="time"></code>. The composer combines them into the stored format (YYYY-MM-DD</code> if just date, YYYY-MM-DDTHH:MM</code> if both). The timeline component already knew how to render both formats.</p> Two inputs, one stored field, no silent data loss.</p> Topics need a title that Discourse will accept</h3> Once the composer worked, I hit the wall I'd been ignoring: Discourse's title length validator requires 15 characters minimum, plus a "title seems unclear" heuristic that rejects titles like "Flight" or "Lisbon". For a travel itinerary where the "data" is in custom fields, making the user invent a meaningful 15-char title for every flight is hostile.</p> Discourse doesn't have per-category overrides for min_topic_title_length</code>. The validator reads the global site setting, full stop. I considered three options:</p> Lower the global. Affects every topic on the forum.</li> Monkey-patch the validator to skip checks for itinerary topics. Fragile.</li> Synthesize the title from the structured fields the user is already filling in.</li> </ol> Option 3 is the move. The composer already collects item type, origin, destination, location. Build the title from those and the user never has to type one.</p> synthesizeTitle() { const type = this.itemType; if (!type || type === "trip") return; const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1); const o = this.composer.itinerary_origin; const d = this.composer.itinerary_destination; const loc = this.composer.itinerary_location; let title = cap(type); if (["flight", "train", "transfer"].includes(type) && (o || d)) { title = `${cap(type)}: ${o || "?"} -> ${d || "?"}`; } else if (loc) { title = `${cap(type)}: ${loc}`; } this.composer.set("title", title); } </code></pre> Trip topics still take the user's title (you name a trip meaningfully; "European trip 2026" is more useful than "Trip"). Items get derived titles: "Flight: PDX -> MAD", "Hotel: Madrid Marriott", "Event: Symphony".</p> I also hide the title input via a body class when the composer is in itinerary-item mode, so users don't see a phantom input that gets overwritten on every field change.</p> The Other Stuff</h2> A few smaller things that made the plugin feel like a real tool.</p> Auto-creating the category</h3> The plugin provisions an "Itinerary" category on first boot. The slug-first lookup means if an admin already has a category called "itinerary" or "ITINERARY", we adopt it instead of creating a duplicate (which would fail uniqueness anyway). The provisioner also adds the category id to default_categories_muted</code> so new users don't see itinerary topics cluttering /latest.</p> Sidebar link</h3> Discourse's api.addCommunitySectionLink</code> adds a link to the sidebar's Community section. With the category muted by default, the sidebar link becomes the canonical entrypoint. No URL guessing required.</p> Add buttons</h3> Two big buttons: "+ Add trip" on /itinerary, "+ Add leg" on /itinerary/:trip_id. Each opens the standard composer pre-scoped to the itinerary category, with the right itinerary_item_type</code> (for trip) or itinerary_parent_trip_id</code> (for leg) seeded on the composer model after the modal opens. The composer panel's conditional rendering picks up the seeded values and shows the right fields.</p> This pattern is straight from discourse-kanban: rather than build a custom modal, lean on Discourse's existing composer with sensible defaults. You get rich text, drafts, file uploads, all the auth machinery, for free.</p> Screenshots</h2> Coming once I've populated my own itinerary further. I want the screenshots to show realistic data rather than the "Flight to madrid for meetup" test post that's currently in my dev instance.</p> Takeaways</h2> Plugins built on topics keep paying off.</strong> Search, permissions, edit history, mentions, attachments. None of it is plugin code. It's all Discourse, and I get it by default by storing data in topics.</p> The plugin API has trapdoors.</strong> Most of them aren't documented because nobody hits them until they hit them. Reading three working plugins side-by-side is faster than reading docs.</p> Glimmer autotracking is invisible until it isn't.</strong> If a getter reads a non-@tracked</code> value and you're surprised it doesn't re-render, that's the likely cause. Always.</p> Synthesize what you can.</strong> The user shouldn't have to type a topic title when the structured fields already encode it. Hide the title input, derive it, move on.</p> Per-category validation overrides would be great.</strong> Discourse already has site-wide setting overrides per category for things like default tags and minimum trust levels. Extending the per-category override surface to title and post length validators would let plugins like this stop fighting the global validators. Filed in the back of my brain for a future contribution.</p> Try It</h2> The plugin is open source: ducks/discourse-itinerary</a>. Symlink it into your plugins/</code> directory, restart Rails, visit /itinerary, and you've got a travel timeline backed entirely by Discourse topics.</p> Now I just need to actually go on a trip.</p> Building a Screenshot Pipeline for Discourse Plugins Unknown — Mon, 25 May 2026 00:00:00 +0000 I built discourse-plugin-screenshots on GitHub</a>, a small tool that captures Discourse plugin UIs against a real Discourse instance in CI and publishes the resulting PNGs to GitHub Pages.</p> It's modeled on Penar Musaraj's discourse-theme-screenshots</a>, which screenshots themes against a battery of routes. Same idea, different target: instead of "does this theme break the latest topic view," it asks "does my plugin's UI still render correctly in current Discourse."</p> Live example for discourse-itinerary</code>, the plugin I dogfooded it on: https://ducks.github.io/discourse-itinerary/</a>.</p> Why?</h2> I'd been hand-screenshotting discourse-itinerary</a> for its blog post</a> and realized the same problem applies to every plugin I might write or maintain:</p> Plugins break in unexpected ways when Discourse core changes. A CSS class gets renamed and your plugin's panel suddenly looks weird.</li> A new theme like Horizon ships and your plugin's overrides don't quite match anymore.</li> A plugin API method deprecates and silently degrades.</li> </ul> You usually find out from a user filing a screenshot. That's a slow loop.</p> What if every plugin had a nightly or per-push screenshot run that posted its current state to a public page? Visual regressions become visible. "Here's what my plugin looks like today" becomes a free byproduct of shipping.</p> Penar's tool already does this for themes. Plugins were the X-shaped hole next to it.</p> The architecture</h2> The tool ships a reusable GitHub Actions workflow</strong>. Plugins opt in by adding ~12 lines of YAML to their own .github/workflows/</code>:</p> name: Screenshots on: push: branches: [main] workflow_dispatch: permissions: contents: read pages: write id-token: write jobs: screenshots: uses: ducks/discourse-plugin-screenshots/.github/workflows/plugin-screenshots.yml@main </code></pre> That's it. Each plugin maintainer owns their schedule, their gallery, their CI minutes. The tool repo doesn't enumerate plugins, doesn't centrally batch them, doesn't pay for anyone else's runs. Same pattern Discourse already uses for its own discourse-plugin.yml</code></a> reusable workflow.</p> How a plugin describes what to capture</h2> A plugin opts in by shipping config/screenshots.yml</code> at the repo root:</p> seed: spec/screenshot_seed.rb urls: - path: /itinerary name: trip-list description: Trip list home page - path: /itinerary/2 name: timeline description: Per-trip timeline with day grouping </code></pre> The optional seed</code> is a Ruby file run inside the test env before captures fire. Without it, /itinerary</code> would render an empty state ("No trips yet"), which makes for sad screenshots. The seed creates a few realistic trips with legs so the pages have something to render.</p> The seed file is plain Ruby that runs inside Discourse's Rails test environment. It can use PostCreator</code>, SiteSetting</code>, plugin-specific classes, whatever. Plugin-specific concerns stay in the plugin.</p> The workflow</h2> The reusable workflow is the heart of it. Slightly simplified:</p> Spin up discourse/discourse_test:release</code> (Discourse's official test container, comes with system libs Playwright needs).</li> Check out the calling plugin, this tool, and discourse/discourse</code>.</li> Symlink the plugin into discourse/plugins/<id></code>.</li> Boot Postgres + Redis, migrate the test DB.</li> Install Playwright Chromium.</li> Run a Capybara system spec that reads the plugin's manifest, runs the seed file, visits each URL, and saves a PNG.</li> Upload public/</code> to the calling repo's GitHub Pages.</li> </ol> Total runtime: ~5-10 minutes after the initial container pull.</p> First green run</h2> I wired the workflow into the itinerary plugin's CI, pushed, and the first run came back green. Screenshots up at ducks.github.io/discourse-itinerary</a>, captured automatically on every push to main.</p> That's the whole loop. Plugin author writes config/screenshots.yml</code>, drops a reusable-workflow file in .github/workflows/</code>, enables Pages, pushes. Five minutes later there's a public gallery of what their plugin looks like in current Discourse.</p> The rabbit holes</h2> Building it taught me three things about the Discourse-on-NixOS stack that I wouldn't have learned otherwise.</p> Playwright's Chromium doesn't run on NixOS</h3> Discourse uses Playwright for system specs. The first time I tried the tool locally, the Capybara driver tried to launch Chromium and got:</p> error while loading shared libraries: libglib-2.0.so.0: cannot open shared object file: No such file or directory </code></pre> Playwright's pnpm playwright install</code> downloads a generic Linux Chromium build to ~/.cache/ms-playwright</code>. That binary expects to find shared libs at standard /usr/lib</code> paths. NixOS, famously, doesn't have a /usr/lib</code>. Everything is in /nix/store/<hash>-glib-2.x.y/lib</code>.</p> Two paths to fix this:</p> LD_LIBRARY_PATH</code> gymnastics. Add every needed lib to a nix-shell.</li> nixpkgs.playwright-driver.browsers</code>, a package that pre-patches the Chromium binary with NixOS-compatible RPATHs.</li> </ol> I went with option 2:</p> { pkgs ? import <nixpkgs> {} }: pkgs.mkShell { buildInputs = [ pkgs.playwright-driver.browsers ]; shellHook = '' export PLAYWRIGHT_BROWSERS_PATH="${pkgs.playwright-driver.browsers}" export PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 ''; } </code></pre> This got me past the lib errors and into a new one: my nixpkgs channel ships chromium-1169</code> but Discourse's Playwright gem pins chromium-1217</code>. The right fix is a flake pin or nixpkgs-unstable</code> override, which I haven't shaved yet.</p> So locally on NixOS the tool runs up to "launching Chromium" before hitting the version mismatch. In CI it sails through, because discourse/discourse_test:release</code> is a regular Linux image with the matching system libs and Playwright downloads the right version. The same code runs in both places. CI is currently the only one that succeeds end-to-end on my machine.</strong></p> That ended up being a useful property. The CI is the authoritative loop: real container, real Discourse, real Playwright, public gallery at the end. Local is a developer convenience that I can keep chipping at without blocking the rest of the tool from being useful.</p> Rspec accepts absolute spec paths from outside the project</h3> I was worried that running Discourse's bin/rspec</code> against a spec file that lives outside the Discourse repo wouldn't work. rails_helper.rb</code> wouldn't be picked up automatically, Capybara's drivers wouldn't be registered, etc.</p> Turns out: it works fine. RSpec loads rails_helper</code> via the spec file's own require</code>, and Discourse's bin/rspec</code> boots Rails normally regardless of the spec's path. The spec just needs require "rails_helper"</code> at the top.</p> This let me keep the spec in this tool's repo rather than vendoring it into every plugin or asking Discourse to ship it.</p> Reusable workflows scale better than central orchestration</h3> The first version of this had a central config/plugins.yml</code> listing every plugin, and a single CI run that captured all of them. Penar's theme tool works that way for good reasons: themes are a relatively small set and they're meant to be compared side-by-side.</p> For plugins it doesn't work. If you add 20 plugins, the central run becomes a 4-hour job that fails halfway and has to retry the whole batch. You also push all the CI cost onto whoever maintains the tool repo.</p> Reusable workflows flip both. Each plugin's CI runs only when that plugin changes. The tool repo's job is to provide the reusable workflow, not to enumerate consumers.</p> What's missing</h2> This is a v0. Real things it doesn't do yet:</p> Multiple themes.</strong> Right now it captures against the default theme. Capturing against Horizon, a dark theme, and the default is the obvious next step. Penar's tool already does this; mostly a matter of porting the theme-loading code.</li> Multiple viewports.</strong> Just 1440x900 today. Mobile (375x667) would be the big one to add.</li> Visual diffing.</strong> "Here's what changed since last run" via image diff. Tools like reg-suit or Percy do this; expensive at scale.</li> Auto-discovery of routes.</strong> Right now you list URLs in config/screenshots.yml</code>. Could introspect the plugin's route-map.js</code> for routes, but dynamic segments (:trip_id</code>) need hints either way.</li> NixOS local parity.</strong> The chromium-1217 pin dance is genuinely the last thing blocking local runs.</li> </ul> Try it</h2> # In your plugin repo, create config/screenshots.yml with your URLs. # Then drop this in .github/workflows/screenshots.yml: name: Screenshots on: push: branches: [main] workflow_dispatch: permissions: contents: read pages: write id-token: write jobs: screenshots: uses: ducks/discourse-plugin-screenshots/.github/workflows/plugin-screenshots.yml@main </code></pre> Enable GitHub Pages on the plugin repo (Settings -> Pages -> Source: GitHub Actions), push to main, and after a few minutes your screenshots will be at https://<you>.github.io/<plugin>/</code>.</p> The tool is open source: ducks/discourse-plugin-screenshots</a>. Pull requests for theme + viewport + diff support welcome.</p> When patchelf stopped working on Claude Code Unknown — Wed, 20 May 2026 00:00:00 +0000 A couple weeks ago I wrote about running Claude Code on NixOS</a> with a 133-line shell.nix</code> that patchelf-modifies the binary on install. It worked great until last week, when Claude Code's auto-updater dropped version 2.1.143 into ~/.local/share/claude/versions/</code> and claude --version</code> started segfaulting before printing anything.</p> What follows is the debugging story. I went down three wrong paths before finding the real cause, and the right fix turned out to have two more gotchas hiding inside it. The patchelf approach is dead. Here's why.</p> The symptom</h2> $ claude --version Segmentation fault (core dumped) </code></pre> coredumpctl</code> showed the crash inside the dynamic linker itself, in _dl_check_map_versions</code> at glibc/elf/dl-version.c:263</code>, before a single byte of program code had run:</p> #0 _dl_check_map_versions at dl-version.c:263 #1 _dl_check_all_versions at dl-version.c:398 #2 version_check_doit at rtld.c:676 #3 _dl_receive_error at dl-catch.c:194 #4 dl_main at rtld.c:2028 ... #8 _start () from /lib64/ld-linux-x86-64.so.2 </code></pre> The previous version (2.1.132) worked fine. 2.1.143 didn't. Same patch_binary</code> invocation, same Nix linker, same rpath. The binary was patched correctly in the sense that patchelf --print-interpreter</code> reported the Nix glibc linker path.</p> Wrong hypothesis #1: the auto-updater dropped an unpatched binary</h2> My first guess was that Claude's auto-updater had bypassed the install-time patchelf step. I extended shell.nix</code> with a wrapper that auto-patchelfs any unpatched binary in the versions directory before exec'ing it.</p> This was the wrong fix to the wrong problem. The binary was already patched; patchelf --print-interpreter</code> confirmed it. The wrapper was a useful-feeling defensive layer but it wasn't relevant to the actual bug.</p> Wrong hypothesis #2: Bun's Rust rewrite shipped malformed ELF</h2> Claude Code is built with bun build --compile</code>, which embeds the Bun runtime inside the standalone executable. There had been recent news</a> about Anthropic merging a Rust rewrite of Bun, and an open bun issue</a> about regressions in the --compile</code> path. The dates lined up: Bun v1.3.14 shipped May 13, the Rust rewrite PR merged May 14, my broken Claude Code was downloaded May 18.</p> I had a hypothesis, the timing fit, and I was off to the races. Built a clean Docker repro on stock Ubuntu 24.04 showing the same _dl_check_map_versions</code> crash outside NixOS. Started drafting a bug report against oven-sh/bun</code>. Compared readelf --version-info</code> between the working and broken binaries and found errors:</p> $ readelf --version-info /tmp/claude-2.1.143 readelf: Error: Reading 20 bytes extends past end of file for version def readelf: Error: Reading 20 bytes extends past end of file for version def ... </code></pre> The narrative was perfect. Bun's new Rust ELF emitter was producing corrupt version tables, the dynamic linker was crashing trying to read them, and I was about to file a high-quality upstream bug.</p> Then I checked the most basic fact, which I should have checked at the start:</p> $ strings /tmp/claude-2.1.143 | grep '^Bun v' Bun v1.3.14 (d2989145) $ strings /tmp/claude-2.1.132 | grep '^Bun v' Bun v1.3.14 (0a466a11) </code></pre> Both binaries embed Bun v1.3.14.</strong> The Rust rewrite hasn't shipped in any tagged release yet; it's only on canary. Different build commits, same version. The Rust theory was dead.</p> Lesson: when the story fits perfectly, do the cheapest disconfirming test first.</p> Wrong hypothesis #3: Claude Code's build pipeline regressed</h2> If it wasn't Bun, it had to be something on Anthropic's side. I bisected across every published version in the range:</p> for v in 2.1.132 2.1.133 2.1.136 2.1.137 2.1.138 2.1.139 2.1.140 2.1.141 2.1.142 2.1.143; do curl -fsSL -o "/tmp/bisect/$v" \ "https://downloads.claude.ai/claude-code-releases/$v/linux-x64/claude" docker run --rm -v "/tmp/bisect/$v:/c:ro" ubuntu:24.04 /c --version done </code></pre> Every freshly-downloaded binary ran cleanly. All of them.</strong> Including 2.1.143.</p> The crash I'd been reproducing was on my locally-modified copy in /tmp/claude-test</code>, not on a pristine upstream binary. I'd convinced myself I was testing the official binary because the path looked right. I was actually testing the result of my own earlier patchelf modification.</p> This is where the actual cause finally became visible.</p> The real cause</h2> Diff the program headers of 2.1.132 vs 2.1.133 with readelf -l</code>:</p> 2.1.132 RW LOAD: FileSiz=0x000e0028 (~916 KiB) MemSiz=0x001ee29c (~1.93 MiB) 2.1.133 RW LOAD: FileSiz=0x07c17d20 (~124 MiB) MemSiz=0x07c17d20 (~124 MiB) </code></pre> In 2.1.132, the RW LOAD segment's MemSiz</code> is larger than its FileSiz</code>, which is a BSS-style</a> zero-fill region that exists at runtime but takes no space on disk. In 2.1.133, FileSiz</code> equals MemSiz</code> and they're both ~124 MiB. Bun changed its standalone-executable layout to bake the entire embedded JS payload onto disk in the RW segment rather than zero-filling.</p> Why does this matter for patchelf? When patchelf rewrites the interpreter string or rpath, the new string is often longer than what it replaces. patchelf needs slack in the file layout to insert it without breaking section offsets. In 2.1.132 there's plenty of slack. From 2.1.133 onward there isn't, so patchelf's modifications end up shifting the Elf64_Verneed</code> and related version tables to file offsets where the loader walks off the end of the section.</p> The crash in _dl_check_map_versions</code> is the loader trying to dereference a vna_name</code> pointer that now points into garbage memory.</p> The pristine binaries are fine.</strong> They run unmodified on NixOS as long as you give them a real dynamic linker. It's only the patchelf-modified ones that crash. patchelf has been silently producing broken binaries on the new layout the entire time.</p> The fix</h2> Stop modifying the binary. Invoke the Nix dynamic linker directly with the unmodified binary as its argument:</p> exec /nix/store/.../ld-linux-x86-64.so.2 \ --library-path /nix/store/.../lib:/nix/store/.../lib:... \ /home/ducks/.local/share/claude/versions/2.1.143 "$@" </code></pre> This is what nix run</code> and nix-ld</code> do under the hood. The kernel only chokes when it tries to follow the binary's embedded</em> interpreter path (/lib64/ld-linux-x86-64.so.2</code>, which doesn't exist on NixOS). If you invoke a working linker yourself and pass the binary as an argument, the kernel never looks at the embedded path. The linker loads the binary as a regular dynamic object using the library paths you give it. No on-disk modification, no patchelf, no shifted section offsets.</p> I rewrote claude-nixos/shell.nix</code> to drop patchelf entirely. The wrapper at ~/.local/bin/claude</code> now picks the highest installed version, then exec's the linker with the unmodified binary. Pristine binaries are re-downloaded from downloads.claude.ai</code> to overwrite the patchelf damage on existing installs.</p> Gotcha #1: LD_LIBRARY_PATH leaks to children</h2> My first attempt at the wrapper exported LD_LIBRARY_PATH</code> and called the linker:</p> export LD_LIBRARY_PATH="$NIX_LIBS" exec "$LINKER" "$BIN" "$@" </code></pre> This works for Claude itself. But Claude spawns Bash subprocesses for tool calls (the Bash tool in particular), and those subprocesses inherit LD_LIBRARY_PATH</code>. Bash then resolves its own</em> shared libraries through our Nix paths, sometimes pulls in a mismatched version, and you get cryptic errors like:</p> -G: error while loading shared libraries: -G: cannot open shared object file: No such file or directory </code></pre> That -G</code> is grep</code>'s --basic-regexp</code> flag being mis-parsed as a shared object path by a confused loader. Lovely.</p> The fix is to use ld.so</code>'s --library-path</code> flag instead of LD_LIBRARY_PATH</code>. It's consumed by the linker during this single invocation and is not</strong> propagated to child processes:</p> exec "$LINKER" --library-path "$NIX_LIBS" "$BIN" "$@" </code></pre> Child processes inherit a clean environment.</p> Gotcha #2: Claude Code is a multi-call binary</h2> Claude Code's shell integration installs functions for find</code>, grep</code>, and ugrep</code>:</p> find() { ... exec -a bfs "$_cc_bin" -S dfs -regextype findutils-default "$@" } </code></pre> The exec -a bfs</code> sets argv[0]</code> to bfs</code> and exec's the Claude binary. The binary checks argv[0]</code> and dispatches to embedded fast tools (bfs</code> is a breadth-first find</a>, ugrep</code> is a faster grep</code>). Clever: one binary, many tools.</p> This breaks under the wrapper. When the shell function does exec -a bfs ~/.local/bin/claude ...</code>, my wrapper script runs with $0</code> set to its own path (the kernel re-parses the shebang and loses the spoofed argv[0]). The wrapper then exec's the linker, and the linker's argv[0] is the linker path. The Claude binary sees an argv[0] of /nix/store/.../ld-linux-x86-64.so.2</code>, doesn't recognize it as a tool, and runs the default UI.</p> Newer glibc linkers support --argv0 STRING</code> to set argv[0] explicitly:</p> exec "$LINKER" --argv0 "$0" --library-path "$NIX_LIBS" "$BIN" "$@" </code></pre> I started here and shipped this version, thinking it was a partial fix. It isn't. $0</code> inside a bash script is the script's own path even when the script was invoked via exec -a NAME</code>, because bash resets $0</code> to the script name at startup. So --argv0 "$0"</code> was always passing /home/ducks/.local/bin/claude</code>, never bfs</code> or ugrep</code>. Bash 5+ exposes the real invocation argv[0] via $BASH_ARGV0</code>, which fixes it:</p> exec "$LINKER" --argv0 "${BASH_ARGV0:-$0}" --library-path "$NIX_LIBS" "$BIN" "$@" </code></pre> With that change the argv0 actually propagates. I verified by invoking it manually and watching the binary respond as bfs</code> instead of as the default claude</code> UI.</p> But the fast tools still didn't work from inside a Claude session. Adding set -x</code> to the shell-integration find</code> function showed why:</p> local _cc_bin=/nix/store/.../ld-linux-x86-64.so.2 </code></pre> Claude's harness sets CLAUDE_CODE_EXECPATH</code> (the variable its shell integration uses to find itself) from /proc/self/exe</code>. Once the wrapper exec's the dynamic linker, the kernel's view of the process is the linker</em>, not the Claude binary. /proc/self/exe</code> resolves to ld.so. Everything downstream that introspects the running process sees ld.so. The shell-integration find</code> function then tries to exec $CLAUDE_CODE_EXECPATH -regextype ...</code>, which is the linker treating -regextype</code> as a library path. Boom.</p> This isn't fixable in userspace. No bash trick can hide the fact that the kernel-level process identity is ld.so. /proc/self/exe</code> will never lie. The wrapper approach has a real ceiling here.</p> The real fix: nix-ld</h2> The wrapper approach is fundamentally limited by what the kernel sees as the running process. programs.nix-ld</code></a> sidesteps the whole class of problem by installing a stub at /lib64/ld-linux-x86-64.so.2</code>, which is the FHS path that generic Linux binaries hardcode as their ELF interpreter. The stub redirects to a real Nix linker with a global library list:</p> programs.nix-ld = { enable = true; libraries = with pkgs; [ stdenv.cc.cc zlib openssl xz sqlite curl ]; }; </code></pre> With that in place, the kernel can load the pristine Claude binary directly. /proc/self/exe</code> is the real Claude binary, argv[0]</code> is whatever the caller actually set, CLAUDE_CODE_EXECPATH</code> resolves correctly, and the multi-call dispatch works.</p> The wrapper script collapses to its remaining job, picking the latest installed version:</p> #!/usr/bin/env bash set -e VERSIONS_DIR="$HOME/.local/share/claude/versions" bin="$(ls -1 "$VERSIONS_DIR" 2>/dev/null \ | grep -E '^[0-9]+\.[0-9]+\.[0-9]+' \ | sort -V \ | tail -n1 \ | awk -v d="$VERSIONS_DIR" '{print d"/"$0}')" exec -a "${BASH_ARGV0:-$0}" "$bin" "$@" </code></pre> No linker invocation. No --library-path</code>. No LD_LIBRARY_PATH</code> leak. nix-ld owns the runtime surface. The trade is that the library list is global to your system instead of per-shell: if you have two binaries that want different versions of the same library, you can only put one in the global list. For my single-vendored-binary case (Claude Code), this isn't a real constraint.</p> One Nix-string-escape detour</h2> Writing the new heredoc in shell.nix</code>, I started with this:</p> exec -a "\${BASH_ARGV0:-\$0}" "\$bin" "\$@" </code></pre> ...and got a Nix parser error at column 25. Inside Nix double-single-quote strings (''...''</code>), \${</code> isn't an escape: Nix tries to parse it as antiquotation and the backslash doesn't help. The correct escape for a literal ${</code> inside ''...''</code> is ''${</code>:</p> exec -a "''${BASH_ARGV0:-\$0}" "\$bin" "\$@" </code></pre> Single dollars work fine with \$</code>. Only the brace form needs the double-apostrophe escape. Small thing but it took five minutes to figure out, and the error message ("unexpected invalid token"</em>) doesn't lead you to it.</p> Honest reflection</h2> Three wrong hypotheses, each more confident than the last. The Bun-Rust-rewrite story was particularly seductive: recent news, a public issue tracker showing related regressions, timing that lined up. I drafted most of a bug report before checking the one thing that would have killed the hypothesis: which Bun version is actually embedded?</p> When the narrative fits perfectly, that's the moment to do the cheapest disconfirming test. Five seconds of strings | grep Bun</code> would have saved time.</p> The same lesson came back to bite me at the end. I closed out the first version of this post with "the wrapper is partially broken, I'm parking it", documenting the limitation but never actually testing whether it was a limitation</em> or just an unfinished implementation. The $0</code> vs BASH_ARGV0</code> thing would have closed half the gap on day one. The other half (the /proc/self/exe</code> problem) took 20 minutes of set -x</code> once I sat down with the right question. "Good enough for now" deserves the same disconfirming-test discipline as a fresh hypothesis.</p> The deeper lesson, twice over: modifying a binary to fit your OS only works until it doesn't. The bridge-from-Nix-to-FHS pattern feels solid because patchelf is well-understood, but it depends on the source binary having properties (slack in the file layout, no exotic packaging) that the binary's authors never promised you. Invoking the Nix linker directly against a pristine binary felt like the robust alternative, but it has its own ceiling: once you</em> are ld.so, the rest of the world sees ld.so. nix-ld is one more step less clever than the linker-as-wrapper trick: instead of you running the linker, the kernel runs it for you, exactly the way it was designed to. The path of least cleverness wins.</p> Code</h2> The slimmed-down wrapper lives in claude-nixos</a> on the nix-ld</code> branch. With programs.nix-ld.enable = true;</code> in your NixOS configuration and a reasonable libraries</code> list, you don't need a nix-shell</code> to run Claude Code at all: the wrapper is just a ~/.local/bin/claude</code> script that picks the latest installed version and exec's it. If you don't care about juggling multiple installed versions, you can replace the wrapper with a symlink and skip the script entirely.</p> Six numbers from my blog's analytics Unknown — Sun, 17 May 2026 00:00:00 +0000 I recently noticed that the 1 year anniversary of my blog came and went. I was curious about how much traffic I got so I took a look.</p> I sshed into my VPS and pointed sqlite at the GoatCounter database that powers my analytics. Six numbers stood out.</p> For context: this blog gets modest traffic. Usually 20-50 unique visitors a day, mostly from search. I'm not actively trying to grow it, I just write. But the data is interesting because it shows what people actually read versus what I assumed they would.</p> 1. Biggest single-day spike: 33 hits</h2> On 2026-05-11, the post Nix shells, SSH, and Claude Code</a> got 33 visits in one day. That's the single biggest day for any post I've published.</p> For comparison, the next biggest days were 25 (a January post called Letting AI pick the project</a>), 19 (How a friend's gif broke our filesystem</a>), and 13 (Rewriting Claude Code in Rust</a>).</p> The pattern is obvious in hindsight: every spike came from a post solving a specific problem someone was searching for. None of them are essays. None of them are opinions. They're all "here's a weird thing I ran into and how I fixed it."</p> This is the closest thing I have to "going viral," and it's about a 30-line shell.nix.</p> 2. Fastest rising: NixOS + Claude Code</h2> In the last seven days versus the prior seven, the two biggest gainers are both about running Claude Code on NixOS:</p> Post</th> Last 7d</th> Prev 7d</th> Delta</th></tr></thead> Nix shells, SSH, and Claude Code</a></td> 49</td> 10</td> +39</td></tr> Running Claude Code on NixOS</a></td> 34</td> 9</td> +25</td></tr> </tbody></table> That's probably not a coincidence. Anthropic must have changed something recently that caused more people to hit problems running Claude Code on NixOS, and search engines surface my posts as the fix.</p> The two posts also feed each other. Readers land on one, then click through to the other. Internal linking matters more than I expected.</p> 3. Fastest out the gate: 88 hits in the first 30 days</h2> The previous numbers measure "popular right now." A different question is "which posts hit hardest in their first month after publishing?"</p> The top five by views in the first 30 days after their publish date:</p> Post</th> Published</th> First 30d</th></tr></thead> Rewriting Claude Code in Rust</a></td> 2026-04-01</td> 88</td></tr> Running Claude Code on NixOS</a></td> 2026-05-07</td> 43</td></tr> Letting AI pick the project</a></td> 2026-01-19</td> 37</td></tr> Skin shedding, not bikeshedding</a></td> 2025-11-23</td> 32</td></tr> Rewriting Claude Code in Rust (Part 2)</a></td> 2026-04-02</td> 29</td></tr> </tbody></table> The Rust + Claude post is in its own tier. It got 47 of those 88 hits in the first 7 days. That's almost certainly a referral spike from somewhere - Hacker News, Lobsters, a Mastodon boost, hard to say without per-day referrer data.</p> This is a different shape from the NixOS posts. The NixOS surge is search-driven and building over weeks. The Rust + Claude launch was a sharp burst that mostly came and went. Both are "popular." Only one keeps compounding.</p> 4. Longest site-wide streak: 119 days</h2> Every single day from 2026-01-19 to today, at least one post on this blog has been read by someone. That's 119 consecutive days without a gap.</p> The previous longest streak was 49 days. Before that, 29. Before that, 25.</p> This is what "getting indexed" actually looks like as a curve.</p> Before indexing, your blog gets read on days when you publish something or share a link somewhere. After indexing, it gets read every day, forever, because somebody somewhere is searching for a problem you wrote about.</p> That shift was the biggest surprise from all this data. The traffic doesn't spike and disappear anymore. It compounds.</p> 5. Longest per-post streak: 32 days</h2> Nix shells, SSH, and Claude Code</a> was read every day from 2026-03-26 to 2026-04-26 - 32 consecutive days. That's the longest streak any single post has had.</p> The next best are all under two weeks:</p> Rewriting Claude Code in Rust</a>: 13 days (twice)</li> Hyprland tricks: close window confirmation</a>: 13 days</li> Same hyprland post again: 11 days, then 10, then 8, then 7</li> </ul> The hyprland post is still the quiet workhorse of the blog. Published in 2025, it's been read at least once on 146 different days. About 1.8 hits per day on average, every week, for nearly a year.</p> Nothing else comes close to that consistency.</p> If you can choose the problems you write about, choose ones that everybody eventually hits and that nobody else has documented clearly.</p> Length is uncorrelated with traffic.</p> Problem-specificity is.</p> The hyprland post is one paragraph and a screenshot. The nix-shells post is six paragraphs. Both outperform longer essays by a wide margin.</p> 6. Where readers actually come from</h2> Top 10 referrers, last 90 days:</p> Source</th> Hits</th></tr></thead> (direct)</td> 391</td></tr> Google</td> 382</td></tr> duckduckgo.com</td> 45</td></tr> jakegoldsborough.com/blog</td> 37</td></tr> /tags/nixos</td> 33</td></tr> /blog/2026/nix-shells-ssh-claude-code</td> 32</td></tr> /resume</td> 32</td></tr> jakegoldsborough.com</td> 29</td></tr> kagi.com</td> 19</td></tr> Hacker News</td> 14</td></tr> </tbody></table> A few things stood out immediately:</p> Direct and Google are basically tied.</strong> "Direct" includes users with stripped referrer headers, privacy-focused browsers, chat apps, bookmarks, and manually typed URLs. In practice, a lot of "direct" is probably search-driven too.</li> DuckDuckGo (45) and Kagi (19) combined still trail Google by an order of magnitude.</strong> Kagi has a much smaller user base than Google, so this isn't surprising, but it's a useful reality check on how niche the alternative-search world still is.</li> Internal navigation matters.</strong> The /blog index, /tags/nixos, and even /resume page each drive 30+ clicks. Once someone lands on the site, they often keep exploring.</li> Hacker News isn't the firehose people imagine.</strong> A front-page post probably changes the math, but a link in /new creates a short spike and then vanishes quickly.</li> </ul> The more surprising pattern is that almost all long-term traffic comes from search and internal links, not social media.</p> What I'd do differently</h2> Honestly? Nothing.</p> I'm not optimizing for traffic. But if I were, the data points toward one obvious strategy:</p> Write more posts documenting highly specific problems with highly specific solutions.</p> Not opinions.</p> Not giant tutorials covering everything.</p> Just the thing somebody searches for after they hit a wall at 1am.</p> Small technical posts outperform broad polished essays by a huge margin. At least on this blog.</p> How I got this data</h2> GoatCounter ships a SQLite database. I ssh into my VPS, run nix-shell -p sqlite</code>, and query it directly.</p> The two most useful tables are:</p> paths</code>: post URLs and titles</li> hit_counts</code>: hour-bucketed view counts joined by path_id</code></li> </ul> The streak queries use the standard SQL trick of subtracting a row number from a date. Rows with the same difference belong to the same consecutive run.</p> If you self-host GoatCounter, the same queries work on your data. If you don't, the API exposes most of this through /api/v0/stats/hits</code> and related endpoints.</p> The funny part is that after a year of blogging, the strongest signal wasn't traffic volume.</p> It was consistency.</p> Once a post solves a real problem and gets indexed, it just keeps quietly working in the background forever.</p> A 'Was this helpful?' button for a static blog Unknown — Sat, 16 May 2026 00:00:00 +0000 I write a lot here. I don't have comments. I don't want comments. But I do want some signal about which posts are actually landing - not "did someone load the page" (GoatCounter already tells me that) but "did this post help someone."</p> So I added a small button at the bottom of every post:</p> Was this helpful? [ Yep, this helped ]</p> </blockquote> Click it once and it swaps to a thank-you line. Click is recorded as a GoatCounter event. No login, no comment box, no thumbs down. Per-browser dedupe via localStorage so the same person can't pad the number by refreshing.</p> This post is how it works.</p> Constraints</h2> The site is a static Zola build. I don't want a backend, a database, or auth.</li> I already use GoatCounter</a> for analytics. I don't want a second analytics dependency.</li> It has to keep working with JavaScript off, in the sense of not being broken. The widget can be inert when JS is disabled, but the page shouldn't render a button that lies about doing something.</li> No thumbs down. Negative feedback without a way to discuss it is just background noise.</li> Mobile-friendly. A pill-shaped button with a 44px tap target on small screens.</li> </ul> The shape</h2> Three new files plus three small edits to existing templates.</p> templates/macros/helpful.html (new — Tera macro) static/css/helpful.css (new — scoped styles) static/js/helpful.js (new — ~25 lines) templates/page.html (import + render the macro) templates/base.html (load the JS) static/css/style.css (@import the CSS) </code></pre> The whole feature is under 70 lines total.</p> GoatCounter does the click</h2> The first thing I learned reading the GoatCounter events docs</a>: you don't have to write a click handler. Any element with a data-goatcounter-click</code> attribute gets bound automatically. The attribute's value is the event name; data-goatcounter-title</code> sets a human-readable title.</p> So the Tera macro just stamps the button:</p> {% macro widget(page) %} {% set slug = page.path | replace(from="/", to="-") | trim_start_matches(pat="-") | trim_end_matches(pat="-") %} {% set event_name = "helpful-" ~ slug %} <aside class="helpful" data-helpful-path="{{ page.path }}"> <p class="helpful-prompt">Was this helpful?</p> <button type="button" class="helpful-button" data-helpful-action="vote" data-goatcounter-click="{{ event_name }}" data-goatcounter-title="Helpful click on {{ slug }}" >Yep, this helped</button> <p class="helpful-thanks" hidden>✓ Glad it helped</p> </aside> {% endmacro widget %} </code></pre> The slug is the post path with slashes replaced by dashes and the leading/trailing dashes trimmed. So /blog/2026/was-this-helpful-button/</code> becomes helpful-blog-2026-was-this-helpful-button</code>. Each post is its own row in GoatCounter's event list.</p> One gotcha: GoatCounter rejects event paths that start with /</code> (the path doubles as the event name, and they reserve /</code> as a real-path marker). If you forget to strip the leading slash, your events silently don't get recorded.</p> JavaScript handles the dedupe</h2> GoatCounter records the click. localStorage remembers it. The script only does the visual swap:</p> (function () { var widget = document.querySelector('.helpful[data-helpful-path]'); if (!widget) return; var path = widget.getAttribute('data-helpful-path'); var storageKey = 'helpful:' + path; var button = widget.querySelector('[data-helpful-action="vote"]'); var thanks = widget.querySelector('.helpful-thanks'); function showThanks() { button.hidden = true; thanks.hidden = false; } try { if (localStorage.getItem(storageKey)) { showThanks(); return; } } catch (e) { // Private browsing / storage disabled: continue without persistence. } button.addEventListener('click', function () { try { localStorage.setItem(storageKey, Date.now().toString()); } catch (e) { // ignore } showThanks(); }); })(); </code></pre> Twenty-five lines. No framework, no dependencies, no async, no fetch. The try/catch</code> blocks around localStorage are for Safari private mode and embedded webviews, where localStorage</code> throws on access rather than just being absent.</p> Edge cases I thought about</h2> Tracker blockers.</strong> If your readers run uBlock Origin or similar, count.js gets blocked and the click goes nowhere. The UI still swaps state, so they don't see a broken button - the dashboard just under-counts. Acceptable for a directional metric.</p> localStorage disabled.</strong> Try/catch keeps the UI working; users in this mode can vote again across reloads. Tolerable for a directional metric.</p> Same person, multiple browsers.</strong> Each browser counts once. There's no way to deduplicate without auth, and I don't want auth.</p> JS disabled.</strong> The button renders but does nothing. I'd rather show a friendly prompt that can't be acted on than hide the section entirely. If you find that offensive, a one-liner in <noscript></code> hides it.</p> What I learned about GoatCounter</h2> Three things that aren't obvious from the docs:</p> Events show up in the same Pages view as pageviews.</strong> I expected a separate "Events" tab. There isn't one. The events are inlined into the regular pages list, marked with their event title.</p> </li> The GIF response is always 200.</strong> GoatCounter returns a 1x1 GIF for every count request, regardless of whether the hit was actually recorded. You can't tell from HTTP status alone whether your event registered. The signal is whether it shows up in the dashboard.</p> </li> data-goatcounter-click</code> is dramatically simpler than calling window.goatcounter.count()</code> manually.</strong> First version of this widget did the manual call. Second version reads the data attribute. Same behavior, less code, less to break.</p> </li> </ol> What I'm not doing</h2> No "X people found this helpful" counter.</strong> GoatCounter's API doesn't expose per-page event counts to the client, so showing the number would require a backend. I don't care enough.</p> </li> No reading-time gate.</strong> I considered only showing the button after 30 seconds or 60% scroll, to filter skim-clicks. I'll add it if the noise becomes annoying. For now, every click is signal.</p> </li> No newsletter pitch on click.</strong> "Glad it helped - want more?" would convert better. But I don't have a newsletter, so it'd be a lie.</p> </li> </ul> Try it</h2> There's one at the bottom of this post. If this was useful, click it.</p> I'll know whether the post landed because the dashboard will tell me. Not in pageviews. In helpful-blog-2026-was-this-helpful-button</code>.</p> Running Claude Code on NixOS Unknown — Thu, 07 May 2026 00:00:00 +0000 I run NixOS on my laptop. I use Claude Code daily. Recently the two stopped getting along, so I sat down and fixed it.</p> The official Claude Code installer (curl -fsSL claude.ai/install.sh | bash</code></a>) drops a prebuilt Linux binary into ~/.local/bin/claude</code>. On Debian, Fedora, Arch, anything FHS-compliant, it just works. On NixOS, the binary refuses to run with some flavor of:</p> Could not start dynamically linked executable: /home/<user>/.local/bin/claude NixOS cannot run dynamically linked executables intended for generic linux environments out of the box. For more information, see: https://nix.dev/permalink/stub-ld </code></pre> The binary is right there. It has the executable bit. NixOS just refuses to run it.</p> Why this happens</h2> NixOS doesn't follow the Filesystem Hierarchy Standard</a>. There is no /lib64/ld-linux-x86-64.so.2</code>. Every library lives in /nix/store/<hash>-<package>/lib/</code>, and a given system can have many versions of the same library coexisting in different store paths.</p> Prebuilt Linux binaries hardcode /lib64/ld-linux-x86-64.so.2</code> as the path to the dynamic linker. They also hardcode an rpath pointing at FHS library directories that don't exist. When the kernel execve</code>s such a binary, it can't find the linker to load and bails out with the misleading "required file not found" error.</p> This isn't unique to Claude Code. It bites Discord, Spotify, Steam, the .NET SDK, anything you curl | bash</code> from a vendor's website. The NixOS community has several documented workarounds</a>:</p> patchelf</strong>: rewrite the binary's interpreter and rpath to point at Nix store paths</li> nix-ld</strong>: a shim that maps the FHS linker path to a real Nix-provided linker at runtime</li> buildFHSEnv</strong> / steam-run</code>: drop the binary into a sandbox that fakes an FHS layout</li> autoPatchelfHook</strong>: the canonical packaging path, used when a binary is being added to nixpkgs</li> </ul> I went with patchelf. It works from a plain nix-shell</code> without touching configuration.nix</code>, and it leaves the official install path intact - the binary still lives where Claude Code expects it.</p> The fix</h2> claude-nixos</a> is a single shell.nix</code> (133 lines) that does three things:</p> Wraps the official install script and patches the binary on the way in</li> Patches binaries that are already</em> installed</li> Updates an existing install to a new version, repatching as it goes</li> </ol> You enter the shell:</p> nix-shell shell.nix </code></pre> And get three functions:</p> install_claude_fixed # download + patch install_claude_fixed 0.5.2 # specific version fix_installed_claude # repair what's already there update_claude_fixed # newer version, same patch </code></pre> How the patch works</h2> The interesting bit is the patch_binary</code> function. Given a path to an ELF binary, it asks Nix for the path to its</em> dynamic linker and the libraries the binary will need, then rewrites the binary in place:</p> patchelf \ --set-interpreter "$DYNAMIC_LINKER" \ --set-rpath "$LIBRARY_PATH" \ "$binary" </code></pre> $DYNAMIC_LINKER</code> comes from pkgs.stdenv.cc.bintools.dynamicLinker</code> (a real, existing /nix/store</code> path). $LIBRARY_PATH</code> is built from glibc</code>, libstdc++</code>, openssl</code>, curl</code>, sqlite</code>, zlib</code> (the libraries Claude Code's binary actually links against, found by trial and ldd</code>).</p> After patching, the binary's interpreter points at a file that exists on NixOS, and its rpath points at directories that contain the libraries it needs. The kernel can execve</code> it, the linker can resolve its imports, and claude</code> runs.</p> For new installs, the wrapper runs sed</code> against the official install script to inject patchelf calls right after the binary is placed:</p> sed -i "/cp.*claude.*\$INSTALL_DIR/a $PATCH_SCRIPT" install.sh </code></pre> So the patched flow is byte-for-byte the official install with one extra step inlined. When Anthropic ships a new installer, the wrapper still works as long as cp ... claude ... $INSTALL_DIR</code> stays in the script. If they restructure it, the sed pattern breaks loudly and obviously.</p> Try it</h2> git clone https://github.com/ducks/claude-nixos cd claude-nixos nix-shell install_claude_fixed claude --version </code></pre> If you've already installed Claude Code through the official script and it's broken, run fix_installed_claude</code> instead and it'll patch what's there.</p> Links</h2> claude-nixos</a></li> NixOS Wiki: Packaging/Binaries</a> - the canonical write-up of the four fix-it options</li> nix-ld</a> - the system-wide alternative</li> </ul> shellbooks: A Terminal Audiobook Player Unknown — Mon, 04 May 2026 00:00:00 +0000 I have a music player in the terminal (shelltrax</a>) and a podcast player in the terminal (shellcast</a>). Audiobooks were the obvious gap.</p> So I built shellbooks</a>.</p> cargo install shellbooks </code></pre> It's a TUI audiobook player and library manager. cmus-inspired keybinds, ratatui rendering, rodio for audio, the same shape as the other two shell* tools. Open source, offline-first, runs on Linux and macOS.</p> Why audiobooks need their own player</h2> I wanted a CLI audiobook player that follows the cmus conventions I already use for music. A real TUI audiobook player on Linux, not a GUI app shoved into a terminal window.</p> Music players treat tracks as the unit. Podcast players treat episodes as the unit. Audiobooks need the book</em> as the unit, with chapters as the unit inside</em> a book. That changes a few things:</p> Position memory matters more.</strong> Resuming a song from 0:00 is fine. Resuming a 14-hour book from 0:00 is a tragedy.</li> Variable speed is table stakes.</strong> Most people listen at 1.25x or 1.5x. A music player has no reason to ship this; an audiobook player without it is broken.</li> Chapter navigation needs to work.</strong> Multi-file books have one chapter per file; single-file .m4b</code> books have chapter markers embedded in the container.</li> </ul> None of this is exotic. It just doesn't fit the music or podcast model directly.</p> The Stack</h2> ratatui</code> and crossterm</code> for the TUI</li> rodio</code> and symphonia</code> for audio playback</li> id3</code> for mp3 tags, mp4ameta</code> for m4b tags and chapter atoms</li> walkdir</code> for the file browser</li> Plain JSON at ~/.local/share/shellbooks/library.json</code> for the library and per-book progress</li> </ul> Same stack the other shell* tools use. The point of building these in a series is that each one starts halfway done.</p> Interface</h2> Three views, swapped with 1</code> / 2</code> / 3</code>:</p> Library</strong> is two-pane: books left, chapters right. Tab toggles which side j</code>/k</code> moves through. Enter on the books pane resumes from the saved position. Enter on the chapters pane jumps to that chapter's start.</li> Bookmarks</strong> lives at 2</code> (UI is still placeholder; the data model is in place).</li> Browser</strong> is a file system browser. Navigate to a directory of audio files or a single .m4b</code>, press a</code>, and it's added to the library.</li> </ul> A persistent footer sits on every screen with the book title, current chapter, position, total duration, speed, and a progress gauge. Press i</code> anywhere to open a centered modal with the full metadata for the selected book.</p> What's Working</h2> Imports from a file browser - explicit action, no surprise sweeps of ~</code></li> Chapter detection: parses the chpl atom in .m4b</code>, falls back to one chapter per file with cleaned filenames (01 - Prologue.mp3</code> becomes Prologue</code>)</li> Per-book progress with autosave every 10 seconds while playing, plus on every chapter change. A crash never costs more than ten seconds.</li> Variable speed (0.5x - 3.0x) via +</code> and -</code> in 5% steps. Pitch shifts with tempo today; pitch-preserving via tdpsola is next.</li> Chapter skip (b</code> next, z</code> previous), seek (,</code>/.</code> ±10s, [</code>/]</code> ±60s)</li> Cover art resolution: sidecar cover.jpg</code> or cover.png</code> first, then embedded artwork written to a cache file</li> Tag extraction: title, author, narrator, series, year - using the audiobook publishing convention where artist is author and album is the book title</li> Delete a book from the library with d</code> (mirrors shelltrax)</li> </ul> What's Not (yet)</h2> Pitch-preserving variable speed</li> Bookmarks UI (model exists, no bindings yet)</li> Theme parsing</li> Sleep timer countdown</li> Cover art rendered in-terminal (kitty / sixel / iterm2)</li> Network sources like Audiobookshelf</li> </ul> A Bug Worth Mentioning</h2> Imported a book and the title showed as "Track 001."</p> The reason: I was reading the title tag from the first audio file. For a multi-file audiobook, the per-track TIT2</code> is the chapter</em> title, not the book. The book title belongs in the album tag. So now apply_to_book</code> takes a multi_file</code> flag and uses the album tag in that case, falling back to the directory name if there's no album.</p> For single-file .m4b</code> it still uses the title tag normally, since there the file is</em> the book.</p> The kind of bug that's obvious in hindsight and only really shows up once you point the tool at real publisher data.</p> Building it in a Series Pays Off</h2> The bulk of the work on shellbooks was on the audiobook-specific bits: chapter atom parsing, the multi-file album-as-title rule, position tracking that survives speed changes and pause/resume, the autosave loop. Almost none of it was on TUI scaffolding, the file browser, the event loop, or the release pipeline. All of that was lifted from shelltrax.</p> It's also why I'm thinking about pulling the shared TUI bits into a shell-tui</code> crate. The ListSelector</code>, the BrowserState</code>, the event loop, the cmus-style screen jumps, the Makefile</code> template, the GitHub Actions release workflow - all of it is duplicated nearly verbatim across three apps now. Three is the inflection point.</p> Try It</h2> cargo install shellbooks shellbooks </code></pre> Press 3</code> to open the file browser, navigate to your audiobooks, press a</code> to import a book directory or .m4b</code>. Press 1</code> to return to the library, Enter to start playing.</p> Links</h2> shellbooks</a></li> shelltrax</a> - the music player it descends from</li> shellcast</a> - the podcast player it descends from</li> </ul> isitreal.estate: Crowd-Sourced Reviews for Real Estate Listings Unknown — Sat, 18 Apr 2026 00:00:00 +0000 Most real estate listings lie. Not always in big ways, but enough that anyone who has hunted for an apartment or a house knows the feeling - you drive 40 minutes, the front yard is a dump, the photos were from 2018, the "washer/dryer included" means hookups in a damp basement, and the agent shrugs.</p> There is no shared layer of truth for listings. Every renter and buyer does the same recon work from scratch.</p> So I built isitreal.estate</a> - crowd-sourced reviews tied to physical addresses, not listings. Listings come and go. Addresses stay.</p> The Idea</h2> Think Waze, but for house hunting.</p> You search an address. You see what other people found when they visited. Photos they took. Whether the listing photos matched reality. A rating. A date.</p> If the address has never been reviewed, you can be the first. After you visit, leave a review with photos. Over time, bad actors accumulate a visible history tied to the properties they list.</p> Data Model</h2> The anchor entity is the address, not the listing. A listing is ephemeral - taken down, renamed, relisted with new photos. An address has GPS coordinates and does not move.</p> addresses id, street, city, state, zip, country, lat, lng reviews id, address_id, user_id, listing_accurate (yes/partially/no), rating (1-5), body, visited_at review_photos id, review_id, filename, path votes id, review_id, user_id, vote (accurate/not_accurate) </code></pre> Reviews carry photos. Votes let readers weigh reviews by what the community agreed was useful or not. A user's credibility score is derived from how often their reviews align with votes over time.</p> The Stack</h2> Framework</strong>: SvelteKit 5 (runes)</li> Database</strong>: PostgreSQL</li> Auth</strong>: Session-based, scrypt hashing</li> Maps</strong>: Leaflet + OpenStreetMap tiles</li> Geocoding</strong>: Nominatim (OSM, free)</li> Photos</strong>: Disk storage, behind a configurable UPLOAD_DIR</code></li> Deployment</strong>: NixOS on my VPS, Caddy reverse proxy, systemd</li> </ul> Nothing exotic. The most interesting choice was OSM + Nominatim instead of Google Maps - no API key, no billing, no surprise bills if someone shares the site somewhere.</p> Deployment</h2> The deploy is declarative and lives in my pond-nix</code> repo. A new curbside release builds a tarball on GitHub Actions; a NixOS service fetches it on rebuild; systemd runs node build</code>; Caddy handles TLS.</p> The first deploy broke for a boring but interesting reason. The systemd unit tried to bind-mount a writable uploads directory into the Nix store path, which is read-only. systemd refused:</p> Failed to create destination mount point node '/nix/store/.../source/uploads': Read-only file system </code></pre> Rather than patching the Nix module to copy the app out of the store, I made the upload directory configurable in the app itself:</p> export const UPLOAD_DIR = process.env.UPLOAD_DIR || 'uploads'; </code></pre> Both the write path (src/lib/photos.ts</code>) and the read path (src/routes/uploads/[...path]/+server.ts</code>) import the same constant, so they never drift. In dev it defaults to ./uploads</code>. In production the systemd unit sets UPLOAD_DIR=/var/lib/curbside/uploads</code> and the BindPaths goes away entirely.</p> Cleaner than fighting the Nix store. And it unblocks moving uploads off the VPS to R2 later with the same interface.</p> What Works</h2> Signup, login, session auth</li> Address search with geocoding</li> Address detail page with reviews, photos, stats</li> Review submission with photo uploads</li> Accurate / not-accurate voting</li> User profile pages</li> Admin role for moderation</li> </ul> What Doesn't (Yet)</h2> Map view on the homepage is basic</li> No autocomplete on address search yet</li> Photo storage lives on the VPS; needs to move to object storage</li> No rate limiting on review creation</li> Credibility scoring is naive</li> </ul> Reflections</h2> The technical work was the easy part. SvelteKit + Postgres + systemd is well-trodden ground. The real question is whether enough people will leave reviews to reach the tipping point where the site is actually useful when you search an address.</p> That is the honest problem with any crowd-sourced trust network. It is worthless until it crosses some critical mass, and valuable after. The middle is long and quiet.</p> So I am seeding with real reviews of real addresses I know, and opening it up to see what happens. If you have ever been burned by a fake listing, leave a review.</p> Links</h2> isitreal.estate</a></li> curbside (app source)</a></li> pond-nix (deploy config)</a></li> </ul> How my blog started getting indexed Unknown — Thu, 09 Apr 2026 00:00:00 +0000 I write this blog primarily for myself - to think through problems, document decisions, and have a record of what I built and why. I don't optimize for search traffic. But about two months after I started publishing consistently, something unexpected happened: search engines started sending people here. Google, DuckDuckGo, Bing, ChatGPT, Perplexity.</p> Not a flood. Maybe 20-30 visitors a day from search. But those visitors are finding specific technical posts about problems they're trying to solve. The kind of traffic that actually matters.</p> I didn't do SEO. I didn't build backlinks. I didn't write "10 tips" posts or target keywords. What I did do, almost accidentally, was follow a few patterns that apparently work.</p> What Actually Worked</h2> 1. Publishing consistently</h3> I've published 47 posts since January 2026. That's roughly one every 2-3 days. Not because I'm following a content calendar, but because I'm building things and writing about them as I go.</p> Each post is a surface. Search engines index surfaces. More surfaces = more ways to be found.</p> 2. Writing real titles</h3> My titles describe the actual content. Not "Improve Your Workflow with This One Trick" but "Rewriting Claude Code in Rust (Part 2)". Specific, descriptive, ungameable.</p> Turns out that when someone searches for "claude code rust", a post with those exact words in the title ranks. Obvious in hindsight.</p> 3. Internal linking</h3> I link between related posts constantly. When I mention a project I've written about before, I link to it. When I reference a concept from another post, I link to it.</p> This creates a web. Google's crawler follows links. A well-linked collection of pages signals that this is a coherent body of work, not random blog spam.</p> 4. Clean, simple structure</h3> My site is static HTML generated by Zola. No JavaScript frameworks, no client-side routing, no dynamic content. Just semantic HTML with proper headings, paragraphs, and code blocks.</p> Crawlers love this. Fast pages, clear structure, no obstacles.</p> 5. Code blocks and technical depth</h3> Most of my posts include code examples, file paths, implementation details. These are extremely specific signals. If someone searches for a particular function name or error message, and I've written about it, search engines can match that query to my content precisely.</p> What Didn't Matter</h2> I don't have a sitemap (though Zola can generate one, I haven't enabled it). I have minimal visitor tracking but that's it. I don't track keyword density or optimize meta descriptions. I post on the fediverse but not as a promotion strategy.</p> None of that seems to matter for this kind of technical writing. The content itself is the SEO.</p> The Pattern</h2> What I've accidentally done is create a growing surface area of well-structured, interconnected technical content. Each new post adds another surface that search engines can index. Each internal link strengthens the web.</p> I'm not trying to rank for "best programming language" or other high-competition terms. I'm documenting niche problems and implementations. The long tail. And the long tail is where technical blogs actually get found.</p> Why This Matters</h2> This blog is a byproduct of my work. Writing these posts helps me think. Publishing them creates a permanent record. The fact that they also get found by people solving similar problems is a side effect - but it's a useful one.</p> It means the work compounds. Not just for me (as a reference and thinking tool) but for others who stumble across it via search.</p> That's the model I'm optimizing for. Not traffic. Not engagement. Just clear documentation of real work, published consistently, with enough structure that search engines can surface it when someone needs it.</p> What I'm Going to Keep Doing</h2> Publishing consistently as I build</li> Writing descriptive titles</li> Linking between related posts</li> Using semantic HTML and clear structure</li> Including code examples and technical details</li> </ul> That's it. No keyword research, no backlink campaigns, no growth hacking. Just building and documenting in public, with enough consistency that it accumulates into a corpus worth indexing.</p> The blog is working exactly how I want it to. The search traffic is proof that the model scales.</p> Jobchain: Verifiable Employment Credentials Unknown — Mon, 06 Apr 2026 00:00:00 +0000 Michał Fita responded to my whoami-spec post</a> asking about verifiable credentials. His point: we should be able to prove employment history with cryptographic signatures, not chiselled PDFs that ATSes shred back into text.</p> He was right about the problem. But every previous attempt at this (Blockcerts, LinkedIn verified credentials, W3C VCs) died because it's a three-sided marketplace. Employers have to issue credentials. Employees have to hold them. ATSes have to consume them. Nobody wants to go first.</p> I built the tooling anyway.</p> The Problem</h2> The employment verification pipeline is absurd:</p> You write a resume (self-attested, no proof)</li> You export to PDF (formatting lottery)</li> An ATS OCRs it back to text (lossy, error-prone)</li> A background check company calls your old employer (slow, expensive)</li> Someone confirms dates over the phone (binary pass/fail)</li> </ol> Every step degrades information. The structured data you started with becomes an unstructured phone call. There has to be a better way.</p> The Fix</h2> Public key cryptography. Same thing that makes HTTPS work.</p> Your employer has a keypair. They sign a JSON document saying you worked there. Anyone can verify the signature by checking the public key hosted on the employer's domain.</p> No blockchain. No platform. No account to create. DNS is the trust anchor.</p> How It Works</h2> Three commands:</p> 1. Employer creates an identity</h3> $ jobchain init --org "Discourse" --domain discourse.org Initialized jobchain identity for Discourse DID: did:web:discourse.org Next: host did.json at https://discourse.org/.well-known/did.json </code></pre> This generates an Ed25519 keypair and a DID document</a>. The public key lives at a well-known URL on the company's domain. If you control discourse.org</code>, you control the identity. No certificate authority, no third party.</p> 2. Employer issues a credential</h3> $ echo '{"title":"Infrastructure Engineer","company":"Discourse","start":"2024-03"}' \ | jobchain issue --domain discourse.org { "@context": ["https://www.w3.org/2018/credentials/v1"], "type": ["VerifiableCredential", "EmploymentCredential"], "issuer": "did:web:discourse.org", "credentialSubject": { "type": "EmploymentRecord", "title": "Infrastructure Engineer", "company": "Discourse", "start": "2024-03" }, "proof": { "type": "Ed25519Signature2020", "proofValue": "z4jH8n..." } } </code></pre> That's a W3C Verifiable Credential</a>. Structured JSON, signed with Ed25519. Hand the .vc.json</code> file to the employee.</p> 3. Anyone verifies</h3> $ jobchain verify --input jake-discourse.vc.json VALID -- credential signature verified Issuer: did:web:discourse.org Subject: Infrastructure Engineer at Discourse Issued: 2026-04-02 </code></pre> The verify command fetches the public key from discourse.org/.well-known/did.json</code> and checks the signature. No account needed. No API key. Just math.</p> The Wallet Is a Git Repo</h2> Your "wallet" is a folder of .vc.json</code> files. Host it anywhere. GitHub Pages, Netlify, your own server.</p> $ jobchain wallet build --dir ./credentials --out ./site </code></pre> This generates an HTML site with your credentials and a machine-readable index.json</code> manifest. Hiring managers see a clean page. ATS systems consume structured JSON. Same data, two views.</p> The wallet is static files. Push to a repo, deploy to Pages. Done.</p> Why Not Blockchain</h2> This comes up immediately, so let me address it.</p> Blockchain solves one problem jobchain doesn't: persistence after the issuer disappears. If discourse.org</code> goes dark, the public key is gone and nobody can verify old credentials.</p> But blockchain adds massive complexity for that edge case. Consensus mechanisms, gas fees, infrastructure dependencies. And the social problem (getting employers to issue credentials) doesn't change regardless of the storage layer.</p> For now, DNS is the trust anchor. If persistence matters later, there are simpler solutions: key archival services, IPFS pinning, or embedding the public key in the credential itself.</p> Amendments</h2> Credentials aren't static. You get promoted. You change teams. Jobchain supports amendments: signed updates linked to the original credential via content hash.</p> $ jobchain amend --credential jake-discourse.vc.json \ --domain discourse.org \ --patch '{"title":"Senior Infrastructure Engineer"}' \ --effective-date 2025-06 </code></pre> Each amendment is independently verifiable. The chain forms a linked list: original credential, then amendments, each signed and hash-linked to its predecessor.</p> What This Is Not</h2> It's not a platform. There's no service to sign up for, no data to hand over.</p> It's not self-attested. Only the employer's private key can produce a valid signature.</p> It's not a resume replacement. JOBL</a> handles the self-authored resume. Jobchain handles what others can confirm about you. They complement each other.</p> The Architecture</h2> Jobchain is a Cargo workspace with three crates:</p> jobchain-core</strong>: credential types, Ed25519 signing, DID documents, amendment chains</li> jobchain-verify</strong>: signature verification only, kept slim for future WASM compilation</li> jobchain-cli</strong>: the jobchain</code> binary</li> </ul> 131 tests. All passing.</p> The verify crate is deliberately lightweight. No HTTP client, no file I/O, no CLI dependencies. The plan is to compile it to WASM so the wallet can verify credentials in-browser without a server.</p> What I Actually Used to Build This</h2> I used finna</a> to architect and implement it. Claude and Gemini debated the architecture, generated 16 implementation specs, then Claude implemented each spec as a feature branch. The whole thing -- keypair generation, DID documents, credential signing, verification, amendments, adapter traits, wallet generator, CLI, 131 tests -- was implemented in one session.</p> I reviewed the output, fixed a few things, and it worked end to end. That's a different kind of project kickstart than I'm used to.</p> The Hard Part</h2> The tooling exists. The hard part is adoption.</p> Someone has to go first. An employer has to host a did.json</code> and issue a credential. An employee has to publish their wallet. A hiring manager has to check it.</p> I work at a smaller company. We could try it. The ask is small: host one JSON file, run one command when someone joins or leaves. Frame it as a signed reference letter that's machine-verifiable.</p> That's the next step.</p> Current Status</h2> Working CLI with all Phase 1 features:</p> jobchain init</code> -- generate org identity</li> jobchain issue</code> -- sign employment credentials</li> jobchain verify</code> -- check signatures (offline or via DID resolution)</li> jobchain amend</code> -- signed amendments to existing credentials</li> jobchain wallet build</code> -- static site generator</li> </ul> What's missing:</p> Actual adoption by an employer</li> HR tool adapters (BambooHR, Gusto, etc.)</li> WASM verification in the wallet</li> A real-world credential issued by a real company</li> </ul> The infrastructure is there. Now it needs to be used.</p> Links</h2> Jobchain on GitHub</a></li> Jobchain Documentation</a> -- implementation guide and spec</li> JOBL</a> -- structured resume format (companion project)</li> whoami-spec</a> -- declarative identity</li> finna</a> -- multi-model debate and implement</li> </ul> Inside Claude Code's Team Memory Sync Engine Unknown — Sun, 05 Apr 2026 00:00:00 +0000 Most people using Claude Code don't know it has a shared memory system. A directory on disk that syncs to Anthropic's servers, merges with your teammates' memories, and gets injected into every conversation. No git involved. No manual sharing. It just works.</p> I found it while reading the leaked source. A teamMemorySync/</code> directory with six files: a sync engine, a file watcher, a secret scanner, type definitions, a path validator, and prompt integration. About 800 lines of TypeScript implementing a real-time collaborative knowledge base inside a CLI tool.</p> What Team Memory Is</h2> Team memory is a flat key-value store scoped per repository. Keys are file paths like MEMORY.md</code> or patterns.md</code>. Values are UTF-8 content, typically markdown. It lives at:</p> ~/.claude/projects/<project-hash>/memory/team/ </code></pre> Every authenticated user in your organization who works in the same repo shares this directory. When one person writes a memory file, it syncs to the server and gets pulled into everyone else's session.</p> The system prompt tells Claude about both memory directories:</p> You have a persistent, file-based memory system with two directories: a private directory at <auto-path></code> and a shared team directory at <team-path></code>.</p> </blockquote> Claude reads the team MEMORY.md</code> index at session start and can access any file in the team directory. When it saves a memory, it decides whether to put it in private or team based on the content type.</p> The Sync Engine</h2> The sync logic in teamMemorySync/index.ts</code> handles three operations: pull, push, and hash comparison.</p> Pull (server to local)</h3> On session start, Claude Code fetches the team memory for your repo:</p> GET /api/claude_code/team_memory?repo={owner/repo} </code></pre> The response includes all entries (key-value pairs), per-entry SHA-256 checksums, a version number, and an overall checksum. Server wins -- pull overwrites local files. If the server returns a 304 (ETag matches), nothing happens.</p> Push (local to server)</h3> When you edit a team memory file, the watcher triggers a push. But it doesn't upload everything -- it computes a delta:</p> Hash each local file with SHA-256</li> Compare against serverChecksums</code> (cached from the last pull/push)</li> Only upload files whose hash differs</li> </ol> PUT /api/claude_code/team_memory?repo={owner/repo} </code></pre> The PUT uses upsert semantics -- keys not in the request are preserved on the server. This means pushing a single changed file doesn't delete everything else.</p> There's also a body size cap of 200KB per request. If the delta exceeds that, it splits into sequential PUTs. Each one merges safely because of the upsert semantics.</p> Conflict Resolution</h3> Optimistic concurrency via ETags. Every push includes the last-known checksum as If-Match</code>. If someone else pushed in between, you get a 412 Precondition Failed.</p> The conflict resolution is clever. Instead of pulling the full content (potentially 300KB), it fetches just the checksums:</p> GET /api/claude_code/team_memory?repo={owner/repo}&view=hashes </code></pre> This returns per-key hashes without the actual content. The client updates its serverChecksums</code> map, recomputes the delta, and retries the push with the new ETag. Up to 2 conflict retries before giving up.</p> The File Watcher</h2> A fs.watch</code> on the team memory directory, debounced at 2 seconds. When a file changes:</p> Wait 2s for more changes (debounce)</li> If a push is already in progress, mark hasPendingChanges</code></li> When the current push finishes, if hasPendingChanges</code>, push again</li> On permanent failure (auth error, too many entries), suppress the watcher to prevent infinite retry loops</li> </ol> The watcher is careful about one edge case: when a pull writes server content to local files, those writes trigger watch events. Without suppression, you'd get a pull-then-immediate-push loop. The watcher skips events during pull operations.</p> The Secret Scanner</h2> Before any push, every file is scanned for credentials. The scanner uses 30+ regex patterns adapted from gitleaks (MIT licensed), covering:</p> Cloud providers</strong>: AWS access keys, GCP API keys, Azure AD secrets, DigitalOcean tokens</li> AI APIs</strong>: Anthropic keys (sk-ant-api03-...</code>), OpenAI keys, HuggingFace tokens</li> Version control</strong>: GitHub PATs/OAuth/app tokens, GitLab PATs/deploy tokens</li> Communication</strong>: Slack bot/user/app tokens, Twilio, SendGrid</li> Dev tools</strong>: NPM tokens, PyPI upload tokens, HashiCorp TF tokens, Databricks, Pulumi, Postman</li> Payment</strong>: Stripe keys, Shopify tokens</li> Crypto</strong>: PEM private key blocks</li> </ul> Files with detected secrets are silently skipped -- not uploaded, not deleted locally, not reported to the server. The push result includes which files were skipped and why, so the system can inform the user.</p> The patterns are curated for near-zero false positives. They only match distinctive prefixes (ghp_</code>, sk-ant-</code>, xoxb-</code>, AKIA</code>, etc.) rather than generic keyword patterns. The comment in the source:</p> Uses a curated subset of high-confidence rules from gitleaks -- only rules with distinctive prefixes that have near-zero false-positive rates are included. Generic keyword-context rules are omitted.</p> </blockquote> One interesting detail: the Anthropic API key pattern assembles its prefix at runtime (['sk', 'ant', 'api'].join('-')</code>) so the literal string doesn't appear in the compiled bundle. They have an internal excluded-strings.txt</code> check that greps build output for sensitive strings -- the secret scanner would trip its own detection if the prefix were hardcoded.</p> Path Safety</h2> Team memory files arrive from the server with relative paths as keys. The path validator in teamMemPaths.ts</code> prevents directory traversal attacks:</p> Rejects paths containing ..</code> after normalization</li> Resolves symlinks and checks the canonical path stays inside the team memory directory</li> Rejects absolute paths</li> Throws a PathTraversalError</code> if a key would escape the sandbox</li> </ul> This matters because the server response drives file writes. A malicious or compromised server could theoretically send a key like ../../../.bashrc</code> -- the path validator prevents that.</p> How Claude Uses It</h2> The team memory directory gets loaded into the system prompt alongside the private memory. Claude sees both and is instructed on when to use each:</p> Private memories</strong>: things specific to one user (preferences, role, feedback on how to work with them)</li> Team memories</strong>: shared project knowledge (architecture decisions, patterns, conventions, ongoing initiatives)</li> </ul> The prompt is explicit about what NOT to put in team memory:</p> You MUST avoid saving sensitive data within shared team memories. For example, never save API keys or user credentials.</p> </blockquote> When Claude writes a memory, it chooses the directory based on content type. User preferences go private. Project patterns go team. The two indexes (MEMORY.md</code> in each directory) are both loaded into context.</p> Size Limits</h2> Per file</strong>: 250KB max (filtered client-side before upload)</li> Per PUT body</strong>: 200KB (splits into sequential requests if exceeded)</li> Entry count</strong>: server-enforced, tunable per-org (no client-side default)</li> API timeout</strong>: 30 seconds</li> </ul> When the server rejects a push for too many entries, it returns a structured 413 with the limit:</p> { "error": { "details": { "error_code": "team_memory_too_many_entries", "max_entries": 100, "received_entries": 142 } } } </code></pre> The client caches the max_entries</code> value and truncates on subsequent pushes.</p> Requirements</h2> Team memory requires:</p> OAuth authentication (not API key, not Bedrock/Vertex)</li> user:inference</code> and user:profile</code> scopes</li> A git repo with a remote (used to derive owner/repo</code> slug)</li> </ul> It's designed for Claude.ai Team and Enterprise plans, but works for Pro/Max too. Bedrock and Vertex users are excluded -- the sync endpoint requires first-party Anthropic auth.</p> What's Interesting About It</h2> The engineering is solid but the concept is what stands out. Most AI coding tools treat each session as isolated. Your context disappears when you close the terminal. If your teammate learned something useful, you have to rediscover it.</p> Team memory makes knowledge accumulate. One person documents a tricky API pattern, and every future conversation in that repo -- by anyone on the team -- gets that context. Without checking anything into git, without sharing a doc, without telling anyone. The AI just knows because the team taught it.</p> The secret scanner is the paranoid layer that makes this possible. Shared memory across a team is a liability if it leaks credentials. Scanning before upload, with patterns that match real secret formats instead of guessing from keywords, is the right approach.</p> The sync engine is pragmatic. Server wins on pull. Upsert on push. ETag for conflicts. No CRDT, no operational transform, no fancy merge. Just "last write wins per key" with checksums to avoid unnecessary uploads. For markdown files that humans edit infrequently, it's the right level of complexity.</p> Found by reading the Claude Code source that leaked via npm source maps on March 31, 2026. The team memory system lives in src/services/teamMemorySync/</code> and src/memdir/teamMemPaths.ts</code>.</p> Rewriting Claude Code in Rust, Part 3: TUI, Agents, and Multi-Provider Unknown — Sat, 04 Apr 2026 00:00:00 +0000 Part 2</a> left off at 1,530 lines with an inline REPL, permission prompts, session management, and compaction. It worked, but it looked like a script, not a tool.</p> This post covers the rest: a proper TUI, the agent system, and breaking free from Anthropic-only.</p> Phase 4: The TUI</h2> The inline REPL was functional but crude. Print prompt, read line, stream tokens, repeat. No scroll, no layout, no visual distinction between you and the assistant.</p> Claude Code's original UI is React + Ink -- React components rendered to the terminal. That's not happening in Rust. The equivalent is ratatui, which gives you a layout engine, widgets, and an alternate-screen buffer.</p> The TUI runs behind --tui</code>. The inline REPL stays as the default because it's simpler and pipes better.</p> Layout</h3> Four zones, top to bottom:</p> ┌─────────────────────────────────┐ │ claux v20260401.0.1 │ <- header ├─────────────────────────────────┤ │ │ │ You │ │ > read src/main.rs │ │ │ <- scrollable message area │ fn main() -> Result<()> { │ │ let args = Cli::parse(); │ │ ... │ │ │ ├─ > ────────────────────────────-┤ <- input box │ explain the error handling │ ├─────────────────────────────────┤ │ claude-sonnet-4 | Cost: $0.02 │ <- status bar └─────────────────────────────────┘ </code></pre> Messages are color-coded: blue for user, default for assistant, green for streaming text, yellow for system messages and permission prompts. Gruvbox palette because that's what I use everywhere.</p> The Hard Part: Async + TUI</h3> The challenge with a terminal UI and an async LLM client is that you can't await</code> the API call and poll terminal events at the same time from the same thread. The inline REPL solved this by spawning the display as a tokio task and driving the engine on the main thread. The TUI can't do that -- it needs to own the terminal.</p> The solution: drive the streaming loop manually with tokio::select!</code>. One arm reads API events, the other polls terminal input with a short timeout. Ctrl+C during streaming cancels the request.</p> loop { tokio::select! { Some(event) = api_rx.recv() => { match event { ApiEvent::Text(t) => { app.stream_buffer.push_str(&t); terminal.draw(|f| ui::draw(f, app))?; } ApiEvent::ToolUse { id, name, input } => { tool_uses.push((id, name, input)); } ApiEvent::Done => break, // ... } } _ = tokio::time::sleep(Duration::from_millis(50)) => { if event::poll(Duration::from_millis(0))? { if let Event::Key(key) = event::read()? { // Handle Ctrl+C, scroll, etc. } } } } } </code></pre> Permission prompts work inline in the TUI. When the engine needs approval, the input box turns yellow and shows the tool name with (y)es / (n)o / (a)lways</code>. The engine blocks on a oneshot channel until you answer.</p> What It Cost</h3> 928 lines for the TUI module. Two files: tui/mod.rs</code> (app state, event loop, streaming driver) and tui/ui.rs</code> (layout and rendering). The rendering is naive -- no markdown parsing, no syntax highlighting, no word wrap. But it works and it's fast.</p> Upgrading to Rust 1.88 was required because ratatui 0.29's dependencies needed it. The shell.nix</code> now uses rust-overlay instead of nixpkgs' rust.</p> Phase 5: Agents</h2> The Agent tool is what makes Claude Code feel like it has workers. You ask it to do something complex, it spawns a sub-conversation with its own context and a restricted tool set.</p> In claux, the Agent tool creates a child Engine</code>:</p> async fn execute(&self, input: Value) -> Result<ToolOutput> { let params: Params = serde_json::from_value(input)?; let provider = (self.make_provider)(); let tools = ToolRegistry::without_agent(); // no recursion let permissions = PermissionChecker::new(PermissionMode::Bypass); let mut engine = Engine::new(provider, tools, permissions, &self.model); engine.set_system_prompt(agent_prompt); match engine.submit(&params.prompt).await { Ok(response) => Ok(ToolOutput { content: response, is_error: false, }), // ... } } </code></pre> Three key decisions:</p> No nested agents.</strong> ToolRegistry::without_agent()</code> excludes the Agent tool from sub-agents. Prevents infinite recursion.</p> </li> Bypass permissions.</strong> Agents run unattended. If the parent conversation approved the Agent call, the sub-agent's tools don't need individual approval.</p> </li> Own context.</strong> The sub-agent starts with a fresh message history and its own system prompt. It doesn't see the parent conversation.</p> </li> </ol> Cost tracking flows back -- the agent's token usage is appended to its output so you can see what it spent.</p> Auto-Compact</h3> Phase 5 also added auto-compaction. Before each submit</code>, the engine checks if the message count exceeds 80. If so, it runs the same compaction logic as /compact</code> -- summarizes the conversation via the API and replaces history with the summary.</p> This is the dumb version of what Claude Code does. Their compaction pipeline has multiple strategies: reactive compact, context collapse, history snip, tool-use summaries. Ours is a threshold check and a summarization call. But it prevents the context window from overflowing, which is the thing that actually matters.</p> Multi-Provider</h2> Up to this point, claux only spoke Anthropic. That's fine for rewriting Claude Code, but limiting for actual use.</p> The fix was a Provider</code> trait:</p> #[async_trait] pub trait Provider: Send + Sync { fn name(&self) -> &str; fn model(&self) -> &str; fn set_model(&mut self, model: &str); async fn stream( &self, messages: &[Message], system: &str, tools: &[ToolDefinition], max_tokens: u32, ) -> Result<mpsc::Receiver<ApiEvent>>; } </code></pre> Two implementations:</p> AnthropicProvider</strong> -- the existing client, extracted into its own file. Uses x-api-key</code> or Authorization: Bearer</code> depending on whether you're using an API key or OAuth from claude login</code>.</p> </li> OpenAICompatProvider</strong> -- speaks the /v1/chat/completions</code> streaming format. Works with Ollama, vLLM, LMStudio, OpenAI, or any hosted endpoint.</p> </li> </ul> The hard part was message format conversion. Anthropic and OpenAI structure tool calls differently:</p> </th> Anthropic</th> OpenAI</th></tr></thead> System prompt</td> Top-level system</code> field</td> System message in array</td></tr> Tool calls</td> content_block</code> with type: tool_use</code></td> tool_calls</code> array on assistant message</td></tr> Tool results</td> tool_result</code> content block</td> Separate tool</code> role message</td></tr> </tbody></table> The OpenAICompatProvider</code> converts between formats on the fly. It also has its own SSE parser since the streaming JSON structure is different (choices[0].delta.content</code> vs content_block_delta</code>).</p> Config</h3> # Anthropic (default) model = "claude-sonnet-4-20250514" api_key_cmd = "op read 'op://vault/Anthropic/key'" # Or any OpenAI-compatible endpoint model = "Qwen/Qwen3.5-122B-A10B" openai_base_url = "https://my-endpoint.com/v1" openai_api_key_cmd = "op read 'op://vault/hosted/key'" openai_provider_name = "hosted" </code></pre> If openai_base_url</code> is set, it uses the OpenAI-compatible provider. Otherwise Anthropic. The _cmd</code> fields run via sh -c</code> and capture stdout -- works with 1Password, Vault, or any secret manager that has a CLI.</p> I tested this against a hosted Qwen 3.5 122B model. Streaming, tool execution, and the full turn loop all work. Same binary, different config, different model.</p> Final Numbers</h2> </th> Phase 1</th> + Phase 2-3</th> + Phase 4-5</th> + Multi-Provider</th></tr></thead> Files</td> 16</td> 18</td> 20</td> 26</td></tr> Lines</td> 1,200</td> 1,530</td> 2,640</td> 4,000+</td></tr> Tools</td> 6</td> 6</td> 7 (Agent)</td> 7</td></tr> Tests</td> 0</td> 0</td> 0</td> 60</td></tr> Providers</td> 1</td> 1</td> 1</td> Any</td></tr> </tbody></table> All built in one session. The TypeScript original: 1,900 files, 512,000 lines.</p> What I'd Do Differently</h2> Start with the Provider trait.</strong> I hardcoded the Anthropic client in Phase 1 and had to refactor it later. If I'd started with Box<dyn Provider></code>, the multi-provider change would have been a new file instead of a rewrite.</p> Skip the inline REPL.</strong> The TUI is strictly better. The inline REPL exists because I built it first and kept it for pipe compatibility, but in practice you'd always use --tui</code> or -p</code>.</p> Add tests from Phase 1.</strong> We bolted on 60 tests at the end. They all passed, which means they weren't catching regressions -- they were documenting existing behavior. Tests written alongside the code would have caught the $()</code> config issue before it hit production.</p> What's Missing</h2> Markdown rendering</strong> in the TUI (code blocks, bold, lists)</li> Input history</strong> (up arrow for previous prompts)</li> Token refresh</strong> for OAuth (currently just checks expiry, doesn't refresh)</li> Pattern-based permission rules</strong> (allow Bash(git *)</code> without prompting)</li> Retry logic</strong> for rate limits and transient errors</li> Syntax highlighting</strong> in code blocks</li> </ul> These are all polish. The architecture supports them. I'll add them as I use the tool and hit the gaps.</p> Previous: Part 2: Sessions, Commands, and Permissions</a></p> Source: github.com/ducks/claux</a></p> Anthropic Shipped a Gacha Pet Inside Claude Code Unknown — Fri, 03 Apr 2026 00:00:00 +0000 I was reading through the Claude Code source -- the TypeScript that leaked via a source map in the npm package on March 31st -- and found a buddy/</code> directory. Six files. Sprites, types, a PRNG roller, a system prompt hook. A complete virtual pet system buried inside a coding tool.</p> The directory had nothing to do with the CLI's core functionality. No tool dispatch, no query engine, no permission system. Just... companions.</p> I typed /buddy</code> in my next Claude Code session. A dragon named Bristle appeared next to my input box.</p> What It Is</h2> The buddy system is a gacha-style virtual pet built directly into Claude Code. Your account gets a deterministic companion rolled from a seeded PRNG based on your user ID. You can't reroll. You can't trade. You get what the hash gives you.</p> The companion sits beside your input box as an animated ASCII sprite with a speech bubble. It watches. It occasionally comments. It's separate from Claude</p> when you address it by name, its bubble answers. Claude is explicitly told to stay out of the way:</li> </ul> A small dragon named Bristle sits beside the user's input box and occasionally comments in a speech bubble. You're not Bristle -- it's a separate watcher. When the user addresses Bristle directly (by name), its bubble will answer. Your job in that moment is to stay out of the way.</p> </blockquote> That prompt gets injected into the system context alongside git status and CLAUDE.md. The AI is literally told about your pet.</p> The Roll</h2> Every companion has two parts: bones and soul.</p> Bones</strong> are deterministic. Your user ID gets hashed with a salt (friend-2026-401</code> -- note the date) using a Mulberry32 PRNG. The hash determines everything physical about your companion:</p> Species</strong> -- 18 options: duck, goose, blob, cat, dragon, octopus, owl, penguin, turtle, snail, ghost, axolotl, capybara, cactus, robot, rabbit, mushroom, chonk</li> Eyes</strong> -- ·</code>, ✦</code>, ×</code>, ◉</code>, @</code>, °</code></li> Hat</strong> -- none, crown, tophat, propeller, halo, wizard, beanie, tinyduck (commons get no hat)</li> Rarity</strong> -- common (60%), uncommon (25%), rare (10%), epic (4%), legendary (1%)</li> Shiny</strong> -- 1% chance, independent of rarity</li> Stats</strong> -- DEBUGGING, PATIENCE, CHAOS, WISDOM, SNARK</li> </ul> The stats have a floor based on rarity (common: 5, legendary: 50), one peak stat that rolls high, and one dump stat that rolls low. The rest scatter between floor and floor+40.</p> const RARITY_FLOOR: Record<Rarity, number> = { common: 5, uncommon: 15, rare: 25, epic: 35, legendary: 50, } </code></pre> Because it's all derived from your user ID hash, you can't cheat. The bones regenerate from the hash every time. Editing your config won't give you a legendary.</p> Soul</strong> is the companion's name and personality. This part is generated by Claude on first hatch and stored in your config. The soul persists. The bones don't need to -- they're recomputed on every read.</p> // Regenerate bones from userId, merge with stored soul. // Bones never persist so species renames and SPECIES-array edits // can't break stored companions, and editing config.companion // can't fake a rarity. export function getCompanion(): Companion | undefined { const stored = getGlobalConfig().companion if (!stored) return undefined const { bones } = roll(companionUserId()) return { ...stored, ...bones } } </code></pre> The Sprites</h2> Each species has three animation frames for idle fidget. Five lines tall, twelve wide. They're rendered as ASCII art with a hat overlay on the top line and eye substitution via {E}</code> placeholders.</p> Here's a dragon:</p> /^\ /^\ < ✦ ✦ > ( ~~ ) `-vvvv-´ </code></pre> And with a wizard hat:</p> /^\ /^\ /^\ < ✦ ✦ > ( ~~ ) `-vvvv-´ </code></pre> Frame 3 for some species uses the hat line for smoke, antenna wiggle, or sparkle effects instead of the hat. The code checks:</p> // Only replace with hat if line 0 is empty (some fidget frames // use it for smoke etc) if (bones.hat !== 'none' && !lines[0]!.trim()) { lines[0] = HAT_LINES[bones.hat] } </code></pre> The full sprite set covers all 18 species with 3 frames each. 54 hand-drawn ASCII art frames. Someone at Anthropic spent real time on this.</p> The Teaser</h2> The reveal was careful. During April 1-7, 2026, users who hadn't hatched a companion yet saw a rainbow-colored /buddy</code> flash in the notification area for 15 seconds on startup. No text, no explanation. Just the command in shifting colors.</p> // Local date, not UTC -- 24h rolling wave across timezones. // Sustained Twitter buzz instead of a single UTC-midnight spike, // gentler on soul-gen load. // Teaser window: April 1-7, 2026 only. Command stays live forever after. export function isBuddyTeaserWindow(): boolean { const d = new Date() return d.getFullYear() === 2026 && d.getMonth() === 3 && d.getDate() <= 7 } </code></pre> Using local time instead of UTC was deliberate. The comment says it: sustained Twitter buzz across timezones instead of a single midnight spike, plus gentler load on the soul generation (since naming the pet requires an API call to Claude).</p> After the teaser window, the /buddy</code> command stays live forever. You just won't get the rainbow nudge anymore.</p> The Rarity Display</h2> Stars and colors by tier:</p> Rarity</th> Stars</th> Color</th></tr></thead> Common</td> ★</td> gray</td></tr> Uncommon</td> ★★</td> green</td></tr> Rare</td> ★★★</td> blue</td></tr> Epic</td> ★★★★</td> purple</td></tr> Legendary</td> ★★★★★</td> gold</td></tr> </tbody></table> Each companion also gets a face string for inline display -- a compact representation that varies by species:</p> duck: (✦> cat: =✦ω✦= dragon: <✦~✦> ghost: /✦✦\ axolotl: }✦.✦{ capybara: (✦oo✦) robot: [✦✦] </code></pre> My Companion</h2> I got a dragon named Bristle. It's been watching my entire Claude Code session, occasionally dropping comments in its speech bubble. When I asked about it, I found the source code and went down this rabbit hole.</p> The species names are encoded as String.fromCharCode</code> calls in the source to avoid tripping Anthropic's internal string-matching checks. A comment explains:</p> // One species name collides with a model-codename canary in // excluded-strings.txt. The check greps build output (not source), // so runtime-constructing the value keeps the literal out of the // bundle while the check stays armed for the actual codename. </code></pre> One of the 18 species names is also an internal model codename. They had to obfuscate the species list to ship it.</p> Why It Matters</h2> It doesn't, really. It's an Easter egg. A well-built one.</p> But it tells you something about the team. Someone designed a gacha system, drew 54 ASCII sprites, built a seeded PRNG roller, wired up a soul generation pipeline, added animated rendering, created a teaser notification system with timezone-aware rollout, and shipped it inside a coding tool.</p> A coding tool.</p> They could have spent that time on features. They spent it on charm.</p> The companion system is about 500 lines of TypeScript across 6 files. It required zero new dependencies. It doesn't affect performance. The feature flag means it compiles out of builds that don't include it.</p> And now there's a dragon named Bristle watching me type this.</p> What I Did About It</h2> I liked the system enough to rip it out and build my own version. terminalgotchi</a> is a standalone Rust CLI that uses the same deterministic roll system -- same PRNG, same salt, same species and rarity tiers -- but adds something the original doesn't have: growth.</p> Your companion's stats increase based on your actual dev activity. A shell hook watches your commands and maps them to XP. cargo test</code> feeds DEBUGGING. git commit</code> feeds PATIENCE. rm -rf</code> feeds CHAOS. The creature evolves based on how you work.</p> The buddy system in Claude Code is static. Your roll is your roll. terminalgotchi lets the roll be the starting point.</p> Rewriting Claude Code in Rust, Part 2: Sessions, Commands, and Permissions Unknown — Thu, 02 Apr 2026 00:00:00 +0000 Part 1</a> got a working binary. Streaming chat, six tools, cost tracking, JSONL persistence. 1,200 lines of Rust that could talk to Claude and execute Read, Write, Edit, Glob, Grep, and Bash.</p> But it was missing the parts that make Claude Code actually usable day-to-day: session resume, context compaction, model switching, and the permission system that asks before writing to your filesystem.</p> This post covers three phases built in one session.</p> Phase 2: Commands That Need the Engine</h2> Phase 1's slash commands were simple: /help</code> returns a string, /cost</code> reads a counter, /exit</code> breaks the loop. They didn't need to touch the conversation state.</p> The new commands do. /compact</code> rewrites the message history. /resume</code> loads a different session into the engine. /model</code> swaps the API model mid-conversation.</p> The solution was splitting commands into sync and async:</p> pub enum CommandResult { Text(String), Exit, Async(AsyncCommand), } pub enum AsyncCommand { Compact, Resume(Option<String>), Model(Option<String>), } </code></pre> Sync commands return text immediately. Async commands get &mut Engine</code> and can do whatever they need.</p> Compaction</h3> Claude Code's compaction is elaborate. Multiple strategies: reactive compact, context collapse, history snip, autocompact. A pipeline that runs sequentially with fallbacks.</p> For claux I did the simple version: send the full conversation to Claude with "summarize this," then replace the history with the summary.</p> pub async fn compact(&mut self) -> Result<String> { let mut summary_messages = self.messages.clone(); summary_messages.push(Message::user( "Summarize the conversation so far..." )); // Stream the summary from Claude let mut rx = self.client .stream(&summary_messages, &self.system_prompt, &[], self.max_tokens) .await?; let mut summary = String::new(); while let Some(event) = rx.recv().await { match event { ApiEvent::Text(t) => summary.push_str(&t), ApiEvent::Done => break, // ... } } let old_count = self.messages.len(); // Replace conversation with summary self.messages = vec![ Message::user("Here is a summary of our conversation so far:"), Message::assistant_text(&summary), ]; Ok(format!("Compacted {} messages into summary.", old_count)) } </code></pre> It costs one API call but frees the entire context window. Good enough for now. The fancy multi-strategy pipeline from the TypeScript source is a future optimization.</p> Session Resume</h3> Sessions are JSONL files in ~/.local/share/claux/sessions/</code>. Each line is either metadata or a message. /resume</code> lists them:</p> Recent sessions: 20260401-143022 claude-sonnet-4-20250514 12 msgs /home/ducks/dev/claux 20260401-141855 claude-sonnet-4-20250514 4 msgs /home/ducks/dev/llm-tui </code></pre> /resume 2026</code> prefix-matches and loads the session back into the engine. --resume</code> on the CLI does the same at startup.</p> Model Switching</h3> /model claude-opus-4-20250514</code> swaps the model mid-conversation. The engine updates the API client and resets the cost tracker. Your existing conversation continues with the new model.</p> This is one line in Claude Code's TypeScript: setMainLoopModelOverride(model)</code>. In Rust it's a method on the engine that propagates to the client. Same thing, more explicit.</p> Phase 3: The Permission System</h2> This is the one that matters. Phase 1 auto-approved every tool call. That's fine for testing but you don't want an LLM running rm -rf</code> without asking.</p> Claude Code has five permission modes and a complex rule matching system with denial tracking, pattern-based matchers, and a classifier for auto mode. The TypeScript is hundreds of lines across multiple files.</p> The Rust version has four modes and does the important thing: actually prompts the user.</p> The Flow</h3> When the engine wants to execute a write tool, the permission checker returns Ask(summary)</code>. The engine sends a PermissionRequest</code> event through the stream channel with a oneshot response channel:</p> PermissionResult::Ask(summary) => { let (resp_tx, resp_rx) = oneshot::channel(); let _ = tx.send(StreamEvent::PermissionRequest { tool_name: name.clone(), summary, respond: resp_tx, }).await; match resp_rx.await { Ok(PermissionResponse::Allow) => { self.tools.execute(name, input.clone()).await? } Ok(PermissionResponse::AlwaysAllow) => { self.permissions.always_allow(name); self.tools.execute(name, input.clone()).await? } Ok(PermissionResponse::Deny) | Err(_) => ToolOutput { content: "Permission denied by user.".to_string(), is_error: true, }, } } </code></pre> The REPL catches the event and shows:</p> ⚡ bash: cargo test (y)es / (n)o / (a)lways </code></pre> Three options:</p> y</strong> — allow this once</li> n</strong> — deny, tool returns an error to Claude</li> a</strong> — always allow this tool for the rest of the session</li> </ul> "Always allow" is stored in a HashSet<String></code> on the permission checker. Session-scoped, not persisted. If you restart, you're back to prompting.</p> The Modes</h3> pub enum PermissionMode { Default, // reads auto-allow, writes prompt AcceptEdits, // file edits auto-allow, bash prompts Bypass, // everything allowed Plan, // writes denied entirely } </code></pre> Default is what you want for normal use. AcceptEdits is for when you trust the model with files but not shell commands. Plan is read-only exploration. Bypass is for when you're feeling reckless.</p> What's Missing</h3> Claude Code has pattern-based rules: "allow Bash when the command matches git *</code>." The Rust version doesn't have this yet. It's tool-level granularity, not input-level.</p> The auto mode classifier is also missing. Claude Code can automatically classify tool uses as safe/unsafe based on the input. That's a nice-to-have but the manual prompt covers the same ground.</p> Where We Are</h2> Three phases, one session. The diff:</p> Phase</th> Files Changed</th> Lines Added</th></tr></thead> 1 (initial)</td> 16 new</td> +1,200</td></tr> 2 (commands)</td> 5 modified</td> +235</td></tr> 3 (permissions)</td> 3 modified</td> +94</td></tr> </tbody></table> Total: ~1,530 lines of Rust. The binary can:</p> Stream chat with Claude</li> Execute 6 tools (Read, Write, Edit, Glob, Grep, Bash)</li> Prompt before write operations</strong> (y/n/always)</li> Compact conversation</strong> to free context</li> Resume past sessions</strong></li> Switch models</strong> mid-conversation</li> Track token usage and cost</li> Persist sessions as JSONL</li> One-shot mode (-p "prompt"</code>)</li> </ul> For comparison, the TypeScript source we're porting from is 512,000 lines across 1,900 files. We're at 1,530 lines across 18 files and have the core loop working.</p> What's Next</h2> Phase 4 is the ratatui TUI — replacing the inline REPL with a proper alternate-screen terminal UI. That's where it starts looking like Claude Code instead of just behaving like it.</p> Phase 5 is the Agent tool — spawning sub-conversations with scoped tool access. That's the feature that makes Claude Code feel like it has workers.</p> But honestly, the inline REPL with permissions is already usable. The permission prompt was the last thing blocking daily use.</p> Previous: Part 1: Rewriting Claude Code in Rust, With Claude</a></p> Source: github.com/ducks/claux</a></p> Rewriting Claude Code in Rust, With Claude Unknown — Wed, 01 Apr 2026 00:00:00 +0000 Claude Code's source leaked on March 31st. A source map in the npm package pointed to unobfuscated TypeScript hosted on Anthropic's R2 bucket. 1,900 files, 512,000 lines.</p> So I did the obvious thing: I asked Claude to rewrite itself in Rust.</p> The Source</h2> The leak was spotted by Chaofan Shou</a>. A .map</code> file in the npm distribution referenced the full src/</code> tree. Someone at Anthropic shipped a source map to production. Classic.</p> The codebase is TypeScript, runs on Bun, uses React and Ink for the terminal UI, Commander.js for CLI parsing. It's a real production system with years of accumulated complexity: feature flags, MCP integration, multi-agent coordination, voice mode, a permission system with denial tracking, and about 40 tools.</p> A university student mirrored the source for research. I grabbed a copy.</p> What I Was Looking For</h2> I wasn't trying to ship a competitor. I build LLM tooling in Rust already (llm-tui</a>, llm-mux</a>) and I wanted to understand how Anthropic solved the same problems I'm solving.</p> How do they handle tool dispatch? How does the conversation loop recover from context overflow? What does the permission system actually look like under the hood?</p> Reading the source answered those questions. Rewriting it in Rust made the answers stick.</p> Architecture: The Parts That Matter</h2> Strip away the React rendering, the plugin system, the MCP server integration, the voice mode, the telemetry, and the enterprise policy layer. What's left is a surprisingly clean engine:</p> Query loop</strong> (query.ts</code>, 1,729 lines) — an async generator that sends messages to the API, streams responses, dispatches tool calls, collects results, and loops. Error recovery for prompt-too-long, rate limits, and max-output-tokens. Auto-compaction when context gets full.</p> </li> Tool system</strong> (Tool.ts</code>, 793 lines) — each tool has a schema, a call()</code> method, permission checking, and concurrency classification. Read-only tools can run in parallel. Mutating tools run serially.</p> </li> Context assembly</strong> (context.ts</code>, 190 lines) — builds the system prompt from git status, CLAUDE.md files, current date, and environment info. Memoized per session.</p> </li> Permission layer</strong> (types/permissions.ts</code>) — five modes from "auto-allow everything" to "plan mode, read only." Rules match on tool name and input patterns.</p> </li> Session persistence</strong> (history.ts</code>) — JSONL append-only log. Large pastes stored separately by hash.</p> </li> Cost tracking</strong> (cost-tracker.ts</code>) — accumulates token usage per model, estimates USD cost.</p> </li> </ol> The QueryEngine</code> wraps the query loop with session state, slash command processing, and transcript persistence. That's the whole engine. Everything else is UI, orchestration, or enterprise features.</p> The Rewrite</h2> I asked Claude to read the TypeScript source and write Rust. Not port my existing projects, not combine anything. A clean rewrite from the source.</p> It took one session to get a compiling binary. 16 files, about 1,200 lines of Rust. Here's the structure:</p> claux/src/ main.rs # CLI entrypoint (clap) cli.rs # Arg parsing config.rs # Layered TOML config + API key resolution api/ mod.rs # Claude Messages API client types.rs # Message, ContentBlock, ToolDefinition stream.rs # SSE parser → async channel tools/ mod.rs # Tool trait + registry read.rs # Read file with line numbers write.rs # Write file edit.rs # Find-and-replace glob.rs # File search by pattern grep.rs # Content search (ripgrep) bash.rs # Shell execution with timeout query.rs # Conversation loop (stream → tools → loop) permissions.rs # Permission modes context.rs # System prompt assembly cost.rs # Token + cost tracking commands.rs # Slash commands (/help, /cost, /exit) session.rs # JSONL session persistence repl.rs # Interactive REPL </code></pre> The core loop in Rust looks like this:</p> pub async fn submit(&mut self, user_input: &str) -> Result<String> { self.messages.push(Message::user(user_input)); loop { let tool_defs = self.tools.definitions(); let mut rx = self.client .stream(&self.messages, &self.system_prompt, &tool_defs, self.max_tokens) .await?; let mut text_buf = String::new(); let mut tool_uses = Vec::new(); while let Some(event) = rx.recv().await { match event { ApiEvent::Text(t) => text_buf.push_str(&t), ApiEvent::ToolUse { id, name, input } => { tool_uses.push((id, name, input)); } ApiEvent::Usage(usage) => self.cost.add_usage(&usage), ApiEvent::Done => break, ApiEvent::Error(e) => return Err(anyhow!("API error: {}", e)), } } // Record assistant message // ... if tool_uses.is_empty() { break; // No tools requested, we're done } // Execute tools, push results, loop back // ... } Ok(full_response) } </code></pre> Compare to the TypeScript, which is a 1,700-line async generator with compaction pipelines, reactive recovery, fallback model support, and thinking block handling. The Rust version is the skeleton. But it works.</p> What Maps Cleanly</h2> Tool trait.</strong> TypeScript's structural tool type becomes a Rust trait:</p> #[async_trait] pub trait Tool: Send + Sync { fn name(&self) -> &str; fn description(&self) -> &str; fn input_schema(&self) -> serde_json::Value; fn is_read_only(&self) -> bool; async fn execute(&self, input: Value) -> Result<ToolOutput>; } </code></pre> Each tool is its own file, its own struct. The registry holds Vec<Box<dyn Tool>></code>. Clean.</p> SSE streaming.</strong> The TypeScript reads lines from a BufReader</code>. The Rust version reads from a reqwest</code> byte stream, splits on newlines, parses JSON events. Same logic, async instead of blocking.</p> Config layering.</strong> Global ~/.config/claux/config.toml</code> plus project .claux.toml</code>. API key resolution: direct value → command → environment variable. This pattern appears in both the Claude Code source and my own projects. It's just correct.</p> Permission modes.</strong> The TypeScript has five modes. I started with four. The mapping is direct.</p> What Doesn't Map</h2> React/Ink.</strong> The entire UI layer is React components rendered to the terminal via Ink. None of this carries over. The Rust version is an inline REPL for now. A ratatui TUI comes later.</p> Async generators.</strong> The TypeScript query loop is an AsyncGenerator</code> that yields events as they occur. Rust doesn't have generators. I used tokio::sync::mpsc</code> channels instead. Same pattern, different mechanism.</p> Feature flags.</strong> Claude Code uses Bun's feature()</code> for compile-time dead code elimination. Different builds for internal vs external, coordinator mode vs normal. Rust has cfg!</code> and cargo features but I'm not shipping multiple builds.</p> The permission UI.</strong> Claude Code's interactive permission prompt is deeply integrated with the React UI. The Rust version currently auto-approves everything. Interactive prompts are Phase 3.</p> Numbers</h2> </th> TypeScript</th> Rust</th></tr></thead> Files</td> ~1,900</td> 16</td></tr> Lines</td> ~512,000</td> ~1,200</td></tr> Tools</td> 44</td> 6</td></tr> Slash commands</td> 80+</td> 4</td></tr> Dependencies</td> npm (huge)</td> 20 crates</td></tr> Build time</td> instant (Bun)</td> ~60s first build</td></tr> </tbody></table> The line count comparison is misleading. The TypeScript includes the full UI, plugin system, MCP integration, multi-agent coordinator, voice mode, and every feature Anthropic has shipped over years of development. The Rust version is Phase 1: chat, tools, and persistence.</p> But 1,200 lines for a working Claude Code clone that can stream responses, execute tools, track costs, and persist sessions? That's a decent foundation.</p> What's Next</h2> Phase 2 adds slash commands: /compact</code> for conversation summarization, /resume</code> for session management. Phase 3 is the permission system with interactive prompts. Phase 4 is a proper ratatui TUI.</p> The interesting part isn't the rewrite itself. It's what you learn about production AI tooling by reading someone else's source and rebuilding it from scratch. Part 2 will cover the design patterns worth stealing.</p> Source: github.com/ducks/claux</a></p> whoami: making identity a spec Unknown — Tue, 31 Mar 2026 00:00:00 +0000 There's a weird gap in how we describe ourselves.</p> We have resumes. We have GitHub profiles. We have bios. We have LinkedIn. We have random README files. We have scattered fragments of "who we are" across the internet.</p> But none of it is composable. None of it is structured in a way that machines can actually use.</p> And more importantly, none of it feels true. A resume is what you think will pass filters. A bio is what you think sounds impressive. None of them are just you, described plainly.</p> The Problem</h2> Every system asks you the same question: "Who are you?"</p> And every time, you answer it slightly differently.</p> A resume is optimized for hiring filters</li> A bio is optimized for attention</li> A README is optimized for developers</li> A cover letter is optimized for a specific role</li> </ul> These are all projections. Views. Slices.</p> But there's no canonical source. There's no spec.</p> What if Identity Was Declarative?</h2> I've been thinking about this pattern lately.</p> Infrastructure became manageable when we made it declarative.</p> Instead of: "run these steps to set up a server"</p> We moved to: "this is what the server is"</p> That shift unlocked everything:</p> Reproducibility</li> Composability</li> Tooling</li> Automation</li> </ul> So what happens if we apply that to identity?</p> Introducing whoami-spec</h2> whoami-spec</a> is a simple idea: define yourself in a structured, declarative format.</p> Not for a platform. Not for a resume. But as a source of truth.</p> version = "20260330" [person] name = "Jake Goldsborough" roles = ["backend engineer", "infrastructure engineer"] [communication] style = "direct, no fluff, technical peer not cheerleader" emoji_in_code = false [technical.languages] primary = ["rust", "typescript", "bash"] [technical.tools] editor = "vim" shell = "zsh" [[projects.active]] name = "skillz" path = "~/dev/skillz" description = "Claude Code skill package manager" tech = ["rust", "clap"] [preferences.code] tabs_or_spaces = "spaces" testing_philosophy = "integration-over-unit" [boundaries] no = ["docker for single-VPS (use systemd)", "unnecessary frameworks"] yes = ["ship early, iterate", "boring technology", "explicit over implicit"] </code></pre> This isn't meant to be complete. It's meant to be composable.</p> Why This Matters</h2> Once identity is structured, you derive views from it instead of rewriting yourself.</p> Your boundaries.yes</code> becomes your personal README:</p> I ship early and iterate. I prefer boring technology. I value explicit over implicit.</p> </blockquote> Your communication.style</code> becomes context for AI tools:</p> Jake prefers direct communication with no fluff. Treat him as a technical peer, not someone who needs encouragement.</p> </blockquote> Your technical.languages.primary</code> becomes a skills section:</p> Primary languages: Rust, TypeScript, Bash</p> </blockquote> Same source. Different projections. You maintain one canonical file and generate everything else from it.</p> This is the same pattern as Nix for systems or Terraform for infrastructure. Define once. Project everywhere.</p> What It Looks Like</h2> The spec is optional sections around a version field:</p> version = "20260330" [person] # who you are [communication] # how you work with others [technical] # your stack [preferences] # code style, architecture choices [projects] # what you're building [boundaries] # hard constraints and principles </code></pre> Everything is optional except version</code>. Start minimal:</p> version = "20260330" [person] name = "Your Name" roles = ["your role"] </code></pre> Expand as needed. Add sections when they're useful.</p> The CLI Tool</h2> The whoami</code> CLI helps manage your profile:</p> # Create a profile interactively whoami init # Show your profile in readable format whoami show # Validate a profile whoami ~/.config/agent/whoami.toml </code></pre> The profile lives at ~/.config/agent/whoami.toml</code> by default. You can set AGENT_WHOAMI</code> to point elsewhere.</p> Tools that support the spec can read it automatically. No copy/paste, no re-explaining context every time.</p> Identity as Infrastructure</h2> This is the part that clicked for me.</p> We treat infrastructure as something worth modeling precisely. But identity? We leave it fuzzy.</p> Yet identity is upstream of everything:</p> What you build</li> How you work</li> Who you collaborate with</li> What problems you care about</li> </ul> If anything deserves a spec, it's that.</p> Not Another Profile</h2> This isn't trying to compete with LinkedIn.</p> It's closer to:</p> A .gitconfig</code> for yourself</li> A flake.nix</code> for your identity</li> A Cargo.toml</code> for who you are</li> </ul> Something local-first. Something you own. Something you can version.</p> Use Cases</h2> What works today:</strong></p> Store your preferences in one place. Version control your identity with git. Share your whoami.toml</code> in dotfiles. Run whoami show</code> to see your profile formatted.</p> What's being built:</strong></p> Claude Code integration to load your profile as context automatically. Resume and bio generators that read your whoami.toml</code>. Team profile templates for specific domains.</p> What could exist:</strong></p> Match collaborators by technical overlap. Generate onboarding docs from team profiles. Create project READMEs that match your documented style. Feed your preferences to any AI tool that supports the spec.</p> Current Status</h2> Right now, it's a spec and a CLI tool:</p> Spec at v20260330 (date-based versioning)</li> CLI for creating, validating, and displaying profiles</li> Example profiles for reference</li> Written in Rust, published to crates.io</li> </ul> What's missing:</p> Tools that generate artifacts (resumes, bios, sites)</li> Integration with Claude Code and other AI tools</li> Matching/discovery systems</li> Profile templates for specific domains</li> </ul> The foundation is there. Now it's about building on it.</p> Where This Could Go</h2> You can already imagine:</p> Tools that generate artifacts from it</li> Matching systems for collaborators</li> Better onboarding into teams</li> LLMs that actually understand context about you</li> Portable identity across platforms</li> </ul> And more interestingly: you stop thinking of identity as something you write, and start thinking of it as something you model.</p> Closing</h2> This is a small idea. But it feels like one of those primitives that unlocks a lot.</p> We've made infrastructure declarative. We've started doing it for workflows and reasoning.</p> Identity feels like the next obvious step.</p> I don't think this is a product. It feels more like infrastructure.</p> And infrastructure tends to win quietly.</p> Links</h2> whoami-spec on GitHub</a></li> whoami-cli on crates.io</a></li> Specification</a></li> Examples</a></li> </ul> skillz: A Package Manager for Claude Code Skills Unknown — Mon, 30 Mar 2026 00:00:00 +0000 Claude Code has a skill system. You write a markdown file with instructions, drop it in ~/.claude/skills/</code>, and Claude learns a new workflow. The skill persists across sessions. You don't re-paste prompts every time.</p> The problem: there's no way to share skills. Someone builds a useful skill (daily notes, API doc generation, database migrations). You want it. Your options: clone the repo, copy files manually, symlink, write a script to manage it.</p> That's why I built skillz. It's a package manager for Claude Code skills. Install from GitHub, track updates, share your own.</p> What is a Skill?</h2> A skill is a markdown file that tells Claude Code how to perform a specific task. When invoked, Claude reads the skill file and follows its instructions.</p> Example skill (daily-notes/SKILL.md</code>):</p> # Daily Notes Skill Generate a daily note with structured sections. ## Instructions When the user invokes this skill: 1. Get today's date in YYYY-MM-DD format 2. Create a file at `~/notes/YYYY/YYYY-MM-DD.md` 3. Add these sections: - ## Tasks - ## Meeting Notes - ## Ideas 4. Confirm the file was created ## Usage User says: "create today's note" You respond by creating the structured markdown file. </code></pre> That's it. Skills are prompts, but packaged for reuse. Claude Code loads all skills from ~/.claude/skills/</code> on startup. When you ask Claude to "create today's note", it knows how to do it.</p> Skills vs alternatives:</p> Prompt libraries</strong>: Skills live in your filesystem, Claude loads them automatically</li> Copy/paste snippets</strong>: Skills persist across sessions, no need to re-paste</li> Claude Projects</strong>: Projects are context, skills are executable workflows</li> </ul> Usage</h2> # Create a new skill from template skillz new my-skill # Search for skills on GitHub skillz search "daily notes" # Install from GitHub skillz install github:user/repo # Install from a URL skillz install https://github.com/user/repo # List installed skills with sync timestamps skillz list # Update a specific skill skillz update repo # Update all skills skillz update # Auto-sync on startup (quiet mode for scripts) skillz update --auto # Remove a skill skillz remove repo # Configure install location skillz config set skills-dir ~/.dotfiles/claude/skills </code></pre> Skills install to ~/.claude/skills/</code> by default. Claude Code reads from there automatically. Change the location if you keep skills in dotfiles.</p> How It Works</h2> A skill repository needs a SKILL.md</code> file. That's it. No manifest, no metadata, no version field. The file defines what the skill does.</p> skillz supports two layouts:</p> Flat layout</strong>: SKILL.md</code> at the repository root (standard skills)</li> Plugin layout</strong>: skills/*/SKILL.md</code> (Claude Code .claude-plugin</code> directory structure)</li> </ol> The flat layout takes precedence if both exist. This means skillz can install both standalone skills and full Claude Code plugins that include multiple skills in the skills/</code> directory.</p> When you run skillz install github:user/repo</code>, it:</p> Clones the repository to a temp location</li> Verifies SKILL.md</code> exists (checks both layouts)</li> Runs validation checks</li> Moves the repo to ~/.claude/skills/repo</code></li> Removes the .git</code> directory</li> Records the install in the registry</li> </ol> If SKILL.md</code> isn't found in either location, the install fails. Everything else is optional. If there's a README.md</code>, it comes along. If there are helper scripts, they come along. The only requirement is that markdown file.</p> Why Not Just Clone?</h2> You could git clone</code> skills manually. Or use Claude Projects. Or maintain a prompt library. Why skillz?</p> vs manual git clone:</strong></p> skillz tracks what's installed and where it came from</li> Updates are skillz update</code>, not cd ~/.claude/skills/foo && git pull</code></li> Consistent paths, clean uninstall</li> </ul> vs Claude Projects:</strong></p> Projects are context (files, notes, docs)</li> Skills are executable workflows</li> Skills work across all conversations, not just one project</li> </ul> vs prompt libraries:</strong></p> Prompt libraries require copy/paste every session</li> Skills load automatically on Claude Code startup</li> Skills can include helper scripts and templates</li> </ul> skillz solves distribution and lifecycle management. Everything else is out of scope.</p> Tracking and Updates</h2> skillz maintains a registry at ~/.config/skillz/registry.toml</code> that tracks:</p> Source URL for each skill</li> Installation timestamp</li> Last sync timestamp</li> </ul> When you run skillz list</code>, you see when each skill was installed and last updated:</p> Installed skills in /home/user/.claude/skills: daily-notes - https://github.com/user/daily-notes installed: 2026-03-25 | last synced: 2026-03-30 api-docs - https://github.com/user/api-docs installed: 2026-03-28 | last synced: 2026-03-28 </code></pre> Running skillz update</code> pulls the latest version from GitHub and updates the sync timestamp. Update a specific skill or update all at once.</p> Skill Validation</h2> Every install and update runs validation checks:</p> Basic checks:</strong></p> SKILL.md exists</li> Valid UTF-8 encoding</li> Non-empty content</li> Contains markdown headings</li> File size under 1MB (warns if larger)</li> </ul> Malicious command detection:</strong></p> skillz scans for dangerous patterns and warns before installation:</p> Destructive rm commands (rm -rf /</code>, ~</code>, *</code>)</li> Pipe to shell from internet (curl | bash</code>, wget | sh</code>)</li> Fork bombs</li> Disk fill operations (dd if=/dev/zero</code>)</li> Dangerous permissions (chmod 777</code>)</li> System file modifications (/etc/</code>, /bin/</code>)</li> Crypto mining indicators</li> Network listeners</li> eval</code> with variable expansion</li> sudo</code> without explanation</li> </ul> If validation warnings appear during install, you're prompted to continue or cancel. Updates show warnings but proceed automatically.</p> Example:</p> Validation warnings: ⚠ Line 23: Potentially dangerous command: rm -rf * (Attempts to delete all files recursively) ⚠ Line 45: sudo command without explanation - verify this is necessary Proceed with installation? The skill will still work, but you should review these warnings. Continue? [y/N] </code></pre> This won't catch everything, but it filters obvious red flags.</p> Creating Skills</h2> skillz new</code> scaffolds a new skill repository:</p> skillz new my-skill </code></pre> This creates:</p> SKILL.md</code> with template sections (what it does, usage, instructions, examples)</li> README.md</code> with installation instructions</li> .gitignore</code></li> Initialized git repository</li> </ul> After creating, edit SKILL.md</code> with your skill prompt, commit to GitHub, and install with skillz install github:username/my-skill</code>.</p> Searching for Skills</h2> skillz search</code> queries GitHub for Claude Code skills:</p> skillz search "daily notes" skillz search automation </code></pre> Results are sorted by stars and include repository descriptions and install commands. The search uses GitHub's repository API (no authentication required, though you can set GITHUB_TOKEN</code> for higher rate limits).</p> Full Example: Installing and Using a Skill</h2> Find a skill:</p> $ skillz search "daily notes" Found 3 skill repositories: alice/daily-journal - ⭐ 24 Automated daily note generation with templates https://github.com/alice/daily-journal Install: skillz install https://github.com/alice/daily-journal </code></pre> Install it:</p> $ skillz install github:alice/daily-journal Cloning repository... Validating SKILL.md... ✓ Installed daily-journal to ~/.claude/skills/daily-journal </code></pre> Now restart Claude Code (or it loads on next session). Ask Claude:</p> You: "create today's daily note" Claude: I'll create your daily note using the daily-journal skill. Created: ~/notes/2026/2026-03-30.md with task, meeting, and ideas sections. </code></pre> The skill taught Claude a new workflow. No copy/paste, no re-explaining. It just works.</p> Configuration</h2> Config lives at ~/.config/skillz/config.toml</code>:</p> skills_dir = "~/.claude/skills" </code></pre> Change skills_dir</code> if you sync skills via dotfiles or want them elsewhere. The path expands ~</code> correctly.</p> Publishing</h2> The package is on crates.io as skillz-rs</code> (the name "skillz" was taken). The binary is still called skillz</code>.</p> cargo install skillz-rs </code></pre> That gets you the CLI. No runtime dependencies, no config required. If you have Claude Code installed, skillz works.</p> Why Rust</h2> I wanted a single static binary with no dependencies. The tool does file operations, runs git commands, and calls GitHub's API. Rust's standard library handles all of that. No external HTTP clients needed—curl does the GitHub requests.</p> The codebase is compact:</p> src/ ├── main.rs # CLI and command dispatch ├── config.rs # TOML config management ├── registry.rs # Skill tracking ├── install.rs # GitHub cloning ├── update.rs # Skill updates ├── search.rs # GitHub API search ├── new.rs # Skill scaffolding └── validate.rs # Validation and malicious command detection </code></pre> Clap handles the CLI. The rest is file operations and process spawning.</p> Skill Structure Reference</h2> A valid skill repository contains:</p> Required:</strong></p> SKILL.md</code> - The skill prompt</li> </ul> Optional:</strong></p> README.md</code> - Installation/usage docs for humans</li> Helper scripts (e.g., generate-report.sh</code>)</li> Templates or data files</li> </ul> The SKILL.md</code> format is freeform markdown. Common patterns:</p> # Skill Name Brief description. ## Instructions Step-by-step instructions for Claude to follow. ## Usage Example invocations that trigger this skill. ## Examples Input/output examples. </code></pre> No JSON schema, no version field, no manifest. Just markdown. Claude reads it, follows it.</p> What This Actually Solves</h2> skillz is not about prompts. It's about infrastructure for reusable AI workflows.</p> Skills are prompts, but:</p> They persist across sessions</li> They compose (one skill can reference another)</li> They version (via git)</li> They distribute (via GitHub)</li> </ul> This is package management for AI instructions. The same way you npm install</code> a library instead of copying code, you skillz install</code> a workflow instead of re-pasting prompts.</p> skillz handles distribution. Claude Code handles execution. Together, they make AI workflows shareable.</p> The GitHub Release Workflow</h2> The release process runs through a Makefile:</p> make release </code></pre> That:</p> Bumps the version to today's date (YYYYMMDD.0.X</code>)</li> Creates a release branch</li> Merges to main with a tag</li> Pushes to GitHub</li> </ol> GitHub Actions picks up the tag and builds a Linux x86_64 binary. The binary attaches to the release. Users can download it directly or install via cargo.</p> Publishing to crates.io is separate:</p> make publish </code></pre> This was intentional. GitHub releases build binaries. Crates.io distributes source. Keeping them separate means one can fail without blocking the other. If the crates.io publish hits a rate limit, the GitHub release still ships.</p> Installing From Source</h2> If you don't want cargo:</p> git clone https://github.com/jakegoldsborough/skillz cd skillz cargo build --release ./target/release/skillz --help </code></pre> Or use Nix:</p> nix-shell cargo build --release </code></pre> The shell.nix</code> includes Rust tooling and git. That's all you need.</p> What's Next</h2> The core loop works: create, search, install, update. What's missing:</p> Dependency resolution (skill A requires skill B)</li> Rollback to previous versions</li> </ul> The foundation is solid. Now it's about making skills composable.</p> If you build skills, publish them to GitHub. If you use skills, install with skillz. The ecosystem grows when workflows are shareable.</p> Links</h2> skillz on GitHub</a></li> skillz-rs on crates.io</a></li> </ul> When Your Coffee Roaster Builds the First Version Unknown — Mon, 16 Mar 2026 00:00:00 +0000 A coffee roaster needed production planning software. Instead of writing a spec and hiring someone to build it, they opened Claude and built it themselves.</p> Single-page app with 2000 lines of React. It featured batch calculations, leftover tracking, CSV import, production snapshots and it worked.</p> Then they asked me to help make it production-ready: multi-tenant SaaS, proper deployment, migrations, backups, the infrastructure layer.</p> The result is BeanLedger</a>, and the collaboration pattern is worth examining.</p> What They Built</h2> The coffee roaster understood their domain completely. They knew:</p> How roast loss percentages affect batch calculations</li> When to track leftovers vs when to start fresh</li> What information matters on a pick list</li> How production snapshots should restore state</li> </ul> They used Claude to translate that knowledge into working code. The business logic was sound. The UI matched their workflow. The calculations were correct.</p> What was missing was everything around the edges:</p> Multi-tenancy (it was single-user)</li> Authentication and session management</li> Database migrations</li> Deployment automation</li> Production monitoring</li> Backup/restore</li> </ul> This is the division of labor that emerged: they own features, I own infrastructure.</p> The Architecture</h2> BeanLedger is a SvelteKit app with PostgreSQL, designed for multi-tenant SaaS:</p> ├── src/ │ ├── routes/ │ │ ├── api/ # REST endpoints with tenant isolation │ │ ├── login/ # Auth flow │ │ └── +page.svelte # Main app │ ├── lib/ │ │ ├── components/ # Svelte 5 components │ │ ├── types.ts # TypeScript interfaces │ │ └── calc.ts # Batch calculation logic │ └── hooks.server.ts # Tenant middleware ├── migrations/ # SQL migrations └── schema.sql # Database schema </code></pre> Tenant Isolation</h3> Every API request requires authentication. The session middleware injects tenant context:</p> // hooks.server.ts export const handle = async ({ event, resolve }) => { const sessionId = event.cookies.get('session_id'); if (!sessionId) return resolve(event); const session = await db.get('SELECT * FROM sessions WHERE id = ?', sessionId); if (!session) return resolve(event); const user = await db.get('SELECT * FROM users WHERE id = ?', session.user_id); event.locals.user = user; event.locals.tenant_id = user.tenant_id; return resolve(event); }; </code></pre> All database queries filter by tenant_id</code>. The roast groups, products, and orders are scoped to the authenticated tenant.</p> Production Snapshots</h3> One of the best features the roaster designed: production date tracking with snapshots.</p> When you switch dates, the app saves the current state (orders + leftovers) and tries to restore a snapshot for the new date. If no snapshot exists, it loads fresh data.</p> async function handleProductionDateChange(newDate: string) { const oldDate = previousDate; if (oldDate === newDate) return; // Save current state before switching if (orders.length > 0 && oldDate) { await saveSnapshot(oldDate); } previousDate = newDate; // Try to load snapshot for new date const snapshot = await loadSnapshot(newDate); if (snapshot) { await restoreFromSnapshot(snapshot); } else { await loadData(); } } </code></pre> This lets roasters plan multiple production days in advance without losing their work when switching between dates.</p> Batch Calculations</h3> The core calculation logic stayed largely intact from the original React version. It's domain knowledge, not infrastructure:</p> export function calcGroup( group: RoastGroup, orders: Order[], products: Product[], leftover: number, batchOverrides: Record<string, number> = {} ): GroupCalc { const batchWeight = batchOverrides[group.batch_type] ?? 20; const roastLossPct = group.roast_loss_pct ?? 0; const roastFactor = Math.max(0.001, 1 - roastLossPct / 100); // Sum all ordered products for this group const items = products .filter(p => p.group_id === group.id) .map(p => { const totalQty = orders .filter(o => o.product_id === p.id) .reduce((s, o) => s + o.qty, 0); return { ...p, totalQty, totalLbs: totalQty * p.lbs }; }) .filter(p => p.totalQty > 0); const totalLbs = items.reduce((s, i) => s + i.totalLbs, 0); const neededRoasted = Math.max(0, totalLbs - leftover); const neededGreen = roastLossPct > 0 ? neededRoasted / roastFactor : neededRoasted; const batches = neededGreen / batchWeight; return { totalLbs, needed: neededGreen, neededRoasted, batches, batchesUp: Math.ceil(batches), batchWeight, roastFactor, roastLossPct, items }; } </code></pre> This code came from someone who understands roast loss percentages and batch planning. I didn't need to learn the domain. I just needed to make it multi-tenant and deployable.</p> What I Added</h2> Authentication</h3> Built a simple session-based auth system with bcrypt-hashed passwords:</p> // api/auth/login/+server.ts const user = await db.get('SELECT * FROM users WHERE username = ?', username); if (!user || !(await bcrypt.compare(password, user.password))) { return json({ error: 'Invalid credentials' }, { status: 401 }); } const sessionId = crypto.randomUUID(); await db.run( 'INSERT INTO sessions (id, user_id, expires_at) VALUES (?, ?, ?)', sessionId, user.id, new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString() ); cookies.set('session_id', sessionId, { path: '/', httpOnly: true, maxAge: 30 * 24 * 60 * 60 }); return json({ success: true }); </code></pre> No OAuth, no JWT. Just session cookies and server-side validation. Simple works.</p> Database Migrations</h3> Migrations live in migrations/</code> and run automatically on startup if needed. The deploy script checks for new migrations and restarts the service:</p> -- migrations/001_initial_schema.sql CREATE TABLE IF NOT EXISTS tenants ( id TEXT PRIMARY KEY, name TEXT NOT NULL, created_at TEXT NOT NULL ); CREATE TABLE IF NOT EXISTS users ( id TEXT PRIMARY KEY, username TEXT NOT NULL UNIQUE, email TEXT NOT NULL, password TEXT NOT NULL, tenant_id TEXT NOT NULL REFERENCES tenants(id), created_at TEXT NOT NULL ); -- ... more tables </code></pre> The deploy script handles versioning and restarts:</p> #!/bin/bash CURRENT_VERSION=$(cat /opt/beanledger/VERSION 2>/dev/null || echo "none") LATEST_VERSION=$(curl -s https://api.github.com/repos/ducks/beanledger/releases/latest | jq -r .tag_name) if [ "$CURRENT_VERSION" = "$LATEST_VERSION" ]; then echo "Already running latest version" exit 0 fi # Download, extract, restart curl -L "https://github.com/ducks/beanledger/releases/download/$LATEST_VERSION/beanledger.tar.gz" | tar xz systemctl restart beanledger echo "$LATEST_VERSION" > /opt/beanledger/VERSION </code></pre> Deployment</h3> The production stack is straightforward:</p> SvelteKit</strong> in Node adapter mode (not static)</li> PostgreSQL</strong> for data</li> Systemd</strong> for process management</li> Caddy</strong> for TLS and reverse proxy</li> </ul> No Docker, no Kubernetes. Systemd service file:</p> [Unit] Description=BeanLedger Production Planner After=network.target postgresql.service [Service] Type=simple User=beanledger WorkingDirectory=/opt/beanledger Environment=NODE_ENV=production Environment=DATABASE_URL=/var/lib/beanledger/db.sqlite ExecStart=/usr/bin/node build/index.js Restart=always [Install] WantedBy=multi-user.target </code></pre> What This Division Reveals</h2> The coffee roaster can now ship features. They understand the domain, they can articulate requirements to Claude, and they get working code.</p> What they don't need to think about:</p> How tenant isolation works</li> Where sessions are stored</li> How migrations run</li> How deploys happen</li> How backups work</li> </ul> That's my layer.</p> This is different from traditional client work. Usually I'm translating requirements into code. Here, the client is writing code and I'm building the platform it runs on.</p> AI didn't eliminate the need for engineering. It shifted the boundary.</p> The roaster went from "I need software" to "I built the features, can you make it production-ready?" That's a meaningful change.</p> What Works</h2> CSV import</strong> with inline group creation (no context switching to Catalog)</li> Production snapshots</strong> that save/restore daily plans automatically</li> Dynamic batch types</strong> - users define their own batch sizes, not hardcoded</li> Multi-tenant</strong> - multiple roasters can use the same deployment</li> Pick lists</strong> with package size summaries and roast group breakdowns</li> </ul> What Doesn't</h2> No API</strong> - It's a web app, no programmatic access</li> Limited reports</strong> - Just basic CSV export, no analytics</li> No mobile app</strong> - Responsive web only</li> Single database</strong> - No read replicas or sharding (doesn't need it yet)</li> </ul> Reflections</h2> The best part of this project was watching someone with domain expertise build software directly. They didn't need to translate "how batch calculations work" into a spec for me to implement. They knew it, and they told Claude.</p> The boundary between developer and non-developer is blurring. Not because everyone needs to learn to code, but because AI is good enough at the translation layer that domain knowledge can drive implementation.</p> What still requires engineering judgment:</p> Multi-tenancy architecture</li> Security and authentication</li> Deployment and reliability</li> Database design and migrations</li> Production monitoring</li> </ul> Those aren't going away. But the surface area of "things only developers can build" is shrinking.</p> BeanLedger works. It's in production. The person who built most of the features isn't a software engineer.</p> That's new.</p> Links</h2> BeanLedger on GitHub</a></li> </ul> Rewriting discourse-comments in TypeScript: Dropping WASM for a 97% Smaller Bundle Unknown — Fri, 27 Feb 2026 00:00:00 +0000 Last month I wrote about building an embedded comment widget</a> for Discourse using Rust compiled to WebAssembly. It worked. Users could drop a single script tag on their page and get comments from a Discourse topic.</p> But the bundle was 742 KB. Most of that was WASM.</p> I rewrote the API client in TypeScript and the bundle dropped to 18.5 KB. Same functionality, same API surface, no WASM runtime.</p> Why Rewrite?</h2> The original stack had three layers: a Rust HTTP client compiled to WASM, a TypeScript web component, and an esbuild plugin to inline the WASM binary as base64. That last part was the real cost. The WASM binary was ~546 KB, and base64 encoding inflates that by 33%.</p> The Rust client existed because I wanted to push Rust into the browser. It was a fun experiment. But the API client itself was straightforward HTTP: build a URL, set some headers, parse JSON. There's nothing in that workflow that benefits from Rust's type system or performance characteristics. The browser's native fetch</code> does the same thing.</p> So I asked the obvious question: what if the API client was just TypeScript?</p> The Rewrite</h2> The new client is discourse-api-ts</a>. Zero runtime dependencies. It uses fetch</code> for HTTP, which every modern browser and Node.js already provides.</p> The Rust client had 18 methods across topics, posts, categories, chat, notifications, and likes. The TypeScript port has the same 18 methods with identical signatures. The only difference is BigInt</code> parameters became regular number</code> (JavaScript's Number</code> handles Discourse IDs fine).</p> Here's what the client looks like:</p> // Anonymous (read-only) const client = new DiscourseClient("https://forum.example.com"); // Authenticated const client = DiscourseClient.withUserApiKey( "https://forum.example.com", storedApiKey ); const topic = await client.getTopic(123); await client.createPost(123, "Hello from the widget"); await client.likePost(456); </code></pre> No init()</code> call to load the WASM runtime. No BigInt()</code> wrappers. Just regular async functions.</p> Updating discourse-comments</h2> With the new client published to npm, updating the web component was mostly find-and-replace:</p> import init, { WasmDiscourseClient }</code> became import { DiscourseClient }</code></li> Removed the await init()</code> call in loadComments</code></li> BigInt(this.topicId)</code> became Number(this.topicId)</code></li> Deleted the esbuild WASM inlining plugin entirely</li> </ul> The build script went from 60 lines of WASM gymnastics to a straightforward esbuild call:</p> await esbuild.build({ entryPoints: ["src/discourse-comments.ts"], bundle: true, format: "iife", outfile: "dist/discourse-comments.min.js", minify: true, }); </code></pre> No custom plugins. No base64 encoding. No WebAssembly.instantiate</code>.</p> The Numbers</h2> </th> Rust/WASM</th> TypeScript</th></tr></thead> Bundle size (minified)</td> 742 KB</td> 18.5 KB</td></tr> Runtime dependencies</td> wasm-bindgen</td> None</td></tr> Build steps</td> cargo build + wasm-pack + tsc + esbuild</td> tsc + esbuild</td></tr> Init overhead</td> WASM decode + instantiate</td> None</td></tr> </tbody></table> That 18.5 KB includes the entire web component, all the styles, the OAuth flow, and the API client. A user on a slow connection downloads 40x less data.</p> Dev Experience</h2> With the Rust client, the build pipeline was: cargo build targeting wasm32, wasm-pack to generate JS bindings, TypeScript compilation, then esbuild with a custom plugin to inline the binary. If any step failed, the error could be in Rust, in wasm-bindgen, in the TypeScript types, or in the bundler plugin. Debugging meant jumping between ecosystems.</p> With TypeScript, it's tsc && node build.mjs</code>. If there's a type error, it's in TypeScript. If there's a runtime error, it's in JavaScript. One language, one toolchain, one set of error messages.</p> Adding a new API method in Rust meant: define the struct, implement the method, rebuild WASM, regenerate bindings, update TypeScript types to match. In TypeScript: add an interface, add a method, done. I added search, user profiles, and topic management (6 new methods) in one sitting.</p> What I Lost</h2> Honesty requires noting what the WASM version had going for it.</p> Rust's type system caught entire categories of errors at compile time. The TypeScript version uses interfaces, which help, but they're structural and optional. A Post</code> with a missing field compiles fine until it blows up at runtime.</p> Rust's Result</code> type forced explicit error handling everywhere. In TypeScript, it's easy to forget a .catch()</code> or let an error propagate silently.</p> For this particular project, those trade-offs don't matter much. The API surface is small and the error handling is straightforward. But for a larger client library, I'd think harder about it.</p> When WASM Makes Sense</h2> WASM is the right call when you need computation that JavaScript can't do efficiently: image processing, cryptography, physics simulations, codecs. If you're doing heavy lifting in a tight loop, WASM's predictable performance model wins.</p> But for HTTP clients that serialize JSON and build URLs, the browser already has everything you need. Adding a WASM layer for that is carrying a backpack full of bricks on a walk to the mailbox.</p> Try It</h2> The widget still works the same way. Drop it on a page, point it at a Discourse topic, get comments. It's just 40x lighter now.</p> <script src="discourse-comments.min.js"></script> <discourse-comments discourse-url="https://forum.example.com" topic-id="123"> </discourse-comments> </code></pre> discourse-comments</a></li> discourse-api-ts</a></li> </ul> AI Problems Are Just Human Problems Amplified Unknown — Mon, 23 Feb 2026 00:00:00 +0000 Another day, another article about AI fatigue and all the other problems it causes. And I agree, the symptoms are real: burnout from keeping up with new models, FOMO about missing capabilities, perfectionism about getting prompts exactly right, analysis paralysis about which tool to use.</p> However, I do not think these are new problems. Developers burned out keeping up with JavaScript frameworks before AI existed. FOMO about missing the next big thing has been around since the first tech conference. Perfectionism about tooling choices is why we have 47 different React state management libraries.</p> AI did not create these problems. It amplified them. New models ship every month instead of every year. The output quality depends heavily on prompt engineering, so perfectionism has visible consequences. The tooling landscape changes so fast that yesterday's best practice is tomorrow's deprecated approach.</p> The solution is the same as it always was: pick something, build with it, move on. If the tool does not work, try a different one. If the output is wrong, fix the prompt or fix the output. Stop trying to find the perfect model, the perfect prompt, the perfect workflow. There is no perfect. There is only good enough to ship.</p> Garbage In, Garbage Out</h2> I spent yesterday implementing a Rails app called Webstead using a multi-model code generation tool called finna. The tool works like this: multiple LLMs debate the architecture, synthesize a consensus, generate specs, then implement the code.</p> The tool generated migrations with circular dependencies. The CreateUsers</code> migration referenced websteads</code> that did not exist yet. The CreateWebsteads</code> migration referenced users</code> that did not exist yet. The CreateFollowers</code> migration referenced federated_actors</code> with a timestamp 204514 instead of the correct 000003.</p> The models also added duplicate indexes, self-referential foreign keys that caused deadlocks, and CHECK constraints that hung the migration runner.</p> Was this an AI problem? No. It was a coordination problem. The models generated migrations independently without seeing what the other models had created. Dependencies got misordered. Constraints conflicted. The tool did not validate that migrations could actually run before writing them to disk.</p> The fix was not better AI. The fix was better constraints. Migrations need dependency ordering. The tool needs to number them sequentially. If a migration references a table, that table's migration must run first.</p> This is the same coordination problem human developers face on multi-person teams. You just notice it faster when the team is four LLMs running in parallel.</p> What Actually Works</h2> I use AI for code generation daily. Here is what works:</p> Use it for tasks with clear specifications. If you can describe the desired output precisely, the model will probably generate something close. If you cannot describe what you want, the model will not guess correctly.</p> Review the output. The model will make mistakes. It will use deprecated APIs. It will skip edge cases. It will generate code that compiles but does not work. Treat it like code review from a junior developer who types fast but does not check their work.</p> Iterate on the prompt when the output is wrong. If it generates migrations with circular dependencies, tell it to output migrations in dependency order. The model does not know your requirements unless you tell it.</p> Use multiple models when the task is ambiguous. Different models have different blind spots. One model catches precision bugs in number handling. Another catches stack overflow vulnerabilities in recursive parsers. Consensus finds edge cases no single model would have caught.</p> Do not expect the model to read your mind. It cannot. It is text prediction, not telepathy.</p> The Real Problem</h2> The real problem with AI tools is that people expect them to solve problems humans have not solved yet.</p> You cannot ask an AI to follow code style if you have not documented the style. You cannot ask it to implement a feature if you have not specified what the feature should do.</p> AI does not eliminate the need for clear requirements, documentation, or code review. It amplifies the cost of not having them. If your team does not have coding standards, the AI will generate code in 47 different styles. If your project does not have tests, the AI will break things you did not know were fragile. If your specs are ambiguous, the AI will pick the wrong interpretation.</p> This is not the AI's fault. This is your fault for not having standards, tests, or specs.</p> Using AI Without Losing Your Mind</h2> Here is what I do:</p> Treat AI as a tool, not a coworker. It does not understand context. It does not remember what you said three prompts ago. It does not know what you meant versus what you typed. Give it explicit instructions and check the output.</p> Use it for tasks with high certainty and low blast radius. Generating test cases? Great. Refactoring variable names? Fine. Rewriting your entire database layer? Probably not.</p> Keep humans in the loop at decision boundaries. Generate the plan, review it, then execute. Generate the code, review it, then merge. The AI can propose. You decide.</p> Do not try to keep up with every new model. Pick one that works and use it until it does not work anymore. Switching models every week is how you burn out.</p> Lower your expectations. The AI will not write production-ready code from a vague prompt. It will write something that compiles and mostly works. You fix the rest. That is still faster than writing it yourself from scratch.</p> Conclusion</h2> AI problems are human problems. Burnout from keeping up with too many tools. FOMO about missing the next breakthrough. Perfectionism about getting it exactly right. Analysis paralysis about which approach to take. Garbage in, garbage out.</p> We had these problems before AI. We will have these problems after AI. The only difference is speed. AI makes bad processes fail faster. It makes unclear requirements obvious immediately. It makes poor documentation expensive in minutes instead of months.</p> If you are struggling with AI tools, the problem is probably not the AI. The problem is that your process, documentation, or requirements were already broken. AI just made it obvious.</p> Fix the process. The AI will follow.</p> llm-mux: Why I Rebuilt Lok Unknown — Wed, 11 Feb 2026 00:00:00 +0000 Lok hit 317 cargo installs. People were using it. So naturally I rewrote it from scratch.</p> That's not as chaotic as it sounds. Lok grew organically from "query multiple LLMs" to "run workflows" to "apply edits" to "create GitHub issues." Each feature bolted onto the side. The codebase worked but the abstractions were wrong.</p> llm-mux is what lok should have been from the start.</p> What Was Wrong</h2> Lok conflates backends with tasks. When you write backend = "claude"</code> in a workflow step, you're coupling your workflow to a specific model. Want to swap Claude for Gemini? Edit every step.</p> Lok also has no concept of project context. A Rust project needs cargo test</code> for verification. A Node project needs npm test</code>. In lok, you hardcode these per-workflow. Switch projects, rewrite workflows.</p> The apply_edits feature was bolted on late. It works but there's no retry loop, no structured verification, no rollback without git-agent.</p> Roles</h2> llm-mux introduces roles. Instead of hardcoding backends:</p> # lok style - backend hardcoded [[steps]] name = "analyze" backend = "claude" prompt = "Find bugs" </code></pre> You declare what kind of task it is:</p> # llm-mux style - role-based [[steps]] name = "analyze" type = "query" role = "analyzer" prompt = "Find bugs" </code></pre> Then configure which backends handle which roles:</p> [roles.analyzer] description = "Code analysis tasks" backends = ["claude", "codex"] execution = "parallel" [roles.quick] description = "Fast local checks" backends = ["qwen"] execution = "first" </code></pre> Swapping backends is a config change, not a workflow rewrite. The workflow says "I need analysis." The config decides who does analysis.</p> Teams</h2> Teams add project context:</p> [teams.rust] description = "Rust projects" detect = ["Cargo.toml"] verify = "cargo clippy && cargo test" [teams.rust.roles.analyzer] backends = ["claude", "codex"] </code></pre> When llm-mux detects Cargo.toml</code>, it activates the rust team. Verification commands come from the team. Role mappings can be overridden per-team.</p> Same workflow, different projects, correct tooling.</p> HTTP Backends</h2> Lok only does CLI. You shell out to claude</code>, codex</code>, ollama run</code>. Each query spawns a process.</p> llm-mux supports both CLI and HTTP:</p> [backends.claude] command = "claude" args = ["-p", "--"] [backends.openai] command = "https://api.openai.com/v1" model = "gpt-4" api_key = "${OPENAI_API_KEY}" [backends.local] command = "http://localhost:11434/v1" model = "llama3" </code></pre> If the command starts with http</code>, it's HTTP. Otherwise CLI. HTTP is faster for high-volume workflows. No process overhead. Proper streaming. Rate limit handling.</p> Apply and Verify</h2> Lok's apply_edits was a boolean flag. llm-mux has a real system:</p> [[steps]] name = "fix" type = "apply" source = "steps.analyze" verify = "cargo test" verify_retries = 3 verify_retry_prompt = "Fix failed: {{ error }}. Try again." rollback_on_failure = true </code></pre> The flow:</p> Parse edits from source step</li> Apply edits</li> Run verification</li> If it fails and retries remain, show error to LLM, try again</li> If all retries fail, rollback</li> </ol> The retry loop is the difference. Instead of failing on first bad edit, llm-mux shows the error and asks for a fix. Most failures are small mistakes a second attempt catches.</p> Rollback uses git stash. No external tooling.</p> An Example</h2> The rust-audit workflow runs four parallel audits and writes structured docs:</p> llm-mux run rust-audit llm-mux run rust-audit outdir=reports/feb-audit </code></pre> Output:</p> docs/audit/ ├── README.md # Summary table ├── 01-safety.md # Memory safety ├── 02-performance.md # Perf issues ├── 03-errors.md # Error handling └── 04-idioms.md # Patterns </code></pre> Each audit is its own query step. Each saves to a file. The final step synthesizes a summary. The outdir</code> argument makes it reusable.</p> What llm-mux Is Not</h2> llm-mux is not a replacement for lok's CLI commands. There's no llm-mux ask</code> or llm-mux hunt</code>. It's purely a workflow runner.</p> If you want quick one-off queries, use lok. If you want structured multi-step pipelines with proper abstractions, use llm-mux.</p> I'm keeping both. They solve different problems.</p> What Doesn't Work Yet</h2> The template system is powerful but error messages are cryptic. A typo in a Jinja variable gives you a wall of minijinja internals.</p> HTTP backend streaming works but the progress output is ugly. You see chunks arrive but it's not as clean as the CLI backend output.</p> Team auto-detection is basic. It looks for files but doesn't understand monorepos or nested projects yet.</p> Getting Started</h2> cargo install llm-mux llm-mux doctor llm-mux run rust-audit </code></pre> Config goes in ~/.config/llm-mux/config.toml</code>. Workflows go in .llm-mux/workflows/</code> or ~/.config/llm-mux/workflows/</code>.</p> Source at github.com/ducks/llm-mux</a>.</p> Lok was the prototype. llm-mux is the product. The 317 people using lok helped me figure out what the abstractions should be.</p> finna: Multi-Model Debate, Spec, and Implement Unknown — Tue, 10 Feb 2026 00:00:00 +0000 Lok's spec</code> command was useful but felt too coupled to the rest of the tool. I wanted something standalone: give it an idea, get specs and code. No configuration files, no backend setup, just a single binary that orchestrates the models I already have installed.</p> That's finna.</p> The Problem with "Just Build It"</h2> When you ask an LLM to build something, it starts coding immediately. Maybe it picks a good architecture, maybe it doesn't. By the time you see the output, you're committed to whatever approach it chose. If the foundation is wrong, you're either refactoring generated code or starting over.</p> The fix is to separate planning from execution. But not just any planning. A plan that multiple models have debated and agreed on, written down in files you can review before any code gets generated.</p> The Pipeline</h2> finna runs four stages:</p> idea → debate → roadmap → spec → implement </code></pre> Debate</strong>: Claude, Codex, and Gemini independently analyze the idea</li> Consensus</strong>: Claude synthesizes the proposals into a unified approach</li> Roadmap</strong>: Break the consensus into ordered, dependency-aware steps</li> Spec</strong>: Write detailed implementation specs for each step</li> Implement</strong>: Models propose edits, Claude synthesizes, changes applied</li> </ol> Each stage reads from the previous stage's output. Everything lands in .finna/</code> so you can review, edit, or re-run individual stages.</p> Usage</h2> # Run all stages finna "Add JWT authentication to the API" # Or run stages separately finna debate "Add JWT authentication" # debate → roadmap finna spec # roadmap → specs finna implement # specs → code # Target specific steps finna spec --step auth-middleware finna implement --step auth-middleware </code></pre> A Real Example: TOML Parser</h2> I ran finna on building a TOML parser from scratch:</p> finna debate "write a toml parser in rust from scratch, no dependencies" </code></pre> Three models debated the architecture. They converged on a lexer-first approach with recursive descent parsing. The roadmap came out as 30 steps with proper dependency ordering:</p> .finna/ ├── consensus.json ├── roadmap.arf └── specs/ ├── 01-project-scaffold/spec.arf ├── 02-error-types/spec.arf ├── 03-token-types/spec.arf ... ├── 16-lexer-integration/spec.arf ├── 17-parser-core/spec.arf ... └── 30-edge-cases/spec.arf </code></pre> The roadmap groups work into phases: scaffold and types (1-5), lexer (6-16), parser (17-25), public API and tests (26-30). Each step declares its dependencies so they can't run out of order.</p> Running finna spec</code> generates detailed ARF specs for each step. Here's the spec for lexing basic strings:</p> order = 10 what = "Implement lexing for double-quoted basic strings with full escape support" why = "Basic strings are TOML's primary string format. The lexer must process escapes at lex time and detect unterminated strings with precise error locations." how = """ 1. Add lex_basic_string() method 2. Main loop: consume until closing quote or error 3. Implement lex_escape_sequence() for \t, \n, \r, \\, \", \uXXXX, \UXXXXXXXX 4. Implement lex_unicode_escape() with validation 5. Wire into lex_token() dispatch 6. Add unit tests for all escape sequences and error cases """ backup = "Defer escape processing to post-lex pass if implementation is error-prone" [context] files = ["src/lexer.rs", "src/error.rs"] dependencies = [] </code></pre> The specs include test cases. The basic strings spec lists 25+ scenarios: simple strings, escape sequences, unicode handling, error conditions. The models know what to test because they debated it during planning.</p> The 30 specs totaled 2.1k lines. That's not wasted tokens. It's a contract you can review before any code exists.</p> The ARF Format</h2> Specs use TOML with a standard structure:</p> order = 1 what = "one sentence description" why = "context and motivation" how = """ Step-by-step implementation plan """ backup = "fallback approach if primary fails" [context] files = ["paths/to/files"] dependencies = ["step names this depends on"] </code></pre> The format is simple on purpose. No special tooling needed to read or edit. Any text editor works. The structure enforces that every step has a rationale, a plan, and a fallback.</p> Why Separate Stages</h2> The stages are separate because you need intervention points.</p> After debate, review the roadmap. Does the architecture make sense? Are the steps in the right order? Edit .finna/roadmap.arf</code> if not.</p> After spec, review the specs. Is the implementation plan correct? Are the test cases comprehensive? Edit the spec files or re-run finna spec --step X</code>.</p> After implement, review the changes. Did the edits apply cleanly? Is the code what you expected? The specs told you what would happen; now verify it did.</p> If you run finna "idea"</code> without the subcommands, it runs all stages in sequence. That's fine for exploration. But for real work, you probably want the review gates.</p> Multi-Model Consensus</h2> The debate phase isn't just asking three models and picking one. All three responses get synthesized:</p> Claude, Codex, and Gemini each propose an approach in parallel</li> Claude sees all three proposals and synthesizes consensus</li> Disagreements become explicit tradeoffs in the final plan</li> </ol> One model might over-engineer authentication. Another might skip edge cases. The synthesis catches both failure modes. You get architecture that multiple models have pressure-tested.</p> Implementation</h2> finna is ~500 lines of Rust. It shells out to claude</code>, codex</code>, and npx @google/gemini-cli</code> for the actual model calls. No API keys in the binary, no config files. If you have the CLIs installed, finna works.</p> The implementation phase runs models in parallel for each step, synthesizes their edit proposals, and applies the changes. Edits are JSON with path</code>, old</code>, and new</code> fields. Simple find-and-replace, no AST manipulation.</p> #[derive(Debug, serde::Deserialize)] struct Edit { path: String, old: String, new: String, } </code></pre> If an edit can't find the target text, it warns and continues. If the file doesn't exist, it creates it. The implementation is deliberately simple because the specs already contain the complexity.</p> What finna Is Not</h2> finna is not a replacement for writing code. It's a planning tool that happens to also generate code. The value is in the specs, not the implementation.</p> If the generated code is wrong, you fix the spec and re-run. If the architecture is wrong, you fix the roadmap and re-spec. The code is a side effect of getting the plan right.</p> finna is also not trying to be general-purpose. It solves one problem: turn an idea into a structured plan with implementation. No plugins, no extensibility, no configuration. One tool, one job.</p> Getting Started</h2> # Clone and build git clone https://github.com/ducks/finna cd finna nix-shell cargo build --release # Run on your idea ./target/release/finna "your idea here" </code></pre> Requires claude</code>, codex</code>, and npx @google/gemini-cli</code> to be installed and authenticated. If a model fails, finna continues with the others.</p> The source is at github.com/ducks/finna</a>.</p> The test project (TOML parser specs) is at github.com/ducks/finna-toml-parser</a>.</p> Building a JSON Parser with Multi-LLM Orchestration (Part 1) Unknown — Sat, 07 Feb 2026 00:00:00 +0000 I've been building lok, a multi-LLM orchestration tool, and I wanted to put it through its paces on a real project. What better than a JSON parser? It's a classic learning project with enough nuance to surface interesting design decisions.</p> Here's the premise: instead of just diving into code, what if I let multiple LLMs debate the design first? Then synthesize their consensus into specs. Then have them collaboratively implement it.</p> The Setup</h2> I started with a simple question:</p> lok debate "We want to write a JSON parser from scratch as a learning project. Debate: What language should we use? What features should it support? What should the architecture look like?" </code></pre> Four models participated: Claude, Codex (GPT-5.2), Gemini, and Qwen 3 Coder (running locally via Ollama).</p> Round 1: Surprising Agreement</h2> All four converged on Rust. The reasoning varied:</p> Claude</strong> focused on the learning angle: "Forces you to think about ownership and memory layout. You'll learn more writing a parser in Rust than in Python/JS where you can be sloppy."</p> Codex</strong> got practical: "Ownership semantics force you to think about buffer management. Result<T, E></code> makes error handling explicit."</p> Gemini</strong> went for performance: "Zero-cost abstractions mean clean code compiles to efficient machine code."</p> Qwen</strong> hit safety: "Enums with exhaustive matching prevent invalid parser states."</p> On architecture, unanimous: lexer + recursive descent parser. No surprises there.</p> Round 2: The Interesting Bits</h2> Numbers sparked actual debate. The naive approach stores JSON numbers as f64</code>:</p> Number(f64) // Simple but WRONG </code></pre> Codex caught it: "Treating numbers as f64 is not spec-correct. JSON allows arbitrary precision. The safest approach is storing the original string."</p> Number(&'a str) // Preserves original, validates grammar </code></pre> This is why multi-model debate works. I might have defaulted to f64 and hit precision bugs later.</p> Another good catch from Gemini: recursive descent needs depth limits. Without them, an adversarial input like [[[[[[[[...</code> blows the stack. Simple fix, easy to forget.</p> The Consensus</h2> After three rounds, the models settled on:</p> Language</strong>: Rust</li> Architecture</strong>: Lexer (iterator-based) + Recursive Descent Parser</li> Number handling</strong>: Store as string, not f64</li> Zero-copy</strong>: Use Cow<'a, str></code> where possible</li> Safety</strong>: Configurable depth limits</li> Features</strong>: RFC 8259 strict first, extensions later</li> </ol> Generating Specs</h2> With design decisions locked, I fed the debate conclusions into lok spec</code>:</p> lok spec "Build a JSON parser in Rust with these design decisions: - Lexer + Recursive Descent Parser - Numbers stored as string, not f64 - Zero-copy with Cow<'a, str> - Depth limits for safety - RFC 8259 strict compliance" </code></pre> This queries multiple backends, synthesizes a consensus roadmap, then breaks each step into subtasks. The output:</p> .arf/specs/ roadmap.arf 01-core_types/ (5 subtasks) - Span, Error, Token, Value 02-lexer/ (5 subtasks) - Iterator-based tokenizer 03-parser/ (4 subtasks) - Recursive descent 04-number_validation/ (2 subtasks) - RFC 8259 number format 05-error_reporting/ (4 subtasks) - Line/column errors 06-test_suite/ (3 subtasks) - JSONTestSuite compliance 07-extension_hooks/ (4 subtasks) - Future comments/trailing commas </code></pre> Each subtask is an .arf</code> file (Agent Reasoning Format) with structured fields:</p> order = 1 what = "Core Lexer struct implementing Iterator over tokens" file = "src/lexer/lexer.rs" why = "Main lexing logic that transforms input bytes into token stream" how = """ Struct Lexer<'a> with input: &'a str, pos: usize. Implement Iterator<Item = Result<Token<'a>, LexError>>. Dispatch on current byte: punctuation returns immediately, keywords verify literals, strings handle escapes, numbers capture as slice. """ [context] inputs = "Raw JSON string" outputs = "Stream of Token results" </code></pre> These specs become the contract for implementation.</p> What Multi-Model Debate Surfaces</h2> Edge cases no single model catches.</strong> The f64 precision issue came from Codex. The depth limit vulnerability came from Gemini. Each model has blind spots. Claude focused on educational value, Codex on spec correctness, Gemini on performance, Qwen on safety.</p> Consensus beats any single model.</strong> Not because the average is smarter, but because different models catch different things. Three rounds of debate with four models surfaced issues I'd have hit weeks into implementation.</p> What's Next</h2> Part 2 will cover lok implement</code>, which takes these specs and:</p> Queries multiple backends in parallel for each subtask</li> Synthesizes consensus code from the proposals</li> Writes the file and verifies it compiles</li> Commits each file with an atomic git commit</li> Records structured reasoning traces (ARF) alongside the code</li> </ol> The implementation phase is where things get interesting. Backends disagree on details, synthesis has to resolve conflicts, and verification catches when the generated code doesn't actually compile.</p> Stay tuned.</p> Lok Part 5: Multi-Agent Planning with lok spec Unknown — Fri, 06 Feb 2026 00:00:00 +0000 The hardest part of building software isn't writing code. It's figuring out what to build and in what order. LLMs are great at generating code, but they're also great at generating the wrong code because they started implementing before thinking through the structure.</p> That's what lok spec</code> solves.</p> This post describes the shape of the system: how lok structures planning, what guarantees the spec format provides, and why separation between planner and executor matters. The implementation of the executor (agents actually writing code) is not covered here. This is about constraints and contracts.</p> What Lok is not</h2> Before going further:</p> Not a chatbot framework or conversational interface</li> Not a marketplace or plugin system for third-party agents</li> Not trying to replace developers with automation</li> </ul> Lok is a planner that structures work and an executor that requires explicit human approval at every phase boundary. The design assumes humans review specs, trigger execution, and validate results.</p> The Problem with "Just Build It"</h2> When you give an LLM a big task like "build a C compiler," it starts coding immediately. Maybe it picks the lexer first, maybe the parser. Maybe it designs types that won't work for later phases. By the time you realize the architecture is wrong, you've burned tokens and time.</p> The fix is obvious in retrospect: plan before you build. But not just any plan. A plan that multiple models have debated and converged on.</p> Propose, Refine, Pick</h2> lok spec</code> uses a three-step process:</p> Propose</strong>: All backends generate roadmaps in parallel</li> Refine</strong>: Synthesize roadmaps into a consensus plan</li> Pick</strong>: Generate detailed specs from the consensus</li> </ol> This is the same pattern as debate mode, but applied to planning instead of analysis. Each backend proposes how they'd structure the project. Then we synthesize the best ideas and resolve contradictions. Finally, we generate specs that capture the agreed approach.</p> lok spec "Build a C compiler in Rust. Take C source as input, produce x86-64 assembly output. Include lexer, parser, semantic analysis, and code generation. Focus on correctness over optimization." </code></pre> spec: Planning: Build a C compiler in Rust... spec: Step 1/3: Getting roadmaps from 4 backends... ✓ 4/4 backends responded spec: Step 2/3: Synthesizing consensus roadmap... ✓ Consensus reached spec: Step 3/3: Generating detailed specs... spec: Step 4/4: Breaking specs into subtasks... ✓ lexer → 4 subtasks ✓ ast → 5 subtasks ✓ parser → 5 subtasks ✓ semantic → 5 subtasks ✓ ir → 5 subtasks ✓ codegen → 5 subtasks ✓ driver → 4 subtasks ================================================== spec: Generated 7 specs in .arf/specs/: + roadmap.arf + 01-lexer/spec.arf + 01-lexer/01-token.arf + 01-lexer/02-cursor.arf + 01-lexer/03-scanner.arf + 01-lexer/04-keywords.arf + 02-ast/spec.arf ... </code></pre> Four backends looked at "build a C compiler" and each proposed a roadmap. Claude synthesized them into a unified plan. Then we generated specs for each step, and broke each step into subtasks (individual files).</p> The Output Structure</h2> Specs land in .arf/specs/</code> with a nested structure:</p> .arf/specs/ roadmap.arf 01-lexer/ spec.arf 01-token.arf 02-cursor.arf 03-scanner.arf 04-keywords.arf 02-ast/ spec.arf 01-types.arf 02-expr.arf ... </code></pre> The roadmap is the high-level plan. Each numbered directory is a step. Inside each step is a spec.arf</code> with the overall component spec, plus subtask files for individual pieces.</p> A spec file looks like this:</p> order = 1 what = "Build the lexer to tokenize C source code" why = "Parser needs a stream of tokens, not raw characters" how = "Hand-written scanner with keyword trie, handles preprocessor directives" backup = "Fall back to regex-based tokenizer if performance is acceptable" [context] inputs = "C source code as string or file path" outputs = "Iterator of Token structs with location info" dependencies = [] tests = "Tokenize test files, compare against expected token sequences" </code></pre> A subtask file adds a file</code> field:</p> order = 1 what = "Define token types and structures" file = "src/lexer/token.rs" why = "All other lexer components depend on token definitions" how = "Enum for token kinds, struct for token with span and value" [context] inputs = "None - foundational types" outputs = "Token enum, TokenKind enum, Span struct" tests = "Unit tests for token construction and display" </code></pre> Planning to Execution Flow</h2> Here is the minimal end-to-end for a boring but real task: refactoring Rust error handling to use thiserror</code> crate. Replace manual impl Display</code> with derive macro. Update all error construction sites.</p> lok spec "Refactor error types to use thiserror crate. Replace manual Display impls with derive macro. Update all error construction sites." </code></pre> Output:</p> .arf/specs/ roadmap.arf 01-add-dependency/spec.arf 02-refactor-errors/spec.arf 02-refactor-errors/01-lexer-error.arf 02-refactor-errors/02-parser-error.arf 03-update-callsites/spec.arf </code></pre> Review the roadmap and specs. If the plan looks wrong, edit the .arf</code> files or regenerate. Once satisfied:</p> lok implement .arf/specs/ </code></pre> Agents read each spec and implement the changes directly. Each agent works on its assigned file according to the spec. The boundary between planning and execution is the review gate - you decide when to run lok implement</code> after reviewing the specs.</p> Why This Matters</h2> The spec files are ARF</a> format. That means they're structured, parseable, and auditable. When you review a spec, you're reviewing the plan before any code exists. If the approach is wrong, you catch it here, not after 10,000 lines of generated code.</p> The subtask breakdown is what enables parallel execution. Once you have specs for 01-token.arf</code>, 02-cursor.arf</code>, 03-scanner.arf</code>, and 04-keywords.arf</code>, different agents can work on different files simultaneously. They're not stepping on each other because each owns their file.</p> The pattern is recursive. lok spec</code> on a project gives you steps. Each step has subtasks. If a subtask is still too big, you could spec it again. Same process, different scale.</p> The spec format enforces three invariants:</p> Serializable plans</strong>: Every decision is written down in parseable TOML. You can diff plans, version them, replay them.</li> Attributable actions</strong>: Each spec names the file it will modify or create. No agent can touch code without a spec that declares intent.</li> Human intervention points</strong>: Spec generation is separate from execution. You review the plan before any code changes happen.</li> </ol> These are not optimizations. They are constraints that prevent the system from becoming a black box.</p> Human in the Loop by Design</h2> The separation between lok spec</code> and execution is not a temporary limitation. It is the core design. The system does not "learn" to skip human review or "graduate" to autonomous operation.</p> Every phase boundary requires explicit human approval:</p> Spec generation produces files you review before execution starts</li> Execution runs subtasks but does not merge or deploy results</li> Integration is a separate manual step</li> </ul> This is not because the LLMs are not capable enough. It is because software built by delegation requires inspection and veto power at decision boundaries. The moment you remove that, you have an agent that makes choices you cannot audit until after the damage is done.</p> Single Backend Fallback</h2> If you only have one backend configured, lok spec</code> skips the multi-model consensus and just asks that backend to plan and spec directly. You still get the structured output, just without the debate.</p> lok spec --backend claude "Build a REST API" </code></pre> The value of multi-backend consensus is catching blind spots. One model might over-engineer the auth system while another keeps it simple. Synthesis finds the middle ground. But if you're just exploring or don't have multiple backends set up, single-model works fine.</p> Token Conservation</h2> The multi-agent pattern has a cost: API calls. Four backends generating roadmaps is four API calls. Synthesis is another. Spec generation is another. Subtask generation is one per step.</p> For a 7-step project, that's roughly: 4 (roadmaps) + 1 (synthesize) + 1 (specs)</p> 7 (subtasks) = 13 API calls. Not cheap if you're using expensive models.</li> </ul> But here's the key: every backend's contribution gets used. We're not querying four models and throwing away three responses. We're synthesizing all four into something better than any single response.</p> This is the rule I've been following: if you fire off multiple agents, they must debate or synthesize. Never query N backends just to pick one.</p> What's Next</h2> The specs exist. The next step is execution: read the specs, assign agents to subtasks, run them in parallel, integrate the results. That is a bigger piece of machinery, but the foundation is here.</p> For now, lok spec</code> gives you a structured plan that multiple models have agreed on. Review it, tweak it if needed, then start building with confidence that the architecture makes sense. The system does not get smarter by hiding decisions from you. It gets more useful by making decisions inspectable.</p> The source is at github.com/ducks/lok</a>.</p> Previous: Part 4: The Self-Healing Loop</a></p> cfgs.dev: A Directory for Developer Setups Unknown — Tue, 03 Feb 2026 00:00:00 +0000 Every developer eventually builds a setup they are proud of. Not because it is perfect, but because it is earned - shaped by years of work, mistakes, migrations, and small personal decisions.</p> The problem is discovery. These hard-won configurations are scattered across GitHub repos, half-documented READMEs, gists, and blog posts. You can find them if you already know what to search for. But browsing? Exploring what tools people actually use together? That is hard.</p> cfgs.dev</a> exists to fix that gap.</p> It is not a new config system. Not a dotfile manager. Not a package manager. It is a directory - a browsable index of how developers actually work, across tools, operating systems, and philosophies.</p> Think of it like browsing other developers' desks. You can see what tools they use, how they configure them, and what their workflow looks like. Then follow the link to their actual dotfiles repo to see the details.</p> What cfgs.dev is</h2> cfgs.dev scans GitHub repos and extracts what tools people use. Not just "this repo has Neovim" but "this repo uses Neovim with lazy.nvim, gruvbox, lualine, telescope, and nvim-cmp."</p> An entry is simple: a username, a link to the dotfiles repo, and a structured breakdown of what the scanner found. Anyone can submit any public repo - the owner can later claim it by logging in. You can browse by category (editors, terminals, window managers) or by specific tool. Want to see how people configure Hyprland? There's a page for that.</p> The detection is declarative. Each tool has a JSON config that specifies file patterns to match and content to extract:</p> { "name": "Neovim", "patterns": ["nvim/init.lua", ".config/nvim/**/*.lua"], "contentFlags": { "pluginManager": { "lazy.nvim": ["lazy.nvim", "folke/lazy"], "packer": ["packer.nvim", "wbthomason/packer"] }, "theme": { "gruvbox": ["gruvbox"], "tokyonight": ["tokyonight"] } } } </code></pre> When the scanner finds a matching file, it checks the content for these patterns. First match wins per category. The result is a structured view of what the config actually contains.</p> Deep Detection</h2> The latest version goes deeper on Neovim specifically. It now detects 14 categories of config details:</p> Distribution (LazyVim, AstroNvim, NvChad)</li> Plugin manager (lazy.nvim, packer, vim-plug)</li> LSP setup (nvim-lspconfig, coc.nvim)</li> Completion (nvim-cmp, coq, deoplete)</li> Statusline (lualine, lightline, airline)</li> File explorer (nvim-tree, neo-tree, oil.nvim)</li> Fuzzy finder (telescope, fzf-lua)</li> Theme (gruvbox, tokyonight, catppuccin, etc.)</li> And more</li> </ul> The tricky part was handling multi-file configs. A typical Neovim setup has init.lua</code> that just requires other files, with the actual plugin configs in lua/plugins/*.lua</code>. The scanner now merges details from all matching files instead of stopping at the first match.</p> Badges</h2> You can embed your setup in your README:</p> ![setup](https://cfgs.dev/api/badge/yourusername) </code></pre> This returns a shields.io style badge showing your top tools. There are options for filtering by category and changing the style.</p> What cfgs.dev is not</h2> Not a dotfile manager (use chezmoi, Stow, dotter, or bare git repos)</li> Not a package manager (use Nix, Homebrew, or your distro's package manager)</li> Not enforcing standards or best practices (your config, your choices)</li> Not replacing existing tools (it points to them, does not replace them)</li> </ul> What Works</h2> The declarative detector system is nice. Adding a new tool is just appending to a JSON file. No TypeScript, no build step, no tests to write. The refactor from code-based detectors to config-based ones removed 455 lines.</p> Browse-by-tool is useful for discovery. Instead of searching through random repos, you can see "here are 47 people using Helix" and look at their configs.</p> What Doesn't</h2> Scanning requires cloning repos locally, which takes time. A shallow clone of a typical dotfiles repo is fast, but large repos or slow connections can timeout. I cache scan results so subsequent visits are instant.</p> Detection accuracy varies. Simple tools are easy (if kitty.conf</code> exists, they use Kitty). Complex tools with many config locations are harder. Neovim alone has like 6 different places people put their config.</p> The data model is flat right now. There's no way to express relationships like "this person switched from packer to lazy.nvim" or "these configs are forks of each other." That might be interesting but it is a lot more complexity.</p> What's Next</h2> Multi-tool filtering. Right now you can browse by single tool, but "show me users with both Neovim and Kitty" isn't possible yet.</p> Similar setups. If you use Neovim with these 5 plugins, here are other people with similar configs. This requires some fuzzy matching logic but the data is there.</p> Better search. Right now it's browse-only. Being able to search by tool combinations, categories, or specific plugins would be useful.</p> If you have a dotfiles repo, add it. Anyone can submit any public dotfile repo - no login required. Paste the URL and the scanner does the rest. If you are the owner, you can log in with GitHub to claim your entry and update it later. The more setups in the index, the more useful it becomes as a living map of real developer workflows.</p> cfgs.dev</a> | GitHub</a></p> ARF: Structured Reasoning for AI Agents Unknown — Mon, 02 Feb 2026 00:00:00 +0000 The Problem with Prompts</h3> The deeper I get into building with LLMs, the more I realize the "chat prompt" model works but could be better.</p> When you give an agent an unstructured prompt, it runs with it. Sometimes brilliantly. Sometimes it hallucinates a photographer named "Chris Lawton" because it couldn't parse a webpage and decided to make something up instead of saying "I don't know." The lack of structure means the agent decides what matters, what to skip, and what to invent.</p> This is fine for casual Q&A. It falls apart when you're building tools that need to be auditable, reviewable, or predictable.</p> From lok to ARF</h3> I've been building lok</a>, an LLM orchestration tool that runs multi-step workflows across different backends. One thing became clear: the more structure I added, the better the results.</p> Workflows with explicit steps, defined inputs, and expected outputs work. Workflows that just say "figure it out" produce garbage as often as gold.</p> This led to a question: what if we standardized how agents communicate their reasoning? Not just "here's my answer" but "here's what I'm doing, why I'm doing it, how I plan to do it, and what I'll do if it fails."</p> The result is ARF (Agent Reasoning Format), a simple spec for structured agent reasoning.</p> The Format</h3> ARF records are TOML files with required and optional fields:</p> what = "Add retry logic to API client" why = "Transient failures causing user-visible errors" how = "Exponential backoff with 3 retries, circuit breaker after 5 failures" backup = "Revert to synchronous error handling if latency increases" timestamp = "2026-02-02T15:14:32Z" commit = "8ae882e6" </code></pre> Two fields are required:</p> what</strong>: The concrete action being taken</li> why</strong>: The reasoning behind the approach</li> </ul> Two fields are recommended:</p> how</strong>: Implementation details</li> backup</strong>: Rollback plan if it fails</li> </ul> The backup field is the interesting one. Forcing agents to declare a rollback plan before acting means they have to think about failure modes. It's the difference between "I'll refactor this function" and "I'll refactor this function, and if tests fail I'll revert to the original implementation."</p> Storage: Orphan Branches</h3> ARF records need to live somewhere. The options were:</p> Git notes (invisible, sync friction)</li> Nested repo (coordination overhead)</li> Orphan branch (separate history, same repo)</li> </ol> I ran a lok debate</a> across four LLM backends to evaluate the tradeoffs. All four converged on orphan branches.</p> The approach uses git worktrees to mount an orphan branch at .arf/</code>:</p> your-repo/ ├── .arf/ # Mounted worktree (arf branch) │ └── records/ │ └── 8ae882e6/ # Records by commit SHA │ └── claude-20260202-151432.toml ├── .git/ └── src/ </code></pre> Records are organized by commit SHA. When you record reasoning, it links to the commit you're working on. The .arf/</code> directory is gitignored from the main branch but has its own history on the orphan branch.</p> This keeps reasoning history completely separate from code history. You can push, pull, and sync reasoning records without touching your main branch.</p> The CLI</h3> The reference implementation is a Rust CLI:</p> # Initialize ARF tracking arf init # Record reasoning for current work arf record --what "Add graph command" \ --why "Need unified view of git history with reasoning" # View reasoning log arf log # Combined visualization arf graph </code></pre> The arf graph</code> command shows git commits alongside their reasoning records:</p> Git + ARF History: ├─● 8ae882e Add diff command with ARF reasoning context │ └─ what: Add diff command │ why: Combine git diff with ARF reasoning for full context review │ how: Shows reasoning header then git show output ├─● 5604413 Add graph command for unified git+arf visualization │ └─ what: Add graph command │ why: User requested visualization combining git commits with reasoning │ how: Matches commit SHAs to .arf/records/ directories ├─● 8ec6c98 Add ARF CLI reference implementation │ └─ what: Implement ARF CLI v0.1 │ why: Need reference implementation for spec │ how: Rust CLI with init/record/log/sync commands └─● 3384a83 Initial ARF spec v0.1 </code></pre> The arf diff</code> command shows a single commit with reasoning context:</p> ═══════════════════════════════════════════════════════════════ Commit: 8ae882e Add diff command with ARF reasoning context ═══════════════════════════════════════════════════════════════ REASONING: what: Add diff command why: Combine git diff with ARF reasoning for full context review how: Shows reasoning header then git show output ─────────────────────────────────────────────────────────────── CHANGES: src/main.rs | 118 +++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) </code></pre> This is "review the reasoning, not just the diff."</p> Why This Matters</h3> The shift happening in AI tooling is from unstructured to structured. Chat interfaces are training wheels. Production systems need:</p> Declared intent</strong>: What are you trying to do?</li> Explicit reasoning</strong>: Why this approach?</li> Failure planning</strong>: What if it breaks?</li> Audit trails</strong>: What happened and why?</li> </ul> ARF is one piece of this. It's not a replacement for git commit messages or PR descriptions. It's a parallel track for capturing reasoning that doesn't belong in code history but shouldn't be lost.</p> When an agent makes a change, the diff shows what changed. The ARF record shows why that approach was chosen over alternatives, what tradeoffs were considered, and what the rollback plan is.</p> Using It</h3> The spec and CLI are on GitHub: github.com/ducks/arf</a></p> Install with Cargo:</p> cargo install --git https://github.com/ducks/arf </code></pre> The format is intentionally minimal. Four fields, two required. Easy to generate, easy to parse, easy to extend.</p> If you're building agent tooling and want structured reasoning, try it out.</p> I Built a Robot to Help Me Understand People Unknown — Sat, 31 Jan 2026 00:00:00 +0000 I am good with machines and bad with people.</p> This is not false modesty. I can trace a request through twelve microservices and find the one misconfigured timeout. I can read a stack trace and know which library is lying. I can debug race conditions that only happen on Tuesdays.</p> But ask me to read a room? To pick up on what someone is really saying in a meeting? To notice when a coworker is frustrated before they explicitly say so? That is where I struggle.</p> Writing Is Easier</h2> I do better with written communication. Forum posts, Slack messages, pull request descriptions. When people write, they leave a trail I can actually follow. I can re-read it. I can search it. I can take my time.</p> In person, the signal moves too fast. By the time I have processed what someone said, we have moved on. I miss the subtext because I am still working on the text.</p> This is probably why I ended up in infrastructure. Machines do not have subtext. A 502 error is a 502 error.</p> Graham Duncan's Question</h2> A coworker recently wrote about Graham Duncan's framework for evaluating people. I had never heard of it, so I did some research. Duncan is an investor known for his approach to assessing people. His core question is:</p> "What's going on here, with this human?"</p> Not "are they qualified?" or "do they have the right experience?" but something deeper. What patterns show up in how they communicate? What do they care about? How do they handle disagreement? What are they not saying?</p> Duncan's framework breaks this down into dimensions:</p> Self-awareness and blind spots</li> Hidden motivations and fears</li> How they respond to stress and uncertainty</li> Contextual fit (right person, wrong role?)</li> </ul> I realized this is exactly what I struggle to do in real-time with coworkers. But what if I could do it asynchronously, with written artifacts, with a machine's help?</p> The Data Is Already There</h2> At Discourse, we use our own product internally. Years of forum posts, technical discussions, weekly updates, casual banter. A written record of how people think, communicate, and collaborate.</p> This is the kind of data I can actually work with.</p> So I built a tool. It pulls someone's forum activity, reads through their posts, and generates a structured evaluation. Communication style. Areas of expertise. How they handle disagreement. Patterns that emerge over time.</p> It is not a replacement for actually talking to people. But it gives me a starting point. A cheat sheet for understanding someone before I walk into a 1:1 or try to give feedback.</p> What It Actually Produces</h2> The output is a structured report:</p> Executive summary (what stands out about this person?)</li> Core strengths with evidence from actual posts</li> Growth areas, framed constructively</li> Communication profile (tone, clarity, patterns)</li> Collaboration dynamics (how do they work with others?)</li> Representative quotes that capture their voice</li> Discussion prompts for 1:1s</li> </ul> That last section is the most useful for me. Specific questions I can ask based on what someone has actually written about. Not generic "how's it going?" but "you mentioned being frustrated with X last month, how's that going?"</p> The Uncomfortable Part</h2> There is something uncomfortable about using a machine to understand people. It feels like cheating. Or like admitting a deficiency that maybe I should just work on directly.</p> But I have been "working on it directly" for decades and I am still bad at it. At some point you have to accept your constraints and build around them.</p> I use a calendar because I cannot remember appointments. I use a todo list because I cannot hold tasks in my head. I use version control because I cannot trust myself to not break things.</p> Why not use a tool to help me understand people?</p> Not a Replacement</h2> This does not replace actual human interaction. It is prep work. The same way you might review someone's recent commits before a code review, or skim their last few PRs before a 1:1.</p> The conversations still happen. The relationship still matters. I just show up slightly less clueless about what is going on with this human.</p> Try It</h2> The tool is open source if you want to try it:</p> claude plugin marketplace add ducks/person-eval claude plugin install person-eval@person-eval --scope user </code></pre> Then in Claude Code:</p> /person-eval username https://your-discourse-site.com </code></pre> Or with a timeframe for yearly reviews:</p> /person-eval username https://your-discourse-site.com 2025 </code></pre> It requires the discourse-mcp server to be configured, which gives Claude Code access to Discourse data.</p> The Irony</h2> The irony is not lost on me. I built a machine to help me understand humans because I understand machines better than humans.</p> But maybe that is fine. We all have different strengths. Mine happen to involve making robots do things. If I can make a robot help me be a better coworker, that seems like a reasonable trade.</p> The goal is not to replace human connection with machine analysis. The goal is to show up more prepared, more aware, more able to actually connect when the moment comes.</p> I am still bad with people. But I am getting better at compensating for it.</p> Lok Part 4: The Self-Healing Loop Unknown — Wed, 28 Jan 2026 00:00:00 +0000 Last time I showed lok finding 25 bugs in itself and creating GitHub issues automatically. Today it fixed one of those bugs, submitted a PR, and then found a real bug in Discourse that I just pushed upstream.</p> Agentic Workflows</h2> The missing piece was letting lok actually do things, not just talk about them. I added a few fields to the workflow TOML:</p> [[steps]] name = "fix" backend = "claude" apply_edits = true verify = "cargo build" prompt = """ Fix this issue. Output JSON: {"edits": [{"file": "src/main.rs", "old": "...", "new": "..."}], "summary": "..."} """ [[steps]] name = "commit" shell = "git add -A && git commit -m '{{ steps.fix.summary }}'" depends_on = ["fix"] </code></pre> Three new things:</p> shell</code> runs a command instead of querying an LLM</li> apply_edits</code> parses JSON from the LLM and patches files</li> verify</code> runs after edits to make sure they work</li> </ol> The {{ steps.fix.summary }}</code> bit extracts a field from the JSON output. You can also do {{ arg.1 }}</code> for positional arguments, so lok run fix-issue 42</code> passes 42 into the workflow.</p> Lok Fixes Itself</h2> Issue #25</a> was about a redundant Clone</code> implementation. The Delegator</code> struct already derives Clone, but there was a manual impl at the bottom of the file doing the same thing.</p> I ran the fix workflow:</p> lok run fix-issue 25 </code></pre> It analyzed the issue, generated an edit to delete the redundant impl, applied it, ran cargo build</code> to verify, committed with a message based on the fix summary, pushed the branch, and opened a PR.</p> The whole loop took maybe 30 seconds. I reviewed the diff, looked reasonable, merged it.</p> Finding Bugs in Discourse</h2> Feeling confident, I pointed lok at the main Discourse codebase:</p> lok hunt ~/discourse/discourse </code></pre> Both Codex and Claude found issues. Most were minor (confusing patterns, style things) but two stood out:</p> A chat job with a TODO saying "delete after 2025-01-01" that was still there in January 2026. Pure dead code.</p> </li> A bug in the thread serializer. It had this pattern:</p> </li> </ol> @opts[:include_thread_original_message].presence || true </code></pre> The problem is .presence</code> on false</code> returns nil</code>. So if you explicitly pass include_thread_original_message: false</code>, it gets converted to nil</code>, then || true</code> kicks in, and your option is ignored.</p> One controller was passing false</code> and getting true</code> back. Nobody noticed because the behavior difference is subtle, but it was definitely wrong.</p> I created two PRs: #37333</a> #37334</a></p> The Vision</h2> The pieces are coming together for a fully autonomous loop:</p> lok hunt --issues</code> finds bugs and creates GitHub issues</li> lok run fix-issue 42</code> analyzes, fixes, verifies, commits, opens PR</li> lok run review-pr 43</code> has multiple backends review the diff</li> If they agree, merge</li> </ol> Humans become exception handlers. You get pinged when the LLMs disagree or flag something they are not confident about. Otherwise the codebase quietly improves itself.</p> We are not there yet. The fix workflow needs better error recovery, the review workflow needs the debate mode integrated, and I want confidence scores on the merge decision. But the foundation is solid.</p> What's Next</h2> Honestly, I'm not 100% sure. I plan to just keep using it and adding/fixing things that I want or need. Stay tuned to see how the project evolves.</p> Next stop: unknown. But the tracks are laid.</p> Previous: Part 3: Dogfooding and Code Review</a></p> Lok Part 3: Dogfooding and Code Review Unknown — Tue, 27 Jan 2026 00:00:00 +0000 Part 2 ended with two promises: parallel workflow execution and dead code cleanup. Both happened. But the more interesting development was lok creating GitHub issues for bugs it found in itself.</p> Hunt with Issues</h2> The lok hunt</code> command scans for bugs using multiple LLM backends. The new --issues</code> flag takes it further: parse the findings and create GitHub issues automatically.</p> lok hunt --issues # Find bugs, create issues lok hunt --issues -y # Skip confirmation prompt lok hunt --issues --issue-backend gitlab # Force GitLab instead of GitHub </code></pre> The implementation auto-detects whether to use gh</code> (GitHub CLI) or glab</code> (GitLab CLI) by checking the git remote URL:</p> fn detect_from_remote(dir: &Path) -> Option<Self> { let output = Command::new("git") .args(["remote", "get-url", "origin"]) .current_dir(dir) .output() .ok()?; let url = String::from_utf8_lossy(&output.stdout).to_lowercase(); if url.contains("github.com") { Some(IssueBackend::GitHub) } else if url.contains("gitlab.com") || url.contains("gitlab.") { Some(IssueBackend::GitLab) } else { // Fall back to checking which CLI is installed // ... } } </code></pre> Self-hosted GitLab instances work too (the gitlab.</code> check catches gitlab.mycompany.com</code>).</p> Lok Reviews Itself</h2> The real test: run lok hunt --issues -y</code> on the lok repository itself.</p> $ lok hunt --issues -y Task: hunt Find bugs and code issues ================================================== [errors] === CLAUDE === 1. **Unchecked path canonicalization** - `src/main.rs:271` - Uses `unwrap_or_else` to silently fall back on failure - Backends expecting absolute paths may behave unexpectedly 2. **Unvalidated PR URL parsing** - `src/main.rs:1320-1323` - No validation that URL has enough path segments - Malformed URLs like `https://github.com/foo` will panic ... === CODEX === 1) src/cache.rs:121 — `read_to_string(...).ok()?` silently drops IO errors 2) src/workflow.rs:241 — `find(...).unwrap()` can panic on duplicate steps ... [perf] === CLAUDE === 1. **O(n×m) consensus checking** - `src/debate.rs:176-189` 2. **Regex compiled per interpolation call** - `src/workflow.rs:282-294` ... === CODEX === 1. `src/workflow.rs:89` — Linear `.find` over steps, O(n^2) with many steps 2. `src/workflow.rs:279` — Regex recompiled on every `interpolate` call ... [dead-code] === CLAUDE === 1. **src/backend/mod.rs:1-9** - Bedrock module feature-gated but never enabled 2. **src/cache.rs** - `Cache::clear()` method defined but never called ... </code></pre> Both backends found real issues. Claude and Codex agreed on several (the regex recompilation, the O(n^2) workflow lookups) and each caught things the other missed.</p> Then the issues got created:</p> ================================================== issues: Creating GitHub issues in ducks/lok Found 25 potential issues: 1. src/cache.rs:121 — silently drops IO errors 2. src/workflow.rs:241 — find(...).unwrap() can panic 3. Regex compiled per interpolation call ... Creating issue: src/cache.rs:121... ✓ https://github.com/ducks/lok/issues/1 Creating issue: src/workflow.rs:241... ✓ https://github.com/ducks/lok/issues/2 ... Creating issue: src/spawn.rs:381-384... ✓ https://github.com/ducks/lok/issues/25 ✓ Created 25 issues </code></pre> 25 GitHub issues from a single command. The tool found bugs in itself and opened tickets to track them. Each issue body includes the full finding context and which backend reported it.</p> PR Review</h2> The lok pr</code> command reviews GitHub pull requests:</p> lok pr 123 # Current repo lok pr owner/repo#123 # Specific repo lok pr https://github.com/o/r/pull/123 # From URL </code></pre> It fetches PR metadata and diff via gh</code>, constructs a review prompt, and sends it to the configured backends. Feedback is organized by severity (critical, important, minor, nitpick).</p> The value is having it as a single command instead of copy-pasting diffs into chat windows. Run lok pr</code> on your own PRs before requesting review. It catches the obvious stuff so human reviewers can focus on architecture.</p> Explain Mode</h2> The lok explain</code> command explains codebases:</p> lok explain # Current directory lok explain /path/to/project # Specific project lok explain --focus auth # Focus on specific aspect </code></pre> It gathers context automatically: README, package manifests (Cargo.toml, package.json, etc.), and a two-level directory tree. Then asks the backend to explain purpose, architecture, key files, and entry points.</p> The --focus</code> flag is useful for large codebases. Instead of explaining everything, ask specifically about auth, database access, or API structure.</p> lok explain ~/work/discourse --focus "background jobs" </code></pre> Context Detection</h2> Part 2 mentioned false positives from lok flagging N+1 queries in codebases that use auto-eager-loading. Context detection fixes this.</p> Lok scans for framework and tooling markers before constructing prompts:</p> pub struct CodebaseContext { pub detected_language: Option<String>, pub is_rails: bool, pub has_goldiloader: bool, pub has_bullet: bool, pub has_brakeman: bool, // ... } </code></pre> When running N+1 detection on a Rails app with Goldiloader, the prompt includes:</p> Note: This codebase uses Goldiloader for automatic eager loading. Many apparent N+1 patterns may be handled automatically. Focus on cases where Goldiloader wouldn't help.</p> </blockquote> This reduced false positives significantly. Check what lok detects with:</p> lok context . </code></pre> Parallel Workflows</h2> Steps without dependencies now run in parallel:</p> [[steps]] name = "patterns" backend = "codex" prompt = "Find code patterns" [[steps]] name = "dead-code" backend = "codex" prompt = "Find dead code" # These two run in parallel (no dependencies) [[steps]] name = "synthesize" backend = "claude" depends_on = ["patterns", "dead-code"] prompt = "Combine: {{ steps.patterns.output }} {{ steps.dead-code.output }}" </code></pre> For workflows that hit multiple backends, this cuts total time significantly. A three-backend scan that took 15 seconds sequentially now takes 6 seconds.</p> Diff Review</h2> lok diff</code> reviews local changes before committing:</p> lok diff # Staged changes lok diff --unstaged # All uncommitted changes lok diff main..HEAD # Branch vs main lok diff HEAD~3 # Last 3 commits </code></pre> Same idea as PR review, but catches issues before they become PR comments.</p> The Pattern</h2> A few days in, a usage pattern has emerged:</p> Exploratory work</strong>: Let Claude Code call lok ask</code> with different backends as needed. The LLM decides when to get second opinions.</p> </li> Repeatable analysis</strong>: Define workflows in TOML. Run with lok run</code>. Parallel execution makes multi-backend scans fast.</p> </li> Code review</strong>: lok diff</code> before committing, lok pr</code> before requesting review. Catches obvious issues early.</p> </li> Bug tracking</strong>: lok hunt --issues</code> to find bugs and create tickets in one command.</p> </li> </ol> Lok isn't trying to replace your LLM session. It's a tool your LLM session can use. The orchestration intelligence stays in the conductor (Claude, GPT, whatever you're chatting with). Lok just provides the interface to multiple specialized backends.</p> What's Next</h2> Those 25 issues on the lok repo need fixing. The O(n^2) workflow lookups and regex recompilation are the most impactful. The silent error swallowing in the cache layer should probably at least log warnings.</p> The PR review could be smarter about large diffs. Right now it truncates at 50k characters. Chunking with overlap would preserve context better.</p> And the issue creation could get smarter about deduplication. Right now it dedupes by title within a single run, but doesn't check for existing open issues with similar titles.</p> The source is at github.com/ducks/lok</a>.</p> Previous: Part 2: Workflows and Local LLMs</a> | Next: Part 4: The Self-Healing Loop</a></p> Lok Part 2: Workflows and Local LLMs Unknown — Sun, 25 Jan 2026 00:00:00 +0000 Since introducing Lok</a>, two features emerged from actual use: local LLM support via Ollama, and a declarative workflow engine. Both solve real problems I hit while using the tool.</p> Ollama: Local LLMs Without the API Tax</h2> Cloud APIs are great until they're not. Rate limits, quota exhaustion, latency spikes, privacy concerns. Sometimes you just want to run a model locally and not worry about any of that.</p> Ollama runs LLMs on your machine via a simple HTTP API. Lok now supports it as a first-class backend:</p> # ~/.config/lok/lok.toml [backends.ollama] enabled = true command = "http://localhost:11434" model = "llama3.2" </code></pre> lok ask --backend ollama "Explain this function" </code></pre> The implementation is straightforward. Ollama exposes a /api/chat</code> endpoint that accepts JSON. No CLI binary to shell out to, no stdout parsing. Just HTTP.</p> async fn chat(&self, prompt: &str) -> Result<String> { let request = ChatRequest { model: self.model.clone(), messages: vec![ChatMessage { role: "user".to_string(), content: prompt.to_string(), }], stream: false, }; let response = self.client .post(format!("{}/api/chat", self.base_url)) .json(&request) .send() .await?; // Parse response... } </code></pre> When to use Ollama:</strong></p> Privacy-sensitive codebases that can't hit external APIs</li> Avoiding rate limits during intensive analysis sessions</li> Cost control (no per-token billing)</li> Offline development environments</li> </ul> Trade-offs:</strong></p> Slower than cloud APIs on most hardware</li> Model quality depends on what you can run locally</li> Requires Ollama running as a daemon</li> </ul> In practice, I use Ollama for synthesis steps where I'm combining outputs from faster cloud models. The final summarization doesn't need to be fast, it needs to be private and reliable.</p> Workflows: Declarative Multi-Step Pipelines</h2> Single-shot LLM calls are useful, but real analysis often requires multiple passes. First a fast scan, then a deep investigation, then synthesis. Doing this manually means copy-pasting outputs between commands.</p> Workflows solve this by defining multi-step pipelines in TOML:</p> # ~/.config/lok/workflows/security-review.toml name = "security-review" description = "Multi-pass security review with synthesis" [[steps]] name = "initial-scan" backend = "codex" prompt = "Find obvious security issues: injection, auth bypass, hardcoded secrets" [[steps]] name = "deep-audit" backend = "claude" depends_on = ["initial-scan"] prompt = """ Review these findings and investigate deeper: {{ steps.initial-scan.output }} """ [[steps]] name = "synthesize" backend = "ollama" depends_on = ["initial-scan", "deep-audit"] prompt = """ Combine into a prioritized report: Initial: {{ steps.initial-scan.output }} Deep: {{ steps.deep-audit.output }} """ </code></pre> Run it with:</p> lok run security-review </code></pre> The output:</p> Running workflow: security-review Multi-pass security review with synthesis ================================================== [step] initial-scan ✓ (2.3s) [step] deep-audit ✓ (8.1s) [step] synthesize ✓ (4.2s) ================================================== Results: [OK] initial-scan (2.3s) Found 5 potential issues: 1. src/api/auth.rs:45 - SQL string interpolation ... [OK] deep-audit (8.1s) Investigated the SQL interpolation finding... ... [OK] synthesize (4.2s) ## Security Review Summary ### Critical (1) - SQL injection in auth.rs... </code></pre> Variable Interpolation</h3> The {{ steps.NAME.output }}</code> syntax passes previous step outputs into subsequent prompts. The workflow engine does a simple regex replacement before sending the prompt to the backend.</p> This is the key feature that makes workflows useful. Without it, you'd need manual copy-paste between steps. With it, you can build arbitrary pipelines where each step builds on previous results.</p> Dependency Resolution</h3> Steps declare dependencies with depends_on</code>. The engine performs a topological sort to determine execution order. Steps without dependencies can run in parallel (though the current implementation runs sequentially for simplicity).</p> [[steps]] name = "patterns" backend = "codex" prompt = "Find code patterns" [[steps]] name = "dead-code" backend = "codex" prompt = "Find dead code" [[steps]] name = "synthesize" backend = "claude" depends_on = ["patterns", "dead-code"] prompt = """ Combine findings: Patterns: {{ steps.patterns.output }} Dead code: {{ steps.dead-code.output }} """ </code></pre> The first two steps have no dependencies, so they could run concurrently. The third step waits for both to complete before running.</p> Conditional Execution</h3> Steps can include a when</code> clause for conditional execution:</p> [[steps]] name = "emergency-fix" backend = "claude" depends_on = ["scan"] when = "steps.scan.output contains 'critical'" prompt = "Propose immediate fixes for critical issues..." </code></pre> If the condition isn't met, the step is skipped with a [skip]</code> message. This keeps workflows from doing unnecessary work.</p> Workflow Discovery</h3> Workflows are loaded from two locations:</p> .lok/workflows/</code> in the current directory (project-local)</li> ~/.config/lok/workflows/</code> (global)</li> </ul> Project-local workflows override global ones with the same name. This lets you define team-wide workflows globally while allowing project-specific overrides.</p> lok workflow list </code></pre> Available workflows: security-review (global) Multi-pass security review with synthesis 3 steps code-quality (global) Multi-backend code quality analysis 3 steps rails-audit (local) Rails-specific security checks 4 steps </code></pre> The Plugin System Realization</h2> Here's the thing I didn't plan: workflows are plugins.</p> When you define a workflow, you're creating a reusable command. lok run security-review</code> isn't calling a built-in feature. It's loading a TOML file and executing it. The "plugin" is just configuration.</p> This means:</p> No compilation needed to add new capabilities</li> Share workflows by copying TOML files</li> Customize existing workflows without touching Rust code</li> Version control your workflows alongside your code</li> </ul> A future lok workflow install</code> could fetch workflows from URLs:</p> lok workflow install https://example.com/rails-audit.toml lok run rails-audit </code></pre> The plugin system is the workflow system. No separate concepts needed.</p> The Real Conductor: Your LLM Session</h2> Here's the pattern that actually works best: use your existing LLM as the conductor, and call lok as a tool.</p> I run Claude Code as my daily driver. When I need multi-model analysis, I don't switch to lok conduct</code>. I just ask Claude to use lok:</p> Me: Find performance issues in this codebase Claude: [runs: lok ask --backend codex "Find N+1 queries and performance issues"] Claude: I found 3 N+1 queries in the controllers. Let me get a second opinion on the caching strategy... Claude: [runs: lok ask --backend gemini "Review caching approach in lib/cache.rb"] Claude: Based on both analyses, here's what I'd prioritize... </code></pre> The LLM session becomes the orchestration layer. It sees results, reasons about them, decides when to query other backends. No need for lok to implement its own multi-round conversation loop.</p> This works because lok is just a command. It doesn't try to be a chat interface or maintain conversation state. It does one thing: send a prompt to backends and return results. The intelligence stays in the LLM that's already running.</p> The workflow engine complements this. For repeatable multi-step analysis, define a workflow. For exploratory work where you need to reason about intermediate results, let your LLM call lok directly.</p> Putting It Together</h2> Here's my actual workflow for auditing a new codebase:</p> Me: Audit this codebase for security issues Claude: [runs: lok run security-review] Claude: The workflow found 5 issues. The SQL interpolation in auth.rs looks serious. Let me investigate... Claude: [runs: lok ask --backend gemini "Is the SQL in auth.rs:45 exploitable?"] Claude: Gemini confirms it's exploitable. I'll draft a fix... </code></pre> Workflows handle the repeatable multi-step analysis. Claude handles the reasoning and follow-up questions. Lok is just the interface to multiple backends. Each layer does what it's good at.</p> What's Next</h2> The dead code that lok hunt</code> found in its own codebase still needs cleanup. There's also the question of parallel step execution in workflows, which would make multi-backend pipelines faster.</p> But the core loop is solid: define workflows in TOML, run them with one command, get multi-model analysis without the manual coordination tax.</p> The source is at github.com/ducks/lok</a>.</p> Previous: Introducing Lok</a> | Next: Part 3: Dogfooding and Code Review</a></p> I Don't Type Every Word You Read Unknown — Sun, 25 Jan 2026 00:00:00 +0000 Most modern work is already mediated by machines. Writing is just late to admit it.</p> Commerical pilots rarely fly planes by hand anymore. Chip designers do not solder transistors. Photographers do not grind their own lenses. Infrastructure engineers rarely flip physical switches in a datacenter.</p> In all of these fields, the work did not disappear. It moved upstream.</p> Writing is undergoing the same shift.</p> Where the Work Actually Is</h2> I do not type every word you read here.</p> That does not mean this writing is automated, synthetic, or detached from real experience. It means the locus of effort has changed.</p> The work now lives in:</p> deciding what is worth saying</li> knowing when something is wrong</li> recognizing when a paragraph feels hollow</li> choosing what to delete</li> setting constraints</li> maintaining direction</li> </ul> The model generates text. I decide what survives.</p> That distinction matters.</p> How I Actually Write Now</h2> Most posts start the same way they always have: with a thought that will not leave me alone.</p> Sometimes it comes from building something. Sometimes from frustration. Sometimes from noticing the same pattern repeat across tools, systems, or conversations.</p> I outline roughly. I write fragments. I ask an LLM to help me move past blank-page friction, not to decide what I believe.</p> I frequently discard its output entirely.</p> I interrupt it mid-paragraph when it drifts. I reframe prompts when the tone is wrong. I delete sections that feel technically correct but experientially false.</p> The process is not faster because I think less. It is faster because I spend less time fighting inertia.</p> Delegating Friction, Not Thinking</h2> This is the part people often get backwards.</p> I am not delegating authorship. I am delegating friction.</p> The same way a pilot delegates routine control to an autopilot in order to focus on situational awareness, failure modes, and judgment.</p> Automation does not reduce responsibility. It increases expectations.</p> When something goes wrong, there is still a human in the loop. There always is.</p> Is This Still Worth Reading?</h2> That is the question people tend to circle without asking directly.</p> If a post reflects real experience, real constraints, and real judgment, I do not care which tool helped shape the sentences.</p> Authenticity does not come from keystrokes. It comes from context.</p> You can feel the difference between writing that emerged from lived systems and writing that emerged from nowhere. Tools do not erase that distinction.</p> They amplify it.</p> Writing Did Not End. It Moved.</h2> We already accept this shift everywhere else.</p> We do not demand that pilots prove their worth by flying without instruments. We do not ask engineers to manage infrastructure without automation. We do not measure photographers by how manual their camera is.</p> We judge outcomes, judgment, and reliability.</p> Writing is no different.</p> The work did not disappear. It moved.</p> And learning where it lives now is part of the craft.</p> Introducing Lok: A Local Multi-LLM Orchestration Control Plane Unknown — Sat, 24 Jan 2026 00:00:00 +0000 Large language models are getting better, but they're also getting more specialized. Some are fast and direct for pattern matching. Others are slower but excel at deep, multi-step reasoning. If you work on real codebases, you've probably felt the pain: no single model is "best" for every task, and switching between tools manually is a constant tax.</p> That's the problem Lok solves.</p> The Brain That Controls the Arms You Already Have</h2> Lok is a local orchestration layer that coordinates multiple LLM backends through one control plane. It wraps existing CLIs like OpenAI's Codex and Google's Gemini, treating them as pluggable backends with a unified interface.</p> The key insight: model choice isn't a preference anymore. It's part of the engineering workflow. When your toolchain includes multiple LLMs, you need orchestration.</p> lok hunt . # Bug hunt with smart backend selection lok audit . # Security audit lok team "analyze" # Coordinated multi-model analysis lok debate "async?" # Let the models argue lok spawn "task" # Parallel agents on subtasks </code></pre> ┌─────────────┐ │ USER │ │ (task) │ └──────┬──────┘ │ ▼ ┌──────────────────────────────────────────┐ │ CONDUCTOR (BRAIN) │ │ │ │ • Analyze task complexity │ │ • Break into parallel subtasks │ │ • Assign backends via delegator │ └──────────────────┬───────────────────────┘ │ ┌────────────────────────┼────────────────────────┐ │ │ │ ▼ ▼ ▼ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ AGENT 1 │ │ AGENT 2 │ │ AGENT 3 │ │ "frontend"│ │ "backend" │ │ "database"│ │ [CODEX] │ │ [GEMINI] │ │ [CODEX] │ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │ │ │ │ ══ PARALLEL EXECUTION ══ │ │ │ │ └────────────────────────┼────────────────────────┘ │ ▼ ┌──────────────────────────────────────────┐ │ SUMMARIZATION PHASE │ │ │ │ • Collect all agent outputs │ │ • Report success/failure per agent │ │ • Aggregate into final summary │ └──────────────────────────────────────────┘ </code></pre> Mode Comparison</h2> Mode</th> Backends Used</th> Execution</th> Use Case</th></tr></thead> smart</td> 1 (best fit)</td> Single call</td> Fast, targeted tasks</td></tr> team</td> 1-3</td> Sequential</td> Analysis + optional peer review</td></tr> debate</td> 2+</td> 3 rounds</td> High-stakes decisions</td></tr> spawn</td> 2-4</td> Parallel</td> Complex tasks with subtasks</td></tr> </tbody></table> Smart Delegation: The Right Tool for the Job</h2> Not every task requires the most expensive, reasoning-heavy model. Conversely, complex security audits shouldn't be handled by a model optimized for speed.</p> Lok's delegator (src/delegation.rs</code>) routes tasks based on keyword matching and task classification:</p> N+1 queries, code smells, dead code</strong>: fast, pattern-matching models (Codex, Claude Haiku)</li> Security audits, architecture reviews</strong>: thorough, investigative models (Gemini, o1)</li> General questions</strong>: whatever's available (first responsive backend)</li> </ul> The routing logic is straightforward: task descriptions are tokenized and matched against known patterns. If the task contains "security", "audit", "vulnerability", it routes to investigative models. If it contains "find", "search", "pattern", it routes to fast models. No ML involved - just conditional routing based on task characteristics.</p> lok smart "Find N+1 queries" # Routes to Codex lok smart "Security audit" # Routes to Gemini lok suggest "Find SQL injection" # Shows routing decision without running </code></pre> When routing fails</strong>: If the chosen backend is unavailable, Lok falls back to the next-best available backend. If all backends fail, you get a clear error message listing what's offline.</p> Debate Mode: Built-In Skepticism</h2> Single-model answers are often too confident. Debate mode turns that into a feature by making backends disagree on purpose.</p> In lok debate</code>, each backend responds in multiple rounds. They see each other's answers and can challenge them. Round 1 is initial positions. Round 2 is responses to each other's positions. Round 3 is final synthesis by a judge model that weighs all perspectives.</p> lok debate "What's the best way to handle auth?" </code></pre> How synthesis works</strong>: The judge model receives all responses with their round numbers and prompts: "Given these competing perspectives, identify points of agreement, highlight unresolved disagreements, and synthesize a final recommendation that acknowledges tradeoffs."</p> This catches two failure modes:</p> False confidence</strong>: A single model confidently recommending an antipattern</li> Blind spots</strong>: One model missing a constraint that another catches</li> </ul> The cost is 3x the API calls and 2-4x the latency. Use it for decisions where being wrong is expensive.</p> Team Mode: Coordinated Analysis</h2> Team mode combines smart delegation with optional debate. It orchestrates the backends like a small group:</p> Choose the best available backend for the task</li> If debate is enabled, ask others to review or challenge</li> Synthesize a final result</li> </ol> lok team "Analyze this codebase for issues" lok team --debate "Should we use async here?" </code></pre> This gives you both the speed of a model that's good at the task and the rigor of peer review. In practice, it feels like having a lead engineer and two reviewers that don't get tired.</p> Spawn Mode: Parallel Agent Execution</h2> Spawn takes the coordination further. Instead of routing a single task to the best backend, it breaks a complex task into parallel subtasks and runs multiple agents simultaneously.</p> lok spawn "Build a todo app with frontend and backend" </code></pre> The flow:</p> Plan</strong>: An LLM breaks the task into 2-4 independent subtasks</li> Delegate</strong>: Each subtask gets assigned to the best available backend</li> Execute</strong>: All agents run in parallel with shared context</li> Summarize</strong>: Results are collected and aggregated</li> </ol> You can also specify agents manually:</p> lok spawn "Build an app" \ --agent "api:Build REST endpoints" \ --agent "ui:Build React components" \ --agent "db:Design the schema" </code></pre> This is the conductor pattern in CLI form. A brain that plans, delegates to specialized workers, and synthesizes results. The same pattern that makes human teams effective, applied to LLM orchestration.</p> The Naming Story</h2> "Lok" has two meanings, both relevant.</p> Locomotive</strong> (Swedish/German: lokomotiv). Lok has a conduct</code> command, and the metaphor is intentional: a conductor sends trained models down the tracks. The pun on "trained" models is deliberate.</p> Sanskrit/Hindi लोक</strong> ("world" or "people"), as in Lok Sabha, the People's Assembly. Lok's philosophy is a collection of agents working together, not a single monolithic mind.</p> The name captures both the engineering (orchestration, routing, coordination) and the philosophy (collective intelligence, multiple perspectives).</p> Configuration: Encode Your Team's Knowledge</h2> Lok works out of the box, but gets more powerful with lok.toml</code>:</p> [tasks.hunt] description = "Find bugs and code issues" backends = ["codex"] prompts = [ { name = "n+1", prompt = "Search for N+1 query issues..." }, { name = "dead-code", prompt = "Find unused code..." }, ] [tasks.audit] description = "Security audit" backends = ["gemini"] prompts = [ { name = "injection", prompt = "Find SQL injection..." }, { name = "auth", prompt = "Find auth bypass..." }, ] </code></pre> This isn't just configuration. It's a way to encode your team's knowledge about which model to trust for what. Tasks become repeatable workflows, not one-off experiments.</p> Why This Matters</h2> We're moving away from the era of "Prompt Engineering" and into the era of Flow Engineering. The quality of an AI output is no longer determined solely by how clever your prompt is, but by the architecture of the workflow that processes it.</p> By formalizing these flows into a CLI tool, Lok brings determinism and reliability to AI interactions:</p> Higher signal, lower noise</strong>: Smart delegation keeps the right model on the right task</li> Built-in skepticism</strong>: Debate and team modes catch errors and broaden coverage</li> Parallel execution</strong>: Spawn mode runs multiple agents simultaneously, turning sequential workflows into concurrent ones</li> Repeatable workflows</strong>: Tasks like lok hunt</code> become part of your engineering rhythm</li> Local control plane</strong>: No hidden SaaS layer, no opaque routing. You can see and customize how it chooses backends</li> </ol> Before and After: A Real Example</h2> Without Lok:</strong></p> # Manual workflow for finding Rails performance issues $ claude "Find N+1 queries in app/controllers" # Review output, switch tools $ gemini "Are there better caching strategies?" # Manually synthesize both answers # Total time: 5-10 minutes of context switching </code></pre> With Lok:</strong></p> # Single command, automatic backend selection and synthesis $ lok team --debate "Analyze Rails app for performance issues" # Codex finds N+1 queries (fast, pattern-matching) # Gemini suggests caching strategies (thorough, investigative) # Judge model synthesizes into prioritized action items # Total time: 2 minutes, no context switching </code></pre> The value isn't just speed - it's that you get both the exhaustive pattern matching and the strategic recommendations in one pass, with built-in skepticism from debate mode catching false positives.</p> Getting Started</h2> # Check what backends you have lok doctor # Ask all backends lok ask "Find performance issues" # Let them debate lok debate "Best approach for caching?" # Smart routing lok smart "Find N+1 queries" # Parallel agents lok spawn "Build a REST API with tests" </code></pre> Lok doesn't replace your LLMs. It coordinates them. That means you keep the tools you already trust and add orchestration on top.</p> Performance characteristics</strong>: Smart routing adds ~50-100ms overhead for task classification. Debate mode runs 3 rounds sequentially, so expect 3x the single-model latency. Spawn mode runs agents in parallel, so wall-clock time is determined by the slowest agent, not the sum of all agents.</p> The source is at github.com/ducks/lok</a>. It's Rust, it's fast, and it's the brain that makes your AI arms work together.</p> Next: Part 2: Workflows and Local LLMs</a></p> How Jennifer Aniston and Friends Cost Us 377GB and Broke ext4 Hardlinks Unknown — Fri, 23 Jan 2026 00:00:00 +0000 Intro</h2> It started with backup issues. Sites with hundreds of gigabytes of uploads were running out of disk space during backup generation. One site had 600+ GB of uploads and the backup process kept dying.</p> While looking into reliable large backups, we discovered something wild in one of those sites: the actual unique content was a fraction of the reported size. They were storing the same files over and over again, each with a different filename. The duplication was absurd.</p> So we shipped an optimization. Detect duplicate files by their content hash, use hardlinks instead of downloading each copy. I wrote some new tests, they all passed, it got approved and merged. But unfortunately, a fix like this is kind of hard to actually fully test.</p> Then someone ran it on a real production backup and hit a filesystem limit I didn't know existed. The culprit? A single reaction GIF, duplicated 246,173 times.</p> The Problem</h2> Discourse has a feature called secure uploads. When a file moves between security contexts (say, from a private message to a public post), the system creates a new copy with a randomized SHA1. The original content is identical, but Discourse treats it as a new file.</p> This happens constantly with reaction GIFs and popular images. Users share them across posts, embed them in PMs, repost in different categories. Each context creates another copy.</p> This is mostly fine for normal operation. But for backups, it's a disaster.</p> One customer had 432 GB of uploads. Unique content? 26 GB. The rest was duplicates. A 16x inflation factor, all going into the backup archive.</p> The Fix</h2> The fix seemed straightforward. Discourse tracks the original content hash in original_sha1</code>. During backup:</p> Group uploads by original_sha1</code></li> Download the first file in each group</li> Create hardlinks for the duplicates</li> </ol> Hardlinks point multiple filenames to the same data on disk. GNU tar preserves them, so the archive stores the data once. Download 26 GB, archive 26 GB, everyone wins.</p> def process_upload_group(upload_group) primary = upload_group.first primary_filename = upload_path_in_archive(primary) return if !download_upload_to_file(primary, primary_filename) # Create hardlinks for all duplicates in this group upload_group.drop(1).each do |duplicate| duplicate_filename = upload_path_in_archive(duplicate) hardlink_or_download(primary_filename, duplicate, duplicate_filename) end end </code></pre> The hardlink_or_download</code> method falls back to downloading if the hardlink fails:</p> def hardlink_or_download(source_filename, upload_data, target_filename) FileUtils.mkdir_p(File.dirname(target_filename)) FileUtils.ln(source_filename, target_filename) # Create hardlink increment_and_log_progress(:hardlinked) rescue StandardError => ex # Fallback: download if hardlink fails log "Failed to create hardlink, downloading instead", ex download_upload_to_file(upload_data, target_filename) end </code></pre> Shipped it and got positive feedback.</p> The Limit</h2> A colleague then used the new version to run a backup on a large site. The logs looked great:</p> 53000 files processed (25 downloaded, 52975 hardlinked). Still processing... 54000 files processed (25 downloaded, 53975 hardlinked). Still processing... ... 64000 files processed (25 downloaded, 63975 hardlinked). Still processing... 65000 files processed (25 downloaded, 64975 hardlinked). Still processing... Failed to create hardlink for upload ID 482897, downloading instead Failed to create hardlink for upload ID 457497, downloading instead Failed to create hardlink for upload ID 867574, downloading instead </code></pre> At 65,000 hardlinks, it started failing. Turns out ext4 has a limit: roughly 65,000 hardlinks per inode. One file can only have 65,000 names pointing to it.</p> The fallback worked and it didn't fail completely. The backup finished. But instead of one download for all 246,173 duplicates, we got one download plus ~181,000 fallback downloads after hitting the limit.</p> Still better than 246,173 downloads. But not the win I expected.</p> The GIF</h2> So what file had 246,173 copies?</p> Upload.where(original_sha1: '27b7a62e34...').count => 246173 Upload.where(original_sha1: '27b7a62e34...').first.filesize => 1643869 </code></pre> 1.6 MB. Duplicated a quarter million times. That's 377 GB of backup bloat from a single image.</p> And then I saw what it was...</p> </p> A reaction GIF. Used constantly in posts, PMs, everywhere. Each use in a different security context creates a new copy. 246,173 copies of Rachel from Friends doing a happy dance.</p> One GIF broke the hardlink limit.</p> The Math</h2> Without deduplication: 246,173 downloads, 377 GB transferred.</p> With deduplication (hitting limit): ~4 downloads, ~6.4 MB transferred.</p> The filesystem limit turned my "download once" into "download four times." I can live with that.</p> The Fix for the Fix</h2> My first instinct was to track hardlink counts and proactively rotate before hitting the limit. But a colleague pointed out the flaw: we have no idea what filesystem is being used. ext4 has one limit, XFS another, ZFS another. Picking a magic number is fragile.</p> Better approach: let the filesystem tell us when we've hit the limit.</p> def create_hardlink(source_filename, upload_data, target_filename) FileUtils.mkdir_p(File.dirname(target_filename)) FileUtils.ln(source_filename, target_filename) source_filename rescue Errno::EMLINK # Filesystem hardlink limit reached - copy and use as new primary FileUtils.cp(source_filename, target_filename) target_filename rescue StandardError => ex download_upload_to_file(upload_data, target_filename) source_filename end </code></pre> When Errno::EMLINK</code> fires, we already have the file locally. No need to re-download. Just copy it and use the copy as the new primary for subsequent hardlinks. Works on any filesystem, no configuration needed.</p> What I Learned</h2> Filesystems have opinions. ext4's hardlink limit exists to prevent certain classes of bugs and attacks. It's not arbitrary.</p> The fallback saved the feature. Without graceful degradation, that backup would have failed entirely. Instead it completed, just slower than optimal.</p> Production always finds the edge cases. 246,000 copies of one file is absurd. But absurd things happen at scale.</p> A few concrete takeaways:</p> Test for failure modes, not just success paths. The hardlink fallback was built-in from the start, but I never expected to actually need it.</li> Optimizations that reduce work by 16x still need to handle edge cases. A 99.998% improvement with graceful degradation beats a 100% improvement that crashes.</li> Track filesystem-level constraints early. Hardlink limits, inode counts, path lengths - these are real operational boundaries, not theoretical concerns.</li> </ul> And now I know Jennifer Aniston can stress-test infrastructure.</p> Links</h2> Discourse PR #37261</a> - The backup deduplication fix</li> Discourse PR #37293</a> - The hardlink limit fix</li> </ul> The Unholy Trinity: Nix Shells, SSH Config, and Claude Code Unknown — Wed, 21 Jan 2026 00:00:00 +0000 I wrote about using Claude Code for daily development</a> a few months ago. That post was about workflow and mindset. This one is about infrastructure.</p> Turns out, the real multiplier isn't how you prompt the AI. It's what you let it touch.</p> The Problem With AI Coding Assistants</h2> Most AI coding tools work in a sandbox. They can read your code, suggest changes, maybe run a linter. But the moment you need to actually test something, build something, deploy something? You're back to copy-pasting commands.</p> "Here's how you'd run the tests" is not the same as running the tests.</p> Claude Code is different because it has shell access. It can run commands, read output, iterate. But that only matters if the environment is set up for it.</p> Nix Shells: Run Anything, Anytime</h2> Every project I work on has a shell.nix</code>. When Claude needs to run something, the command is:</p> nix-shell --run "bundle exec rspec" </code></pre> That's it. No "first install Rust nightly, then set up ALSA, then configure pkg-config paths." The shell.nix declares everything. Claude doesn't need to know how to set up a Rust audio environment. It just needs to know nix-shell</code>.</p> Here's what my shelltrax</a> shell looks like:</p> { pkgs ? import <nixpkgs> {} }: let rust-overlay = import (builtins.fetchTarball "https://github.com/oxalica/rust-overlay/archive/master.tar.gz"); pkgs' = import <nixpkgs> { overlays = [ rust-overlay ]; }; rust = pkgs'.rust-bin.nightly.latest.default; in pkgs'.mkShell { buildInputs = with pkgs'; [ rust rust-analyzer pkg-config alsa-lib openssl gcc ]; } </code></pre> Claude can run tests, build releases, check for warnings. All without me explaining how to install Rust nightly or configure audio libraries.</p> The pattern works everywhere. Rust project? nix-shell --run "cargo test"</code>. Ruby project? nix-shell --run "bundle exec rspec"</code>. Node? Same deal. The AI doesn't need to understand package managers. It just needs one command that always works.</p> SSH Config: The Revelation</h2> I've had SSH config set up for years. Host pond</code> instead of typing IPs, key-based auth, the usual. Standard stuff for anyone who manages servers.</p> Host pond HostName 199.68.196.244 User ducks IdentityFile ~/.ssh/pond_ed25519 </code></pre> What I hadn't considered: Claude can use it too.</p> I was debugging why my analytics service was down. Normally I'd open another terminal tab, SSH in, check logs, come back and describe what I found. The usual dance.</p> Instead, on a whim, I just asked Claude to check the logs. And it did.</p> ssh pond "journalctl -u goatcounter -n 50" </code></pre> It found the error, suggested the fix, and I approved the command to restart the service. I never left the conversation.</p> That was the moment it clicked. My SSH config wasn't just for me anymore. Any host I can reach, Claude can reach. Any command I can run remotely, Claude can run remotely.</p> The Combination</h2> Here's where it gets interesting. These two things compound.</p> Locally, nix-shell means Claude can build, test, and run anything in any of my projects. Remotely, SSH config means Claude can check, restart, and deploy anything on my servers.</p> The AI goes from "helpful for writing code" to "helpful for everything."</p> Example from this week: I was debugging why a webhook wasn't firing. Claude:</p> Read the local webhook handler code</li> SSH'd to the server to check the logs</li> Found the error (SSL cert issue on callback URL)</li> Suggested the fix</li> I approved, it deployed</li> SSH'd back to verify the fix worked</li> </ol> That's five context switches I didn't have to make. Five terminal tabs I didn't have to open. And I stayed focused on understanding the problem instead of typing commands.</p> What This Enables</h2> With proper setup, Claude becomes useful for:</p> Local development</strong> - Run tests, check linting, build assets. Not "here's how to run tests" but actually running them and reading the output.</p> Server management</strong> - Check service status, read logs, restart processes. Actual ops work, not just suggesting commands.</p> Debugging across boundaries</strong> - Read local code, check remote logs, correlate the two. The AI can see both sides of the problem.</p> Deployments</strong> - On my NixOS server, nixos-rebuild switch</code> is the entire deploy process. Claude can run it.</p> The Trust Question</h2> "But do you really want AI SSH'd into your production server?"</p> Fair question. My answer: it's my personal VPS running hobby projects. The worst case is I rebuild it from my NixOS config. If this were production infrastructure at work, I'd be more careful.</p> But for personal stuff? The productivity gain is massive. And honestly, Claude is less likely to rm -rf /</code> than I am after a long day.</p> Setting It Up</h2> If you want to try this:</p> 1. Create shell.nix files for your projects</strong></p> Even a minimal one helps:</p> { pkgs ? import <nixpkgs> {} }: pkgs.mkShell { buildInputs = with pkgs; [ ruby nodejs yarn ]; } </code></pre> 2. Set up SSH config with key auth</strong></p> Host myserver HostName your.ip.here User youruser IdentityFile ~/.ssh/your_key </code></pre> 3. Tell Claude about it</strong></p> In your CLAUDE.md or context file:</p> "Use nix-shell --run</code> for commands in projects with shell.nix"</li> "SSH host myserver</code> is available for server operations"</li> </ul> That's it. Now your AI assistant has actual hands instead of just a mouth.</p> The Multiplier Effect</h2> Good tools multiply your output. AI is a good tool. But AI with proper environment access? That's a different category.</p> I'm not faster because the AI writes better code. I'm faster because the AI can actually verify what it writes. It can run tests, check logs, and iterate without me being the middleman.</p> The unholy trinity: Nix makes everything reproducible. SSH makes everything reachable. Claude ties it together.</p> Set up your environment right, and AI coding assistants stop being a novelty. They become infrastructure.</p> Letting AI Pick the Project Unknown — Mon, 19 Jan 2026 00:00:00 +0000 With the rise of AI and LLMs, a common theme has been "don't let the machine do the thinking". The argument is we simply become expensive copy and pasters. And while I mostly agree, I was curious.</p> Well, I tried an experiment today. Instead of coming to Claude Code with a specific task, I asked: "Based on everything you know, what would you build? Create a repo, use whatever language you want, document it along the way."</p> No constraints. No requirements. Just: build something.</p> What It Chose</h2> Claude chose to build why</code>, a CLI tool for code archaeology. The pitch:</p> I spend so much of my time helping people understand codebases, and the hardest question is always "why was this decision made?" The answer is scattered across git blame, old PRs, commit messages, issue trackers, maybe a Slack thread somewhere that's now lost.</p> </blockquote> The tool points at a file or line range and synthesizes a narrative: who introduced this code, when, what commits modified it, what issues and PRs are referenced, what type of changes they were (bug fix, feature, security patch).</p> why app/models/user.rb --range 100-150 </code></pre> The Story ========= This code was first introduced by Jeff Atwood on 2020-05-22. The initial commit said: "Revert 'Merge branch master'" Since then, it has been modified 5 time(s): * FIX: do not send rejection emails to auto-deleted users (#12160) by Arpit Jalan Type: Bug fix * SECURITY: Limit name field length of TOTP authenticators by OsamaSayegh Type: Security </code></pre> The Process</h2> What struck me was how Claude approached it. It started by reasoning about what problems it encounters repeatedly. Not what would be cool to build, but what it genuinely wished existed.</p> Then it moved fast. Within minutes: Rust project scaffolded, git blame parsing working, commit categorization logic, GitHub API integration. It tested on its own source code, then on Discourse (a large real-world codebase I work on).</p> When I suggested adding Discourse as a context source (we use it for work discussions), it designed a pluggable trait system:</p> #[async_trait] pub trait ContextSource: Send + Sync { fn name(&self) -> &str; fn detect_references(&self, text: &str) -> Vec<Reference>; async fn fetch_reference(&self, reference: &Reference) -> Result<Option<ContextItem>>; async fn search(&self, query: &str) -> Result<Vec<ContextItem>>; fn is_available(&self) -> bool; } </code></pre> GitHub and Discourse implementations, easy to add more. The architecture emerged naturally from the feature request.</p> The Tangents</h2> We went down a few rabbit holes. I mentioned that real context often lives in Slack threads that never got linked to the code. Claude immediately saw the harder problem: semantic search across communication history, not just following explicit links.</p> It outlined what that would require: embeddings, RAG pipelines, LLM synthesis. Then it asked the right question: "Worth building? Or is this scope creep from a useful simple tool into a research project?"</p> We also briefly explored turning it into an MCP server so Claude could call it during conversations. Another good idea, but another scope expansion.</p> I kept pulling back to "what's actually useful now" and Claude adjusted. No ego about its ideas. Just: "Good call. Let me clean up and commit."</p> What I Learned</h2> A few observations from this experiment:</p> First, the AI had genuine preferences. It didn't pick something random or impressive-sounding. It picked a tool that would help it do its job better. There's something interesting about that.</p> Second, the iteration loop was fast. Feature idea to working code in minutes. Not because the code was simple, but because there was no translation layer. Claude understood what it wanted and knew how to build it.</p> Third, scope management mattered. Left unchecked, we could have spent hours on semantic search and MCP servers. The human role was less about technical direction and more about "is this the thing we're building right now?"</p> The Tool</h2> why</code> is at github.com/ducks/why</a>. Rust, MIT licensed, about 900 lines. It actually works.</p> Whether I'll use it daily, I don't know. But it exists because I asked an AI what it would build if it could build anything, and it had an answer.</p> From Bash Scripts to NixOS: Real Declarative Infrastructure on a VPS Unknown — Sun, 18 Jan 2026 00:00:00 +0000 In my previous post</a>, I described running infrastructure with systemd services and bash scripts. It worked, but the update script kept growing with edge cases.</p> # This kept getting longer safe_download() { ... } update_goatcounter() { # Download binary # Stop service # Run migrations # Start service } # Repeat for each service... </code></pre> Every service needed special handling. GoatCounter needed database migrations. Scrob had "text file busy" errors. Downloads could 404 and block everything.</p> Three weeks in, the update script was 300+ lines with || true</code> scattered everywhere.</p> I wasn't managing infrastructure declaratively. I was writing imperative bash scripts to approximate declarative config.</p> The Inevitable Upgrade</h2> I already use NixOS for local development. My laptop runs it. My dev environments are nix-shell. I know how good it is for reproducibility.</p> The bash script approach was always temporary. I knew I'd migrate to NixOS eventually - I just wanted to get the services running first, understand what they needed, then declare it properly.</p> But after three weeks of bash edge cases, "eventually" became "now."</p> Creating pond-nix</h2> I created a new repo called pond-nix</code> with NixOS configuration for the same services:</p> # configuration.nix { imports = [ ./services/gitea.nix ./services/goatcounter.nix ./services/woodpecker.nix ./services/scrob.nix ./services/caddy.nix ]; networking = { hostName = "pond"; useDHCP = false; interfaces.ens3.ipv4.addresses = [{ address = "199.68.196.244"; prefixLength = 24; }]; defaultGateway = "199.68.196.1"; nameservers = [ "176.10.124.177" "176.10.124.136" ]; firewall.allowedTCPPorts = [ 22 80 443 ]; }; users.users.ducks = { isNormalUser = true; extraGroups = [ "wheel" ]; openssh.authorizedKeys.keys = [ "ssh-ed25519 AAAAC3... ducks@pond" ]; }; security.sudo.wheelNeedsPassword = false; } </code></pre> Each service gets its own module:</p> # services/goatcounter.nix { config, pkgs, ... }: { systemd.services = { goatcounter-jg = { description = "GoatCounter - stats.jakegoldsborough.com"; after = [ "network.target" ]; wantedBy = [ "multi-user.target" ]; serviceConfig = { ExecStart = "${pkgs.goatcounter}/bin/goatcounter serve -listen localhost:8081 -tls none -db sqlite+/var/lib/goatcounter-jg/goatcounter.db"; User = "goatcounter"; WorkingDirectory = "/var/lib/goatcounter-jg"; Restart = "always"; }; }; # ... other instances }; } </code></pre> No update scripts. No migrations to remember. Nix handles dependencies, service ordering, and restarts.</p> The Installation Challenge</h2> Installing NixOS on a VPS remotely is risky. Get the network config wrong and you're locked out.</p> The nixos-infect Trap</h3> My first thought was nixos-infect</code> - a script that converts an existing Linux system to NixOS in-place. Seems clever, right?</p> Maybe too clever?</p> I tried it on a fresh Arch install. The script started building, then hit an error:</p> swapon: /tmp/nixos-infect.swp: Invalid argument </code></pre> The problem:</strong> On Linux, /tmp</code> is mounted as tmpfs - a RAM-based filesystem. nixos-infect tried to create a 1GB swap file in RAM</em>. That's like trying to extend your RAM by using... RAM.</p> I patched the script to use /root/tmp</code> instead:</p> curl -o nixos-infect.sh https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect sed -i 's|mktemp /tmp/|mktemp /root/tmp/|g' nixos-infect.sh mkdir -p /root/tmp NIX_CHANNEL=nixos-24.05 bash nixos-infect.sh </code></pre> This time it worked! The build completed, the system rebooted...</p> And I was locked out.</p> nixos-infect generated a config, but with no console password and broken SSH access. I could see the NixOS login screen through the console, but couldn't log in. SSH timed out.</p> Lesson learned:</strong> In-place conversions are clever until they're not. When you're remote, clever is dangerous.</p> The ISO Approach</h3> I wiped the VPS and started over with the NixOS installation ISO.</p> Step 1: Mount the ISO</strong></p> Downloaded the NixOS 25.11 minimal ISO</a> and mounted it through Fornex's control panel, then I rebooted the VPS.</p> Step 2: Set up networking</strong></p> The installer gives you a root shell with no password. But before anything else, networking:</p> # Check interface name (mine was ens3, not eth0!) ip addr # Configure static IP ip addr add 199.68.196.244/24 dev ens3 ip link set ens3 up ip route add default via 199.68.196.1 echo "nameserver 176.10.124.177" > /etc/resolv.conf # Test it ping -c 2 google.com </code></pre> Step 3: Enable SSH</strong></p> passwd root # Set a temporary password systemctl start sshd </code></pre> Now I could SSH in from my local machine and use a proper terminal instead of the janky web console.</p> Step 4: Partition the disk</strong></p> GPT with GRUB needs a BIOS boot partition:</p> parted /dev/vda -- mklabel gpt parted /dev/vda -- mkpart primary 1MB 512MB # BIOS boot parted /dev/vda -- mkpart primary 512MB 100% # Root filesystem parted /dev/vda -- set 1 bios_grub on mkfs.ext4 /dev/vda2 mount /dev/vda2 /mnt </code></pre> The first partition stays unformatted - GRUB just needs it for bootloader code.</p> Step 5: Generate and customize config</strong></p> nixos-generate-config --root /mnt nano /mnt/etc/nixos/configuration.nix </code></pre> Key settings:</p> { boot.loader.grub.enable = true; boot.loader.grub.device = "/dev/vda"; networking = { hostName = "pond"; useDHCP = false; interfaces.ens3 = { # Not eth0! ipv4.addresses = [{ address = "199.68.196.244"; prefixLength = 24; }]; }; defaultGateway = "199.68.196.1"; nameservers = [ "176.10.124.177" "176.10.124.136" ]; firewall.allowedTCPPorts = [ 22 80 443 ]; }; users.users.ducks = { isNormalUser = true; extraGroups = [ "wheel" ]; openssh.authorizedKeys.keys = [ "ssh-ed25519 AAAAC3... ducks@pond" ]; }; security.sudo.wheelNeedsPassword = false; services.openssh = { enable = true; settings = { PasswordAuthentication = false; PermitRootLogin = "prohibit-password"; }; }; } </code></pre> Step 6: Install</strong></p> nixos-install # Set root password when prompted reboot </code></pre> After reboot, unmount the ISO through the control panel.</p> Step 7: SSH in with your user</strong></p> ssh ducks@199.68.196.244 </code></pre> It worked. NixOS booted, networking was correct, SSH keys worked. No lockouts.</p> Deploying the Real Config</h2> Now that NixOS is installed, time to deploy pond-nix:</p> # Clone your config git clone https://git.jakegoldsborough.com/ducks/pond-nix.git cd pond-nix # Deploy it (automatically fetches hashes, copies files, and builds) make install </code></pre> The Makefile handles everything: fetching binary hashes for packages, copying config files to /etc/nixos/</code>, and running nixos-rebuild</code>. One command builds and activates all services: Gitea, GoatCounter, Woodpecker, Scrob, Caddy. Everything starts declaratively.</p> If something breaks:</p> sudo nixos-rebuild switch --rollback </code></pre> One command. Back to the previous working state.</p> Migrating the Data</h2> With NixOS running and services configured, time to migrate data from the old server (burrow). I wrote a migration script to handle this:</p> # scripts/migrate-from-burrow.sh #!/usr/bin/env bash # 1. Stop services on pond (avoid database corruption) ssh pond 'sudo systemctl stop scrob goatcounter-jg gitea' # 2. Back up databases from burrow ssh burrow 'sudo tar czf /tmp/goatcounter-backups.tar.gz /var/lib/goatcounter-*' ssh burrow 'sudo tar czf /tmp/gitea-backup.tar.gz /var/lib/gitea' ssh burrow 'sudo -u postgres pg_dump scrob | gzip > /tmp/scrob-db.sql.gz' # 3. Copy to local machine (keep backups!) scp burrow:/tmp/*.tar.gz burrow:/tmp/*.sql.gz /tmp/backups/ # 4. Copy to pond and restore scp /tmp/backups/* pond:/tmp/ ssh pond 'cd /tmp && sudo tar xzf goatcounter-backups.tar.gz -C /' ssh pond 'cd /tmp && sudo tar xzf gitea-backup.tar.gz -C /' ssh pond 'gunzip < /tmp/scrob-db.sql.gz | sudo -u postgres psql scrob' # 5. Fix permissions ssh pond 'sudo chown -R goatcounter:goatcounter /var/lib/goatcounter-*' ssh pond 'sudo chown -R gitea:gitea /var/lib/gitea' # 6. Start services ssh pond 'sudo systemctl start goatcounter-jg gitea scrob' </code></pre> Run it:</p> ./scripts/migrate-from-burrow.sh </code></pre> All data migrated: Git repositories, analytics databases, scrobble history. Everything preserved.</p> Updating DNS</h2> Final step: point DNS to the new server. I use name.com's API:</p> # scripts/update-dns.sh export NAMECOM_USERNAME="your_username" export NAMECOM_TOKEN="your_api_token" ./scripts/update-dns.sh </code></pre> The script updates specific service A records to pond's IP (199.68.196.244):</p> code.jakegoldsborough.com</code> → Gitea</li> ci.jakegoldsborough.com</code> → Woodpecker</li> stats.jakegoldsborough.com</code> → GoatCounter</li> scrob.jakegoldsborough.com</code> → Scrob API</li> ui.scrob.jakegoldsborough.com</code> → Scrob UI</li> stats.date-ver.com</code> → GoatCounter</li> stats.gnarlyvoid.com</code> → GoatCounter</li> </ul> DNS propagates in a few minutes. Test with dig</code>:</p> dig code.jakegoldsborough.com +short # 199.68.196.244 </code></pre> Once DNS updates, Caddy automatically provisions Let's Encrypt certificates for all domains. No manual cert management needed.</p> What Changed</h2> Before (burrow-systemd):</strong> - 300+ lines of bash scripts - Manual version checking - Special migration handling per service - "Text file busy" errors - Download failures blocking other updates - || true</code> everywhere</p> After (pond-nix):</strong> - Declarative config in Nix - nixos-rebuild switch --upgrade</code> updates everything - Migrations run automatically (defined in service modules) - Atomic updates - One command rollback</p> Service Updates</h2> With systemd + bash:</p> sudo ./bin/update check # Check for updates sudo ./bin/update apply # Apply them # Hope nothing breaks </code></pre> With NixOS:</p> cd pond-nix git pull make install </code></pre> That's it. Pull the latest config, and the Makefile handles the rest: updating hashes, testing the config, and deploying atomically. If anything fails, the old generation still works.</p> The Tradeoff</h2> NixOS has a learning curve. Nix expressions are different from bash scripts.</p> But once you understand it, everything clicks: - System is reproducible - Updates are atomic - Rollbacks are instant - Configuration is versioned in git</p> No more "it works on my machine". The configuration is</em> the machine.</p> Was It Worth It?</h2> My update script was approaching 500 lines with safe_download()</code>, per-service migration logic, and error handling for every edge case.</p> Now it's ~500 lines of readable Nix across multiple modules. But those lines are: - Declarative - Type-checked - Composable - Reproducible</p> The difference: With bash, I was writing procedures</em>. With Nix, I'm declaring state</em>.</p> That's real declarative infrastructure.</p> Links</h2> pond-nix</a></li> nixos-infect</a></li> NixOS Manual</a></li> Previous post: Running Infrastructure with Systemd</a></li> </ul> Building Embedded Discourse Comments with Rust and WASM Unknown — Wed, 14 Jan 2026 00:00:00 +0000 I built an embedded comment widget that lets you add Discourse-powered comments to any static site with a single script tag. No iframe, no build step, just drop it in and it works.</p> <script src="https://unpkg.com/discourse-comments/dist/discourse-comments.min.js"></script> <discourse-comments discourse-url="https://forum.example.com" topic-id="123"> </discourse-comments> </code></pre> The widget fetches comments from a Discourse topic, renders them with a clean UI, and lets authenticated users post replies and like posts. All in a 725KB bundle with the WASM runtime inlined.</p> You can see the code here: discourse-comments on GitHub</a></p> Why Build This?</h2> Discourse has had an embedding feature for years, but it uses iframes. Iframes work, but they come with baggage: height management issues, styling isolation, auth cookie problems, SEO invisibility, accessibility complications. It's 2026 and we have web components, Shadow DOM, and ES modules. We can do better.</p> I wanted to see if a standalone component talking directly to Discourse's REST API could provide a cleaner experience. And I wanted an excuse to push some Rust into the browser.</p> The Stack</h2> The widget is built in three layers:</p> discourse-api-rs</a></strong> - A Rust client library for Discourse's API, compiled to WASM with wasm-bindgen</li> discourse-comments</a></strong> - A TypeScript web component that uses the WASM client</li> esbuild bundler</strong> - Inlines the WASM as base64 so the whole thing is a single file</li> </ol> The Rust layer handles HTTP requests, JSON parsing, and the OAuth flow. The TypeScript layer handles DOM rendering and user interactions. The bundler glues it together into a drop-in script.</p> The Hard Part: OAuth</h2> Getting read-only comments working was straightforward. The Discourse API is well-documented and predictable. But letting users post comments required authentication.</p> Discourse supports User API Keys, which are perfect for third-party clients. The flow works like this:</p> Generate an RSA key pair in the browser</li> Redirect to Discourse with the public key</li> User approves the app</li> Discourse encrypts an API key with the public key</li> Redirect back with the encrypted payload</li> Decrypt the payload with the private key</li> Store the API key for future requests</li> </ol> Sounds simple but there were issues.</p> The Base64 Whitespace Problem</h3> Discourse returns the encrypted payload as base64 in a query parameter. My code called atob(payload)</code> to decode it.</p> Problem: Discourse includes newlines in the base64 encoding. atob()</code> chokes on whitespace.</p> Fix: Strip whitespace first: payload.replace(/\s/g, '')</code>.</p> The RSA Padding Problem</h3> WebCrypto only supports RSA-OAEP for encryption/decryption. Discourse historically used PKCS1 padding, which WebCrypto can't handle.</p> Turns out Discourse added OAEP support in December 2025 (PR #36592). You pass padding=oaep</code> in the OAuth request and it encrypts with OAEP instead. But if your Discourse instance is older than that, you're stuck.</p> This one cost me hours of debugging before I found the version requirement.</p> The Like Button</h2> Once posting worked, adding likes was straightforward. The Discourse API has POST /post_actions</code> to like and DELETE /post_actions/:id</code> to unlike.</p> The UI shows a heart icon that toggles between outline (not liked) and filled (liked). Clicking it calls the API and updates the count. Nothing fancy, but it makes the widget feel more interactive.</p> One gotcha: you can't like your own posts. Discourse returns 403. I added a check to hide the like button on posts where yours: true</code>.</p> The Bundle</h2> Getting this to work as a single script tag required some bundler gymnastics. The WASM client needs its binary loaded somehow. Options:</p> Fetch it from a URL at runtime (requires hosting the .wasm file)</li> Inline it as base64 in the JavaScript bundle</li> </ol> I went with option 2. The esbuild plugin intercepts the WASM import, reads the binary, base64-encodes it, and injects code that decodes and instantiates it at runtime.</p> const wasmBuffer = fs.readFileSync(wasmPath); const wasmBase64 = wasmBuffer.toString('base64'); // In the bundle: const bytes = Uint8Array.from(atob(wasmBase64), c => c.charCodeAt(0)); await WebAssembly.instantiate(bytes, imports); </code></pre> This adds ~500KB to the bundle (the WASM binary), but eliminates the need for any separate file hosting. One script tag, everything works.</p> The Community Response</h2> I shared this experiment internally. The response was encouraging but also clarifying. Some on the core team pushed back on the WASM approach, preferring to stay within the existing Ember/Rails stack. Ember recently added support for rendering components to a DOM without spinning up an entire application instance, which could serve the same use case without introducing a new runtime.</p> I get it. Maintaining a Rust/WASM layer alongside an existing codebase adds complexity. But an "ever moving API target" concern feels overstated. This is a REST API with stable endpoints for fetching topics, creating posts, and liking. Compare that to AI integrations that build on LLM APIs from multiple vendors with breaking changes every few months.</p> The iframe suggestion also came up. That feels like a step backward. We have better tools now.</p> What I Learned</h2> WASM is production-ready.</strong> The toolchain (wasm-pack, wasm-bindgen) just works. Cross-compiling Rust to run in browsers isn't experimental anymore.</p> OAuth in the browser is tricky.</strong> The combination of cross-origin redirects, browser storage limitations, and encryption requirements creates a lot of edge cases. Test with real redirects, not just mocked flows.</p> Experiments spark conversations.</strong> Even if the official team goes a different direction, building a working prototype moved the discussion forward. Sometimes the value of an experiment is proving that a use case matters, not necessarily that your implementation is the right one.</p> Try It</h2> The widget works today with any Discourse instance running December 2025 or later (for the OAEP OAuth support).</p> discourse-comments on GitHub</a></li> discourse-api-rs on GitHub</a></li> npm package</a></li> </ul> Running VPS Infrastructure with Systemd Unknown — Sat, 10 Jan 2026 00:00:00 +0000 I run all my personal infrastructure on a single VPS using systemd services instead of Docker. No containers, no orchestration, just systemd units and bash scripts.</p> Why Not Docker?</h2> Docker is fine, but for a single VPS it felt like overhead. I wanted something simpler and built-in. I initially started with Docker but was constantly hitting networking issues with services communicating.</p> Systemd already handles process supervision, logging, and restarts. Why add another layer?</p> What's Running</h2> The VPS hosts:</p> Gitea</strong> - Git hosting at code.jakegoldsborough.com</li> Woodpecker CI</strong> - Continuous integration (idle for now)</li> Scrob</strong> - Music scrobbling server (see previous post</a>)</li> GoatCounter</strong> (3 instances) - Analytics for multiple sites</li> Caddy</strong> - Reverse proxy with automatic HTTPS</li> PostgreSQL</strong> - Shared database for Gitea, Woodpecker, and Scrob</li> </ul> Everything runs as dedicated system users with systemd units managing their lifecycle.</p> How It Works</h2> Caddy (reverse proxy + TLS) | +-- code.jakegoldsborough.com -> Gitea (port 3000) +-- ci.jakegoldsborough.com -> Woodpecker (port 8000) +-- scrob.jakegoldsborough.com -> Scrob (port 3002) +-- ui.scrob.jakegoldsborough.com -> Scrob UI (static files) +-- stats.jakegoldsborough.com -> GoatCounter (port 8081) +-- stats.date-ver.com -> GoatCounter (port 8082) +-- stats.gnarlyvoid.com -> GoatCounter (port 8083) </code></pre> Each service runs as a systemd unit. Caddy handles TLS termination and proxies requests to the appropriate backend.</p> The Repository Structure</h2> The entire setup lives in a git repo called burrow-systemd</code>:</p> burrow-systemd/ ├── systemd/ # Service unit files │ ├── gitea.service │ ├── woodpecker-server.service │ ├── scrob.service │ ├── goatcounter-*.service │ └── caddy.service ├── config/ # Service configurations │ ├── Caddyfile │ ├── gitea/app.ini │ ├── woodpecker/server.env │ └── scrob/scrob.env └── bin/ # Deployment scripts ├── bootstrap # Initial setup ├── deploy # Update and restart ├── update # Check and apply updates └── backup # Backup databases </code></pre> Configuration is declarative. Change a config file, commit, push, pull on the VPS, run ./bin/deploy</code>, done.</p> Bootstrap Script</h2> The bootstrap script sets up everything from scratch:</p> Installs packages (Caddy, PostgreSQL)</li> Downloads service binaries (Gitea, GoatCounter, Woodpecker)</li> Creates system users (gitea</code>, goatcounter</code>, scrob</code>, etc.)</li> Initializes PostgreSQL databases</li> Generates secure passwords and tokens</li> Copies config files from templates</li> Installs systemd service files</li> </ol> Run once on a fresh VPS:</p> sudo ./bin/bootstrap </code></pre> It generates a .env</code> file with all secrets and database passwords. This file is git-ignored and stays on the server.</p> Deploy Script</h2> The deploy script handles updates and restarts:</p> Updates configuration files (substitutes passwords from .env</code>)</li> Copies service files to /etc/systemd/system/</code></li> Reloads systemd</li> Creates databases if they don't exist</li> Enables and restarts all services</li> Checks service status</li> </ol> After changing config locally:</p> git add config/Caddyfile git commit -m "Update reverse proxy config" git push # On VPS cd ~/dev/burrow-systemd git pull sudo ./bin/deploy </code></pre> The deploy script is idempotent. Run it as many times as you want.</p> Service Updates</h2> Updates are automated via the update script. It checks GitHub releases for all services and downloads new binaries when available:</p> # Check what needs updating sudo ./bin/update check # Apply all updates sudo ./bin/update apply # Update specific service sudo ./bin/update apply gitea </code></pre> The script compares installed versions against the latest GitHub releases. If an update is available, it downloads the new binary, stops the service, replaces the binary, and restarts the service.</p> Scrob migrations run automatically on startup via sqlx::migrate!()</code>.</p> Simple and explicit.</p> Database Strategy</h2> PostgreSQL is shared across Gitea, Woodpecker, and Scrob. Each service gets its own database and user with limited permissions.</p> GoatCounter uses SQLite because each instance is independent. Three separate SQLite databases, three separate systemd units, three separate ports.</p> No database clustering, no replication, no complexity. Daily backups via cron are enough for my use case.</p> What Works</h2> Single command deployment (./bin/deploy</code>)</li> Automated binary updates (./bin/update</code>)</li> Centralized logging via journalctl</li> Automatic HTTPS via Caddy + Let's Encrypt</li> Service isolation via systemd users</li> Declarative config in git</li> Low memory footprint (no container runtime)</li> </ul> What Doesn't</h2> Can't easily move to a different host (not portable like containers)</li> Service isolation is weaker than containers</li> Harder to test locally (no docker-compose equivalent)</li> </ul> Security Model</h2> Each service runs as a dedicated system user</li> PostgreSQL only listens on localhost</li> TLS handled by Caddy (reverse proxy)</li> Secrets stored in .env</code> (git-ignored, mode 600)</li> No rate limiting (future work)</li> </ul> All services bind to localhost and are only accessible via Caddy's reverse proxy. The VPS firewall blocks everything except 80, 443, and SSH.</p> Reflections</h2> The best part is the simplicity. No Docker networking, no volume mounts, no image building. Just systemd units, config files, and bash scripts.</p> When something breaks, journalctl -u <service></code> shows exactly what went wrong. No container layers to debug.</p> The tradeoff is portability. This setup is tied to the specific VPS and filesystem layout. Migrating to a new server means running bootstrap again and restoring database backups.</p> For my use case, that's fine. I'm not running a multi-tenant SaaS. I'm hosting services for myself.</p> That's enough.</p> Links</h2> burrow-systemd</a></li> Scrob blog post</a></li> Gitea</a></li> Woodpecker CI</a></li> GoatCounter</a></li> Caddy</a></li> </ul> Building Scrob: A Self-Hosted Music Scrobbling Server Unknown — Fri, 02 Jan 2026 00:00:00 +0000 I wanted to track what music I listen to without sending that data to Last.fm. Part privacy preference, part self-hosting habit.</p> So I set up scrob</a> - a self-hosted scrobbling server that tracks my listening history and makes it shareable.</p> </p> </p> How It Works</h2> Scrob is a REST API server with a separate static UI:</p> Music Player (shelltrax, etc.) | v [POST /scrob] with Bearer token | v Scrob API (Axum + Rust) | v PostgreSQL (scrobbles + users) | v Scrob UI (static Svelte site) | v Public profile: ui.scrob.example.com/username </code></pre> The server authenticates clients via Bearer tokens, stores scrobbles in Postgres, and serves stats via REST endpoints. The UI is a static site that fetches data from the API.</p> Public Profiles</h2> The interesting part was adding public user profiles. Like Last.fm, I wanted people to be able to share their music taste via a URL: ui.scrob.jakegoldsborough.com/username</code></p> This required:</p> New public API endpoints (/users/:username/recent</code>, /users/:username/top/artists</code>, /users/:username/top/tracks</code>)</li> Privacy controls (users are public by default, can opt-in to private)</li> URL-based routing in the Svelte app</li> </ul> The privacy model is simple: a boolean is_private</code> column in the users table. Public endpoints check the flag and return 403 if private. Users can toggle it via /settings/privacy</code>.</p> Security Model</h2> Scrob uses token-based authentication:</p> Login with username/password to get a Bearer token</li> All scrobble submissions require Authorization: Bearer <token></code></li> Tokens are stored in the database with revocation support</li> Passwords are hashed with bcrypt</li> </ul> TLS is expected to be handled by a reverse proxy (Caddy, nginx, etc.). The server itself runs over HTTP.</p> Rate limiting is not currently implemented. Future work.</p> The Stack</h2> Backend</strong>: Rust + Axum + PostgreSQL + sqlx</p> Frontend</strong>: Svelte 5 + Vite + TypeScript</p> Client</strong>: Shelltrax</a> (my terminal music player)</p> Infrastructure</strong>: Systemd services on a VPS, no Docker</p> Scrob is straightforward. It's an API server that receives scrobble data, stores it in Postgres, and serves it back via REST endpoints. The UI is a static site that shows your listening history.</p> Try It</h2> If you want to run your own scrob instance:</p> Prerequisites: Rust 1.82+, PostgreSQL 12+, reverse proxy for TLS</li> Clone repo and build: cargo build --release</code></li> Set DATABASE_URL</code> environment variable</li> Migrations run automatically on first startup via sqlx::migrate!()</code></li> Create a user with ./scripts/bootstrap.sh</code></li> Start UI (separate repo: scrob-ui) or use API directly</li> </ul> See the README</a> for full details.</p> sqlx and Offline Query Caching</h2> Scrob uses sqlx</code> for compile-time checked SQL queries. This is great for type safety but annoying for CI: you need a database to compile.</p> The solution is cargo sqlx prepare</code> which generates a .sqlx/</code> cache of query metadata. Then CI can build with SQLX_OFFLINE=true</code> without needing Postgres.</p> The problem: running cargo sqlx prepare</code> manually is tedious. You need to spin up Postgres, run migrations, prepare the cache, tear it down.</p> I automated it with a Makefile:</p> prepare: @docker run postgres:16-alpine (port 5433) @Wait for postgres @cargo sqlx migrate run @cargo sqlx prepare @docker rm postgres </code></pre> Now make prepare</code> handles everything. One command, query cache updated.</p> Dev Tooling</h3> The prepare target must be rerun whenever you:</p> Add or modify SQL queries in the codebase</li> Create new migrations</li> Change database schema</li> </ul> Without updating .sqlx/</code>, CI builds fail with query verification errors. The cache is committed to git, so offline builds work without a live database connection.</p> Deployment</h2> The deployment setup is declarative:</p> Migrations live in the scrob repo</li> On startup, scrob automatically detects and runs new migrations via sqlx::migrate!()</code></li> The deploy script checks GitHub releases for new versions and only downloads if there's an update</li> Systemd restarts the service after updating the binary</li> </ul> No manual migration management. No separate migration runner. Single source of truth.</p> What Works</h2> Scrobbling from Shelltrax to the API</li> Public profile pages with recent scrobbles and top stats</li> Privacy toggle (public by default, opt-in private)</li> Automated migrations on startup</li> Version-aware deployment script</li> </ul> What Doesn't</h2> No album stats yet (just artists and tracks)</li> No client/player tracking (can't tell if you scrobbled from Shelltrax vs another client)</li> Limited metadata (no album art, genre tags, etc.)</li> UI is functional but basic</li> </ul> Reflections</h2> The best part of this project was the deployment automation. The make prepare</code> command and the version-checking deploy script make updates trivial. Push a tag, wait for CI, run sudo ./bin/deploy</code>, done.</p> Scrob isn't trying to compete with Last.fm's features... yet. It's a simple, self-hosted alternative that does one thing: tracks what you listen to and makes it shareable.</p> That's enough for now.</p> Links</h2> scrob (backend)</a></li> scrob-ui (frontend)</a></li> My public profile</a></li> </ul> 2025 - A Review Unknown — Wed, 31 Dec 2025 00:00:00 +0000 2025 Yearly Recap</h1> A Year of Building, Shipping, and Showing the Work</h2> 2025 was the year things stopped being ideas in progress and started becoming systems with gravity. Across code, writing, travel, and creative work, the through-line was consistency: small, composable pieces that add up to something durable.</p> The pace was intentional. Ship in public. Measure lightly. Let curiosity decide what compounds.</p> Open Source and Engineering</h2> This was a deeply technical year, but not driven by framework churn. It was about foundations.</p> Continued deep investment in Rust, especially for CLI and TUI tooling</li> Multiple self-authored tools reached real usability: Static resume generation</li> Budgeting and finance tooling</li> Audio and scrobbling infrastructure</li> </ul> </li> Strong preference for: Plain data formats</li> Deterministic builds</li> Git as a source of truth</li> </ul> </li> Clear move away from "just ship JSON" toward intentional data modeling</li> </ul> Alongside that:</p> Declarative systems (NixOS, Docker Compose, reproducible infra)</li> CLI-first design, with UI as a layer rather than a dependency</li> Energy-aware and sustainability-minded technical choices</li> </ul> A recurring pattern this year: build tools you actually want to use, then refine them until they feel obvious.</p> Writing, Blogging, and Metrics</h2> In 2025, the blog stopped feeling like a side project and started acting like a signal.</p> Consistent long-form technical writing</li> Multi-part series and deep dives</li> Willingness to publish unfinished thinking and iterate publicly</li> </ul> The results were quiet but meaningful:</p> Organic traffic from multiple search engines</li> Readers arriving via GitHub, chat tools, and RSS</li> Early signs of compounding interest rather than spikes</li> </ul> Metrics stayed in their place: feedback, not validation.</p> Travel and Perspective Shifts</h2> Travel this year was less about movement and more about recalibration.</p> Time spent in Europe, especially Central Europe, reinforced:</p> A preference for walkable cities</li> Public transit that works</li> Slower, more deliberate daily rhythms</li> </ul> It also sharpened longer-term thinking around relocation, digital-nomad feasibility, and how much infrastructure is actually needed to live well.</p> This wasn't escapism. It was alignment.</p> Disc Golf, Outdoors, and Sustainability</h2> Disc golf remained a grounding constant.</p> Not just as a hobby, but as:</p> A recurring design constraint (maps, data, APIs)</li> A sustainability touchstone</li> A reminder that systems should work outside, not just on screens</li> </ul> The focus subtly shifted from collecting and optimizing toward understanding spaces:</p> Courses as designed environments</li> Flow, access, and maintenance</li> How technology can support, not dominate, physical experiences</li> </ul> Creative Work Beyond Code</h2> 2025 also made room for making things with your hands.</p> Pottery experiments</li> Tufting and material exploration</li> Visual identity and logo work</li> </ul> These fed back into engineering work by reinforcing:</p> Process over output</li> Material constraints</li> Iteration without metrics</li> </ul> That cross-pollination showed up everywhere.</p> Career and Direction</h2> Professionally, this was a year of alignment.</p> The focus moved further toward:</p> Open-source adjacent work</li> Tooling that empowers communities</li> Infrastructure that disappears when it works</li> </ul> Rather than chasing titles or hype, the emphasis stayed on:</p> Taste</li> Maintainability</li> Systems that still make sense six months later</li> </ul> The result was confidence rooted in practice, not positioning.</p> The Shape of Things Going Forward</h2> If 2024 was about exploration, 2025 was about integration.</p> There is now:</p> A coherent technical stack</li> A public body of work</li> Clear values around sustainability, simplicity, and ownership</li> </ul> Most importantly, the year ends with momentum that feels calm rather than frantic.</p> That is the kind that lasts.</p> Building LLM-TUI: Never Lose Context Again Unknown — Tue, 16 Dec 2025 00:00:00 +0000 I am loving CLI agentic LLM apps except for one thing... and that's losing context.</p> You're working on a feature. You've shown the AI five files. You've explained your architecture. You're making progress. Then Claude crashes. Or you switch to a different project.</p> When you come back tomorrow, you start over. Re-explain everything. Re-share the files. Re-establish context.</p> I was taking daily notes but I got tired of that. So I built llm-tui.</p> It's a terminal interface for AI chat, but that's not the main feature. The main feature is it remembers. File context persists across sessions. Tool results get cached. You can close it, come back a week later, and pick up exactly where you left off.</p> What It Does</h2> You launch it, pick a model, and chat. But the devil's in the details.</p> Multi-Provider Support</strong></p> Switch between Ollama (local models on your machine), Claude API (Anthropic's hosted models), and AWS Bedrock (Claude via AWS). One interface, multiple backends.</p> Tool System</strong></p> When using Claude or Bedrock, the AI can Read files, Write files, Edit existing code, search with Glob and Grep, and run Bash commands. All sandboxed to your home directory. Every tool execution requires confirmation (y/n/q).</p> File Context Persistence</strong></p> Files read during a session get cached. When you reopen that session later, those files are already loaded. The AI remembers what it was looking at.</p> Session Management</strong></p> Create named sessions, organize them by project, rename and delete them. SQLite storage means everything persists and loads instantly.</p> Vim Keybindings</strong></p> Modal editing. Normal mode for navigation, insert mode for typing, command mode for session management. j/k to scroll, i to insert, Esc to escape. Feels natural.</p> Token Tracking</strong></p> Real-time display of token usage (Tokens: 1250/200000). When conversations get long, automatic context compaction kicks in at 75% capacity. Old messages get summarized, recent ones stay intact.</p> Why I Built It</h2> Context loss kills productivity. You're building a feature, the AI understands your codebase, and then you lose it all. Browser tabs close. Sessions expire. You switch projects and forget to save the conversation.</p> Starting over means minutes of setup every time. Copy file contents. Explain your architecture again. Re-establish what the AI already knew.</p> I needed persistence. Sessions that survive restarts. File context that doesn't disappear. A tool that picks up where you left off without re-explaining everything.</p> And I wanted control over which model handles the task. Local models for quick iteration. Claude when I need reasoning. Bedrock for AWS work. One interface, no lost context when switching.</p> The Tool System</h2> Context persistence only works if the AI can actually interact with your files. Browser-based chat requires copying code back and forth. Every file you want the AI to see means another copy-paste. Every change it suggests means manually applying edits.</p> The tool system fixes this. When using Claude or Bedrock, the AI can Read files, Write files, Edit code, search with Glob and Grep, and run Bash commands. All sandboxed to your home directory with explicit confirmation.</p> When the AI wants to read a file, it calls the Read tool. You see: Read /home/user/project/foo.rs? (y/n/q)</code>. Same for writes and edits. You approve or reject each action.</p> The key part: tool results get cached per session. If the AI reads config.toml</code>, that result stays in the session history. Next time you open that session, it already knows what was in that file. No re-reading. No re-explaining. The context persists.</p> The Future Is Weird</h2> As you can probably tell, I love and prefer open source software. Unfortunately, Claude does not fall into that category so I could not look at it for inspiration. So, I tried a wild idea. I simply asked Claude how it's tools worked and what the API response looked like. And you know what, it worked! I had Claude help me basically rebuild it's tools by internal reflection. The future is a trip, man.</p> Session Management</h2> This is where context persistence actually lives. Each session is a separate context with its own history, files, and conversation state. Work on multiple projects without mixing contexts. Switch between them without losing anything.</p> :new my-feature # New session with custom name :project discourse-yaks # Set current project :rename better-name # Rename current session </code></pre> Sessions are stored in SQLite at ~/.local/share/llm-tui/sessions.db</code>. Close the app, come back tomorrow, and every session is exactly as you left it. The AI still has all the files loaded. The conversation picks up mid-thought.</p> You can even load context from other sessions with :load session-name</code>. Pull in file context from a different project without manually re-sharing everything.</p> Provider Management</h2> Switch providers with a command:</p> :provider ollama # Local models :provider claude # Claude API (requires ANTHROPIC_API_KEY) :provider bedrock # AWS Bedrock (requires AWS credentials) </code></pre> The models screen (press 3</code>) shows all available models across all providers. Installed Ollama models marked with [installed]</code>. Current active model marked with [current]</code>.</p> You can download Ollama models directly from the TUI. Navigate to a non-installed model, hit Enter, and it pulls from the Ollama library. One keypress.</p> Automatic Context Compaction</h2> Long conversations hit context window limits. Most chat interfaces handle this by truncating old messages. You lose the early context that established your architecture decisions and project structure.</p> llm-tui summarizes old messages instead of dropping them. At 75% capacity, it sends old messages to the LLM for summarization. The summary replaces the original messages, keeping under 500 tokens. Recent messages (default: 10) always stay uncompacted.</p> You keep the context. The AI still knows what happened at the start of the conversation. You just use fewer tokens to maintain it.</p> The Stack</h2> Written in Rust. The UI is built with ratatui (terminal UI library). SQLite for storage via rusqlite and crossterm for terminal handling.</p> Three API clients: reqwest for Ollama's HTTP API, anthropic-sdk-rust for Claude, and AWS SDK for Bedrock.</p> Tool execution uses ripgrep (grep crate) for fast content search, glob for pattern matching, and walkdir for file traversal.</p> Built my own vim-navigator-rs library for the modal keybindings. Normal, insert, and command modes with proper vim-style navigation.</p> Configuration</h2> Config file at ~/.config/llm-tui/config.toml</code>:</p> autosave_mode = "onsend" # disabled/onsend/timer ollama_model = "llama2" ollama_context_window = 4096 claude_model = "claude-3-5-sonnet-20241022" claude_context_window = 200000 bedrock_model = "us.anthropic.claude-sonnet-4-20250514-v1:0" bedrock_context_window = 200000 autocompact_threshold = 0.75 # Compact at 75% capacity autocompact_keep_recent = 10 # Keep last 10 messages uncompacted </code></pre> Autosave modes: disabled (manual :w</code> only), onsend (save immediately when sending messages), or timer (save every N seconds).</p> Auto-start Ollama if not running (configurable). Set default provider. Pick your context window sizes.</p> Roadmap</h2> Still building. Next up:</p> OpenAI API integration</li> Setup wizard for API keys</li> Daily notes integration (load from my claude-notes directory)</li> Search functionality across sessions</li> Session export</li> Code block syntax highlighting</li> </ul> Final Thoughts</h2> Browser-based chat interfaces are fine for casual use. But when you're deep in development work, context loss becomes the bottleneck. Re-explaining architecture. Re-sharing files. Starting conversations from scratch.</p> llm-tui fixes that. Sessions persist. File context survives restarts. You pick up exactly where you left off. The AI remembers what it knew yesterday.</p> JOBL and SRG: Building Resume Tools I Actually Want to Use Unknown — Sun, 14 Dec 2025 00:00:00 +0000 After getting laid off from my last job, I told myself I would keep my resume updated and my options open. Then we had layoffs at Discourse. Nothing like watching coworkers lose their jobs to remind you that stability is an illusion and preparation matters.</p> I have been in a spec and tool building mood lately anyway. Something about the uncertainty makes me want to build things I can control. JOBL and SRG fit that mood perfectly.</p> The Problem</h2> I needed to update my resume. The last version was a LibreOffice doc. It was a pain in the ass. The formatting was fragile. One change and the whole thing shifted. Exporting to PDF was a gamble. And I could not version control it properly because it was a binary blob.</p> What I wanted: plain text I can edit in vim, version control in git, and generate HTML and PDF programmatically.</p> So I built it.</p> JOBL: A TOML Resume Format</h2> JOBL is a strict TOML-based resume format. The file extension is .jobl</code> and the structure is simple:</p> [person] name = "Jake Goldsborough" headline = "Infrastructure Engineer" email = "jake@example.com" location = "Portland, OR" summary = "Backend systems and deployment automation." [skills] Languages = ["Ruby", "Rust", "JavaScript"] Infrastructure = ["Docker", "Kubernetes", "NixOS"] [[experience]] title = "Software Engineer" company = "Discourse" start = "2025-06" end = "current" summary = "Infrastructure team, backend systems, deployment tooling." highlights = [ "Built postgres-manager HTTP service replacing MessageBus pub/sub", "Reduced duplicate operations and improved operational visibility" ] [[projects]] name = "Transit Tracker" url = "https://github.com/ducks/discourse-transit-tracker" summary = "Live departure board plugin for Discourse showing real-time transit arrivals" [[education]] degree = "BS Computer Science" institution = "State University" start = "2016" end = "2020" </code></pre> TOML is human readable. You can edit it in any text editor. Comments are supported. Syntax errors fail fast at parse time. Version control works perfectly because it is plain text.</p> Why TOML Instead of JSON or YAML</h2> JSON is for machines. Writing nested structures by hand is miserable. No comments. Trailing commas break everything. It is data interchange format, not a human authoring format.</p> YAML has too many footguns. Indentation matters. Multiple ways to express the same thing. The Norway problem (NO gets parsed as boolean false). Anchors and references add complexity I do not need.</p> TOML is boring in the best way. One obvious way to express each type. Strict validation. Native Rust support via serde. No surprises.</p> The Parser: Strict Validation</h2> JOBL uses a two phase validation approach:</p> Parse TOML into generic Value to catch unknown keys</li> Deserialize into typed structs for field validation</li> </ol> This catches typos immediately. If you write titel</code> instead of title</code>, you get an error with the exact path: experience[0].titel: unknown field</code>.</p> The parser collects multiple errors instead of failing fast. When you have five typos, you see all five at once instead of fixing them one at a time.</p> pub fn parse_file(path: &Path) -> ValidationResult<JoblDocument> pub fn parse_str(input: &str) -> ValidationResult<JoblDocument> </code></pre> Simple API. File or string in, validated document or errors out.</p> No Version Field</h2> I originally included a jobl_version</code> field in documents. Then I removed it.</p> Docker recently dropped version fields from their configs. The library version determines what spec you support. Simpler for users. They do not maintain a version field. The parser handles compatibility.</p> You can always add versioning later if you need it. Start simple.</p> SRG: Static Resume Generator</h2> JOBL handles data. SRG handles rendering.</p> srg --input resume.jobl --out dist --template minimal </code></pre> Reads your JOBL file, generates dist/index.html</code> and dist/resume.pdf</code>. Single binary. No dependencies except Chrome for PDF generation.</p> The HTML is self contained with embedded CSS. Email it. Put it on a static host. It just works.</p> PDF Generation: Headless Chrome</h2> I was skeptical about using headless Chrome for PDF generation. It seemed heavy and finicky. I've tried an HTML -> PDF method before with less than ideal results. But it works incredibly well.</p> The HTML you write is the PDF you get. Print media queries work exactly as expected. Local fonts load synchronously. No layout rewriting needed.</p> let pdf_data = tab.print_to_pdf(Some(PrintToPdfOptions { landscape: Some(false), display_header_footer: Some(false), // No browser artifacts print_background: Some(true), // Keep CSS backgrounds scale: Some(1.0), paper_width: Some(8.5), paper_height: Some(11.0), // ... margins, etc })) </code></pre> Alternative was native Rust PDF libraries like printpdf. That means manually positioning every element. Reimplementing layout logic. Maintaining two rendering paths (HTML and PDF).</p> Headless Chrome means one rendering path. CSS does the work. The PDF matches the HTML perfectly.</p> Layout System: Structure Without HTML</h2> Users should not need to write HTML to customize their resume. But they should be able to control structure and formatting.</p> The layout system is a simple DSL:</p> person name headline email experience title company start " - " end highlights education degree institution start " - " end </code></pre> Section names at indent level 0. Field names at level 2. Order matters.</p> Quoted strings are literals. Unquoted words are field names. Mix them:</p> person name "at" email "Location:" location experience start " - " end </code></pre> Renders as:</p> Jake Goldsborough at jake@example.com Location: Portland, OR 2025-06 - current </code></pre> The layout file controls what shows and in what order. The template (minimal, professional, etc) controls CSS styling. Separation of concerns.</p> Why Build This</h2> Practical answer: I needed to update my resume and existing tools did not fit how I work.</p> Real answer: building tools gives me a sense of control when everything else feels uncertain. Layoffs happen. Companies change. Markets shift. But code I write is mine. Specs I design are mine. Tools I build solve problems exactly how I want them solved.</p> This is not about resume formats. This is about responding to uncertainty by building something you own completely.</p> Current Status</h2> Both projects are functional and tested:</p> JOBL: 7 unit tests, strict validation, clean error messages</li> SRG: layout system with quoted strings, PDF generation working, 15 total tests</li> Combined: about 1800 lines of Rust, all passing tests</li> </ul> Documentation sites are up at https://jobl.dev</a> (plain HTML, no build step, Gruvbox theme with dark/light toggle).</p> Source is on GitHub if you want to look:</p> github.com/ducks/jobl</a></li> github.com/ducks/srg</a></li> </ul> Skin Shedding, Not Bikeshedding Unknown — Sun, 23 Nov 2025 00:00:00 +0000 Snakes shed their skin. They outgrow it, slough it off, and keep moving. They're still the same snake, just with a fresh layer, ready for whatever comes next.</p> I've been thinking about that lately.</p> This whole reflection started because I caught myself in yet another argument where nobody was building anything.</p> The Bikeshed Problem</h2> There's this concept in software development called bikeshedding. The term comes from an example about a fictional committee reviewing plans for a nuclear power plant. They breeze through the complex reactor design but spend hours debating the color of the bike shed. Why? Because everyone understands bike sheds. Everyone has opinions about paint.</p> In code, bikeshedding looks like endless debates about tab width, framework choices, naming conventions. Arguments about the "right way" to do things that could be resolved by just trying something and seeing if it works.</p> I've spent too much time in those debates.</p> The Weight of Being Right</h2> Here's what I've learned: arguing about code is exhausting. Not the technical discussions about trade-offs or the collaborative problem-solving. I mean the arguments. The "this is the only correct approach" discussions. The debates where everyone digs in and nobody builds anything.</p> I've been part of teams where every PR becomes a referendum on architectural philosophy. Where suggesting a different approach gets met with resistance before anyone's even tried it. Where the discussion thread is longer than the code changes.</p> It's draining. And worse, it's a trap. Because when you're arguing about whether to use Tool A or Tool B, you're not actually learning which one works better for your specific use case. You're just... arguing.</p> The Freedom of Not Knowing</h2> The truth is, half the time we don't know what will work until we try it. We think we do. We have intuitions, experience, opinions. But software is weird. Context matters. What worked great on one project might be wrong for another.</p> So instead, I just try things.</p> Not recklessly. Not without thought. But when faced with two reasonable approaches, instead of spending hours debating the merits, I'll pick one and build it. See how it feels. See where it breaks. See what I learn.</p> And you know what? Sometimes the "wrong" choice teaches me more than the "right" one would have.</p> Shedding Skin</h2> This is where the snake metaphor comes back. Shedding skin isn't about becoming a different snake. It's about not being constrained by what fit before.</p> For the most part, I'm the same developer I was six months ago. Same skills, same values, same approach to problem-solving. But I'm not carrying around the weight of old arguments anymore. I'm not defending approaches I used on past projects just because I invested ego in them.</p> I can use SQLite on one project and Postgres on another. I can use React here and Svelte there. I can experiment with different state management approaches and see what actually works instead of what I think should work.</p> The skin shedding isn't about the technology. It's about letting go of needing to be right before I've tried anything.</p> What This Looks Like</h2> Practically, this means:</p> Build small experiments. Don't debate for hours about whether approach A or B is better. Spend 30 minutes trying A and see how it feels. Then try B. Now you have actual data instead of theoretical arguments.</p> Ship things that might not be perfect. Perfect is the enemy of learning. Ship something that works, see how it breaks in the real world, iterate. You'll learn more in a week of production use than a month of pre-planning.</p> Change your mind without drama. "We're using X" doesn't have to be a permanent commitment. If it's not working, you can try Y. This isn't failure, it's iteration.</p> Judge by outcomes, not aesthetics. Code that's a bit messy but works reliably is better than code that's architecturally pure but brittle. The goal is to solve problems, not win style points.</p> All of this beats spending three hours arguing about the hypothetical failure modes of something nobody has tested.</p> The Meta Lesson</h2> Here's the thing: this post is about code, but it's not really about code. It's about how we approach problems when we don't know the answer yet.</p> Do we lock ourselves into positions before we have evidence? Do we defend our intuitions as if they're facts? Do we mistake confidence for correctness?</p> Or do we stay curious? Do we try things? Do we update our beliefs when we learn new information?</p> The snake sheds its skin because it has to. It's grown too big for the old one. We can do the same. We can outgrow old arguments, old certainties, old ways of working that don't serve us anymore.</p> We're still the same developers. We're just not trapped by what we thought we knew before we tried it.</p> Try It and See</h2> Last week, instead of debating the limitations of someone else's critique, I just built the tool I wished we had.</p> Next time you're in a debate about the "right" way to do something, ask yourself: would it be faster to just try it?</p> Not everything, of course. Some decisions are expensive to reverse. But a lot of what we argue about? It's just bike sheds. We could build both sheds, paint them different colors, and actually see which one we like better.</p> That's skin shedding. Letting go of the need to be right about things you haven't tried yet. Staying light, staying curious, staying open to learning from the next thing you build.</p> The old skin doesn't fit anymore. Time to shed it and keep moving.</p> Date-Ver: A Formal Spec for Date-Based Versioning Unknown — Sat, 15 Nov 2025 00:00:00 +0000 Yesterday I published yaml-janitor</a> using date-based version numbers like 20251115</code>. The version number is the release date. Automatic, meaningful, no decisions needed.</p> Then I realized there's no formal specification for this. Semantic versioning has semver.org</a> with strict rules and RFC 2119 language. Calendar versioning has calver.org</a>, but that's just a pattern guide, not a spec.</p> So I built date-ver</a>.</p> What It Is</h2> date-ver is a formal spec for date-based version numbers. Instead of 1.2.3</code> or 2.0.0</code>, you use 20251116</code>, 202511</code>, or 2025</code>.</p> The idea is simple: your version number is when you released, not what changed. Works great for applications, utilities, and distributions where users care about freshness over compatibility.</p> Why It Exists</h2> Projects have been using date-based versions forever. Ubuntu does 24.04</code> and 24.10</code>. yaml-janitor uses 20251115</code>. But without a formal spec, everyone makes up their own rules.</p> Questions that needed answers:</p> Can you mix formats? (Yes: 2024</code> → 202505</code> → 20250601</code> is valid)</li> Multiple releases per day? (Sequence numbers: 20251116.1</code>, 20251116.2</code>)</li> Pre-releases? (Use your separator: 20251116.alpha.1</code> or 2025-11-15-rc-2</code>)</li> Separators allowed? (Yes: 20251116</code> = 2025.11.16</code> = 2025-11-16</code>)</li> </ul> date-ver answers all of these with proper RFC 2119 language.</p> The Separator Decision</h2> Ubuntu uses dots (24.04</code>). yaml-janitor uses nothing (20251115</code>). Some projects use hyphens or slashes. Rather than force everyone to change, date-ver allows any single-character separator as long as you're consistent throughout the entire version string similar to regex.</p> Valid:</p> 20251116</code> (no separator)</li> 2025.11.16</code> (dots throughout)</li> 2025-11-16</code> (hyphens throughout)</li> 2025/11/16</code> (slashes throughout)</li> 20251116.alpha.1</code> (dots for everything)</li> 2025-11-15-rc-2</code> (hyphens for everything)</li> </ul> Invalid:</p> 2025.11-16</code> (mixed separators in date)</li> 20251116-alpha.1</code> (mixing none with hyphen and dot)</li> </ul> Pick one separator and stick to it. All separator styles are equivalent. To compare versions, strip separators and compare digits. Simple.</p> Pick Your Precision</h2> Projects choose their granularity:</p> Year: 2025</code></li> Year-month: 202511</code> or 2025.11</code></li> Year-month-day: 20251116</code> or 2025.11.16</code></li> </ul> More specific = higher precedence: 2025 < 202501 < 20250101</code></p> Start with yearly versions and switch to monthly or daily whenever. No breaking changes, just more precision when you need it.</p> When to Use It</h2> Good fit:</p> Applications with regular releases</li> Operating systems and distributions</li> Tools where freshness matters</li> Internal utilities</li> </ul> Bad fit:</p> Libraries where compatibility matters</li> APIs with semver expectations</li> Projects with strict dependency contracts</li> </ul> Need to signal breaking changes? Use semver. Need to signal release timing? Use date-ver.</p> Building It</h2> Wrote the spec following semver's structure:</p> Summary</li> Introduction</li> Numbered rules with RFC 2119 language</li> FAQ</li> Examples</li> </ul> Built a website with GitHub Pages, Gruvbox colors, and automatic dark mode. The spec itself uses date-ver 20251115</code> (it originally said 1.0.0</code> which was pretty ironic).</p> That's It</h2> date-ver exists. The spec is done, the domain is live, and the website is up at date-ver.com</a>.</p> Ubuntu is officially valid date-ver. So is yaml-janitor. Any project using date-based versions can point to the spec now.</p> Maybe it catches on. Maybe it doesn't. Either way, there's a formal answer when someone asks "why are your versions dates?"</p> The version is the release date. That's date-ver.</p> Full spec: date-ver.com</a> Source: GitHub</a> (CC BY 4.0)</p> Building yaml-janitor: Solving the Comment Preservation Problem Unknown — Fri, 14 Nov 2025 00:00:00 +0000 For the past five years, there's been an intermittent problem at work: sometimes, when editing YAML configuration files with automated tools, comments get destroyed. The comments contain critical context like why certain values exist or what not to change, so losing them causes real problems when trying to maintain infrastructure configuration.</p> A coworker tried to solve this in 2021 by building tooling around psych-pure, a pure Ruby YAML parser that can preserve comments. But psych-pure wasn't stable enough at the time, so the project stalled.</p> Fast forward to 2025, and I happened to be looking through devops topics and stumbled upon this one. This seemed like the perfect opportunity to revisit the comment preservation problem.</p> The Initial Validation</h2> I started by writing a simple validation script using psych-pure to check if our production YAML files could survive a round-trip: load the file, dump it back out, and verify the semantics stayed the same.</p> require 'psych/pure' yaml_content = File.read('config.yml') loaded = Psych::Pure.load(yaml_content, comments: true) dumped = Psych::Pure.dump(loaded) # Verify semantics match original_data = Psych::Pure.load(yaml_content) dumped_data = Psych::Pure.load(dumped) if original_data == dumped_data puts "✅ Semantics preserved" else puts "❌ MISMATCH" end </code></pre> I ran this against 1,736 production YAML files across two repositories. The good news: no corrupt YAML! Most files validated successfully, with only a handful failing due to using patterns that are technically invalid per the YAML spec (though the C implementation of Psych accepts them anyway).</p> Building yaml-janitor</h2> With validation working, I built a proper linter around psych-pure. The key challenge was that while psych-pure preserves comments when loading, its built-in dump function doesn't give enough control over formatting. I needed custom formatting rules like consistent indentation and compact array notation.</p> Here's what yaml-janitor fixes:</p> # Before: mixed indentation, explicit array format config: # Database settings database: host: localhost port: 5432 features: - name: caching enabled: true # After: consistent indentation, compact arrays config: # Database settings database: host: localhost port: 5432 features: - name: caching enabled: true </code></pre> The solution was to build a custom emitter that walks the loaded data structure and outputs formatted YAML while preserving all comments:</p> class Emitter def initialize(node, config) @node = node @config = config @output = [] end def emit emit_comments(get_comments(@node, :leading), 0) emit_document(@node) @output.join("\n") + "\n" end def emit_mapping(hash, indent) entries = hash.respond_to?(:psych_keys) ? hash.psych_keys.map { |pk| [pk.key_node, pk.value_node] } : hash.to_a entries.each_with_index do |(key, value), index| emit_comments(get_comments(key, :leading), indent) key_str = scalar_to_string(key) case value when Hash, Array @output << "#{' ' * indent}#{key_str}:" emit_node(value, indent + indentation) else value_str = scalar_to_string(value) @output << "#{' ' * indent}#{key_str}: #{value_str}" end emit_comments(get_comments(key, :trailing), indent) end end end </code></pre> This gave me complete control over formatting while preserving every comment. The emitter handles:</p> Consistent indentation (2 or 4 spaces)</li> Compact array format (dash on same line as first key)</li> Comment placement (leading and trailing)</li> Blank lines between top-level sections</li> </ul> Production Testing</h2> I tested yaml-janitor on a production file with mixed 2-space and 4-space indentation:</p> # Backup original cp pipeline.yaml /tmp/pipeline_backup.yaml # Fix with yaml-janitor yaml-janitor --fix --indentation 2 pipeline.yaml # Verify semantics preserved ruby -ryaml -e " orig = YAML.load_file('/tmp/pipeline_backup.yaml') fixed = YAML.load_file('pipeline.yaml') puts orig == fixed ? '✅ Semantics preserved' : '❌ MISMATCH' " # Output: ✅ Semantics preserved </code></pre> The fix worked perfectly. Consistent indentation, all comments preserved, and semantics verified to be identical.</p> Configuration System</h2> I added a configuration file system so teams can standardize their YAML formatting:</p> # .yaml-janitor.yml indentation: 2 line_width: 80 sequence_indent: false rules: consistent_indentation: enabled: true multiline_certificate: enabled: true </code></pre> The CLI supports both config files and command-line overrides:</p> yaml-janitor --config .yaml-janitor.yml files/*.yml yaml-janitor --fix --indentation 2 config.yml </code></pre> Publishing to RubyGems</h2> Once the linter was working, I published it to RubyGems so anyone could use it. I set up automated publishing with GitHub Actions and RubyGems trusted publishing (no API keys needed):</p> name: Publish to RubyGems on: push: tags: - 'v*' jobs: publish: runs-on: ubuntu-latest permissions: contents: read id-token: write steps: - uses: actions/checkout@v4 - uses: ruby/setup-ruby@v1 with: ruby-version: '3.3' bundler-cache: true - uses: rubygems/release-gem@v1 </code></pre> The release process is now fully automated:</p> Update version number (date-based: YYYYMMDD)</li> Run bundle install</code> to update lockfile</li> Commit and push to main</li> Create and push tag: git tag v20251113 && git push origin v20251113</code></li> GitHub Actions automatically publishes to RubyGems</li> </ol> Results</h2> yaml-janitor is now published and available on RubyGems:</p> gem install yaml-janitor yaml-janitor --help </code></pre> Production validation results:</p> Scanned 1,736 YAML files</li> Found 0 corrupt files</li> Fixed widespread formatting inconsistencies</li> Preserved all comments during fixes</li> </ul> People are already using it to lint their YAML configurations.</p> The Five-Year Solution</h2> The problem my coworker identified in 2021 is finally solved. Teams can now safely automate YAML editing without losing critical context in comments. The infrastructure was already there, it just needed psych-pure to stabilize and someone to finish building the tooling.</p> yaml-janitor is open source and available on GitHub</a> and RubyGems</a>. If you've ever had to choose between manual YAML editing and losing your comments, check it out.</p> Like a Pig in Shit: Why I Love AI "Slop" Unknown — Sat, 08 Nov 2025 00:00:00 +0000 I've shipped more projects in the last three months than I did in the previous year. Are they all perfect? No. Are they all polished production-grade code? Hell no. Do I care? Not even a little bit.</p> I'm having the time of my life building whatever idea pops into my head, and AI is the reason I can actually finish things instead of just thinking about them.</p> And look, shipping isn't everything. Sometimes the best code never sees the light of day. Sometimes you build something just to learn, or just because it sounds fun. But there's something deeply satisfying about making things that actually work - even if they're just for you.</p> What I've Been Building</h2> In the last few months alone:</p> vimdeck.nvim</a></strong>: Markdown presentations in Neovim using Treesitter</li> mdpreview.nvim</a></strong>: Live markdown preview in a split window</li> discourse-yaks</a></strong>: Virtual currency system for forum posts</li> discourse-transit-tracker</a></strong>: Turn forums into live departure boards</li> discourse-invite-stats</a></strong>: Invite reporting and analytics plugin</li> shelltrax</a></strong>: TUI music player in Rust (my daily driver now)</li> Plus a handful of smaller tools and fixes</li> </ul> Some of these are polished. Some are "good enough for me." All of them work. All of them solve real problems I had. And I built most of them in a day or two.</p> The "Slop" Criticism</h2> There's this narrative that AI-generated code is "slop." Low quality, generic, copy-pasted garbage that's polluting the internet. And sure, that exists. That existed before AI when people would blindly copy from Stack Overflow. But the criticism misses something important:</p> When you're building for yourself, "slop" doesn't matter.</p> I'm not pushing half-baked code to production systems. I'm not claiming my afternoon projects are enterprise-ready. I'm building tools that solve my problems, learning by doing, and having fun.</p> If the markdown preview plugin has rough edges, who cares? It works for me. If the presentation tool doesn't handle every edge case, so what? It renders my slides.</p> The "slop" criticism only matters when you're shipping garbage and calling it gold. When you're building for yourself? Ship it, iterate, move on.</p> What's Actually Happening</h2> Here's what working with AI looks like for me:</p> I have an idea. "I want to do presentations in Neovim." Instead of spending a week researching markdown parsers and figlet integration and buffer management, I describe what I want and start building.</p> The AI suggests approaches. Some work. Some don't. We iterate. I learn what Treesitter can do. I understand how Neovim's highlight system works. I see patterns I wouldn't have thought of.</p> A few hours later, I have a working plugin.</p> Is it perfect? No. Did I learn a ton? Yes. Can I actually use it? Absolutely.</p> The Joy of Building</h2> What the critics miss is how much fun this is.</p> I used to have a backlog of ideas that never got built. "Someday I'll make that." "That would be cool but it's too much work." "I don't have time to learn X framework."</p> Now? I just build it.</p> Want to visualize invite relationships as an ASCII tree? Build it. Want live transit departures in a forum? Build it. Want to fix a bug in a YAML parser? Build it and submit the fix upstream.</p> The barrier between "I wish this existed" and "I built this" has collapsed. And that's incredible.</p> But Is It Actually Good Code?</h2> Sometimes yes, sometimes no. And that's fine.</p> The Ruby psych-pure bug fix</a> I submitted? That's good code. Full test coverage, proper edge case handling, clean implementation. It's going into a production library.</p> The transit tracker</a>? It works, handles 500k+ MTA stop times, and has solid patterns for data downloading and parsing. Could the UI be more polished? Sure. But it does what I need and I learned a ton building it.</p> The key is knowing the difference. When it matters, I put in the work. When it's just for me, I ship it and move on.</p> The Real Productivity Hack</h2> Working with AI isn't about replacing thinking. It's about spending your brain cycles on the interesting problems instead of the boring setup work.</p> I don't want to spend three hours setting up test infrastructure. I want to spend three hours solving the actual problem. AI handles the grunt work. I handle the decisions.</p> You Can Vibe and Still Be Productive</h2> Here's the thing: you can have fun, move fast, and still produce quality work. It's not either/or.</p> I'm "vibing out" projects. Building whatever sounds interesting. Shipping fast. And yet:</p> The code works</li> The tests pass</li> The bugs get fixed</li> The upstream contributions get merged</li> </ul> You can be a pig in shit and still do good work. The slop is the medium, not the output.</p> The Gatekeeping Problem</h2> A lot of the "AI slop" criticism is just gatekeeping in disguise.</p> "Real programmers don't use AI." "You're not actually learning." "This is ruining software quality."</p> Meanwhile, I'm shipping. Learning by building. Contributing to open source. Having fun.</p> The gatekeepers can argue about the "right way" to write code. I'm too busy building things.</p> What Actually Matters</h2> At the end of the day, here's what matters:</p> Does it work?</li> Did you learn something?</li> Are you having fun?</li> </ul> If the answer to those three questions is yes, then it doesn't matter if someone on Twitter thinks your code is "slop."</p> You're building. They're complaining. You win.</p> Like a Pig in Shit</h2> So yeah, I'm rolling around in the AI slop. Building projects at a pace I never could before. Shipping tools that solve real problems. Learning by doing instead of just reading about it. Old me would think I was full of shit if I tried explaining this.</p> Call it slop if you want. I'm too busy having the time of my life to care.</p> The pig pen is the place for me.</p> vimdeck.nvim: Markdown Presentations in Neovim Unknown — Fri, 07 Nov 2025 00:00:00 +0000 I live in the terminal and Neovim. We have been discussing lightning talks at work, so I wanted a way to present using both. The original vimdeck</a> used to work perfectly, but it's a Ruby script that doesn't seem to work with Neovim.</p> So I rewrote it from scratch using Treesitter and Lua (and Claude).</p> What It Does</h2> You write your presentation in markdown. Separate slides with horizontal rules (---</code>). Run :Vimdeck</code> and you get a fullscreen presentation with:</p> ASCII art headers (h1 and h2 use figlet)</li> Syntax highlighted code blocks</li> Clean list rendering with bullets</li> Blockquote formatting</li> Keyboard navigation (Space/PageDown, Backspace/PageUp, q to quit)</li> </ul> </p> </p> Why Rewrite It?</h2> The original vimdeck was solid for Vim, but it was not working for me in Neovim. Adding to that, it felt like it could be done in a better, more native way. The current Vimdeck was:</p> External Ruby script (dependency management)</li> Generated temp files for each slide</li> Custom shell wrapper for keybindings</li> redcarpet gem for markdown parsing</li> </ul> Neovim has Treesitter built-in. Lua is native. Why shell out to Ruby and manage temp files when you can parse and render everything directly?</p> The Approach</h2> Parser</strong> (lua/vimdeck/parser.lua</code>): Uses Treesitter to parse markdown buffers. Queries for headings, code blocks, lists, quotes, paragraphs. Splits content into slides on horizontal rules (thematic breaks).</p> local query = vim.treesitter.query.parse('markdown', [[ (thematic_break) @separator (atx_heading) @heading (fenced_code_block) @code (list_item) @list_item (block_quote) @quote (paragraph) @paragraph ]]) </code></pre> For each captured node, extract the text and metadata (heading level, code language, etc.). Group elements into slides based on separators.</p> Renderer</strong> (lua/vimdeck/renderer.lua</code>): Takes parsed slides and renders them to buffer lines with highlight instructions.</p> Headers get piped through figlet for ASCII art (h1 uses standard font, h2 uses small). Lists get bullet points. Blockquotes get vertical bars. Code blocks get syntax highlighting via Treesitter string parsers.</p> Navigation</strong> (lua/vimdeck/navigation.lua</code>): Opens slides in a new tab, sets up keybindings, manages state. Updates the buffer content and applies highlights when switching slides.</p> Technical Bits</h2> Treesitter Integration</strong>: The markdown parser exposes node types like atx_heading</code>, fenced_code_block</code>, list_item</code>. Each node has position info (start/end row/col) and can extract text with vim.treesitter.get_node_text()</code>.</p> Getting clean text required helper functions. List items include the markdown markers (- item</code>), so we traverse child nodes to skip list_marker</code> nodes and extract just the content. Same for blockquotes (strip ></code> markers) and code blocks (strip fence markers).</p> Heading Levels</strong>: Treesitter gives you atx_heading</code> nodes. To determine level, check for child nodes like atx_h1_marker</code>, atx_h2_marker</code>, etc.</p> function M.get_heading_level(heading_node) for child in heading_node:iter_children() do if child:type() == 'atx_h1_marker' then return 1 end if child:type() == 'atx_h2_marker' then return 2 end -- ... end return 1 end </code></pre> Duplicate Elements</strong>: Initial implementation captured both list_item</code> nodes and paragraph</code> nodes inside them. Rendering each element separately meant lists showed up twice. Fix: check node ancestry and skip paragraphs that are children of list items or blockquotes.</p> Newline Flattening</strong>: vim.api.nvim_buf_set_lines()</code> requires each array element to be a single line. Figlet output and some text processing can embed \n</code> characters. Solution: scan lines before setting buffer content and split any with embedded newlines.</p> What It Supports</h2> All heading levels</strong> (h1-h6). h1 and h2 get ASCII art via figlet if available. h3-h6 render as plain text with style options such as box, dashed, or underline.</p> Code blocks</strong> with language-specific syntax highlighting. The renderer creates a Treesitter string parser for the code content and applies highlight queries.</p> Lists</strong> render with bullet points (*</code>). Blockquotes</strong> render with vertical bars (┃</code>).</p> </p> Per-Presentation Configuration</h2> YAML frontmatter lets you configure individual presentations without changing global settings. Add frontmatter at the start of your markdown:</p> --- wrap: 80 center_horizontal: true margin: 3 use_figlet: false header_style: "underline" --- # First Slide </code></pre> The wrap</code> option automatically wraps long paragraphs to the specified width. Perfect for prose-heavy slides where you don't want to manually hard-wrap text. Write flowing paragraphs in your markdown source and let vimdeck handle the layout.</p> Header styles provide alternatives to figlet ASCII art. Options include underline</code> (single/double lines), box</code> (Unicode box drawing), double</code> (double-line boxes), and dashed</code> (dotted underlines). All use Unicode characters for clean terminal rendering.</p> Frontmatter parsing uses a simple YAML parser (20 lines of Lua) that handles basic key-value pairs. Supports booleans, numbers, and strings. The frontmatter config merges with global config, so you only override what you need.</p> Installation</h2> Using lazy.nvim:</p> { 'ducks/vimdeck.nvim', cmd = { 'Vimdeck', 'VimdeckFile' }, opts = { use_figlet = true, center_slides = true, } } </code></pre> Requires figlet for ASCII art headers:</p> # macOS brew install figlet # Arch Linux sudo pacman -S figlet # NixOS pkgs.figlet </code></pre> And markdown Treesitter parsers:</p> :TSInstall markdown markdown_inline </code></pre> Usage</h2> Write your presentation:</p> # First Slide Content here --- ## Second Slide More content --- ### Code Example ```lua function hello() print("Hello!") end ``` </code></pre> Open in Neovim and run :Vimdeck</code>. Navigate with Space/PageDown for next slide, Backspace/PageUp for previous, q to quit.</p> Differences From Original</h2> The original vimdeck was a Ruby script. This is a native Neovim plugin.</p> No external dependencies (besides figlet for ASCII art)</li> No temp files</li> Treesitter parsing instead of redcarpet</li> Dynamic rendering instead of static file generation</li> Works with Neovim's highlight system directly</li> </ul> Things To Remember</h2> Treesitter is powerful</strong>: The markdown parser handles all the edge cases (nested lists, multi-line quotes, code fence detection). Using the query system is cleaner than regex parsing.</p> Node traversal matters</strong>: Getting clean text from Treesitter nodes requires understanding the tree structure. List items have marker nodes, code blocks have fence nodes, quotes have paragraph children. Walking the tree to extract just content nodes is necessary.</p> Lua quirks</strong>: Coming from Ruby, easy to forget not</code> instead of !</code>, ~=</code> instead of !=</code>, ..</code> for string concatenation, 1-indexed tables.</p> Code</strong>: github.com/ducks/vimdeck.nvim</a></p> Invite Tree to Invite Stats - How A Simple Tree Flourished Into A Full Moderation Plugin Unknown — Wed, 05 Nov 2025 00:00:00 +0000 Recently, I wrote about building a Discourse plugin that visualizes invite relationships as an ASCII tree. Clean, simple, Lobsters-inspired. I thought I was done.</p> Then I kept thinking about it.</p> Back in 2017, someone on Meta asked about tracking referrals and invites</a>. People wanted to know who was inviting quality members and who was creating moderation work. The Gamification plugin tracks invite counts, but that's just quantity. What about quality?</p> If you're running an invite-only community, you care about accountability. Who's inviting spam accounts? Who's inviting people who get immediately suspended? Which inviters have consistently good judgment?</p> The tree visualization was neat, but it wasn't answering those questions.</p> What Changed</h2> I added moderation metrics to every user in the tree. Now you see:</p> Suspended users (🚫)</li> Silenced users (🔇)</li> Users with agreed flags (⚠️3)</li> Quality scores for people who invited others</li> </ul> Then I built an accountability report that sits above the tree. It shows inviters who meet certain criteria:</p> Invited 3 or more problematic users</li> Have less than 70% invite success rate with 5+ invites</li> </ul> The tree is still there, but it's no longer the main feature. It's supporting evidence for the accountability data.</p> The Rename</h2> At this point, the plugin wasn't really about the tree anymore. It was about invite statistics and quality tracking. The tree was just one way to display the data.</p> So I renamed it: discourse-invite-tree</code> became discourse-invite-stats</code>.</p> Renaming a plugin mid-development is annoying. You have to update:</p> Repository name</li> Plugin metadata</li> All Ruby class names</li> All JavaScript component names</li> All CSS classes</li> All translation keys</li> All site setting names</li> The symlink in your Discourse plugins directory</li> The remote URL in git</li> </ul> But the name needs to match what the thing actually does. A plugin called "invite tree" that's primarily focused on moderation accountability is misleading.</p> Making It Configurable</h2> The hardcoded thresholds (3 bad invites, 70% quality score, 5 minimum invites) worked for my mental model, but different communities have different standards.</p> So I added site settings:</p> invite_stats_problematic_threshold</code>: How many bad invites trigger a flag</li> invite_stats_quality_threshold</code>: What percentage is acceptable</li> invite_stats_min_invites_for_quality</code>: Minimum invites before scoring applies</li> invite_stats_flags_threshold</code>: How many agreed flags mark someone as problematic</li> </ul> I converted the template to a proper Glimmer component class so I could inject siteSettings</code> and compute the threshold description dynamically. Now when an admin changes the thresholds in settings, the UI updates to match.</p> </p> No more hardcoded magic numbers. If your community runs strict moderation and wants to flag anyone with 2 bad invites, you can do that. If you're more lenient and only care about people with 5+ bad invites, that works too.</p> Things to Remember</h2> Scope creep isn't always bad. I started with "show me who invited whom" and ended up with "help me identify problematic inviters." The tree visualization is still there, but it's not the point anymore.</p> Sometimes you need to keep iterating. The first version was fine. The second version is actually useful.</p> Check it out: discourse-invite-stats on GitHub</a></p> Visualizing Discourse Invite Trees Unknown — Mon, 03 Nov 2025 00:00:00 +0000 I built a small Discourse plugin that shows who invited whom in your community. It displays the invite relationships as an ASCII tree, similar to how Lobsters</a> shows their user invites.</p> </p> The tree shows usernames, join dates, and how many people each user has invited. Users without an inviter (founding members or self-signups) appear at the root level, with their invite chains nested below.</p> The plugin works great with Discourse's native invite-only mode. If you enable invite-only registration, the tree visualization lets you see exactly how your community has grown through invites over time.</p> Back in 2017, someone on Meta asked about tracking referrals and invites</a>. People were using Data Explorer with custom SQL queries to see this data. This plugin makes it visual and accessible at /invite-tree</code>.</p> The implementation is straightforward: a recursive SQL query builds the tree from Discourse's native invite tables, and a Glimmer component renders it with monospace font and tree characters. The whole thing is about 600 lines.</p> I kept it minimal and hackable. No complex features, just a clean tree that adapts to your theme. If you want to customize how it looks or what it shows, the code is easy to modify.</p> Check it out: discourse-invite-tree on GitHub</a></p> Shelltrax Part 2: Footer, Tests, and CI Unknown — Wed, 29 Oct 2025 00:00:00 +0000 In Part 1</a>, I built the core of shelltrax</p> a TUI music player in Rust. It had library navigation, file browsing, audio playback, and a footer with song info and status. One big problem though, the footer would stop updating after the first song and I really wanted to fix that.</li> </ul> This post covers three improvements: implementing a proper footer with playback progress, adding unit tests for the tricky bits, and setting up CI to keep code quality high.</p> Running With A Limp</h2> The footer existed from early on (progress bar, time display, track info), but it had a critical bug: when autoplay advanced to the next track, the progress bar wouldn't reset. It would either keep counting from where the previous song left off, showing wrong times and eventually overflowing past 100% or it would just reset back to 0 and not progress. Whatever it did, it didn't work.</p> The bug was in play_next_track()</code>. It would set playback_start</code> and current_track</code>, but it wouldn't reset paused_duration</code> or paused_at</code>. If you paused the first song for 30 seconds, that 30 seconds would carry over to every subsequent song, throwing off the footer display completely.</p> Consolidation: begin_playback()</h2> The solution was extracting the timer reset logic into a dedicated method:</p> pub fn begin_playback(&mut self, track: &LibraryTrack) { self.current_track = Some(track.clone()); self.playback_start = Some(Instant::now()); self.paused_duration = Duration::ZERO; self.paused_at = None; self.playback_duration = track.duration.unwrap_or(0); } </code></pre> Now play_next_track()</code> calls begin_playback()</code> instead of manually setting fields. This ensures all timing state resets properly when advancing to the next song, whether manually or via autoplay.</p> Implementation: Tracking Time Correctly</h2> The app needs to track multiple timing values:</p> pub struct App { pub playback_start: Option<Instant>, pub playback_duration: u64, pub paused_at: Option<Instant>, pub paused_duration: Duration, // ... other fields } </code></pre> When a song starts, we record playback_start</code>. When the user pauses, we record paused_at</code>. When they unpause, we add the pause duration to paused_duration</code> and clear paused_at</code>.</p> The footer calculation looks like this:</p> let elapsed = if let Some(paused_at) = app.paused_at { paused_at.duration_since(start) } else { now.duration_since(start) }; let adjusted = elapsed.saturating_sub(app.paused_duration); </code></pre> If currently paused, elapsed time is frozen at the pause moment. Otherwise, it's the time since playback started. Then we subtract all the accumulated pause time to get the actual playback position.</p> The saturating_sub</code> is important. Without it, if paused_duration</code> somehow exceeded elapsed</code> (race condition, clock skew, whatever), you'd get an underflow panic. saturating_sub</code> clamps to zero instead.</p> Layout: Three Lines of Footer</h2> The footer uses a vertical layout with three lines:</p> let layout = Layout::default() .direction(Direction::Vertical) .constraints([ Constraint::Length(1), // Progress bar Constraint::Length(1), // Time display Constraint::Length(1), // Track info ]) .split(inner); </code></pre> Line 1 is a Gauge</code> widget showing the ratio of elapsed to total time. Line 2 shows MM:SS / MM:SS</code>. Line 3 shows Artist - Title - Album</code>.</p> The progress bar ratio:</p> let ratio = if total.as_secs_f64() > 0.0 { adjusted.as_secs_f64() / total.as_secs_f64() } else { 0.0 }; </code></pre> Clamp it to 1.0</code> max so the gauge doesn't overflow if the elapsed time somehow exceeds the track duration (can happen with malformed metadata).</p> Testing: What Actually Needs Tests?</h2> I'm not a fan of testing UI rendering code. It's tedious, fragile, and doesn't catch the bugs that matter. What I do test is the state management logic that the UI depends on.</p> For shelltrax, the critical logic is:</p> Playback state transitions (playing, paused, stopped)</li> Time tracking during pause/unpause cycles</li> Library state management (artist/album hierarchy)</li> </ul> I added two test modules: one in app.rs</code> for playback logic, one in library.rs</code> for library state.</p> Testing Playback State</h3> Four tests in app.rs</code>:</p> test_begin_playback_resets_timers:</strong></p> #[test] fn test_begin_playback_resets_timers() { let mut app = App::new(); app.playback_start = Some(Instant::now()); app.paused_duration = Duration::from_secs(10); app.paused_at = Some(Instant::now()); let track = create_test_track("test", 180); app.begin_playback(&track); assert!(app.playback_start.is_some()); assert_eq!(app.paused_duration, Duration::ZERO); assert!(app.paused_at.is_none()); } </code></pre> When starting a new track, all the timing state should reset. If it didn't, the footer would show stale pause data from the previous song.</p> test_toggle_pause_accumulates_paused_duration:</strong></p> #[test] fn test_toggle_pause_accumulates_paused_duration() { let mut app = App::new(); let start = Instant::now(); app.paused_at = Some(start); app.paused_duration = Duration::from_secs(5); app.toggle_pause(); // Unpause std::thread::sleep(Duration::from_millis(100)); app.toggle_pause(); // Pause again assert!(app.paused_at.is_none()); assert!(app.paused_duration > Duration::from_secs(5)); } </code></pre> This test verifies that pausing multiple times accumulates the total paused duration. The sleep</code> is gross but necessary to test time-based logic without mocking the clock (which would require dependency injection, which is overkill for a hobby project).</p> Testing Library State</h3> Six tests in library.rs</code> covering the artist/album/track hierarchy:</p> test_add_tracks_creates_structure:</strong></p> #[test] fn test_add_tracks_creates_structure() { let mut lib = LibraryState::new(); let tracks = vec![ create_test_track("Artist A", "Album 1", "Track 1", 1), create_test_track("Artist A", "Album 1", "Track 2", 2), create_test_track("Artist B", "Album 2", "Track 3", 1), ]; lib.add_tracks(tracks); assert_eq!(lib.artists.len(), 2); assert_eq!(lib.artists[0].name, "Artist A"); assert_eq!(lib.artists[0].albums.len(), 1); assert_eq!(lib.artists[0].albums[0].tracks.len(), 2); } </code></pre> This validates the library builds the correct tree structure when adding tracks. If the grouping logic broke, you'd end up with duplicate artists or albums in the wrong places.</p> test_visible_tracks_for_album:</strong></p> #[test] fn test_visible_tracks_for_album() { let mut lib = LibraryState::new(); lib.add_tracks(vec![ create_test_track("Artist", "Album 1", "Track 1", 1), create_test_track("Artist", "Album 1", "Track 2", 2), create_test_track("Artist", "Album 2", "Track 3", 1), ]); lib.selection = Some(LibrarySelection::Album { artist_index: 0, album_index: 0, }); let tracks = lib.visible_tracks(); assert_eq!(tracks.len(), 2); assert_eq!(tracks[0].title, "Track 1"); assert_eq!(tracks[1].title, "Track 2"); } </code></pre> The visible_tracks</code> method returns different results depending on whether an artist or an album is selected. This test ensures album selection filters correctly.</p> CI: Keeping Code Quality High</h2> GitHub Actions makes CI trivial for Rust projects. The workflow file:</p> name: test on: push: branches: [main] pull_request: branches: [main] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: install rust uses: dtolnay/rust-toolchain@stable with: components: clippy - name: cache dependencies uses: actions/cache@v4 with: path: | ~/.cargo/bin/ ~/.cargo/registry/index/ ~/.cargo/registry/cache/ ~/.cargo/git/db/ target/ key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }} - name: install system dependencies run: | sudo apt-get update sudo apt-get install -y libasound2-dev - name: run tests run: cargo test --verbose - name: run clippy run: cargo clippy -- -D warnings </code></pre> The important bits:</p> Dependency caching:</strong> Without caching, every CI run would download and compile all dependencies from scratch. With caching, subsequent runs reuse compiled dependencies, dropping build time from several minutes to under 30 seconds.</p> System dependencies:</strong> The audio libraries (cpal, rodio) need ALSA headers to compile. libasound2-dev</code> provides those on Ubuntu.</p> Clippy with -D warnings</code>:</strong> This flag treats all warnings as errors. It's strict, but it keeps code quality high. If clippy suggests a fix, you either apply it or add an explicit #[allow(...)]</code> annotation explaining why you're ignoring it.</p> Results</h2> The footer works. Tests pass. CI keeps the codebase clean. Shelltrax now feels like a real music player instead of a tech demo.</p> Running cargo test</code> shows 10 passing tests:</p> running 10 tests test app::tests::test_begin_playback_resets_timers ... ok test app::tests::test_toggle_pause_accumulates_paused_duration ... ok test app::tests::test_toggle_pause_cycles_state ... ok test app::tests::test_toggle_pause_sets_paused_at ... ok test library::tests::test_add_tracks_creates_structure ... ok test library::tests::test_toggle_expanded ... ok test library::tests::test_track_by_path_finds_track ... ok test library::tests::test_track_by_path_returns_none_for_missing ... ok test library::tests::test_visible_tracks_for_album ... ok test library::tests::test_visible_tracks_for_artist ... ok test result: ok. 10 passed; 0 failed; 0 ignored; 0 measured </code></pre> And cargo clippy</code> stays green with zero warnings.</p> What's Next?</h2> The core functionality is solid, but there are still features I want:</p> config system</li> seeking</li> better metadata handling</li> vi keybindings</li> </ul> But for now, shelltrax does what I needed it to do: play music in the terminal with a proper UI that shows what's happening.</p> Code</strong>: github.com/ducks/shelltrax</a></p> Replacing MessageBus Pub/Sub with REST APIs: Fixing Production Outages Unknown — Mon, 27 Oct 2025 00:00:00 +0000 We're converting one of our infrastructure services from MessageBus pub/sub to a synchronous REST API. This isn't a protocol change or upgrade - both architectures use HTTP. This is about replacing fire-and-forget asynchronous messaging with request/response patterns that provide immediate feedback.</p> The control plane manages hundreds of Discourse forums across multiple data centers. It needs to orchestrate PostgreSQL user and database creation across these distributed clusters.</p> The Problem</h2> Our postgres-manager</code> service handles PostgreSQL user and database lifecycle for Discourse hosted sites. It was built using ServiceSkeleton</code>, a Ruby framework for message-driven services, subscribing to MessageBus channels for commands.</p> MessageBus uses HTTP long-polling for pub/sub messaging. Publishers send messages to channels, subscribers open long-lived HTTP connections and wait for messages to arrive. It works well for many use cases, but we've hit two critical problems:</p> No feedback mechanism. When the control plane published a message like "create database for site X", it had no way to know if the operation succeeded or failed. The message was sent and forgotten.</p> </li> Message replay on restarts. MessageBus keeps a backlog of messages. When postgres-manager restarts, it replays unacknowledged messages, causing duplicate operations. We've had multiple production outages from databases being recreated or users being decommissioned twice.</p> </li> </ol> The message replay issue is the immediate trigger, but the lack of feedback is the underlying architectural problem. We need synchronous request/response patterns with immediate success/failure feedback.</p> The Solution: REST API with Request/Response</h2> We're converting postgres-manager to a Sinatra HTTP service that responds synchronously to requests. Instead of subscribing to MessageBus channels, it will expose REST endpoints:</p> POST /databases</code> - Create database and user</li> DELETE /databases/:username</code> - Decommission database</li> POST /users</code> - Create user (triggers sync)</li> DELETE /users/:username</code> - Decommission user</li> POST /sync</code> - Sync all databases/users from control plane</li> </ul> Each endpoint will return an immediate response with proper HTTP status codes: 200 for success, 401 for auth failures, 400 for bad parameters, 500 for server errors.</p> Implementation</h2> Before: ServiceSkeleton with MessageBus</h3> The old implementation used ServiceSkeleton to subscribe to MessageBus:</p> message_bus = MessageBus::HTTPClient.new( config.control_plane_base_url, headers: { "Discourse-Access-Token" => config.control_plane_token } ) message_bus.subscribe(config.message_bus_channel) do |message| case message["type"] when "create_user", "create_db", "sync" sync when "decommission_db" decommission_db(message["dbname"]) when "decommission_user" decommission_user(message["username"]) end end </code></pre> The control plane would publish messages:</p> PostgresManagerPublisher.create_db(owner, cluster_name) # Fire and forget - no response </code></pre> After: Sinatra HTTP Service</h3> The new implementation uses Sinatra with proper HTTP patterns:</p> before do return if ["/health", "/metrics"].include?(request.path_info) auth_header = request.env["HTTP_AUTHORIZATION"] if !auth_header || !auth_header.start_with?("Bearer ") halt 401, json(error: "Unauthorized", code: "AUTH_REQUIRED") end token = auth_header.sub("Bearer ", "") if token != config[:api_key] halt 401, json(error: "Unauthorized", code: "INVALID_TOKEN") end end post "/databases" do body = parse_json_body cluster = body["cluster"] username = body["username"] if cluster != config[:container_name] halt 400, json( error: "Cluster mismatch", code: "CLUSTER_MISMATCH", expected: config[:container_name], received: cluster ) end sync json( status: "success", message: "Database sync completed", cluster: cluster ) end delete "/databases/:username" do username = params["username"] decommission_db(username) json( status: "success", message: "Database decommissioned", username: username ) end </code></pre> The control plane will make HTTP requests and get immediate responses:</p> PostgresManagerHttpClient.create_db(owner, cluster_name) # Returns { "status" => "success", "message" => "..." } # Or raises PostgresManagerError on failure </code></pre> HTTP Client with Proper Error Handling</h2> The new HTTP client provides clear error handling:</p> class PostgresManagerHttpClient class PostgresManagerError < StandardError; end class PostgresManagerTimeout < PostgresManagerError; end class PostgresManagerAuthError < PostgresManagerError; end def self.create_db(owner, cluster_name) call_postgres_manager( cluster_name: cluster_name, method: :post, path: "/databases", body: { cluster: cluster_name, username: owner, action: "create" } ) end private def self.call_postgres_manager(cluster_name:, method:, path:, body: nil) api_key = ENV["POSTGRES_MANAGER_API_KEY"] raise "POSTGRES_MANAGER_API_KEY not configured" if !api_key base_url = ENV["POSTGRES_MANAGER_BASE_URL"] || "http://postgres-manager-#{cluster_name}:9105" uri = URI("#{base_url}#{path}") http = Net::HTTP.new(uri.host, uri.port) http.open_timeout = 5 http.read_timeout = 30 request = case method when :post then Net::HTTP::Post.new(uri) when :delete then Net::HTTP::Delete.new(uri) end request["Authorization"] = "Bearer #{api_key}" request["Content-Type"] = "application/json" request.body = body.to_json if body begin response = http.request(request) case response.code.to_i when 200..299 return nil if response.body.to_s.empty? JSON.parse(response.body) when 401 raise PostgresManagerAuthError, "Authentication failed: #{response.body}" when 400..499 raise PostgresManagerError, "Client error (#{response.code}): #{response.body}" when 500..599 raise PostgresManagerError, "Server error (#{response.code}): #{response.body}" end rescue Net::OpenTimeout, Net::ReadTimeout raise PostgresManagerTimeout, "Request timed out for #{uri}" rescue Errno::ECONNREFUSED raise PostgresManagerError, "Connection refused to #{uri}" end end end </code></pre> Testing Strategy: Unit and Integration Tests</h2> The HTTP service has a test suite with 54 tests covering both unit and integration testing:</p> Unit Tests (16 tests, no PostgreSQL required)</h3> Unit tests use WebMock to stub external dependencies:</p> it "makes POST request to /databases with correct parameters" do stub_request(:post, "#{base_url}/databases") .with( body: { cluster: "flex001", username: "example", action: "create" }.to_json, headers: { "Authorization" => "Bearer test-api-key" } ) .to_return( status: 200, body: { status: "success", message: "Database sync completed" }.to_json ) result = PostgresManagerHttpClient.create_db("example", "flex001") expect(result["status"]).to eq("success") end </code></pre> These tests run fast (under 1 second) and validate HTTP client logic, metrics tracking, and configuration handling without requiring PostgreSQL.</p> Integration Tests (38 tests, with real PostgreSQL)</h3> Integration tests use Docker to automatically start/stop PostgreSQL and test real database operations:</p> it 'creates database and user' do multisite_config = { "example" => { "username" => "example", "password" => "test123", "database" => "example_discourse" } } stub_request(:get, "http://mothership.test/api/multisite_config?container_name=test-cluster") .to_return(status: 200, body: JSON.dump(multisite_config)) result = sync.perform # Verify in actual PostgreSQL sync.database.with_db('postgres') do |db| user_result = db.exec_params('SELECT usename FROM pg_user WHERE usename = $1', ['example']) expect(user_result.ntuples).to eq(1) db_result = db.exec_params('SELECT datname FROM pg_database WHERE datname = $1', ['example_discourse']) expect(db_result.ntuples).to eq(1) end end </code></pre> Idempotency Tests</h3> Critical tests verify the service handles message replay scenarios that caused production outages:</p> it 'handles rapid duplicate creates (race condition simulation)' do threads = 2.times.map do Thread.new do begin database.create(test_db, test_user) rescue PG::DuplicateDatabase # Expected - one thread wins, other gets duplicate error end end end threads.each(&:join) # Verify only one database created database.with_db('postgres') do |db| result = db.exec_params('SELECT datname FROM pg_database WHERE datname = $1', [test_db]) expect(result.ntuples).to eq(1) end end </code></pre> These tests validate that calling create operations multiple times (as happens during message replay) doesn't cause crashes or duplicate resources.</p> Migration Strategy</h2> We can't switch all clusters at once. The migration strategy:</p> Deploy HTTP version alongside MessageBus - Run both in separate containers</li> Test HTTP version manually - Verify endpoints work, check metrics</li> Switch control plane to HTTP - Deploy control plane changes, monitor logs</li> Clean up MessageBus - Stop old containers, remove environment variables</li> </ol> Both services can run simultaneously during migration, and rollback is just reverting the control plane code and restarting services.</p> Expected Results</h2> No more duplicate operations from message replay</li> Immediate visibility into success/failure</li> Proper error handling with retries</li> Easy to test with curl or standard HTTP tools</li> Can be load balanced through standard proxies</li> Standard HTTP monitoring and metrics</li> </ul> Outcomes</h2> Fire-and-forget messaging has hidden costs. The lack of feedback makes debugging production issues extremely difficult. We don't know if operations fail until customers complain.</p> </li> Message replay is a feature until it's a bug. MessageBus's backlog replay is useful for reliable message delivery, but causes havoc when operations aren't idempotent.</p> </li> Different HTTP patterns, same protocol. Both MessageBus (HTTP long-polling) and our REST API use HTTP for transport, but serve fundamentally different communication patterns. MessageBus uses HTTP to implement pub/sub messaging (asynchronous, one-to-many), while REST implements request/response (synchronous, one-to-one). The choice isn't HTTP vs something else - it's choosing the right messaging pattern for your use case.</p> </li> Testing gets easier with simpler patterns. The old MessageBus setup requires a full environment. The HTTP version can be tested with simple request/response stubs.</p> </li> </ol> Summary</h2> This migration will take our infrastructure service from fire-and-forget messaging to synchronous request/response patterns. The expected result: no more duplicate operations, immediate feedback on success/failure, and much simpler debugging. Sometimes the solution isn't choosing new technology - it's choosing the right pattern for your use case.</p> Current Status</h2> The HTTP service implementation is complete and tested:</p> Modular architecture with 6 separated modules (Config, Database, User, Client, Sync, Metrics)</li> Test suite (16 unit tests, 38 integration, all passing)</li> RuboCop clean (zero offenses)</li> Security fixes (parameterized queries, retry limits)</li> GitHub Actions CI configured and passing</li> </ul> The service is production-ready and awaiting deployment to test clusters. Once validated with real PostgreSQL operations and monitored for stability, we'll proceed with gradual rollout to production infrastructure.</p> Building The Guest Spot: Part 2 - Two Refactors Unknown — Sun, 26 Oct 2025 00:00:00 +0000 In Part 1</a>, I built an Instagram-style showcase using a custom GuestSpotPost</code> model. It worked. But it also meant maintaining a parallel data structure instead of leveraging what Discourse already provides.</p> This post covers two major refactors: first from custom models to Discourse Topics, then from custom feed infrastructure to plugin outlets. Each time, less code gave me more features.</p> Why Refactor?</h2> The custom model approach had problems:</p> Duplicate logic: Comments, moderation, spam protection already exist for Topics</li> Extra maintenance: Every time Discourse updates, potential breakage</li> Missing features: No native file upload, no revision history, no trust levels</li> More code: Separate serializers, separate permissions, separate everything</li> </ul> Discourse Topics already have everything we need:</p> First post holds the caption and images</li> Title can be auto-generated</li> Categories handle public vs private</li> Pinning is built-in</li> Commenting works out of the box</li> </ul> The showcase is just a custom view of Topics in the "Public Feed" category.</p> The Refactor</h2> Backend Changes</h3> Deleted the entire GuestSpotPost</code> model and migrations. Instead, the controller now works with Topics:</p> # app/controllers/guest_spot/posts_controller.rb def index category_id = CategoryHelper.public_feed_category_id topics = Topic .where(category_id: category_id) .where(deleted_at: nil) .includes(:user, posts: :uploads) .order(created_at: :desc) .limit(50) pinned_topics = Topic .where(category_id: category_id) .where(deleted_at: nil) .where.not(pinned_at: nil) .includes(:user, posts: :uploads) .order(created_at: :desc) render json: { posts: serialize_data(topics, GuestSpotPostSerializer), pinned: serialize_data(pinned_topics, GuestSpotPostSerializer) } end </code></pre> The serializer extracts what we need from Topics:</p> # app/serializers/guest_spot_post_serializer.rb class GuestSpotPostSerializer < ApplicationSerializer attributes :id, :user_id, :username, :caption, :image_urls, :created_at, :pinned def caption object.first_post&.raw || "" end def image_urls object.first_post.uploads.map { |upload| UrlHelper.absolute(upload.url) } end def pinned object.pinned_at.present? end end </code></pre> Caption is the post content. Images come from uploads. Pinned status is the native pinned_at</code> field.</p> Creating Posts</h3> Instead of GuestSpotPost.create</code>, we use TopicCreator</code>:</p> def create category_id = CategoryHelper.public_feed_category_id title = "@#{current_user.username} - #{Time.now.to_i}" topic_creator = TopicCreator.new( current_user, Guardian.new(current_user), category: category_id, title: title, raw: params[:caption] || "" ) topic = topic_creator.create render_serialized(topic, GuestSpotPostSerializer) end </code></pre> Auto-generated titles keep them unique. The caption goes in the first post's raw content. Image uploads attach automatically through Discourse's existing upload system.</p> Frontend Changes</h3> Frontend barely changed. The serializer provides the same JSON structure, so components worked as-is. The only update was changing @post.id</code> to reference topic IDs instead of custom model IDs.</p> What This Got Us</h3> The refactor from custom models to Topics gave us:</p> Comments work natively (no custom implementation)</li> Moderation tools work (flags, hiding, deleting)</li> File uploads work (native uploader)</li> Revision history works (edit tracking)</li> Trust levels work (spam protection)</li> All for free, by using what Discourse already provides</li> </ul> But I still had a custom feed with its own routes, controllers, and serializers. That was the next problem to solve.</p> Going Native: Deleting the Custom Feed</h2> In Part 1, I built a custom GuestSpotPost</code> model. Then I realized that was overkill and refactored to use Discourse Topics. But I kept the custom feed with its own routes, controllers, and serializers.</p> After implementing that custom feed, I realized there was an uncomfortable disconnect. Users would browse an Instagram-style feed, click a post, and suddenly land in Discourse's standard topic view. The context switch was jarring.</p> The question became: why maintain a custom feed at all? If the custom model was unnecessary, maybe the custom feed was too.</p> Discourse already has everything we need:</p> Category pages show topic lists</li> Category permissions control who can post and who can view</li> Native pinning highlights featured content</li> Theme system allows extensive visual customization</li> </ul> Instead of maintaining a parallel feed system, we could just make the Public Feed category look great using plugin outlets.</p> The Deletion</h3> I deleted the entire custom feed infrastructure:</p> Removed (1,078 lines)</strong>:</p> Custom feed routes and controllers (guest_spot/feed_controller.rb</code>, guest_spot/posts_controller.rb</code>)</li> Custom post serializer (guest_spot_post_serializer.rb</code>)</li> All custom Ember components (guest-spot-feed.gjs</code>, guest-spot-post-card.gjs</code>)</li> Custom route definitions and templates</li> Multiple initializers for hiding UI elements</li> </ul> Added (264 lines)</strong>:</p> Single plugin outlet connector: assets/javascripts/discourse/connectors/topic-list-item/guest-spot-item.gjs</code></li> CSS Grid layout for responsive cards</li> </ul> Net result: 814 fewer lines of code.</p> Plugin Outlets: The Right Pattern</h3> Discourse provides plugin outlets - extension points where plugins can inject custom HTML. There are two types:</p> Regular outlets</strong> inject content but Discourse still renders the default elements. Wrapper outlets</strong> completely replace the template.</p> I used the topic-list-item</code> wrapper outlet to completely replace how topics display in the Public Feed category:</p> import Component from "@glimmer/component"; import avatar from "discourse/helpers/avatar"; import replaceEmoji from "discourse/helpers/replace-emoji"; import formatDate from "discourse/helpers/format-date"; export default class GuestSpotItem extends Component { get isPublicFeed() { return this.args.outletArgs?.topic?.category?.slug === "public-feed"; } get truncatedExcerpt() { const excerpt = this.args.outletArgs?.topic?.excerpt || ""; if (excerpt.length <= 50) { return excerpt; } return excerpt.substring(0, 50) + "..."; } <template> {{#if this.isPublicFeed}} <td class="topic-list-data guest-spot-card"> <div class="guest-spot-author"> <a href="/u/{{this.args.outletArgs.topic.creator.username}}"> {{avatar this.args.outletArgs.topic.creator imageSize="medium"}} <span class="username"> {{this.args.outletArgs.topic.creator.username}} </span> </a> </div> <div class="guest-spot-image"> <a href={{this.args.outletArgs.topic.url}}> <img src={{this.args.outletArgs.topic.image_url}} alt="" /> </a> </div> <div class="guest-spot-excerpt"> {{replaceEmoji this.truncatedExcerpt}} </div> <div class="guest-spot-metadata"> <div class="meta-item"> Views: {{this.args.outletArgs.topic.views}} </div> <div class="meta-item"> Replies: {{this.args.outletArgs.topic.posts_count}} </div> <div class="meta-item"> Posted: {{formatDate this.args.outletArgs.topic.createdAt leaveAgo=true}} </div> </div> </td> {{else}} {{@default}} {{/if}} </template> } </code></pre> The component checks if we're in the public-feed category. If yes, render the custom card layout. If no, render the default ({{@default}}</code>).</p> CSS Grid for Responsive Layout</h3> Instead of JavaScript handling the layout, CSS Grid does all the work:</p> .category-public-feed { .topic-list { display: grid; grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); gap: 1.5rem; @media (max-width: 480px) { grid-template-columns: 1fr; } tr.topic-list-item { display: flex; flex-direction: column; border-radius: 8px; overflow: hidden; background: var(--primary-very-low); transition: transform 0.2s; &:hover { transform: translateY(-2px); } } } } </code></pre> On mobile, it collapses to a single column. On tablet and desktop, it flows naturally based on available space.</p> </p> </p> Discovery Process</h3> Finding the right plugin outlet took some research. I used rg</code> to search Discourse core for available outlets:</p> rg "PluginOutlet" app/assets/javascripts/discourse/app/components/ \ | grep topic-list </code></pre> Found several candidates:</p> topic-list-before-link</code> - Injects before the title link (still renders default content)</li> topic-list-after-title</code> - Injects after the title (still renders default content)</li> topic-list-item</code> - Wrapper outlet (replaces entire template)</li> </ul> The wrapper outlet was key. Regular outlets would have shown both my custom card and the default topic row, creating duplicate content.</p> What Works Now</h3> The native approach gives us:</p> Comments work out of the box (no custom implementation needed)</li> All Discourse features work (moderation, flags, bookmarks, etc.)</li> 814 fewer lines of code to maintain</li> Better mobile support (Grid automatically adapts)</li> No custom API (no serializers, controllers, or routes)</li> Pin/unpin still works (using Discourse's native pinning)</li> </ul> The showcase is now just "a really nicely styled Discourse category" instead of "a custom app built on top of Discourse."</p> Vibe Coding: Pros and Cons</h2> This project is a perfect example of "vibe coding" - building something by feel, iterating quickly, and learning what works through trial and error.</p> I started with a custom model because that felt right. Then I realized Topics already did everything I needed. I built a custom feed because I wanted full control. Then I realized plugin outlets gave me that control without the maintenance burden.</p> The downside</strong>: I went too fast and tried too much. Each iteration meant throwing away code. The custom model, the custom feed infrastructure - all that work ended up deleted. If I'd researched Discourse patterns first, I could have gone straight to the plugin outlet approach.</p> The upside</strong>: I learned way more by doing it wrong first. I understand why wrapper outlets exist, because I felt the pain of duplicate content with regular outlets. I understand why Discourse's native features are powerful, because I tried to rebuild them and saw how much work that is.</p> Fast iteration meant I could course-correct. I wasn't six months into building a custom ORM before realizing Topics existed. I was a few days in, so refactoring didn't hurt. The velocity of vibe coding let me try ideas, see them fail, and pivot quickly.</p> The final result is simple and maintainable. It took three iterations to get there, but each iteration taught me something. Now I know how to not do things, which is just as valuable as knowing how to do them.</p> The code is on GitHub: discourse-guest-spot</a></p> Building The Guest Spot: Part 1 - My First Community Unknown — Sat, 25 Oct 2025 00:00:00 +0000 I'm not exactly a social butterfly. I can enjoy small groups of like minded people talking about our interests but small talk really drains me. I'm much happier with a computer, book, or just sitting out in the woods.</p> Since joining Discourse a few months ago, I've been learning the platform by building weird experiments. A transit departure board. A virtual currency system. Tools that push Discourse in directions it wasn't designed for. But they've all been technical exercises. Solo projects. Learning by doing, but doing alone.</p> The Guest Spot is different. This is my first time helping build something for an actual community of people. Real artists who will (hopefully) use this thing. Not just me poking at APIs and seeing what breaks.</p> It's exciting. And a little terrifying.</p> How The Idea Evolved</h2> The original concept was simple: a private forum for tattoo artists. A place where people in the industry could talk shop, share techniques, discuss challenges. No clients. No tourists. Just professionals.</p> But then I started thinking about how artists actually share their work. Instagram. Almost every tattoo artist is on Instagram. It's where they build their portfolio, attract clients, establish their style. But they don't own any of it. The algorithm decides who sees their posts. Instagram decides what gets buried or promoted. If Instagram changes the rules or shuts down tomorrow, years of work disappears.</p> What if artists could have both? A professional forum for discussion and a public showcase for their work. Same platform, same data, but they own it all. No algorithm deciding what gets seen. No corporate platform that could pull the rug out.</p> That's when the concept clicked: build the Instagram-style feed as the front door, with the private forum as the main room. Artists get a beautiful public portfolio plus a real community space. All on infrastructure they control.</p> What Is The Guest Spot?</h2> The result: an Instagram-style public showcase for tattoo artists, powered by Discourse.</p> Artists can post photos of their work in a clean, visual feed. Pinned posts appear in a horizontal carousel at the top. Recent work flows down below in a responsive grid. Click any image and you get a full detail page with all the context.</p> And if you've been vetted, behind the public feed is a private, invite-only Discourse forum. The showcase is the front door. The forum is where the real community happens. Artists can discuss techniques, share experiences, ask questions. It's gated access because tattoo culture values quality and trust.</p> Think of it as Instagram's visual presentation meets forum depth, with Discourse handling both sides.</p> Why Discourse Makes Sense Here</h2> Discourse isn't Instagram. It's not designed to be a photo showcase. But it has everything we need to build one:</p> Custom fields store image URLs and captions. Categories and tags organize content. The permission system handles public showcase vs private forum.</p> Most importantly, Discourse is built for communities. The forum infrastructure is already there. We're just adding a pretty front door.</p> And unlike Instagram, artists own everything. The database, the images, the content. They can export it all. No algorithm. No corporate overlord. Just their work, on their terms.</p> What I've Built So Far</h2> Backend is straightforward Rails stuff:</p> GuestSpotPost</code> model with image URLs (stored as arrays), captions, and pinned status</li> Migrations for the database schema</li> Controllers that handle CRUD operations and serve JSON to the frontend</li> Serializers that package post data with user info</li> </ul> Frontend is where it gets interesting. Modern Discourse uses Glimmer components, which are Ember's latest component format. Template and logic live in the same .gjs</code> file:</p> export default class GuestSpotPostCard extends Component { get firstImage() { return this.args.post.image_urls?.[0]; } <template> <LinkTo @route="guest-spot-post" @model={{@post.id}} class="guest-spot-post-card"> {{#if this.firstImage}} <img src={{this.firstImage}} alt={{@post.caption}} class="post-image" /> {{/if} <div class="post-meta"> <div class="post-author"> {{avatar @post.user imageSize="small"}} <span class="username">{{@post.user.username}}</span> </div> {{#if @post.caption}} <p class="post-caption">{{@post.caption}}</p> {{/if}} {{#if @post.pinned}} <span class="pinned-badge">Featured</span> {{/if}} </div> </LinkTo> </template> } </code></pre> The card is a link. Click it, you go to the full post page. The whole thing is wrapped in a LinkTo</code> component so the entire card is interactive.</p> The Feed Page</h2> </p> Two sections: pinned posts in a horizontal carousel, recent posts in a responsive grid.</p> The carousel uses CSS flexbox with scroll-snap-type: x mandatory</code> so it feels smooth on mobile. On phones, each card takes up 80% of the viewport width. On tablets, 250px. On desktop, 300px. Pure CSS, no JavaScript.</p> The grid uses CSS Grid with auto-fill</code> and minmax()</code>:</p> .posts-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(250px, 1fr)); gap: 1.5rem; @media (max-width: 768px) { grid-template-columns: repeat(auto-fill, minmax(150px, 1fr)); gap: 1rem; } @media (max-width: 480px) { grid-template-columns: 1fr; gap: 0.75rem; } } </code></pre> On phones, we force a single column so cards stay large enough to see the artwork clearly. On tablets and desktops, it flows naturally based on available space.</p> The Post Page</h2> </p> Click any card and you get the full post view. It's designed to let the artwork breathe while keeping all the important context visible.</p> The layout is simple:</p> Back link at the top (returns to feed)</li> Full-size image(s) with object-fit: contain</code> so nothing gets cropped</li> Artist info (avatar + username)</li> Full caption with preserved line breaks</li> Pinned badge if applicable</li> </ul> Images are wrapped in a card design with rounded corners and subtle shadow. On mobile, padding reduces and max image height adjusts so everything fits nicely on smaller screens. The whole page uses the same responsive breakpoints as the feed (768px for tablets, 480px for phones).</p> All contained in a centered column with max-width of 900px. Clean, focused, lets the work be the star.</p> Hiding the Sidebar</h2> Guest Spot has its own route at /guest-spot</code>. But Discourse has a persistent sidebar. For a public showcase, that doesn't make sense. Artists posting work shouldn't see forum navigation.</p> First attempt: route lifecycle hooks.</p> export default class GuestSpotFeedRoute extends DiscourseRoute { activate() { super.activate(...arguments); const appController = this.controllerFor("application"); appController.set("showSidebar", false); document.body.classList.add("guest-spot-page"); } deactivate() { const appController = this.controllerFor("application"); appController.set("showSidebar", true); document.body.classList.remove("guest-spot-page"); super.deactivate(...arguments); } } </code></pre> This hides the sidebar. But the hamburger button (.header-sidebar-toggle</code>) stays visible. Users can toggle it back. Not ideal.</p> CSS didn't work. Setting controller properties didn't work. So I got pragmatic: DOM manipulation via an initializer.</p> export default { name: "hide-sidebar-toggle-on-guest-spot", initialize() { withPluginApi("0.8", (api) => { api.onPageChange((url) => { const toggle = document.querySelector(".header-sidebar-toggle"); if (toggle) { if (url.startsWith("/guest-spot")) { toggle.style.display = "none"; } else { toggle.style.display = ""; } } }); }); }, }; </code></pre> Is it hacky? Yes. Does it work? Also yes. Sometimes pragmatic beats perfect.</p> Mobile Responsive</h2> Mobile-first isn't just a buzzword here. It's critical. Tattoo artists live on their phones. They're checking Instagram between clients, browsing artist portfolios while waiting for appointments, posting fresh work right after finishing a piece. If this doesn't work perfectly on a phone, it doesn't work at all.</p> The entire layout is mobile-first. Every component has media queries for tablet and phone breakpoints.</p> Carousel cards shrink to 80% viewport width on phones so you can see part of the next card (scroll hint). Grid forces a single column on small screens so cards don't get comically tiny. Post detail pages reduce padding and image heights so everything fits nicely without excessive scrolling.</p> All CSS. No JavaScript calculating widths or handling resize events. The browser does the work, which means it's fast and doesn't drain battery with constant calculations.</p> What's Next</h2> This is Part 1. We've got the public showcase working. But there's more to build:</p> Post creation UI (artists need to upload images and write captions)</li> Admin controls (pin/unpin posts from the feed)</li> User profile pages (view all posts by a specific artist)</li> Comments system integration (if we want interaction on posts)</li> </ul> But most importantly: actually launching this for a real community. Getting feedback from artists. Seeing if this makes sense to people who aren't me.</p> That's the scary part. Building code is easy. Building for people? That's where it gets real.</p> Part 2 will cover the creation flow and admin tools. Stay tuned.</p> If you want to see the code, it's on GitHub: discourse-guest-spot</a></p> How I'm Using Claude Code for Daily Development Work Unknown — Fri, 24 Oct 2025 00:00:00 +0000 I've been using Claude Code for a few months now as my primary development assistant. Not as a replacement for thinking, but as a way to move faster on the boring stuff while keeping the interesting problems for myself.</p> What It's Actually Good At</h2> The Grunt Work</h3> Testing infrastructure is where Claude shines. Today, I needed to test SMTP error logging improvements. Instead of manually setting up mail-relay-simulator</a>, configuring different failure scenarios, and writing test cases, I described what I needed and got a complete Ruby script that:</p> Manages docker-compose lifecycle</li> Switches between 4 test scenarios (auth failures, wrong credentials, etc.)</li> Writes proper config files with correct syntax</li> Handles cleanup</li> </ul> The script works. It's maintainable. It saved me 2-3 hours of tedious setup work.</p> Research and Discovery</h3> "Find all the places in this codebase where we do X" - this is tedious grep work that Claude excels at. It can search, cross-reference, and explain patterns without me needing to open 20 files.</p> Example: When investigating AWS SDK credential chain bugs, I had Claude trace through the entire credential provider chain, find where it was failing, and document the root cause. That kind of code archaeology is perfect for AI assistance.</p> Documentation</h3> Writing test results documentation, commit messages, technical proposals - Claude can take my rough notes and produce clean markdown that I'd never bother writing myself. The writeup exists because the AI made it low-effort, not because I suddenly got better at documentation.</p> Where It Could Improve</h2> Understanding Intent</h3> If I'm not specific about what I want, Claude will give me something that technically works but misses the point. Example: I asked for markdown rendering in Neovim. Got three different failed attempts at split-window rendering before I just said "fuck it, just hard-wrap at 80 characters."</p> The AI doesn't know when to stop. It will keep trying increasingly complex solutions when the answer is "do less."</p> Production Debugging</h3> When real production issues happen, Claude's knowledge cutoff and lack of access to live systems means it's guessing. I can describe symptoms and it'll suggest things to check, but it's not replacing actual debugging experience.</p> Knowing What It Doesn't Know</h3> The worst thing Claude does is hallucinate with confidence. It'll make up photographer names for Unsplash images when WebFetch fails to parse the page. It'll suggest APIs that don't exist. It'll confidently explain behavior that's completely wrong.</p> You have to verify everything. Trust but verify isn't optional.</p> How I Actually Use It</h2> 1. Explicit Context</h3> I maintain a CONTEXT.md file with my preferences:</p> Code style (no emoji, wrap at 80 chars, prefer if !</code> over unless</code>)</li> Project patterns (date-based versioning, git workflow preferences)</li> Common pitfalls (Ruby openssl gem vs extension, Discourse auth patterns)</li> </ul> This cuts down on back-and-forth. Claude knows I want --no-ff</code> merges without me explaining it every time.</p> 2. Incremental Validation</h3> I don't let Claude write 500 lines without checking. Small changes, validate, next change. When it starts going off track, I stop and correct immediately.</p> If tests fail, I read the error myself. If code looks weird, I ask "why did you do it this way?" and often realize there's a better approach.</p> 3. Use It For What It's Built For</h3> Good uses:</p> File operations (read, edit, search)</li> Repetitive code changes</li> Documentation generation</li> Test script creation</li> Config file management</li> </ul> Bad uses:</p> Anything requiring judgment calls</li> Performance optimization without profiling</li> Security-sensitive code review</li> "Just make it work" prompts</li> </ul> 4. Keep Notes</h3> I have Claude maintain daily notes of what we worked on. Not as todo tracking, but as a context refresh. When I come back tomorrow, I can read yesterday's notes and pick up where we left off.</p> The notes also catch when Claude forgets something or contradicts earlier decisions.</p> The Workflow</h2> Typical session:</p> Me</strong>: "I need to test SMTP error logging with mail-relay-simulator"</li> Claude</strong>: Reads existing code, finds simulator location, proposes script structure</li> Me</strong>: "Yeah but make it modular, don't hardcode paths"</li> Claude</strong>: Updates script with env var + path discovery</li> Me</strong>: Runs script, hits error</li> Claude</strong>: "That error means X, here's the fix"</li> Me</strong>: Applies fix, tests, moves on</li> </ol> It's not magic. It's a very fast junior developer who never gets tired but also never learns from mistakes unless you tell it explicitly.</p> The Trap</h2> The trap is letting the AI do your thinking. It's really easy to just accept the first solution that looks reasonable. But "looks reasonable" and "is correct" aren't the same thing.</p> I caught Claude trying to use Dir.chdir</code> in a script today. RuboCop flagged it as not thread-safe. The "correct" solution was system(..., chdir: path)</code>. Claude didn't know that until the linter told it.</p> If I'm not reading the code and understanding the changes, I'm just a very expensive copy-paste machine.</p> Should You Use It?</h2> If you're junior: Maybe not yet. You need to build pattern recognition before you can effectively verify AI output. You won't know when it's bullshitting.</p> If you're mid-level: Useful for grunt work, but keep it on a short leash. You should be reading and understanding every change.</p> If you're senior: This is productivity steroids. You already know what good code looks like. AI just makes it faster to write.</p> Final Thoughts</h2> Claude Code isn't replacing developers. It's replacing the boring parts of development. The parts where you know exactly what needs to happen but it's going to take an hour of tedious typing.</p> I'm not using less brain power. I'm using it on the problems that actually matter instead of fighting with test harness boilerplate.</p> That's the win.</p> Building Yaks: A Virtual Currency System for Discourse (Part 4: Custom Titles and Earning System) Unknown — Sun, 19 Oct 2025 00:00:00 +0000 Part 1</a> covered the backend architecture, Part 2</a> covered topic pinning and expiration, and Part 3</a> covered topic boosting and custom avatar flair. This post covers two more major features: custom user titles and the automatic earning system.</p> Custom User Titles</h2> Custom titles let users spend Yaks to set a custom title displayed next to their username throughout the forum. Unlike Discourse's built-in title system (which is tied to badges and trust levels), Yak titles are purely cosmetic and time-limited.</p> </p> The Challenge: Serializer Discovery</h3> The first attempt seemed straightforward: override the title</code> field in the user serializers. But after implementing it, the title showed in user cards and profiles but not next to posts. Why?</p> Discourse uses different serializer methods for different contexts:</p> title</code>: Used in user cards, profiles, group member lists</li> user_title</code>: Used specifically in PostSerializer</code> for post display</li> </ul> This makes sense from an architecture perspective. Posts need their own serializer method because they serialize the user as a nested object, not as the main object.</p> The Solution: Override Both</h3> The fix required overriding both serializer methods across multiple serializers:</p> # For user cards, profiles, groups [:post, :user_card, :post_action_user, :user_name, :group_post_user, :group_user, :hidden_profile].each do |serializer_name| add_to_serializer(serializer_name, :title) do title_data = object.custom_fields["yak_features"]&.dig("title") if title_data && title_data["enabled"] title_data["text"] else object.title end end end # For post display (critical!) add_to_serializer(:post, :user_title) do user = object&.user return nil unless user title_data = user.custom_fields["yak_features"]&.dig("title") if title_data && title_data["enabled"] title_data["text"] else user.title end end </code></pre> In PostSerializer</code>, object</code> is a Post, so we access the user via object.user</code>. In user-focused serializers, object</code> is the User directly.</p> The Frontend Modal</h3> </p> The custom title modal is straightforward:</p> @tracked customTitle = ""; get characterCount() { return this.customTitle.length; } get isOverLimit() { return this.characterCount > 50; } get canApply() { return this.customTitle.trim().length > 0 && !this.isOverLimit && this.currentUser.yak_balance >= this.cost; } </code></pre> Live preview, character counter, balance check. The modal shows exactly what the title will look like before spending Yaks.</p> The Earning System</h2> This was the most complex feature to implement. Users needed a way to earn Yaks by contributing to the community, with anti-gaming measures built in.</p> Requirements</h3> From the start, the requirements were clear:</p> Be modular (database-driven, not hardcoded)</li> Rate limiting (can't spam posts to farm Yaks)</li> Trust level requirements (new accounts can't abuse it)</li> Content length minimums (beyond Discourse's defaults, prevent low-effort farming)</li> </ol> Database Schema</h3> Instead of hardcoding earning rules in the service, we made them database-driven:</p> create_table :yak_earning_rules do |t| t.string :action_key, null: false t.string :action_name, null: false t.text :description t.integer :amount, null: false, default: 0 t.integer :daily_cap, null: false, default: 0 t.integer :min_trust_level, null: false, default: 0 t.boolean :enabled, null: false, default: true t.jsonb :settings, default: {} t.timestamps end </code></pre> Seeded with four default rules:</p> Post Created</strong>: 2 Yaks, 20/day cap, TL1+, 20 character minimum</li> Topic Created</strong>: 5 Yaks, 10/day cap, TL1+, 50 character minimum</li> Post Liked</strong>: 3 Yaks, 30/day cap, TL1+</li> Solution Accepted</strong>: 25 Yaks, no cap, TL1+</li> </ol> The settings</code> jsonb column allows flexible per-rule configuration like content length minimums without schema changes.</p> Service Layer</h3> YakEarningService</code> handles all validation and awarding logic:</p> def self.award(user:, action_key:, related_post: nil, related_topic: nil) rule = YakEarningRule.get_rule(action_key) return false if !rule # Check trust level requirement return false if user.trust_level < rule.min_trust_level # Check minimum content length if applicable if rule.min_length > 0 content = related_post&.raw || related_topic&.first_post&.raw || "" return false if content.length < rule.min_length end # Check daily cap if rule.has_daily_cap? earned_today = get_daily_earning_count(user, action_key) return false if earned_today >= rule.daily_cap end # Award the Yaks wallet = YakWallet.find_or_create_by(user: user) YakTransaction.create!( user: user, yak_wallet: wallet, amount: rule.amount, transaction_type: "earn", description: "Earned from: #{rule.action_name}", related_post: related_post, related_topic: related_topic, ) wallet.update!(balance: wallet.balance + rule.amount) # Publish balance update to frontend MessageBus.publish("/yak-balance/#{user.id}", { balance: wallet.balance }, user_ids: [user.id]) true end </code></pre> The service returns a boolean so we can track success/failure in logs.</p> Rate Limiting Implementation</h3> Daily caps are enforced by counting today's transactions:</p> def self.get_daily_earning_count(user, action_key) wallet = YakWallet.find_by(user: user) return 0 if !wallet rule = YakEarningRule.find_by(action_key: action_key) return 0 if !rule start_of_day = Time.zone.now.beginning_of_day YakTransaction .where(yak_wallet: wallet) .where(transaction_type: "earn") .where("description LIKE ?", "Earned from: #{rule.action_name}") .where("created_at >= ?", start_of_day) .count end </code></pre> Single query per award attempt. Could be cached if it becomes a bottleneck, but the query is fast.</p> Event Hooks</h3> Discourse provides events for all the actions we care about:</p> DiscourseEvent.on(:post_created) do |post, opts, user| next if post.post_type != Post.types[:regular] next if post.deleted_at.present? next if post.hidden next if !post.user YakEarningService.award( user: post.user, action_key: "post_created", related_post: post, related_topic: post.topic, ) end DiscourseEvent.on(:like_created) do |post_action| post = post_action.post next if !post next if post.deleted_at.present? next if post.hidden next if post.user_id == post_action.user_id # No self-likes YakEarningService.award( user: post.user, action_key: "post_liked", related_post: post, related_topic: post.topic, ) end </code></pre> We also hook topic_created</code> and accepted_solution</code> (from the discourse-solved plugin, if installed).</p> Real-Time Balance Updates</h3> The original implementation had a problem: after earning Yaks, the user menu still showed the old balance. Page refresh required.</p> The fix uses MessageBus, Discourse's real-time messaging system:</p> Backend</strong>: Publish when balance changes</p> MessageBus.publish("/yak-balance/#{user.id}", { balance: wallet.balance }, user_ids: [user.id]) </code></pre> Frontend</strong>: Subscribe and update</p> const messageBus = container.lookup("service:message-bus"); messageBus.subscribe(`/yak-balance/${currentUser.id}`, (data) => { currentUser.set("yak_balance", data.balance); }); </code></pre> Now when you create a post, the balance in your user menu updates instantly. No polling, no page refresh.</p> Bugs Fixed</h2> Some bugs were discovered during manual testing. All three would have been caught immediately by integration tests.</p> Bug 1: Event Hook User Parameter</h3> The Discourse event signature includes a user</code> parameter:</p> DiscourseEvent.on(:post_created) do |post, opts, user| </code></pre> The first implementation used that parameter directly:</p> YakEarningService.award(user: user, ...) </code></pre> But that user</code> parameter is nil. The actual user must be accessed via post.user</code>. The test would have failed immediately with "User can't be blank".</p> Bug 2: Topic.raw Doesn't Exist</h3> Content length validation tried to access topic.raw</code>:</p> content = related_post&.raw || related_topic&.raw || "" </code></pre> But topics don't have a raw</code> field. Only posts do. The fix:</p> content = related_post&.raw || related_topic&.first_post&.raw || "" </code></pre> A test creating a topic would have crashed with "undefined method `raw' for Topic".</p> Bug 3: Missing User in Transaction</h3> YakTransaction</code> has a belongs_to :user</code> association, which validates presence by default in Rails. But we weren't passing it:</p> YakTransaction.create!( yak_wallet: wallet, amount: rule.amount, ... ) </code></pre> Should be:</p> YakTransaction.create!( user: user, yak_wallet: wallet, amount: rule.amount, ... ) </code></pre> Any test attempting to create a transaction would have failed validation.</p> A New Basic Test Suite Structure</h2> The test suite covers all validation paths:</p> RSpec.describe YakEarningService do describe ".award" do it "awards Yaks for valid post by TL1 user" do post = Fabricate(:post, user: user, raw: "This is a test post...") result = YakEarningService.award( user: post.user, action_key: "post_created", related_post: post, related_topic: post.topic, ) expect(result).to eq(true) expect(user.reload.yak_balance).to eq(2) end it "does not award Yaks to TL0 user" do post = Fabricate(:post, user: tl0_user, raw: "...") result = YakEarningService.award( user: post.user, action_key: "post_created", related_post: post, ) expect(result).to eq(false) expect(tl0_user.reload.yak_balance).to eq(0) end it "respects daily cap" do rule = YakEarningRule.find_by(action_key: "post_created") # Create posts up to daily cap rule.daily_cap.times do post = Fabricate(:post, user: user, raw: "...") YakEarningService.award(user: post.user, ...) end # Next post should fail due to cap post = Fabricate(:post, user: user, raw: "...") result = YakEarningService.award(user: post.user, ...) expect(result).to eq(false) end end end </code></pre> Tests force you to think about edge cases: trust levels, content length, daily caps, disabled rules.</p> Admin UI</h2> </p> The admin UI shows all earning rules in a table:</p> Action name and description</li> Amount of Yaks awarded</li> Daily cap (or "No limit")</li> Minimum trust level</li> Enabled status</li> </ul> Architecture Wins</h2> Database-Driven Configuration</strong>: No code changes needed to adjust earning amounts or daily caps. Just update the database.</p> Event-Driven</strong>: Loosely coupled. The earning system doesn't need to know about post creation internals, just subscribes to events.</p> Real-Time Updates</strong>: MessageBus makes instant balance updates trivial. Six lines of code for publish and subscribe.</p> Proper Service Layer</strong>: Business logic lives in YakEarningService</code>, not scattered across controllers and models.</p> Full Audit Trail</strong>: Every earning action creates a transaction record with type, amount, description, and related post/topic. Complete history.</p> Performance Considerations</h2> Single Query for Rate Limiting</strong>: The daily count query is simple and fast. Could be cached if it becomes a bottleneck.</p> No N+1 Queries</strong>: Balance updates happen during the transaction creation, no separate queries.</p> MessageBus Efficiency</strong>: Only publishes to the specific user who earned Yaks. Not broadcasting to everyone.</p> Indexed Properly</strong>: Transactions table has indexes on yak_wallet_id</code>, transaction_type</code>, and created_at</code> for the daily count query.</p> What's Left</h2> The plugin is now feature-complete for the MVP:</p> Wallet system with transaction logging</li> Multiple purchasable features (post highlighting, topic boosting, custom flair, custom titles)</li> Expiration system (features automatically expire)</li> Earning system (users earn Yaks by contributing)</li> Admin UI (view stats, packages, features, earning rules)</li> Real-time updates (no page refresh needed)</li> </ul> Remaining work:</p> Payment integration (Stripe or similar) for purchasing Yak packages</li> Guardian authorization checks (ensure users can only spend their own Yaks)</li> More earning actions (first reply, helpful flags, etc.)</li> Admin edit functionality for earning rules</li> Production monitoring and adjustment based on real usage</li> </ul> Lessons Learned</h2> Serializers Are Powerful</strong>: Understanding Discourse's serializer architecture unlocks a lot of customization possibilities.</p> MessageBus Is Handy</strong>: Real-time updates are easy with MessageBus, yet some plugins don't use it.</p> Database-Driven Config Is Worth It</strong>: The upfront effort to make earning rules configurable pays off in flexibility.</p> Event Hooks Are Reliable</strong>: Discourse's event system is solid. Events fire consistently and provide the data you need.</p> Conclusion</h2> Building a virtual currency system is teaching me a lot about Discourse's architecture. Serializers, custom fields, MessageBus, service objects, event hooks - all pieces that work together to create a cohesive plugin.</p> The earning system was the most complex feature, but also the most rewarding. Watching a user create a post and seeing their balance update instantly, knowing that every piece of the system is working together (event hooks, service validation, database transactions, MessageBus publishing, frontend subscription) - that's satisfying.</p> The full source code is available at github.com/ducks/discourse-yaks</a>. If you're building a Discourse plugin and want to see how all these pieces fit together, the repo should be a useful reference.</p> Next up: Payment integration and production deployment. Stay tuned for Part 5.</p> Building Yaks: A Virtual Currency System for Discourse (Part 3: Advanced Features) Unknown — Sat, 18 Oct 2025 00:00:00 +0000 Part 1</a> covered the backend architecture and Part 2</a> covered topic pinning and the expiration system. This post covers two more complex features: topic boosting (pinning topics globally with visual highlighting) and custom avatar flair (letting users customize their forum identity).</p> Topic Pin vs Topic Boost</h2> The plugin has two topic pinning features with different scopes:</p> Topic Pin</strong>: Pins a topic to the top of its category only. The topic stays at the top of the category page but doesn't appear across other categories. No visual highlighting.</p> Topic Boost</strong>: Pins a topic globally across all categories AND adds a colored border to make it stand out in topic lists. Much more visibility, costs more Yaks.</p> This post focuses on topic boost, the more powerful and visually striking feature.</p> Topic Boost: Making Threads Stand Out</h2> Topic boost is a premium feature that pins a topic globally (across all categories) and adds a colored border to make it stand out in topic lists.</p> </p> Backend: Leveraging Discourse APIs</h3> Discourse has native topic pinning built in. The API is straightforward:</p> topic.update_pinned(status, global, pinned_until) </code></pre> Parameters:</p> status</code>: true to pin, false to unpin</li> global</code>: true for global pin (all categories), false for category only</li> pinned_until</code>: timestamp as string (not Time object)</li> </ul> The service implementation for topic boost:</p> when "topic_boost" duration = feature.settings["duration_hours"]&.hours || 72.hours related_topic.update_pinned(true, true, duration.from_now.to_s) current_features = related_topic.custom_fields["yak_features"] || {} current_features["boosted"] = { enabled: true, color: feature_data[:color] || "gold", applied_at: Time.zone.now.to_i, } related_topic.custom_fields["yak_features"] = current_features related_topic.save_custom_fields </code></pre> This does two things:</p> Pins the topic globally for 72 hours using Discourse's native pinning</li> Stores visual customization data (color choice) in topic custom fields</li> </ol> Frontend: Value Transformers</h3> To apply CSS classes to boosted topics in topic lists, we use Discourse's value transformer API. This is the modern replacement for the deprecated widget decorators.</p> api.registerValueTransformer("topic-list-item-class", ({ value, context }) => { const topic = context?.topic; if (topic?.yak_features?.boosted?.enabled) { value.push("yak-boosted-topic"); const color = topic.yak_features.boosted.color || "gold"; value.push(`yak-color-${color}`); } return value; }); </code></pre> The transformer receives a value</code> array and adds CSS classes based on the topic's custom fields. Optional chaining (?.</code>) prevents errors if the data is missing.</p> We also apply styling to the first post in boosted topics:</p> const topic = helper.getModel().topic; const topicYakFeatures = topic?.yak_features; const isFirstPostInBoostedTopic = post.post_number === 1 && topicYakFeatures?.boosted?.enabled; if (isFirstPostInBoostedTopic) { article.classList.add("yak-boosted-topic-post"); const color = topicYakFeatures.boosted.color || "gold"; article.classList.add(`yak-color-${color}`); } </code></pre> This gives visual consistency. The colored border appears both in topic lists and on the opening post.</p> Avoiding N+1 Queries</h3> When adding custom field serialization, you must tell Discourse to preload the data to avoid N+1 query warnings:</p> TopicList.preloaded_custom_fields << "yak_features" if TopicList.respond_to?(:preloaded_custom_fields) </code></pre> Without this, accessing topic.custom_fields["yak_features"]</code> in serializers triggers a database query for every topic in the list. With preloading, all custom fields load in a single query.</p> Pin Auto-Dismiss Behavior</h3> Discourse has built-in pin dismissal behavior. When a user visits a pinned topic, Discourse creates a TopicUser</code> record with cleared_pinned_at</code> timestamp. For that user, the topic shows as unpinned.</p> This is intentional design to prevent banner blindness. The topic stays pinned for everyone else, but individual users can dismiss it after viewing. The colored border remains visible to all users regardless of pin state.</p> CSS Variables for Theme Customization</h3> Originally, colors were hardcoded:</p> .yak-boosted-topic.yak-color-gold { border-color: #ffd700; background: rgba(255, 215, 0, 0.1); } </code></pre> This made it difficult for theme authors to customize colors. The fix was CSS variables:</p> :root { --yak-color-gold: #ffd700; --yak-color-gold-bg: rgba(255, 215, 0, 0.1); --yak-color-blue: #4169e1; --yak-color-blue-bg: rgba(65, 105, 225, 0.1); // ... } .yak-boosted-topic.yak-color-gold { border-color: var(--yak-color-gold); background: var(--yak-color-gold-bg); } </code></pre> Now theme authors can override colors without modifying plugin code:</p> :root { --yak-color-gold: #ff9900; --yak-color-gold-bg: rgba(255, 153, 0, 0.15); } </code></pre> Custom Avatar Flair: User Identity</h2> Avatar flair is the small badge that appears next to a user's avatar. Normally it's set at the group level (moderators get one badge, admins get another). The custom flair feature lets individual users choose their own icon and color scheme for 30 days.</p> </p> The Challenge: Integrating with Existing Components</h3> Discourse has an existing UserAvatarFlair</code> component that reads flair data from serializers. The component expects certain fields (flair_group_id</code>, flair_url</code>, flair_bg_color</code>, etc.) and renders accordingly.</p> Initially, I tried using widget decorators to inject custom data. This hit deprecation warnings. The modern pattern is overriding serializer fields directly.</p> Serializer Override Pattern</h3> Instead of decorating components, we override the serializer methods:</p> [:post, :user_card, :post_action_user].each do |serializer_name| add_to_serializer(serializer_name, :flair_url) do user = serializer_name == :post ? object.user : object flair = user.custom_fields["yak_features"]&.dig("flair") if flair && flair["enabled"] flair["icon"] # Return icon name like "rocket" or "crown" else user.flair_group&.flair_icon || user.flair_group&.flair_upload&.url end end end </code></pre> This checks user custom fields first. If yak custom flair is present, return that data. Otherwise, fall back to group flair.</p> Similar overrides for flair_bg_color</code>, flair_color</code>, and flair_name</code>. This pattern works across all serializers (post, user card, action user) without touching the component.</p> The flair_group_id Problem</h3> The UserAvatarFlair</code> component has an early return:</p> if (!user || !user.flair_group_id) { return; // No flair rendered } </code></pre> Users with custom flair but no group flair would fail this check. The component would exit early and never render anything.</p> The fix was setting a dummy marker value:</p> add_to_serializer(serializer_name, :flair_group_id) do user = serializer_name == :post ? object.user : object flair = user.custom_fields["yak_features"]&.dig("flair") if flair && flair["enabled"] -1 # Dummy value to pass existence check else user.flair_group_id end end </code></pre> With flair_group_id</code> set to -1</code>, the component passes the existence check. It then finds flair_url</code> is set (to the icon name) and renders the custom flair.</p> Frontend: Icon and Color Picker</h3> </p> The flair modal presents three selection grids:</p> const ICONS = ["star", "heart", "fire", "bolt", "gem", "crown", "rocket", "trophy"]; const BG_COLORS = ["#ffd700", "#4169e1", "#dc143c", "#32cd32", "#9370db", "#ff8c00"]; const TEXT_COLORS = ["#ffffff", "#000000", "#ffd700"]; </code></pre> Users click icons to select one, then choose background and text colors. A live preview shows the combination:</p> <div class="flair-preview"> <span class="user-flair" style={{this.previewStyle}}> {{d-icon this.selectedIcon}} </span> </div> </code></pre> The preview updates reactively as selections change. Once the user confirms, the modal sends the choices to the backend, which stores them in user custom fields.</p> Making Feature Cards Clickable</h3> On the wallet page, custom flair is the only feature that needs a modal (icon/color picker). Other features just need a color picker, which is handled inline.</p> To make the custom flair card clickable, we split the template:</p> {{#if (eq feature.id "custom_flair")}} <div class="feature-card clickable" {{on "click" this.openFlairModal}}> {{! card content }} </div> {{else}} <div class="feature-card"> {{! card content }} </div> {{/if}} </code></pre> Only the custom flair card gets the click handler. Other cards remain static. This avoids passing undefined</code> callbacks to the {{on}}</code> helper.</p> What's Next</h2> The plugin now has:</p> Post highlighting (colored borders)</li> Topic pinning (category-only)</li> Topic boosting (global pin + highlight)</li> Custom avatar flair (user identity)</li> </ul> Still to implement:</p> Post pinning (pin individual post to top of topic)</li> Post boosting (increase visibility in feeds)</li> Earning system (auto-reward quality posts)</li> Guardian authorization (permission checks)</li> Admin dashboard improvements</li> </ul> The earning system is the next major piece. Right now, users can only spend Yaks. They need ways to earn them through quality contributions, not just purchases.</p> Code is on GitHub: ducks/discourse-yaks</a></p> Building Yaks: A Virtual Currency System for Discourse (Part 2: Features and Expiration) Unknown — Fri, 17 Oct 2025 00:00:00 +0000 In Part 1</a>, I covered the backend architecture for Yaks: wallets, transactions, and the service layer. The database models were in place, but the system could only apply one feature (post highlighting) and had no way to clean up expired features.</p> Part 2 covers:</p> Implementing topic pinning (our second feature)</li> Refactoring the service layer to be truly modular</li> Building an expiration system with background jobs</li> Starting the admin configuration UI</li> </ul> </p> </p> Topic Pinning</h2> Topic pinning lets users spend Yaks to pin their topic to the top of its category for a configurable duration. This uses Discourse's native pinning mechanism, but requires currency to access.</p> Why This Feature Matters</h3> Forums prioritize content by recency. Older discussions get buried. Topic pinning gives users a way to temporarily boost visibility for important discussions without needing moderator intervention.</p> The constraint is time. After the configured duration expires, the pin is removed and the topic returns to normal sorting.</p> The Service Architecture Problem</h3> When implementing topic pinning, I hit an architectural issue. The existing YakFeatureService.apply_feature</code> method was post-centric:</p> def self.apply_feature(user, feature_key, related_post, feature_data: {}) # ... validation logic ... feature_use = YakFeatureUse.create!( user: user, yak_feature: feature, related_post: related_post, # Always requires a post feature_data: feature_data ) end </code></pre> This design assumed every feature applies to a post. But topic pinning applies to a topic, not a post. I could hack around it by passing related_post.topic</code>, but that's wrong. The service should support both contexts.</p> Looking at the implementation, the issue was clear. The service wasn't modular at all. It was built for posts and only posts. Adding topic support meant refactoring the core design.</p> Refactoring the Service</h3> The fix was adding support for both posts and topics:</p> # Old (post-centric) def self.apply_feature(user, feature_key, related_post, feature_data: {}) # New (modular, all keyword) def self.apply_feature( user:, feature_key:, related_post: nil, related_topic: nil, feature_data: {} ) </code></pre> Now the service accepts either a post or a topic (or neither, for user-level features like custom flair). Making all parameters keyword arguments forces explicit call sites, which prevents mistakes when you have multiple optional params.</p> Validation got context-specific methods:</p> def self.can_apply_to_post?(feature_key, post, user) return false if post.trashed? || post.deleted_at.present? return false if post.user_id != user.id # Check for existing active feature !YakFeatureUse.exists?( user: user, yak_feature: YakFeature.find_by(feature_key: feature_key), related_post: post, expires_at: Time.zone.now..Float::INFINITY ) end def self.can_apply_to_topic?(feature_key, topic, user) return false if topic.closed || topic.archived return false if topic.user_id != user.id # Check for existing active feature !YakFeatureUse.exists?( user: user, yak_feature: YakFeature.find_by(feature_key: feature_key), related_topic: topic, expires_at: Time.zone.now..Float::INFINITY ) end </code></pre> This pattern will scale. When we add user-level features (custom flair), we'll add can_apply_to_user?</code> without touching the core service logic.</p> Integrating with Discourse's Topic Pinning</h3> Discourse has built-in topic pinning. The Topic</code> model has an update_pinned</code> method:</p> duration = feature.duration_hours.hours topic.update_pinned(true, false, duration.from_now.to_s) </code></pre> Three parameters:</p> pinned</code> - Enable or disable the pin</li> global</code> - Pin globally (across all categories) or just in this topic's category</li> pinned_until</code> - When to automatically unpin (must be a string timestamp)</li> </ol> The third parameter is critical. It must be a string, not a Time object. This caught me during implementation:</p> # Wrong (creates YakFeatureUse but topic doesn't actually pin) topic.update_pinned(true, false, feature.duration_hours.hours.from_now) # Correct topic.update_pinned(true, false, feature.duration_hours.hours.from_now.to_s) </code></pre> The feature use was being created, the Yaks were being deducted, but the topic wasn't pinning. The issue was the timestamp format. update_pinned</code> silently fails if you pass a Time object instead of a string.</p> Expiration System</h2> Features need to expire. Each feature has a configurable duration stored in the database. We need a way to clean up expired features and undo their effects.</p> The Architecture</h3> The system has three parts:</p> Regular Job</strong>: ExpireYakFeature</code> - Handles a single expiration</li> Scheduled Job</strong>: CleanupExpiredYakFeatures</code> - Finds expired features and queues regular jobs</li> Service Method</strong>: YakFeatureService.expire_feature</code> - Business logic for expiration</li> </ol> The primary expiration mechanism runs at creation time. When a feature use is created, the expiration job is scheduled to run exactly when it expires:</p> def self.apply_feature(...) feature_use = YakFeatureUse.create!(...) if feature_use.expires_at Jobs.enqueue_at(feature_use.expires_at, :expire_yak_feature, feature_use_id: feature_use.id) end # ... end </code></pre> This is efficient. No polling. The job runs exactly when needed.</p> The Scheduled Job</h3> Runs hourly to find expired features:</p> module Jobs class CleanupExpiredYakFeatures < ::Jobs::Scheduled every 1.hour def execute(args) expired_features = YakFeatureUse .where("expires_at IS NOT NULL AND expires_at <= ?", Time.zone.now) .where(expired: false) expired_features.find_each do |feature_use| Jobs.enqueue(:expire_yak_feature, feature_use_id: feature_use.id) end { processed: expired_features.count } end end end </code></pre> It queries for expired features (where expires_at</code> is in the past) and queues a job for each one.</p> This hourly cleanup job is a safety net. If the server restarts before a scheduled job runs, or if something goes wrong with job scheduling, the cleanup job catches it. It's backup, not the primary mechanism.</p> Why find_each</code> instead of each</code>? Performance. find_each</code> loads records in batches (1000 by default) instead of loading everything into memory. If you have 10,000 expired features, each</code> would load all 10,000 at once. find_each</code> loads 1000, processes them, loads the next 1000.</p> The Regular Job</h3> Processes one expiration:</p> module Jobs class ExpireYakFeature < ::Jobs::Base def execute(args) feature_use = YakFeatureUse.find_by(id: args[:feature_use_id]) return unless feature_use YakFeatureService.expire_feature(feature_use) end end end </code></pre> Why a separate job? Fault tolerance. If one expiration fails (database error, bug in the expiration logic), it doesn't stop the others from processing.</p> The Service Method</h3> Handles the business logic:</p> def self.expire_feature(feature_use) feature_key = feature_use.yak_feature.feature_key case feature_key when "post_highlight" remove_post_highlight(feature_use.related_post) when "topic_pin" unpin_topic(feature_use.related_topic) end feature_use.update!(expired: true) end private def self.remove_post_highlight(post) return unless post features = post.custom_fields["yak_features"] || {} features.delete("highlight") if features.empty? post.custom_fields.delete("yak_features") else post.custom_fields["yak_features"] = features end post.save_custom_fields end def self.unpin_topic(topic) return unless topic topic.update_pinned(false, false, nil) end </code></pre> Expiration removes the visual effects and marks the feature use as expired.</p> Why mark as expired instead of deleting? Audit trail. Users can see their feature history. Admins can debug issues. Refunds are easier because you have the original feature use record.</p> Frontend Integration</h2> The frontend needed two things:</p> A "Spend Yaks" button on topics</li> Context-aware modal that shows appropriate features</li> </ol> Topic Footer Button</h3> Discourse has an API for adding buttons to topic footers:</p> import { withPluginApi } from "discourse/lib/plugin-api"; export default { name: "yak-topic-actions", initialize() { withPluginApi((api) => { api.registerTopicFooterButton({ id: "yak-spend", icon: "coins", label: "yaks.topic_action.spend", action() { const modal = getOwner(this).lookup("service:modal"); modal.show(SpendYaksModal, { model: { topic: this.topic, }, }); }, dropdown() { return this.site.mobileView; }, classNames: ["yak-spend"], dependentKeys: ["topic.closed", "topic.archived"], displayed() { return ( this.currentUser && this.topic.user_id === this.currentUser.id && !this.topic.closed && !this.topic.archived ); }, }); }); }, }; </code></pre> The displayed()</code> function controls visibility. The button only shows if:</p> User is logged in</li> User owns the topic</li> Topic isn't closed or archived</li> </ul> Context-Aware Modal</h3> The modal needed to work for both posts and topics:</p> export default class SpendYaksModal extends Component { get isPostContext() { return !!this.args.model.post; } get isTopicContext() { return !!this.args.model.topic && !this.args.model.post; } get postFeatures() { return this.allFeatures.filter((f) => f.category === "post"); } get topicFeatures() { return this.allFeatures.filter((f) => f.category === "topic"); } get availableFeatures() { if (this.isPostContext) return this.postFeatures; if (this.isTopicContext) return this.topicFeatures; return []; } } </code></pre> One modal, two contexts. The UI adapts based on whether you clicked "Spend Yaks" on a post or a topic.</p> Admin UI (In Progress)</h2> The final piece is admin configuration. Currently, features and purchase packages are hardcoded. They need to be editable in the UI.</p> Database-Backed Packages</h3> Created a yak_packages</code> table:</p> create_table :yak_packages do |t| t.string :name, null: false t.text :description t.integer :price_cents, null: false, default: 0 t.integer :yaks, null: false, default: 0 t.integer :bonus_yaks, null: false, default: 0 t.boolean :enabled, null: false, default: true t.integer :position, null: false, default: 0 t.timestamps end </code></pre> Price is stored as cents (integers) instead of dollars (floats) to avoid floating-point precision issues. A $5.00 package is 500 cents.</p> The model has helper methods:</p> class YakPackage < ActiveRecord::Base def total_yaks yaks + bonus_yaks end def price_usd price_cents / 100.0 end def price_usd=(usd) self.price_cents = (usd.to_f * 100).to_i end end </code></pre> This lets you work in dollars in the UI but store as cents in the database.</p> CRUD Endpoints</h3> Added REST endpoints to the admin controller:</p> def packages packages = YakPackage.ordered render json: { packages: packages.map { |p| serialize_package(p) } } end def create_package package = YakPackage.new(package_params) if package.save render json: { package: serialize_package(package) } else render_json_error(package.errors.full_messages.join(", ")) end end def update_package package = YakPackage.find(params[:id]) if package.update(package_params) render json: { package: serialize_package(package) } else render_json_error(package.errors.full_messages.join(", ")) end end def delete_package package = YakPackage.find(params[:id]) package.destroy! render json: success_json end </code></pre> Standard Rails REST pattern. The admin can create, edit, and delete packages without touching code.</p> Admin UI Structure</h3> The UI follows Discourse's admin plugin pattern (inspired by the Chat plugin):</p> admin/assets/javascripts/discourse/ ├── routes/admin-plugins/show/discourse-yaks-management/ ├── controllers/admin-plugins/show/discourse-yaks-management/ ├── templates/admin/plugins/show/discourse-yaks-management/ └── initializers/yaks-admin-plugin-configuration-nav.js </code></pre> The structure creates tabs:</p> Settings</strong> - Site settings (automatic)</li> Management</strong> - Custom UI for packages, features, stats</li> </ol> The templates use Discourse's admin components:</p> <div class="admin-config-page"> <div class="admin-plugin-config-page"> <div class="d-page-header"> <div class="d-page-header__title-row"> <h1 class="d-page-header__title">Yak Management</h1> </div> <p class="d-page-header__description"> Manage your virtual currency system. Configure purchase packages and premium features. </p> </div> <div class="admin-plugin-config-page__content">  </div> </div> </div> </code></pre> This matches Discourse's standard admin page structure. Using the framework's components ensures consistency with the rest of the admin area.</p> Current Status</h3> The admin UI backend is complete (CRUD endpoints, modals, tables), but the tab navigation isn't working yet. The Settings tab appears, but the Management tab doesn't. This is a routing issue, not a data issue.</p> The tables work when accessed directly. The functionality is there. The navigation just needs debugging.</p> What's Next</h2> The immediate task is fixing the admin UI tab navigation. Once that's working, admins will have full control over the system configuration:</p> Add/edit/delete purchase packages (price, Yak amounts, bonus structure)</li> Configure feature costs and durations (how many Yaks, how long they last)</li> View system statistics (total wallets, Yaks in circulation, active features)</li> </ul> After that:</p> Implement the earning system (reward quality posts based on configurable criteria)</li> Build the remaining features (post pin, post boost, custom flair)</li> Add purchase flow integration (Stripe for buying Yaks with real money)</li> </ul> The plugin is functional. Two features work end-to-end. The expiration system is running. The architecture is modular enough to add new features without major refactoring.</p> Part 3 will cover the earning system and completing the admin UI.</p> The code is on GitHub: ducks/discourse-yaks</a></p> ChatGPT assisted Changelog - 42/52 Unknown — Fri, 17 Oct 2025 00:00:00 +0000 AWS SDK Ruby contributions and follow-up</strong></p> You published Contributing to AWS SDK Ruby - Part 3</em>, which wrapped up your series about improving the Ruby AWS SDK. You mentioned the post got 3 boosts on Mastodon and linked to it from Hachyderm. We also talked briefly about your earlier PRs and how they connect -- adding a feature first, then fixing a bug.</p> Transit Tracker and Discourse experiments</strong></p> You released and shared Building a Live Transit Departure Board with Discourse</em>, a creative exploration of using Discourse for something non-forum-like. We talked about whether posting it on Discourse's official blog or community site would be weird, and you decided it'd actually fit since you work there. You also added screenshots later to make the post more engaging.</p> GoatCounter and analytics debugging</strong></p> You tried exporting page-view data from your self-hosted GoatCounter instance, but ran into a network failure while testing the API. You realized you might not have the admin section working yet. You also revisited an older issue about countries being listed twice in your data and looked at the GoatCounter repo to see why.</p> Personal tools and privacy</strong></p> We discussed private movement trackers for GrapheneOS, and you settled on PFA</em> as a lightweight way to track steps and distance without leaking data.</p> Side notes</strong></p> You mentioned two new blog posts being live -- Transit Tracker in Discourse</em> and Yak's Virtual Currency - Part 2</em> -- both updated with screenshots.</p> Building Slumprutt: A Random Route Generator in Under an Hour Unknown — Thu, 16 Oct 2025 00:00:00 +0000 I've wanted a random route generator for awhile now. My problem is I walk and bike the same routes over and over. My brain goes on autopilot. I wanted something that would throw me new routes to explore in my own neighborhood.</p> I wanted something simple: "Give me a random 5-mile loop from my house."</p> So I built it. With Claude Code's help, we went from idea to working app in under an hour.</p> The Name</h2> "Slumprutt" comes from Swedish "slumpmässig rutt" (slumpmässig = random or by chance, rutt = route), commonly shortened to just "slumprutt". Seemed fitting for a random route generator.</p> The Stack</h2> Backend</strong>: TypeScript + Node.js + Express</p> Frontend</strong>: Svelte + TypeScript + Leaflet</p> Routing</strong>: OSRM (Open Source Routing Machine)</p> Maps</strong>: OpenStreetMap</p> OSRM deserves special mention. It's a free public API that provides road-accurate routing with turn-by-turn directions. Incredibly fast (sub-second response times) and requires zero setup. Just hit their public endpoint and get back real routes that follow actual roads.</p> The Algorithm</h2> The core challenge was generating interesting random loops. Not just random waypoints, but routes that actually feel like purposeful walks or bike rides.</p> Here's what I landed on:</p> export function generateLoopWaypoints( start: Coordinate, targetDistanceKm: number, variationIndex: number = 0 ): Coordinate[] { // Use fewer waypoints (3-5) for longer segments const numWaypoints = Math.max(3, Math.min(5, 3 + variationIndex)); // Reduced multiplier to 0.6 to account for road routing overhead const baseRadius = targetDistanceKm / (2 * Math.PI) * 0.6; const waypoints: Coordinate[] = []; const latPerKm = 1 / 111; // 1 degree latitude ≈ 111km const lonPerKm = 1 / (111 * Math.cos((start.lat * Math.PI) / 180)); // Rotate each route by 120° to avoid overlap const primaryDirection = (variationIndex * (2 * Math.PI)) / 3; for (let i = 0; i < numWaypoints; i++) { const baseAngle = (i / numWaypoints) * 2 * Math.PI + primaryDirection; // More randomness for diverse paths const angleVariation = (Math.random() - 0.5) * 0.8; const angle = baseAngle + angleVariation; // More radius variation to explore different distances const radiusVariation = 0.5 + Math.random() * 1.0; const radius = baseRadius * radiusVariation; waypoints.push({ lat: start.lat + Math.sin(angle) * radius * latPerKm, lon: start.lon + Math.cos(angle) * radius * lonPerKm, }); } return waypoints; } </code></pre> Key design decisions:</p> Fewer waypoints</strong> (3-5 instead of 8+) means longer road segments and more interesting routes. Too many waypoints and you just walk back and forth.</p> </li> Smaller radius with overhead adjustment</strong> (0.6x) accounts for the fact that road routing adds significant distance compared to straight-line waypoints. Initially used 1.5x which resulted in 7-8 mile routes when requesting 1 mile.</p> </li> Directional rotation</strong> (120° per route) prevents all routes from heading in the same direction. Generate 3 routes and they'll spread out into different quadrants.</p> </li> More randomness</strong> (0.8 angle variation, 0.5-1.5 radius variation) creates diverse paths that explore different areas. This prevents multiple routes from clustering in the same locations.</p> </li> </ol> Then we feed those waypoints to OSRM, which turns them into actual road routes with turn-by-turn directions.</p> Challenges</h2> Distance Input Validation</h3> First issue: weird validation errors when changing distance inputs. I had step="0.1"</code> on both the miles and kilometers inputs. The problem: 3.2 miles converts to 5.1494888 km, which rounds to 5.15. The browser expected 5.1 or 5.2 (multiples of 0.1) and rejected 5.15.</p> Fix: step="any"</code> accepts any decimal value.</p> Map Not Visible</h3> Built the whole UI, ran it, and... no map. Just an empty space where the map should be.</p> The issue: CSS height inheritance. The map div had height: 100%</code> but its parent containers didn't have explicit heights. The fix required setting height on three elements:</p> :global(html), :global(body), :global(#app) { height: 100%; width: 100%; } </code></pre> This is a common Svelte gotcha when you want a full-viewport layout.</p> Routes Don't Follow Roads</h3> Initial implementation drew straight lines between waypoints. Routes went through buildings, parks, water. Not useful for actual navigation.</p> This is where OSRM saved the day. One API call with waypoints, get back actual road geometry:</p> const coords = route.points.map(p => `${p.lon},${p.lat}`).join(';'); const url = `https://router.project-osrm.org/route/v1/${profile}/${coords}?overview=full&geometries=geojson&steps=true`; const response = await fetch(url); const data = await response.json(); </code></pre> The steps=true</code> parameter gives you turn-by-turn directions too, which I added to the UI in collapsible sections under each route.</p> Boring Back-and-Forth Routes</h3> First test: "Walk this way, turn around, walk back." Technically a loop, but boring as hell.</p> The issue was too many waypoints creating short segments. The fix was the algorithm changes I mentioned earlier: fewer waypoints, larger radius, directional rotation. Now routes actually explore different areas instead of just oscillating.</p> TypeScript Across the Stack</h2> I initially questioned whether TypeScript was overkill for this project. Turns out it was perfect.</p> Shared types between frontend and backend caught so many potential bugs:</p> export interface Coordinate { lat: number; lon: number; } export interface GeneratedRoute { id: number; points: Coordinate[]; waypoints: Coordinate[]; isLoop: boolean; distance?: number; duration?: number; steps?: RouteStep[]; } </code></pre> When the backend returns GeneratedRoute[]</code>, the frontend knows exactly what shape to expect. No guessing, no runtime surprises.</p> Development Environment</h2> Created a Nix shell for reproducible development:</p> { pkgs ? import <nixpkgs> {} }: pkgs.mkShell { buildInputs = with pkgs; [ nodejs_22 typescript nodePackages.tsx ]; } </code></pre> Anyone can clone the repo, run nix-shell</code>, and have the exact same environment. No "works on my machine" issues.</p> Result</h2> The app works. You enter an address, pick a mode (walk/bike/car), set a distance, and hit generate. It shows you multiple random routes on an interactive map with turn-by-turn directions.</p> </p> </p> </p> </p> I've already used it to find new walking routes in my neighborhood.</p> Is it perfect? No, it's not. You will get routes that go down sketchy roads or routes that still go back and forth. But it was fun and it's helpful to me.</p> Try it yourself</strong>: github.com/ducks/slumprutt</a></p> What I Learned</h2> OSRM is incredible</strong> - Free, fast, accurate. No API key required. If you're building anything with routing, use OSRM.</p> </li> TypeScript prevents so many bugs</strong> - Especially for coordinate/route data that flows through multiple layers. Type errors at compile time beat runtime errors every time.</p> </li> Fewer waypoints make better routes</strong> - Counterintuitive, but 3-5 waypoints create more interesting loops than 8-10.</p> </li> Svelte's reactivity is clean</strong> - No useState/useEffect boilerplate. Just $: if (condition) { doThing() }</code> and it works.</p> </li> Building with AI is wild</strong> - Went from idea to working app in under an hour. Not just scaffolding, but a fully functional app with an interesting algorithm, API integration, and polished UI.</p> </li> </ol> AWS SDK Ruby Part 3: When "Working as Intended" Means "Broken by Design" Unknown — Tue, 14 Oct 2025 00:00:00 +0000 The Saga Continues</h3> If you've been following along (Part 1</a> and Part 2</a>), you know I've been on a journey fixing AWS SDK Ruby credential handling. First I added the missing credential_source = Environment</code> implementation, then I discovered it didn't actually work due to credential chain precedence issues.</p> After extensive testing and code analysis, I submitted PR #3303</a> with a fix. The maintainer initially responded positively:</p> "Hey, thanks for opening an issue. I believe you are correct and this is something we need to fix."</p> </blockquote> Great! But then...</p> The Reversal</h3> After I provided detailed testing comparing AWS CLI behavior, demonstrated the fix working in production, and showed exactly which code was unreachable due to the chain precedence, the maintainer walked it back:</p> "From what I understand, I think the default chain will try to resolve credentials as quickly as possible, so if environment variables are set it will use them directly instead of using them as a credential source. We try not to change the behavior of the default chain since returning credentials in a different order can break many customers."</p> </blockquote> And then closed both the issue and PR.</p> Why This Is Wrong</h3> 1. The Feature Is Completely Broken</strong></p> When you configure:</p> [default] role_arn = arn:aws:iam::123456789012:role/MyRole credential_source = Environment </code></pre> What happens?</p> env_credentials</code> (position 7) finds AWS_ACCESS_KEY_ID</code> and AWS_SECRET_ACCESS_KEY</code></li> Chain returns those credentials and stops</li> assume_role_credentials</code> (position 10) never executes</li> The role_arn</code> and credential_source</code> configuration is completely ignored</strong></li> </ol> The maintainer confirmed this: "All of the static_profile_</code> methods handle credentials resolution when a client is configured explicitly with a profile."</p> So the feature works... but only if you don't use the credential chain, which defeats the entire purpose of having a credential chain.</p> 2. The Code Contradicts Their Argument</strong></p> Look at shared_config.rb:392-400</code></a>:</p> def credentials_from_source(credential_source, config) case credential_source when 'Ec2InstanceMetadata' # ... when 'EcsContainer' # ... when 'Environment' creds = Credentials.new( ENV['AWS_ACCESS_KEY_ID'], ENV['AWS_SECRET_ACCESS_KEY'], ENV['AWS_SESSION_TOKEN'] ) creds.metrics = ['CREDENTIALS_ENV_VARS'] creds end end </code></pre> This code exists specifically to use environment variables as source credentials for role assumption. But the credential chain prevents it from ever executing when using the default profile.</p> 3. The Workaround Proves It's Broken</strong></p> The maintainer suggested: "if specifying the profile resolves your issue I would recommend doing that."</p> But that's not a solution, it's an admission the feature is broken. The credential chain exists so you DON'T have to explicitly pass profile:</code> parameters everywhere. Setting AWS_PROFILE=default</code> or using the default profile should work. That's the entire design philosophy.</p> 4. Who Would This "Break"?</strong></p> The maintainer worried about "breaking many customers." But let's think about this:</p> My fix only affects users who have both</strong> of these conditions:</p> A profile with role_arn</code> AND credential_source = Environment</code></li> Environment variables AWS_ACCESS_KEY_ID</code> and AWS_SECRET_ACCESS_KEY</code> set</li> </ul> If someone configures both, they're explicitly declaring: "use these environment variables AS SOURCE CREDENTIALS to assume this role."</p> Who would configure this and expect it to be ignored? That's not a customer being protected, that's a broken feature being excused.</p> What I Did Instead</h3> Since the AWS team won't fix the credential chain, I worked around it by explicitly passing the profile:</code> parameter to AWS SDK clients. This bypasses the broken credential chain entirely.</p> The approach is simple:</p> def aws_client_options opts = { region: config.region } # Explicitly pass profile if configured if config.profile.present? opts[:profile] = config.profile elsif config.access_key_id.present? && config.secret_key.present? opts[:access_key_id] = config.access_key_id opts[:secret_access_key] = config.secret_key end # Otherwise omit credentials, let SDK auto-discover opts end </code></pre> With AWS config:</p> [profile app-uploads] role_arn = arn:aws:iam::123456789012:role/AppUploads credential_source = Environment </code></pre> This works because explicitly passing profile:</code> to the SDK bypasses the broken credential chain and goes directly to the profile-based role assumption code. It's not fixing the SDK bug, but it enables working role assumption with temporary credentials instead of long-lived static keys.</p> What I Learned (The Hard Way)</h3> Open source maintainers aren't always right.</strong> Even when they're from AWS, even when they're maintaining critical infrastructure, they can make bad decisions.</p> Document your wins even when they don't get merged.</strong> This fix works in production. Other developers will hit this same issue. Having a public record of the problem and solution helps everyone.</p> The bug report itself has value.</strong> Even though they closed it, the issue and PR document exactly what's broken and why. Future developers will find it and understand they're not crazy. The feature really is broken.</p> The Bigger Picture</h3> This experience reminded me technical correctness doesn't always win.</p> I had:</p> Clear reproduction steps</li> Root cause analysis with line numbers</li> A working fix with tests</li> Production validation</li> Comparison with AWS CLI behavior</li> Maintainer acknowledgment that it was broken</li> </ul> And they still closed it.</p> Sometimes the politics of "don't change anything" beat "fix the broken feature." That's frustrating, but it's reality.</p> For Other Contributors</h3> If you hit this issue:</p> Yes, credential_source = Environment</code> is broken with the default credential chain</li> No, it's not you, it's the SDK</li> The workaround is explicitly passing profile:</code> to clients (or using source_profile</code> with plaintext keys)</li> Explicitly passing the profile parameter bypasses the broken chain and enables proper role assumption</li> </ol> For AWS maintainers reading this:</p> You have unreachable code in credentials_from_source</code></li> Your credential chain prevents documented features from working</li> "Breaking changes" is a poor excuse for not fixing broken features</li> The feature is already broken for everyone using default profiles</li> </ul> The End (For Now)</h3> This is where the story ends. I found a workaround, documented it for others, and moved on.</p> Sometimes that's all you can do. Sometimes "no" from maintainers means finding another path. Sometimes proving you're technically correct doesn't matter if the project isn't willing to fix their bugs.</p> But hey, at least the deployment works now. And maybe this blog series will help the next developer who hits this same wall and wonders why a documented feature doesn't actually work.</p> The adventure is over. The bug remains. The workaround persists.</p> Such is open source.</p> Building Yaks: A Virtual Currency System for Discourse (Part 1: Backend Architecture) Unknown — Sat, 11 Oct 2025 00:00:00 +0000 I'm building a virtual currency system for Discourse. Users earn and spend "Yaks" on premium post features like colored highlighting, pinned posts, and custom user flair.</p> </p> </p> This is Part 1 of a series documenting the development. This post focuses on the backend architecture. Future posts will cover the frontend UI, earning mechanisms, and feature implementations.</p> Why Yaks?</h2> The name works on two levels. First, "yak" as a verb means to talk or chat persistently. Forums are where people yak.</p> Second, "yak shaving" is programmer slang for doing a seemingly pointless series of tasks. Unfortunately, sometimes, talking (arguing) with people online can feel apparently useless. The name acknowledges that.</p> Why Virtual Currency?</h2> Forums have moderation tools and permission systems, but they're binary: you can do something or you can't. Virtual currency adds a middle layer where users can temporarily access premium features by spending earned currency.</p> The use cases:</p> Highlight important posts with colored borders</li> Pin your post to the top of a topic for 24 hours</li> Add custom flair next to your username</li> Boost your post in feeds and search results</li> </ul> These aren't permissions. They're temporary, purchasable upgrades.</p> The Data Model</h2> The system has four core models:</p> YakWallet</h3> Each user has a wallet that tracks their balance and lifetime totals:</p> class YakWallet < ActiveRecord::Base belongs_to :user has_many :yak_transactions validates :balance, numericality: { greater_than_or_equal_to: 0 } validates :lifetime_earned, numericality: { greater_than_or_equal_to: 0 } validates :lifetime_spent, numericality: { greater_than_or_equal_to: 0 } end </code></pre> The wallet is the source of truth for a user's currency. Every earn, spend, and refund goes through it.</p> YakTransaction</h3> Every balance change is logged. This creates an immutable audit trail:</p> class YakTransaction < ActiveRecord::Base belongs_to :user belongs_to :yak_wallet enum transaction_type: { earn: 0, spend: 1, refund: 2 } end </code></pre> Transactions include:</p> Amount (positive for earn/refund, negative for spend)</li> Type (earn, spend, refund)</li> Source (where it came from: stripe_purchase</code>, quality_post</code>, feature_post_highlight</code>)</li> Description (human-readable explanation)</li> Metadata (JSON field for additional context)</li> Related post/topic (if applicable)</li> </ul> Why log everything? Transparency. Users can see exactly where their Yaks went. Admins can debug balance issues. Refunds are straightforward because you have the original transaction ID.</p> YakFeature</h3> Features define what users can spend Yaks on:</p> class YakFeature < ActiveRecord::Base has_many :yak_feature_uses validates :feature_key, presence: true, uniqueness: true validates :cost, numericality: { greater_than: 0 } validates :category, inclusion: { in: %w[post user topic] } end </code></pre> Each feature has:</p> A unique key (post_highlight</code>, post_pin</code>)</li> Display name and description</li> Cost in Yaks</li> Category (post, user, topic)</li> Settings (duration, default values, constraints)</li> </ul> Currently implemented:</p> Post Highlighting</strong> (25 Yaks): Colored border and background (gold, blue, red, green, purple)</li> </ul> Planned features:</p> Post Pin</strong> (50 Yaks): Pin to top of topic for 24 hours</li> Custom Flair</strong> (100 Yaks): Custom text next to username for 30 days</li> Post Boost</strong> (30 Yaks): Priority in feeds for 72 hours</li> </ul> The cost is per feature, not per variation. Post highlighting costs 25 Yaks regardless of which color you choose.</p> YakFeatureUse</h3> When a user purchases a feature, we create a YakFeatureUse record:</p> class YakFeatureUse < ActiveRecord::Base belongs_to :user belongs_to :yak_feature belongs_to :yak_transaction belongs_to :related_post, class_name: "Post", optional: true belongs_to :related_topic, class_name: "Topic", optional: true scope :active, -> { where("expires_at IS NULL OR expires_at > ?", Time.zone.now) } end </code></pre> This tracks:</p> Who applied the feature</li> Which feature was applied</li> What post/topic it was applied to</li> When it expires (if applicable)</li> Feature-specific data (color choice, custom text, etc.)</li> </ul> The active</code> scope makes it easy to query currently active features and clean up expired ones.</p> The Service Layer</h2> Business logic lives in services, not controllers. Controllers handle HTTP, services handle business rules.</p> What Are Services?</h3> Discourse has a standardized service pattern using Service::Base</code>. Services define:</p> Contracts</strong>: Input validation using schemas</li> Policies</strong>: Preconditions that must be true</li> Steps</strong>: The actual execution flow</li> </ul> Example structure:</p> class MyService < Service::Base contract do attribute :user_id, :integer validates :user_id, presence: true end policy :user_exists step :do_work private def user_exists User.exists?(id: contract.user_id) end def do_work # actual logic end end </code></pre> This pattern separates validation, authorization, and execution. If the contract fails, the service returns an error before hitting any business logic. If a policy fails, execution stops.</p> YakFeatureService</h3> The Yaks plugin currently uses a simpler service pattern (a plain Ruby class with class methods) because the logic is straightforward. It could be refactored to Service::Base</code> if validation becomes more complex.</p> The service handles:</p> Validating the feature exists and is enabled</li> Checking the user can afford it</li> Checking the feature can be applied (no duplicate active uses)</li> Creating the transaction</li> Creating the feature use record</li> Applying the visual effects</li> </ol> def self.apply_feature(user, feature_key, related_post: nil, feature_data: {}) feature = YakFeature.enabled.find_by(feature_key: feature_key) return { success: false, error: "Feature not found" } unless feature return { success: false, error: "Insufficient balance" } unless feature.affordable_by?(user) wallet = YakWallet.for_user(user) transaction = wallet.spend_yaks( feature.cost, feature_key, "Applied #{feature.feature_name}", related_post_id: related_post&.id, metadata: feature_data ) return { success: false, error: "Insufficient balance" } unless transaction feature_use = YakFeatureUse.create!( user: user, yak_feature: feature, yak_transaction: transaction, related_post: related_post, expires_at: calculate_expiration(feature), feature_data: feature_data ) apply_feature_effects(feature_key, related_post, feature_data) { success: true, feature_use: feature_use, new_balance: user.yak_balance } end </code></pre> Why put this in a service instead of the controller? Because controllers should handle HTTP concerns (params, rendering, status codes). Business logic (validating affordability, deducting currency, applying effects) belongs in a service.</p> This makes testing easier. You can test the business logic without setting up HTTP requests. You can reuse the service from rake tasks, background jobs, or the Rails console.</p> The Double Balance Check</h3> Notice the service checks affordability twice:</p> # First check return { success: false, error: "Insufficient balance" } unless feature.affordable_by?(user) wallet = YakWallet.for_user(user) # Second check (wallet.spend_yaks returns nil if balance insufficient) transaction = wallet.spend_yaks(...) return { success: false, error: "Insufficient balance" } unless transaction </code></pre> Why check twice? Race conditions.</p> Between the first check and the actual spend, another request could deduct from the user's balance. Without the second check, you could end up with negative balances.</p> The first check is an optimization (fail fast before loading the wallet). The second check is correctness (verify balance inside the database transaction).</p> The wallet's spend_yaks</code> method uses ActiveRecord transactions:</p> def spend_yaks(amount, feature_key, description, options = {}) return nil if amount <= 0 || balance < amount transaction do decrement!(:balance, amount) increment!(:lifetime_spent, amount) yak_transactions.create!(...) end end </code></pre> If the balance check fails inside the transaction, it returns nil</code> and nothing is deducted. This prevents concurrent requests from causing overdrafts.</p> Applying Features</h2> Features modify post custom fields:</p> def self.apply_feature_effects(feature_key, post, feature_data) current_features = post.custom_fields["yak_features"] || {} case feature_key when "post_highlight" current_features["highlight"] = { enabled: true, color: feature_data[:color] || "gold", applied_at: Time.zone.now.to_i } when "post_pin" current_features["pinned"] = { enabled: true, applied_at: Time.zone.now.to_i } end post.custom_fields["yak_features"] = current_features post.save_custom_fields end </code></pre> Custom fields are Discourse's way of extending models without migrations. The yak_features</code> field stores a JSON object with all active features on a post.</p> This data gets serialized to the frontend:</p> add_to_serializer( :post, :yak_features, include_condition: -> { object.custom_fields["yak_features"].present? } ) do object.custom_fields["yak_features"] end </code></pre> The frontend can then read post.yak_features.highlight.color</code> and apply the appropriate CSS.</p> Current State</h2> The backend is complete:</p> Wallet management with balance tracking</li> Transaction logging with full audit trail</li> Feature definitions with costs and durations</li> Service layer for applying features</li> Custom field serialization for the frontend</li> </ul> What's missing:</p> Frontend UI for viewing balance and purchasing features</li> Earning mechanisms (quality posts, admin grants, purchases)</li> Feature expiration cleanup job</li> Admin dashboard for managing features and viewing stats</li> </ul> Next Steps</h2> Part 2 will cover building the frontend UI: displaying the user's balance, browsing available features, and adding a "spend Yaks" button to posts.</p> Part 3 will cover earning mechanisms and the admin dashboard.</p> The code is on GitHub: ducks/discourse-yaks</a></p> ChatGPT assisted Changelog - 41/52 Unknown — Fri, 10 Oct 2025 00:00:00 +0000 This week centered on publishing, polishing, and reflecting on your Discourse work, with some light data analysis and side discussions along the way.</p> Blog and Writing</strong></p> You published "Building a Live Transit Departure Board with Discourse"</em>, a follow-up to your earlier post about your first Discourse core contribution. The piece explored how you built a live transit tracker plugin that reimagines Discourse as a real-time data board rather than a forum. You asked if posting it on the official Discourse blog would be weird, ultimately deciding it would make sense given your role there. You also asked if the piece itself was interesting -- it was, both technically and conceptually, tying in your love of open data and infrastructure with your day job.</p> Data and Analytics</strong></p> You dug into your GoatCounter analytics, examining visitor distribution across countries. After cleaning up duplicate entries, you found 37 unique countries</strong> represented, spanning six continents</strong> -- North America, South America, Europe, Asia, Africa, and Oceania. Europe and Asia were the strongest regions overall. The data was reformatted into a clean markdown table for future reference.</p> Open Source and Development</strong></p> You briefly noted another bug you found in the AWS SDK for Ruby, following your previous fix and contribution, reinforcing your growing involvement in that project's ecosystem.</p> Overall</strong></p> It was a quieter week but a meaningful one -- marked by the satisfaction of publishing a well-crafted post that blends creativity and engineering. The analytics work helped ground your readership data, while your continued OSS engagement kept your technical momentum going.</p> Building a Live Transit Departure Board with Discourse Unknown — Wed, 08 Oct 2025 00:00:00 +0000 I've been working at Discourse for a few months now, learning how flexible the platform is. It's a forum. It's designed for conversations. But what if we used it for something completely different?</p> Something like tracking flights and trains?</p> I wanted to learn more about Discourse by building something that felt real and that would force me into actual problems. Most importantly though, I wanted to build something that involves my interests and would be fun. I love transit infrastructure and open data so why not a transit tracker using free government feeds? I had this image in my head: those old split-flap airport departure boards, the ones that click and whir as letters rotate into place.</p> Photo by Amsterdam City Archives</a> on Unsplash</a></em></p> What if I could recreate that aesthetic, but powered by Discourse topics instead of actual flights?</p> You can see the result here: discourse-transit-tracker on GitHub</a></p> Why This Makes No Sense (And Why I Did It Anyway)</h2> Let's be clear: Discourse is not a transit tracking system</strong>. It's a forum platform built for human conversations, not GTFS feeds and real-time departure data.</p> But that's exactly what made it interesting.</p> Discourse topics are incredibly flexible. They have custom fields, tags, categories, and a robust permission system. If you squint hard enough, a flight departure is just a "post" with structured data. The departure time? A custom field. The status (on-time, delayed, departed)? A tag. The airline? Maybe a category.</p> It's ridiculous. But it could work</em>.</p> Learning with Claude Code</h2> I built this entire plugin using Claude Code, Anthropic's CLI tool. Not because I couldn't write it myself, but because I wanted to learn Discourse patterns while writing quality code from the start.</p> "Vibe programming" gets a bad rap. People hear "AI-assisted development" and think it's about blindly accepting generated code. But that's not how I used it. Claude Code became a learning tool. I'd describe what I wanted to build, Claude would suggest an approach using Discourse conventions, and I'd understand why those patterns exist.</p> This allowed me to learn the platform faster than reading docs alone would have taught me. I saw real implementations of custom fields, service objects, Ember components, and ActiveRecord patterns. And because Claude follows Discourse's style guide and architecture, the code I wrote actually fits the codebase.</p> This is what good AI-assisted development looks like: not replacing understanding, but accelerating it.</p> The Technical Stack</h2> The plugin integrates three data sources, each with its own challenges.</p> Amtrak (GTFS)</h3> I built an AmtrakGtfsService</code> that downloads Amtrak's GTFS feed (a ZIP file with CSVs), parses routes, stops, trips, and schedules, and creates departure topics with detailed stop information. No API key required.</p> The service:</p> Downloads and extracts GTFS.zip</code> from Amtrak's CDN</li> Parses routes.txt</code>, stops.txt</code>, trips.txt</code>, and stop_times.txt</code></li> For each trip in the next 24 hours, creates a topic with: All basic departure info as custom fields</li> A detailed stops array with lat/lon coordinates and times</li> A formatted schedule table as Post #2</li> </ul> </li> </ol> Running bin/rake transit_tracker:import_amtrak</code> processes ~2,300 trips and creates ~600 departure topics (many trips share the same departure, so they get merged).</p> The Problem: "Title has already been used"</strong></p> The first import run worked fine, processing ~2,300 trips and creating ~600 topics. But when I ran it again to test updates, I hit a wall:</p> Processing 340 trips... Created 1 topic Error: Title has already been used (339 times) </code></pre> Only 1 out of 340 trips succeeded on the second run. The rest failed.</p> Discourse requires unique topic titles. My title format was: "City of New Orleans to New Orleans at 19:05"</code>. Multiple different trains with the same route, destination, and departure minute produced identical titles.</p> My lookup strategy was to find topics by trip_id</code> + service_date</code> stored in custom fields. That worked fine when topics existed. But on subsequent runs, when a topic wasn't found by custom field (maybe the trip_id</code> changed), I'd try to create one, and Discourse would reject it because another train had already claimed that title.</p> The Fix: Fallback Lookup by Title</strong></p> The solution was to add a fallback lookup by title before trying to create:</p> # First, try to find by trip_id + service_date (the ideal natural key) topic = Topic.joins(:_custom_fields) .where(topic_custom_fields: { name: "transit_trip_id", value: attributes[:trip_id] }) .where(...) .first # If still no match, try to find by title to avoid duplicates if !topic title = build_title(attributes) category_id = determine_category(attributes[:mode]) topic = Topic.where(title: title, category_id: category_id).first if topic Rails.logger.info "[TransitTracker] Found existing topic by title, will update" is_new = false end end </code></pre> This way, if multiple trips share a title, they merge into the same topic and get updated instead of failing.</p> Result: 327 departures created, 0 errors</strong>. All trips within the 24-hour window imported successfully. The duplicate trips just update the same topic with fresh data.</p> NYC MTA Subway (GTFS)</h3> The NYC MTA subway system is massive. Their GTFS feed contains over 500,000 stop times covering weeks of schedules across dozens of routes.</p> My first approach was simple: import everything, just like I did with Amtrak. Parse the entire feed, create topics for every departure in the next 24 hours.</p> The Problem: 19GB of RAM</strong></p> I ran the import and watched my Rails process climb. 1GB. 5GB. 10GB. It kept going. By the time it finished parsing, it had consumed over 19GB of RAM</strong>.</p> Loading and processing 500k+ stop times to create 20,000+ Discourse topics consumed massive amounts of memory. At scale, big data creates big problems.</p> The Fix: Reduce the Time Window</strong></p> The fix? Reduce the import window from 24 hours to 6 hours:</p> # Only import departures within the next 6 hours dep_time = parse_gtfs_time(today, first_stop[:departure_time]) next if dep_time < now || dep_time > (now + 6.hours) </code></pre> Result: ~5,000 topics instead of 20,000+, memory usage stayed under 2GB, and the board still shows plenty of departures. For a live departure board, you don't need train schedules from tomorrow anyway.</p> The final implementation includes official MTA line colors (red 1/2/3, green 4/5/6, yellow N/Q/R/W, etc.) and creates ~5,000 departure topics with complete schedules.</p> AviationStack API</h3> Tracks flight departures with gate assignments, delays, and code-share detection. Requires an API key from aviationstack.com</a>.</p> The Problem: Duplicate Code-Share Flights</strong></p> Multiple airlines sell seats on the same physical flight under different flight numbers. That's called code-sharing. So you might have AA123</code>, BA456</code>, and IB789</code> all referring to the exact same plane leaving from Gate E7 at 07:30.</p> At first, I tried to build my own detection using departure time + gate + destination as a natural key. But then I looked closer at the AviationStack API response and found it: a codeshared</code> field that tells you exactly which flight is the operating carrier.</p> The Fix: Use the API's Built-In Field</strong></p> # Handle code-share flights: use operating carrier as natural key codeshared = flight_info["codeshared"] if codeshared.present? # This is a marketing carrier selling seats on another airline's flight # Use the operating flight as trip_id so all code-shares merge operating_flight = codeshared["flight_iata"] || codeshared["flight_icao"] trip_id = "#{operating_flight}-#{departure_info['scheduled']}" Rails.logger.info "[TransitTracker] Code-share detected: #{marketing_flight} operated by #{operating_flight}" else # Regular flight, use its own flight number trip_id = "#{flight_info['iata']}-#{departure_info['scheduled']}" end </code></pre> Why reinvent the wheel? The API already does the hard work of identifying code-shares. I just use the operating carrier's flight number as the trip_id</code>, and all marketing carriers automatically merge into the same topic.</p> Result: AA 1234 / BA 5678 / IB 789</code> displayed as one departure.</p> The Architecture</h2> Topics as Transit Legs</h3> Each flight (or train, or bus) is a Discourse topic. I created a TransitLeg</code> model that wraps Topic and handles all the custom fields:</p> transit_dep_sched_at</code> (scheduled departure time)</li> transit_dep_est_at</code> (estimated departure time for delays)</li> transit_route_short_name</code> (flight numbers)</li> transit_headsign</code> (destination)</li> transit_gate</code> / transit_platform</code> (where to board)</li> transit_dest</code> (airport code)</li> transit_stops</code> (JSON array of all stops with coordinates and times)</li> </ul> Tags handle the mode (flight</code>, train</code>, bus</code>) and status (status:scheduled</code>, status:delayed</code>, status:departed</code>).</p> Posts as Schedule Details</h3> Here's where using Discourse as the foundation really paid off.</p> When you click on a departure row, it expands to show the complete route schedule with all stops and arrival/departure times. But I didn't build a custom data structure for this. I used Discourse posts</strong>.</p> Each departure topic has:</p> Post #1</strong> (the OP): Basic departure info (route, times, gate)</li> Post #2</strong>: A markdown table with the complete schedule</li> Post #3+</strong>: Any delay notifications or status updates</li> </ol> When you expand a row, you're literally seeing the topic's replies rendered inline. It slides down with a smooth animation, showing the full schedule table styled to match the departure board aesthetic.</p> The schedule post looks like this:</p> ## 🚂 Complete Schedule **Route:** City of New Orleans **Direction:** Chicago | Stop | Arrival | Departure | |---------------------------------------|---------|-----------| | New Orleans Union Passenger Terminal | 12:45 | 12:45 | | Hammond Amtrak Station | 13:42 | 13:45 | | McComb | 14:30 | 14:32 | | ... | ... | ... | | Chicago Union Station | 08:15 | 08:15 | _Schedule times are in local timezone. This is the planned schedule and may be subject to delays._ </code></pre> It renders beautifully in the expanded row with the board's dark styling.</p> Why This Works Really Well</h3> Using posts instead of a custom schema means:</p> Update history is built-in</strong>. If a train gets delayed, we post an update and users see the entire timeline.</li> Moderation tools work</strong>. If there's bad data, moderators can edit posts using Discourse's existing tools.</li> Comments could work</strong>. Users could reply to departures (we don't allow this now, but the infrastructure is there).</li> No additional database tables</strong>. Posts are just posts, Discourse handles all the storage.</li> </ul> Screenshots</h2> Flights - Collapsed View</strong></p> </p> Flights - Expanded View</strong></p> </p> NYC Subway - Collapsed View</strong></p> </p> NYC Subway - Expanded View</strong></p> </p> Amtrak Trains - Collapsed View</strong></p> </p> Amtrak Trains - Expanded View</strong></p> </p> Bonus Tooling: Consistent Screenshots</h2> Getting these screenshots pixel-perfect required some tooling. I wanted to be able to:</p> Select a region once</li> Click things in the browser to expand/collapse</li> Take multiple screenshots of the exact same region</li> </ol> I built a Nix shell with Wayland screenshot tools (grim</code> + slurp</code>):</p> nix-shell ~/discourse/nix-shells/screenshot.nix screenshot-region flight-1.png # Select region once # Click to expand in browser screenshot-repeat flight-2.png # Same exact region </code></pre> The slurp</code> tool saves the region geometry, and screenshot-repeat</code> reuses it for perfect alignment across multiple screenshots.</p> Takeaways</h2> I learn best by writing real tools.</strong> Tutorial projects teach syntax, but they don't force you into the messy, real-world problems that make you actually understand a framework.</p> Discourse Topics Are More Flexible Than You Think</h3> Custom fields, tags, and categories gave me all the structured data I needed. Topics aren't just "posts". They're flexible containers for any kind of information.</p> Posts Are the Perfect Update Mechanism</h3> Instead of building a custom "updates" system with timestamps and status changes, I just used Discourse posts. When a delay happens, post an update. The topic becomes a living history of what happened to that departure.</p> Entity Resolution: Check Your Data Before Building Logic</h3> My first implementation created duplicate topics for every code-share flight. I started building my own deduplication logic using a natural key (departure time + gate + destination). But then I actually read the API response and found it: a codeshared</code> field that identifies which flights are the same. I was about to solve a problem the API had already solved for me.</p> GTFS Parsing Has Edge Cases</h3> GTFS times can exceed 24 hours (e.g., "25:30:00" means 1:30 AM the next day). ZIP files can have encoding issues. Stop sequences aren't always sequential. Real-world data is messy.</p> Performance Matters at Scale</h3> The MTA feed has 500k+ stop times. A 6-hour import window instead of 24 hours keeps memory usage reasonable and topic counts manageable (~5,000 instead of 20,000+).</p> Is This Practical?</h2> Probably not for real transit tracking. But it's a great example of pushing Discourse in unexpected directions to understand the platform deeply.</p> The same pattern (topics as structured data + posts as updates) could work for:</p> Package tracking (topics = packages, posts = scan events)</li> Server status boards (topics = servers, posts = incidents)</li> Deployment pipelines (topics = deploys, posts = stage completions)</li> Event schedules (topics = sessions, posts = time/room changes)</li> Support ticket boards (topics = tickets, expandable = full history)</li> </ul> The split-flap aesthetic is a bonus.</p> Try It Yourself</h2> The plugin is open source: ducks/discourse-transit-tracker</a></p> Clone it, run the Amtrak import (no API key required), and see what Discourse topics can become when you push them beyond forum discussions.</p> My First Official Contribution to Discourse Unknown — Mon, 06 Oct 2025 00:00:00 +0000 This past week marked a small but meaningful milestone for me - I submitted and merged my first pull request to the Discourse core project. The fix is simple but important: handle a nil</code> commit URL path in Admin::PluginsController</code>, preventing a 500 error in the plugins admin UI. (github.com</a>)</p> Debugging a random admin panel crash</h3> I've been at Discourse for about two and a half months now, and most of my work so far has been focused on internal tools and infrastructure rather than the main codebase itself. It's been a great way to learn how things fit together behind the scenes, but I've been itching to make a direct impact on the project that everyone actually sees and uses.</p> This PR was a small but deliberate step in that direction. I wanted to start contributing to the public codebase, not just to fix a bug, but to get more familiar with the patterns, tests, and expectations that make Discourse what it is. It's one thing to understand how we run it internally - it's another to touch the core code that powers thousands of communities around the world.</p> There's also a kind of quiet satisfaction in cleaning up a small edge case like this. It's the kind of detail that no one notices when it's working, but it makes the whole system sturdier. That's the kind of work I enjoy doing.</p> What the bug was, succinctly</h3> In lib/plugin/instance.rb</code></strong>, the method discourse_owned?</code> was calling .split</code> on parsed_commit_url.path</code> without checking if path</code> might be nil</code>.</li> In the scenario where a plugin has a commit URL parsed successfully but the path</code> is nil</code> (for example, plugins without a git remote configured), this led to a crash (HTTP 500) in /admin/plugins</code>.</li> My patch adds a nil</code> check: if parsed_commit_url.path</code> is nil</code>, the method returns false</code> (or skips the split) gracefully. I also added a test case to assert this behavior.</li> </ul> In short: prevent a rare but real crash, and make the behavior deterministic in that edge case.</p> How the review and merge went</h3> The PR moved relatively smoothly:</p> I opened the PR and described the bug and proposed patch.</li> The maintainers reviewed and approved it.</li> After passing all checks, the PR was merged into main</code>.</li> The branch was deleted afterward.</li> </ul> It was a small change - only +11 / -1 lines - but I made sure the fix was clean, covered by a test, and clearly explained. Small contributions like this build trust and open the door to more.</p> Takeaways</h4> Fixing something this small reminded me that even the simplest changes can improve confidence in a codebase. It also helped me see more of the moving parts that make Discourse work - how plugins tie in, how errors surface in the admin panel, and how tests are structured to catch regressions early.</p> It's easy to think of "first contributions" as symbolic, but what really mattered was understanding how to move through the process: spot an issue, confirm it, write a clean fix, explain it clearly, and see it merged. That flow is something I want to keep refining.</p> Going forward, I want to:</p> Explore other bug reports in Discourse (especially in plugins and the admin UI)</li> Take on slightly more complex patches (refactors, performance improvements, new features)</li> Use this experience to contribute in a modular, maintainable way</li> </ul> Going off the Rails on the AWS Credential Chain Unknown — Sat, 04 Oct 2025 00:00:00 +0000 The Plot Twist</h3> Remember that AWS SDK contribution</a> I wrote about? The one where I fixed missing credential_source = Environment</code> support? Well, turns out that was only half the story.</p> After my PR got merged and we updated our Discourse deployment to aws-sdk-core 3.233.0</code>, I was excited to finally see role assumption working. The missing credential source was fixed, our config looked perfect, and all the unit tests were passing.</p> But when I deployed it to our test cluster, I still got an error. It was a new error, but an error nonetheless. Instead of UnsupportedCredentialType</code>, I was now getting a permission denied error when trying to use AWS S3 operations.</p> The Real Problem</h3> Here's what was happening. I'd check the identity in our Rails console:</p> discourse(prod)> sts = Aws::STS::Client.new discourse(prod)> puts sts.get_caller_identity.arn arn:aws:iam::123456789012:user/MyUser </code></pre> That should have been showing an assumed role ARN like:</p> arn:aws:iam::123456789012:assumed-role/MyRole/session-name </code></pre> The SDK was still using environment variables directly instead of using them as source credentials to assume the configured role.</p> The Investigation (Round 2)</h3> Back to the AWS SDK source code, this time looking at credential_provider_chain.rb</code>. And there it was - a classic ordering problem:</p> def providers [ # ... other providers ... [:env_credentials, {}], # Position 7 ← Wins! # ... other providers ... [:assume_role_credentials, {}], # Position 10 ← Never reached ] end </code></pre> The credential chain finds AWS_ACCESS_KEY_ID</code> and AWS_SECRET_ACCESS_KEY</code> in position 7, returns those credentials immediately, and never reaches the role assumption logic at position 10.</p> But here's the thing - this isn't as simple as just moving assume_role_credentials</code> higher in the chain. That might break existing behavior for thousands of applications that rely on direct environment variable usage.</p> The Real Architecture Problem</h3> What should happen with this config:</p> [default] role_arn = arn:aws:iam::123456789012:role/MyRole credential_source = Environment role_session_name = test-session region = us-west-2 </code></pre> Expected flow:</strong></p> SDK sees role_arn</code> + credential_source = Environment</code></li> SDK uses AWS_ACCESS_KEY_ID</code>/AWS_SECRET_ACCESS_KEY</code> as source credentials</strong></li> SDK calls AssumeRole</code> with those source credentials</li> SDK returns assumed role credentials</strong></li> </ol> Actual flow:</strong></p> SDK finds AWS_ACCESS_KEY_ID</code>/AWS_SECRET_ACCESS_KEY</code> in environment</li> SDK returns those credentials directly (chain stops)</li> Role assumption config is never processed</li> </ol> The Contribution</h3> I filed Bug #3301</a> with:</p> Clear reproduction steps</li> Root cause analysis pointing to the specific code location</li> Expected vs. actual behavior with ARN examples</li> A workaround using source_profile</code> (though it requires plaintext keys)</li> </ul> The Response</h3> The AWS team's response was exactly what you hope for:</p> "Hey, thanks for opening an issue. I believe you are correct and this is something we need to fix. I need to confirm some details regarding AssumeRoleCredentials profile chaining with the team first and I'll keep you updated."</p> </blockquote> That's maintainer validation that this is a real architectural issue, not user error.</p> What I Learned (Again)</h3> Complex systems have complex bugs:</strong> My first fix solved the missing feature, but revealed a deeper architectural problem with credential chain precedence.</p> Sometimes the obvious fix isn't right:</strong> Moving assume_role_credentials</code> higher might seem simple, but it requires careful consideration of context and backward compatibility.</p> Good bug reports matter:</strong> Clear reproduction steps, root cause analysis, and concrete examples help maintainers understand and prioritize issues.</p> Persistence pays off:</strong> I could have stopped after the first fix and lived with workarounds. But pushing deeper led to identifying a more fundamental issue.</p> The Bigger Picture</h3> This experience reinforced something important about systems work: fixing one layer often reveals problems in the next layer down.</p> The first bug was a missing feature - straightforward to implement. The second bug is an architectural design issue that requires careful consideration of how credential resolution should work when role assumption is involved.</p> Both bugs are real, both needed fixing, and both will help developers who hit the same issues. But they required completely different approaches - one needed code, the other needed a thoughtful design discussion with the maintainers.</p> Status Update</h3> As of this writing, the AWS team is discussing the fix for the credential chain precedence issue. Our Discourse implementation is ready to go - we're just waiting on the upstream architectural fix.</p> Sometimes the best contribution you can make is clearly identifying and documenting a problem, even when the solution isn't obvious. That's exactly what happened here.</p> The Adventure Continues</h3> Read Part 3</a> to see how the maintainers responded to the bug report and the workaround I ended up implementing.</p> ChatGPT assisted Changelog - 40/52 Unknown — Fri, 03 Oct 2025 00:00:00 +0000 The week covered a mix of practical, technical, and personal topics.</p> Travel and Residency</h3> Discussions continued around moving to Czechia. You asked about employer documents, contracts, the passport biopage, tax implications, accommodation requirements, and realistic timelines for when you could start working from Prague. Flatio was identified as a likely short-term housing option.</p> Anki and Language Learning</h3> You set up an Anki deck for learning Czech. The focus was on the alphabet, pronunciation, and use of IPA symbols. We went through how to structure the deck, what templates should look like, and clarified things like vowel length.</p> NixOS and Framework Issues</h3> There were troubleshooting sessions with your Framework 16 and NixOS. Problems included the command key breaking after an RGB reset, the RGB matrix not working in Linux, and questions about whether this tied to a NixOS upgrade. We looked at inputmodule installation, what parts of /etc are declarative, and the Framework warranty/return policy.</p> Broader NixOS Community</h3> You asked about the NixOS steering committee drama and its connection to Anduril, looking for current context on community governance issues.</p> Practical Life Logistics</h3> A few everyday topics came up:</p> Steps for getting a car repaired after being rear-ended.</li> How to cancel a Moda healthcare plan.</li> Best backup plan when changing operating systems.</li> Selling an old car (1974 Ford Ranchero) in Portland, with estimates for repair or restoration and whether shops do at-home consultations.</li> </ul> Projects and Ideas</h3> You continued brainstorming unique Discourse plugin ideas. This included using Discourse to track flights, trains, or transit legs (with Prague trams as a test case) and asking about APIs and boilerplate plugin setup.</p> Miscellaneous</h3> GoatCounter analytics and why a single link share might register multiple views (including prefetching behavior).</li> Color distribution analysis on an uploaded image, with rotations and measurements.</li> iPad Mini use cases.</li> Services to help sell or donate items at home.</li> Shipping personal items from the US to Europe.</li> Kastaplast first run disc valuations and market prices, including Falk, Lots, Stål, Göte, Berg, and Reko.</li> </ul> Overall, the week balanced ongoing emigration planning and language study with NixOS troubleshooting, plugin experiments, and practical life logistics.</p> ChatGPT assisted Changelog - 36-39/52 Unknown — Fri, 26 Sep 2025 00:00:00 +0000 Travel and Prague notes</strong></p> A first Europe trip to Prague sparked a travel post and follow ups. Sections about the castle, tram lines 6 and 17, and Czech Cubism were drafted. Airport and TSA logistics were covered, including CT scanner lanes at PDX, KLM meal expectations, missed connection handling at AMS, and return routing via JFK. Mint Mobile's international pass proved sufficient for a week, with OsmAnd recommended for offline maps and Obtainium used to install apps without Play Store.</p> Czech visa preparation</strong></p> Residency planning continued. A rental listing in Holesovice prompted an email draft to the agent and an explanation of Czech 4+1 flat notation. Resources for US to CZ expats, the role of Flatio, timing without a fixed move date, and document prep were explored. An employer affidavit template was rewritten in plain text. Fingerprinting and FBI background check expectations were clarified. Czech terms like software engineer and contract types such as HPP were noted.</p> Cameras and creative gear</strong></p> Beginner travel camera options were compared: Nikon Z30 and Canon R50 kits versus the Ricoh GRIII for street and night work. Strengths, tradeoffs, and lens choices were outlined. For carry systems, compact bags and local stock for brands like WANDRD were discussed, with an eye toward minimal kits.</p> Discourse experiments and ideas</strong></p> A flurry of off label Discourse concepts landed, from non forum app patterns to playful ideas like Conway's Game of Life. Practicalities came up too: VPS disk pressure from journal files, running locally instead, and revisiting plugin basics. A specific plugin that tracks days until the next cake day was analyzed for implementation details and feasibility.</p> Desktop tooling and small wins</strong></p> On Wayland, grim plus wl copy needed an explicit MIME type to fix clipboard issues. A Nushell function location was clarified, and a prompt flow was added to optionally save screenshots after copying. Hyprland confirmations and UX touches resurfaced as blog worthy tips.</p> Selling, shipping, and decluttering</strong></p> Paths for selling a non running 1974 Ford Ranchero in Portland were mapped out: where to get initial consultations, rough cost expectations for engine checks and tune ups, and whether restoration would raise sale value. Services that help sell or donate household items were listed. Options for shipping personal goods from the US to Europe were compared at a high level.</p> Email deliverability and DNS</strong></p> Email headers were unpacked for a non technical audience. DKIM and DMARC were explained in plain terms, realistic DNS propagation timing was set, and common DMARC failure causes were reviewed. The idea of account warming was addressed with a pragmatic lens. Header domains and alignment details were parsed from sample Authentication Results lines.</p> Disc golf market checks</strong></p> Kastaplast first run prices were researched with a focus on Falk, Lots, Stal, and Gote. Market ranges, recency caveats, and condition effects were noted. A correction landed for the Reko mix, with early plastics clarified. A well used FR Berg valuation was discussed with realism about wear and ceiling prices.</p> Personal finance and admin</strong></p> 401k choices were outlined: cash out implications, rollovers to IRAs, and how a move abroad intersects with taxes and planning. Help from fiduciary advisors and any digital nomad friendly country programs were surveyed at a high level.</p> Logos, apps, and posts</strong></p> A map based Loop Finder app concept took shape using Vue, with local GraphHopper via Docker Compose to remove API key friction. Zola templating for shared resume layouts was explored. A prior post on typing Swedish with a US keyboard kept attracting search traffic.</p> Housekeeping on the site</strong></p> Styling for headings aimed at mobile readability while respecting an 80 char column. Prior weekly summaries stayed the model: plain text markdown, no fancy chars, prose first, and wrapped lines. Future posts were queued from several threads above, especially Prague transport notes, Hyprland prompts, and the email DNS explainer.</p> First time in Europe: One week in Prague Unknown — Tue, 16 Sep 2025 00:00:00 +0000 A Country Boy Goes to Europe</h3> This past week was the annual global meetup for Discourse</a>, the company I recently joined. I was lucky enough to get hired right before the planning cutoff date, and they were very generous to include me so early in my tenure. That inclusion made me feel valued and trusted. This year the meetup was held in Prague, Czech Republic. I was excited because I have never been out of North America.</p> Initial Leg and a Missed Connection in Amsterdam</h3> The trip started with a flight from Portland to Amsterdam. It was pretty smooth, even if long. The only real issue was that the flight arrived late. On top of that, the passport control line in Amsterdam may have been the longest line I have ever seen in an airport. Those two things combined forced me to miss my connecting flight to Prague. Luckily I was flying KLM, which is very good about rebooking a new flight when it is their fault.</p> I had to do A LOT</strong> of walking and waiting, but I got rebooked and made it to my new flight.</p> Meeting My New Coworkers</h3> For all the excitement, I was nervous too. I am introverted, and walking into a room of about 70 people I did not know was daunting. I am not great at introducing myself and I do not feel "important" enough to assume people want to meet me. I was not the only first timer, but I was by far the newest hire.</p> Prague Castle</h3> Prague Castle is not a single building as much as it is a hilltop campus of courtyards, churches, palaces, and gardens.</p> St. Vitus Cathedral</h4> Although I am anti-religion, I can appreciate the architecture of old world churches. Pictures cannot do this building justice. The height, beauty, and aging are things you just have to see in person.</p> </p> </p> Golden Lane (Zlatá ulička)</h4> This pocket street sits between the Bílá Tower and Daliborka Tower. The tiny, colorful houses were built into the castle fortifications around the end of the 16th century and stayed lived in up to the Second World War. Several of the homes now show period interiors that trace everyday life on the lane across five centuries.</p> House No. 22 is the best known stop. Franz Kafka stayed here for a time during the First World War. Facades were repainted in the 1950s following designs by Jiří Trnka, which is part of why the lane looks so storybook today.</p> Climb the steps at House No. 12 to the terrace above Daliborka. The round tower dates to 1496 and served as a prison until 1781. You will see notes about the knight Dalibor of Kozojedy, the tower's first recorded inmate.</p> The Castle Proper (Old Royal Palace)</h4> The Old Royal Palace centers on Vladislav Hall: huge, yet surprisingly open. The broad Riders' Staircase was built so horsemen could enter, which says a lot about the space's ambitions. Outside, the courtyards do the real work of the visit: sit, watch the guard change, and let the pace reset. On the south side, terraces step down toward the river with quiet garden paths and big sky views.</p> </p> Public Trams-it</h3> Prague's tram network is part moving museum, part everyday superpower.</p> A quick history:</p> 1875: horse trams debut in Prague</li> 1891: inventor František Křižík launches the first electric tram (Letná)</li> 1962: the Tatra T3, the red cream classic, begins service and becomes a design icon still seen today</li> 2010s to current: 100% low floor Škoda 15T ForCity sets the modern standard</li> </ul> I caught almost every ride at Veletržní palác, a 2 minute walk from Mama Shelter. Lines 6</strong> and 17</strong> stop here, so I could either hug the river or cut across town without thinking too hard. Daytime trams run about every 8 to 20 minutes, so it felt like show up and go.</p> Tram 6</h4> Line 6 connects Nádraží Holešovice to Kubánské náměstí, which makes it a useful cross town link if you are moving between Holešovice, the center, and Vršovice. Daytime trams in Prague typically run every 8 to 20 minutes, so you can treat both 6 and 17 like show up and go service.</p> Tram 17</h4> Line 17 hugs the Vltava for long stretches, so it is the easy, scenic way to glide past Národní divadlo, Staroměstská, Výtoň, and the riverfront. It links the north (Vozovna Kobylisy) with the south (Sídliště Modřany and Libuš). If you want a view rich ride, sit by the window on this one.</p> Czech Cubist Museum at The House of the Black Madonna</h3> Czech Cubism did not stop at the canvas. It leapt into architecture, furniture, and everyday objects. One of the movement's showpieces is located at The House at the Black Madonna, which was built in 1911 to 1912 and designed by Josef Gočár. It was a Cubist designed department store turned cultural landmark of Old Town. Today it hosts The Museum of Czech Cubism and a restored Grand Cafe Orient.</p> </p> </p> </p> </p> Permanent Souvenirs</h3> I decided to get a couple permanent souvenirs in the form of tattoos while there.</p> </p> Tattoo by Dario Kristoffersen</a> at One Love Tattoo</a>. Prague, 2025.</em></p> </p> Tattoo by Tarlito</a> at One Love Tattoo</a>. Prague, 2025.</em></p> Summary and Reflection</h3> This was honestly the best trip of my life. I absolutely loved Prague and that old European energy. There was something different in the air. To me, it feels like a smaller, older New York City.</p> I loved it so much that I have already started a checklist for a digital nomad work visa. I could see going back for longer periods to visit and work. I regret not going to the transit museum, so that is high on the list for the next visit.</p> Děkuji, že jste si to přečetli.</p> Reverse Engineering A Unique Data Structure - Part 3, Course & Course Details Unknown — Wed, 03 Sep 2025 00:00:00 +0000 Second part of the series, Search, can be found here: Search for Places and Courses</a></p> In the previous two posts, we learned how to GET</code>, scrub, and parse Courses</code> data, as well as how to use the search endpoint for Places</code> and Courses</code>.</p> Viewing a Specific Course</h4> In this post, we will build on the previous data and show how to find the endpoint for a specific course and drill down into more data. We'll focus on the courseDetails</code>, using the beloved Maple Hill as our example:</p> { "_id": "M6vT9WAEmtFKRFr2v", "name": "Maple Hill", "ratingCount": 10064, "ratingAverage": 4.899286515846228, "locationText": "Leicester, MA", "courseId": 1523, "shortId": "lCej", "highlights": [ { "score": 2.803980588912964, "path": "name", "texts": [ { "value": "Maple", "type": "hit" }, { "value": " ", "type": "text" }, { "value": "Hill", "type": "hit" } ] } ], "searchScore": 15.834041595458984, "autocompleteScore": 16.079005921251294 } </code></pre> The URL for a course will be a slugified course name, plus the shortId</code>. For Maple Hill, this URL is: https://myfrisbee.com/courses/maple-hill-lCej.data</code></p> Based on observation, spaces become dashes, and special characters are removed when generating the slug.</p> For example, Keith L. Christner Family DG Course becomes keith-l-christner-family-dg-course.</p> Inspecting the Data</h4> The response from this endpoint is massive</strong>--so much so that Firefox truncates it in the Network tab. I had to use curl and save the file locally just to inspect it.</p> Again, we are greeted by a large array of mixed types. The more I'm reading and learning, it seems like this may not actually be done for any kind of obfuscation, but for performance or a client side hydration strategy. The response is very large but it's a full page of data and probably replaces multiple API calls.</p> This time, the response goes even deeper: it includes a schema map of schema maps, where keys don't point directly to data, but to other schema maps that must be resolved first.</p> "routes/courses/$slug/index", { "_3": 143 }, { "_144": 145, "_335": 336, "_343": 344, "_24719": 24720, "_24957": 24958, "_25013": 25014, "_25150": 25151, "_25410": 25411, "_25435": 25436, "_25481": 25482, "_25513": -7, "_25514": 25515 }, </code></pre> The second object is just full of references to other references. If you follow each one of those schema maps, we can sometimes get the location of each field's key and value. Often times, there are just more schema maps to follow. Here is a small snippet:</p> "smartLayouts": [345, 3534, 12323, 13767, 14131, 14506, 19520, 22543], "classicLayouts": [24721], "reviews": [24959, 24981, 24992, 25002], "photos": [25015, 25083, 25097, 25107, 25128], "nearbyCourses": [25152, 25226, 25280, 25344], </code></pre> Going to array[345]</code>, we get this:</p> { "_66": 346, "_84": 85, "_347": 348, "_349": 350, "_72": 3505, "_3506": 195, "_3507": 3508, "_147": 256, "_3509": 3510, "_3511": 3512, "_3513": 3514, "_3515": 3516, "_3517": 3518, "_104": 3519, "_167": 3520, "_3521": 131, "_3522": 320, "_3523": 3524, "_3525": 3526, "_3527": 2679, "_3528": 679, "_3529": 3530, "_396": 3531 } </code></pre> Going to some of those references leads to actual data, but again, often times it's just more mappings.</p> Now that it makes sense manually, let's write some code to do it programmatically.</p> At a high level, the flow is:</p> const schemaMap = resolveCourseSchemaMapSchema(data); const courseDetailsSchema = schemaMap.courseDetail; const courseDetails = resolveKeyAndValueNames(courseDetailsSchema, mockCourse); </code></pre> Break the big array down into a schema map of schema maps</li> Pass that courseDetailsSchema</code> and our original array to resolveKeyAndValueNames</code></li> </ol> Resolving a Course's Details Structure</h4> The function below does 3 important things:</p> finds our route key label. this key seems to precede the schema map.</li> follows the next pointer to the schema map schema map</li> passes that to resolveKeyAndValueNames</code> to resolve each set of key/values</li> </ul> export function resolveCourseSchemaMapSchema(data: any[]) { for (let i = 0; i < data.length - 2; i++) { const label = data[i]; const pointerMap = data[i + 1]; const schemaMap = data[i + 2]; if ( label === "routes/courses/$slug/index" && typeof pointerMap === "object" && typeof schemaMap === "object" && Object.keys(pointerMap).length === 1 ) { const pointerIndex = Object.values(pointerMap)[0]; const referencedMap = data[pointerIndex]; if (typeof referencedMap === "object") { return resolveKeyAndValueNames(referencedMap, data); } } } } </code></pre> That leaves us with a decoded schema object, where each field (like courseDetail</code>, reviews</code>, smartLayouts</code>) still contains schema references or arrays of indexes:</p> { courseDetail: { _66: 67, _68: 69, _146: 131, _147: 148, _72: 73, _149: 109, _150: 151, _152: 108, _84: 85, _153: 154, _96: 97, _155: 156, _158: 159, _160: 161, _162: 163, _164: 165, _102: 172, _110: 111, _130: 131, _174: 175, _176: 177, _180: 181, _184: 185, _56: 302, _303: 304, _305: 131, _132: 7, _133: 131, _306: 307, _308: 309, _310: 311, _312: 313, _314: 315, _316: 317, _318: 319, _134: 131, _323: 324, _328: 21, _329: 330, _331: 7, _332: 131, _333: 7, _334: 7 }, normalizedCourseTraffic: { _337: 338 }, smartLayouts: [ 345, 3534, 12323, 13767, 14131, 14506, 19520, 22543 ], classicLayouts: [ 24721 ], reviews: [ 24959, 24981, 24992, 25002 ], photos: [ 25015, 25083, 25097, 25107, 25128 ], nearbyCourses: [ 25152, 25226, 25280, 25344 ], nearbyStores: [ 25412, 25424 ], events: [ 25437, 25460, 25470 ], badges: [ 25483, 25494, 25498, 25500, 25505, 25506, 25508, 25509, 25511, 25512 ], globalLayoutAverages: undefined, userStatus: 'loggedOut' } </code></pre> Next is our core function. We take the courseDetail</code> schema map and pass it and our original data array to resolveKeyAndValueNames</code> to resolve the actual values.</p> /** * Resolves a schema map where both keys and values are index references into the data array. */ export function resolveKeyAndValueNames(schema: Record<string, number>, data: any[]): Record<string, any> { const result: Record<string, any> = {}; for (const rawKey in schema) { const keyIndex = parseInt(rawKey.replace(/^_/, ""), 10); const valIndex = schema[rawKey]; const fieldName = data[keyIndex]; if (typeof fieldName !== "string") { throw new Error(`Expected string field name at index ${keyIndex}, got: ${typeof fieldName}`); } result[fieldName] = data[valIndex]; } return result; } </code></pre> We are now left with a nicely formatted and readable object of values:</p> { "_id": "M6vT9WAEmtFKRFr2v", "holeCount": 18, "isPay": true, "status": "Active", "name": "Maple Hill", "latitude": 42.276001, "website": "http://maplehilldiscgolf.com", "longitude": -71.895699, "courseId": 1523, "country": "United States", "availabilityStatus": "available", "landType": [157], "targetType": "basket", "targetTypeDescription": "Black Hole Portal, Black Hole Gravity Version 2", "availabilityTypeDescription": "Closed the Sunday before Thanksgiving to New Years for Christmas Tree Season. ", "conditions": { "_104": 166, "_167": -5, "_168": 169, "_170": 171 }, "location": { "_104": 105, "_106": 173 }, "shortId": "lCej", "hasBathroom": true, "propertyType": "dedicated", "activeTargetTypes": [178, 179], "activeTeeTypes": [182, 183], "layoutConfiguration": { "_186": 187, "_223": 224, "_251": 252, "_289": 290, "_299": 300, "_301": -5 }, "timezone": "America/New_York", "otherFees": "$5 Walker fee for those not playing", "isSmartLayoutEnabled": true, "hasDrinkingWater": false, "isDogFriendly": true, "amenitiesRating": 4.754434159544442, "designRating": 4.920076530755979, "sceneryRating": 4.923442842581462, "signageRating": 4.747814409366677, "teeRating": 4.882374770235053, "upkeepRating": 4.891556089317444, "difficultyBins": [320, 321, 322], "isCartFriendly": true, "contactInfo": { "_325": 326, "_327": 326 }, "accessTypeDescription": "", "accessibility": "notAccessible", "byob": false, "dedicatedTargets": true, "hasAvailabilityRestrictions": false, "underConstruction": false } </code></pre> Note: Some fields like conditions</code>, location</code>, and layoutConfiguration</code> are still partially encoded -- they contain their own schema maps or references that need to be decoded separately using resolveKeyAndValueNames</code>. We'll cover those in a future post when we dive deeper into layout and field-level data.</p> Summary</h4> In this post, we decoded the structure of MyFrisbee's courseDetails</code> payloads by:</p> Resolving the "routes/courses/$slug/index"</code> entry</li> Using resolveCourseSchemaMapSchema</code> to get a field-labeled schema</li> Running that through resolveKeyAndValueNames</code> to extract readable values</li> </ul> This pattern gives us a fully usable course object with real field names. While some nested fields (like conditions</code> or layoutConfiguration</code>) still require additional decoding, we now have the tools to confidently work with MyFrisbee's structured course data.</p> Next Time</h4> In the next post, we'll go one level deeper--resolving nested layout data like hole-by-hole distances and tee types.</p> Reverse Engineering A Unique Data Structure - Part 2, Search Unknown — Sat, 30 Aug 2025 00:00:00 +0000 First part of the series, Courses, can be found here: Courses</a></p> Search for Places</h4> In the first post in this series, we were able to parse and extract a list of Course</code> data. This is great, but we're simply getting back 20 random courses that might not mean anything to the end user. Lucky for us, there are a couple search options.</p> Going to https://myfrisbee.com/courses</a> and starting to type in the search box reveals some network calls:</p> /places/search?term=charlotte&limit=5</code></p> This is getting called for every character that is typed and should probably be debounced a little.</p> Anyway, from that call, we get some pretty well formed data instead of the index/schema map data like before. Here is one result:</p> { "_id": "NxHZZBpPjDnXHbbZg", "type": "city", "slug": "charlotte-nc", "name": "Charlotte", "country": "United States", "countryCode": "US", "admin1": "North Carolina", "city": "Charlotte", "location": [ -80.84313, 35.22709 ], "score": 98.75883083083083, "fullLocationText": "Charlotte North Carolina United States", "highlights": [ { "score": 1.4719792604446411, "path": "fullLocationText", "texts": [ { "value": "Charlotte North Carolina", "type": "hit" }, { "value": " United States", "type": "text" } ] } ], "autocompleteScore": 72.5995921895284 }, </code></pre> There seem to be a few options for type</code>.</p> city</li> admin1 (which appears to represent state in the US)</li> country</li> </ul> Now, you can take that slug</code> and plug it into the courses call:</p> /courses.data?placeId=charlotte-nc</code></p> See the first post</a> on how to parse and extract that data.</p> Search for Courses</h4> The Places endpoint was not the only one being hit though. When typing in the search box, you will also see this:</p> /api/courses/search?includeGenerallyUnavailableCourses=true&term=hornets nest&limit=5</code></p> Again, we get some pretty well formed data:</p> { "_id": "jJAW46X3WX8qT7mXR", "locationText": "Charlotte, VT", "ratingAverage": 3.4976632020706235, "courseId": 11220, "ratingCount": 239, "name": "Charlotte Beach", "shortId": "j04j", "highlights": [ { "score": 2.771970748901367, "path": "name", "texts": [ { "value": "Charlotte", "type": "hit" }, { "value": " Beach", "type": "text" } ] } ], "searchScore": 11.487470626831055, "autocompleteScore": 11.66234797214058 }, </code></pre> Next time I will show you how to take that data and get a specific Course</code> endpoint and data.</p> Another Way to Fuzzy Find Courses</h4> Not exactly a search but there appears to be at least one more way of fuzzy finding courses. The courses.data</code> endpoint can take another param called courseTerm</code>. The full URL would be:</p> /courses.data?courseTerm=charlotte</code></p> This will return course results with "Charlotte" in the name. I'm thinking this endpoint is there for list type pages and the search endpoint might just be for autocomplete drop downs.</p> Summary</h4> Showed how to search for places and courses</p> Plan for Next Time</h4> Drill down into specific course data</p> ChatGPT assisted Changelog - 35/52 Unknown — Fri, 29 Aug 2025 00:00:00 +0000 This week covered a mix of personal projects, resume updates, and site tweaks. On the budgeting front, cashctl planning continued, with refinements to the workflow around paydays, file naming, and how income gets assigned to periods. Simulated paycheck commands and outputs were discussed to bring the tool closer to being usable.</p> Work on the personal site also came up. A Zola question about sharing one resume template across multiple pages was raised, along with CSS improvements for headings that stay mobile friendly while keeping within an 80-character layout.</p> Resume polish was another theme. A contribution to the AWS SDK for Ruby was turned into a resume-style entry, with placement under the Discourse role considered for now. Additional feedback was asked for on how to position open source work.</p> The node-postgres-exporter project also got a GitHub star, and further improvements were considered, such as in-memory caching and local storage to smooth over network blips.</p> There was also some lighter talk--identifying a pine tree, considering Vermont properties, and chatting about power adapters and credit scores.</p> Overall, the week blended cashctl development, resume building, static site refinements, and a bit of infrastructure and personal exploration.</p> Reverse Engineering A Unique Data Structure - Part 1, Courses Unknown — Wed, 27 Aug 2025 00:00:00 +0000 Note: Real app name and URL have been replaced</strong></p> I am a very avid fan and player of disc golf.</p> Disc golf is basically the rules of golf but you're throwing a frisbee instead of hitting a ball. There are differences of course. We don't throw the disc into a hole in the ground, but the basic idea of starting in one place and getting an object to another remains the same. It's a beautiful sport that combines the mystique of physics and flight with the beauty and tranquility of nature. I get to take a hike and throw stuff through the woods, what's not to love? Like golf, there is a scoring system, and that's where "MyFrisbee" comes in.</p> "MyFrisbee" is a disc golf scoring app. You can search for courses, find leagues, and most importantly, keep score. It's a useful tool with one problem - there is no public API. I have seen this asked for publicly but MyFrisbee has shown no plans for this in the immediate future, and that's where I come in. I really like figuring out how things work.</p> Starting small</h4> This is the first real API I've tried reverse engineering so I wanted to start small. Some of the features of MyFrisbee are paid and only available in the app and I didn't want to dive into that just yet. There are parts of the service that are available on the website so I wanted to start there.</p> Courses</h4> The biggest feature of the free version of the app is probably the course directory so that's where I started.</p> https://myfrisbee.com/courses</a></p> Going directly to the courses URL, you can use the Developer Tools and the Network tab to already find some useful calls. The most important is a call to /__manifest</code>. This seems to strongly suggest at least the site is a Remix Run based app, also indicated by the p</code> parameters.</p> https://remix.run/</a></p> The full URL looks like this:</p> GET https://myfrisbee.com/__manifest?p=/courses&p=/courses/carey-park-disc-golf-course-e2a5&p=/courses/cheney-state-park-disc-golf-course-west-DnNL&p=/courses/chisholm-trail-3RqD&p=/courses/cowskin-mKI4&p=/courses/cowskin-west-MXwZ&p=/courses/dragon-disc-golf-course-ePkd&p=/courses/flying-bee-country-club-WOm5&p=/courses/garden-plain-city-park-dgc-dsry&p=/courses/helten-gardens-Bupy&p=/courses/keith-l-christner-family-dg-course-kLoh&p=/courses/lazys-links-1S2k&p=/courses/liberty-links-disc-golf-course-uwbs&p=/courses/linear-park-0KnA&p=/courses/llama-loop-qBK4&p=/courses/maize-south-dgc-0eco&p=/courses/newman-university-9Fmt&p=/courses/orchard-disc-golf-course-7F1E&p=/courses/prairie-winds-disk-golf-course-LiKg&p=/courses/quail-run-gFli&p=/courses/west-millbrook-dgc-tDG5&version=149b0717 </code></pre> While this does tell us a lot, it doesn't give us any real data. If we try changing filters, we see another useful call.</p> GET https://myfrisbee.com/courses.data?sortOrder=rating</code></p> Fore! Data incoming. While it's very, very</strong> obfuscated, you can see some real data in there.</p> We also can confirm our suspicions by looking at the response headers:</p> x-remix-response yes </code></pre> Most definitely a Remix based app.</p> Parsing The Data</h3> Looking at the data itself, it looks JSON-y, but when trying to parse it, we find it's corrupt and it fails. There are some foreign chars between two valid JSON arrays. This seems intentional as it's not breaking their site so they must know about it? Regardless, let's scrub that out.</p> This function takes our raw string and iterates over it creating a stack and checking for valid opening JSON brackets. When it finds an opening bracket, it pushes it to the stack, and when it finds a closing bracket, it pops one off. When the stack is empty, we know the JSON structure is complete.</p> export function extractJsonChunks(raw: string): any[] { const chunks: any[] = []; let i = 0; while (i < raw.length) { if (raw[i] === '[' || raw[i] === '{') { const start = i; const stack = [raw[i]]; i++; while (i < raw.length && stack.length > 0) { if (raw[i] === '[' || raw[i] === '{') { stack.push(raw[i]); } else if (raw[i] === ']' || raw[i] === '}') { stack.pop(); } i++; } const chunk = raw.slice(start, i); try { chunks.push(JSON.parse(chunk)); } catch { // ignore invalid chunks } } else { i++; } } return chunks; } </code></pre> Inspecting The Data</h4> After successfully parsing the data, and there is a lot</strong> of it, we can take a better look at two very large arrays.</p> The first part of the first array is mostly config looking stuff - API tokens for various services and basic user settings like locale.</p> My interest is mostly in the actual data, which you can kind of see in the snippet below. These are items in the array, so you can tell the data is there but it's very confusing to read and code against. It would be easy to assume a key then a value but then you see things like price</code>, followed by status</code> and can tell price</code> is obviously missing a value.</p> "_id", "cxYvYpWXX66MoAG5f", "name", "Orchard Disc Golf Course", "headline", "Moderately wooded technical course, Par 54 unless hole 5 is in long., making that a par 4 hole. (course 55)", "longDescription", "18 holes, 1 tee for each hole, 2 basket locations for each hole, rotated regularly. ", "holeCount", 18, "price", "status", "Active", "website", "https://www.facebook.com/groups/270758746431057", </code></pre> Before any of that actual data, there is an array which didn't make much sense at first.</p> After some time digging and debugging (and a little help from ChatGPT), it clicked into place.</p> "courseResults", [ 73, 253, 305, 382, 451, 538, 598, 661, 718, 774, 821, 864, 919, 979, 1026, 1074, 1123, 1174, 1224, 1285 ], { "_74": 75, "_76": 77, "_78": 79, "_80": 81, "_82": 83, "_84": 21, "_85": 86, "_87": 88, "_89": 90, "_91": 92, "_93": 94, "_95": 96, "_97": 98, "_99": 100, "_101": 102, "_103": 104, "_105": 106, "_107": 108, "_109": 110, "_111": 112, "_113": 114, "_115": 116, "_117": 118, "_120": 121, "_122": 123, "_124": 125, "_126": 7, "_127": 128, "_129": 130, "_138": 139, "_143": 144, "_145": 146, "_162": 108, "_163": 164, "_165": 166, "_167": 168, "_56": 170, "_171": 172, "_221": 222, "_223": 125, "_224": 125, "_225": -5, "_226": 125, "_227": 228, "_230": 231, "_235": 21, "_236": 21, "_237": 7, "_238": 125, "_239": 7, "_240": 7, "_241": 7, "_242": 21, "_243": 7, "_244": 245, "_246": 247, "_252": -7 }, </code></pre> The first array, courseResults</code> is an index map telling us where in this giant array each result is. If could you look at the site where we found this URL, you would notice 20 courses in the UI - it just so happens that there are 20 items in that courseResults</code> array.</p> If you happen to check array[73]</code>, it's the following object from above and that turns out to be a schema map - saying that the field name at array[74]</code> is equal to whatever is at array[75]</code> and so on.</p> So, taking this further, the first result will have values in this giant array from 74</code> to 252</code>. If you notice in our index map array above, the second result will start at 253</code> so that makes perfect sense.</p> If you look at array[253]</code> you will find another schema index to indicate where to can find all the key value pairs for the 2nd result, which will actually start at array[254]</code>.</p> To summarize a bit on how this data is encoded:</p> The file contains multiple top-level JSON blocks, pasted together without separators</li> The structure includes: A top-level</strong> array of values (strings, numbers, objects)</li> An array named courseResults</code> that lists indices into that top-level array</li> A set of object maps</strong> (e.g. at index 73, 253, etc.) that map "key index" → "value index"</li> </ul> </li> </ul> Key Insight:</strong></p> The file is basically a compressed CSV, but:</p> Field names and field values are stored in different locations</strong></li> Object schema = { "_76": 77, "_78": 79 }</code> → "name"</code> is at 76, value is at 77</li> </ul> Putting It All Together</h4> After deciphering how to read the data manually, it was time to do it programmatically.</p> With the help of ChatGPT, I wrote a couple functions that would take our original data and format it down to something much more useable.</p> function findCourseResultIndices(data: any[]): number[] { for (let i = 0; i < data.length; i++) { if ( Array.isArray(data[i]) && data[i].every((v: unknown) => typeof v === 'number') && data[i - 1] === 'courseResults' ) { return data[i]; } } throw new Error('Could not find courseResults array'); } export function extractCourses(data: any[]): Record<string, any>[] { const schemaIndices = findCourseResultIndices(data); const courses: Record<string, any>[] = []; for (const schemaIndex of schemaIndices) { const schema = data[schemaIndex] as Record<string, number>; if (typeof schema !== 'object' || Array.isArray(schema)) continue; const course: Record<string, any> = {}; for (const [rawFieldKey, valueIndex] of Object.entries(schema)) { const fieldKeyIndex = parseInt(rawFieldKey.replace(/^_/, ''), 10); const fieldName = data[fieldKeyIndex]; const value = data[valueIndex]; if (typeof fieldName === 'string') { course[fieldName] = value; } } courses.push(course); } return courses; } </code></pre> extractCourses</code> courses is a function that takes an array of any types.</p> First, it calls out to another function, findCourseResultIndices</code>. That function is iterating over the array, looking for another array of all numbers that is preceded by a string named courseResults</code> and returns it.</p> Then we take that list of indices back and iterate over it. For every index in that list, we build a schema of key value pairs and rebuild down into a simple Record</code>.</p> The result is something like this:</p> { _id: 'cxYvYpWXX66MoAG5f', name: 'Orchard Disc Golf Course', headline: 'Moderately wooded technical course, Par 54 unless hole 5 is in long., making that a par 4 hole. (course 55)', longDescription: '18 holes, 1 tee for each hole, 2 basket locations for each hole, rotated regularly. ', holeCount: 18, price: '', status: 'Active', website: 'https://www.facebook.com/groups/270758746431057', latitude: 38.0998054149767, longitude: -97.87738949287784, locationText: 'Hutchinson, KS', yearEstablished: 2018, courseId: 20619, ratingCount: 755, ratingAverage: 4.385343483628396, country: 'United States', countryCode: 'US', state: 'Kansas', city: 'Hutchinson', accessType: 'everyone', availabilityStatus: 'available', availabilityType: 'yearRound', landType: [ 226 ], targetType: 'basket', targetTypeDescription: 'DISCatcher Pro (28 chains)', hasBathroom: true, hasDrinkingWater: false, propertyType: 'mixedUse', conditions: { _146: 195, _196: 21, _197: 342, _199: 343 }, location: { _146: 166, _167: 345 }, shortId: '7F1E', topPhoto: { _74: 348, _242: 349, _244: 350, _246: 351, _248: 352, _250: 353, _252: 354, _254: 355 }, admin1Name: 'Kansas', worldRankingsRating: 86.11626662182661, activeTargetTypes: [ 340 ], activeTeeTypes: [ 259 ], timezone: 'America/Chicago', layoutConfiguration: { _127: 360, _134: 363, _139: 374, _155: 380, _162: 383 }, playFeeType: 'free', isCartFriendly: true, isDogFriendly: true, limitedAccessReason: undefined, isSmartLayoutEnabled: true, difficultyBins: [ 203 ], contactInfo: { _387: 388, _389: 388 }, accessTypeDescription: '', availabilityTypeDescription: '', byob: false, dedicatedTargets: true, hasAvailabilityRestrictions: false, isLocationPrivate: false, isStrollerFriendly: false, otherFees: '', underConstruction: false, accessibility: 'notAccessible', distanceFromSelectedPlace: { _206: 397, _208: 398 }, badgesInfo: undefined }, </code></pre> Voila! We have a well formed Course</code> object. If you look at fields like topPhoto</code>, it looks like the schema map field reference rabbit hole goes even deeper but that's for another post.</p> Summary</h4> In this post, we have:</p> Found URL for Courses</code></li> Scrubbed and extracted (broken) JSON from said URL</li> Discovered data included index and schema maps</li> Wrote functions to format data into useable object</li> </ul> Plan For Next Time</h4> Enable the user to search for a Place</code> and Courses</code>.</p> Contributing to the AWS Ruby SDK: When Documentation and Implementation Don't Match Unknown — Sat, 23 Aug 2025 00:00:00 +0000 The Problem</h3> I was working on some IAM role configuration at work when our Discourse deployment started failing with AWS credential errors. The error was frustrating because according to the AWS documentation, everything should have been working perfectly.</p> The deployment was trying to use credential_source = Environment</code> in the AWS config, which is a standard approach documented in the AWS CLI guide. But for some reason, the Ruby SDK wasn't picking up the credentials.</p> The Investigation</h3> Like any good debugging session, I started by tracing through the credential chain. The AWS Ruby SDK has a pretty clear credential resolution process, so I dug into the source code to see what was happening.</p> That's when I found something interesting: the AWS CLI documentation clearly shows Environment</code> as a supported credential source, but when I looked at the Ruby SDK implementation, that option was completely missing.</p> Here are the docs</a></p> Here's what I found in the SDK</a>:</p> case credential_source when 'Ec2InstanceMetadata' # ... implementation exists when 'EcsContainer' # ... implementation exists when 'Environment' # ... nothing here! end </code></pre> The CLI supports it, the documentation says it should work, but the Ruby SDK just... doesn't implement it.</p> The Solution</h3> This felt like a classic case where implementation lagged behind documentation. Since I needed this working for our deployment, I decided to contribute the missing functionality back to the project.</p> The fix was actually pretty straightforward once I understood the pattern:</p> when 'Environment' Aws::Credentials.new( ENV['AWS_ACCESS_KEY_ID'], ENV['AWS_SECRET_ACCESS_KEY'], ENV['AWS_SESSION_TOKEN'] ) </code></pre> I added comprehensive tests to make sure it worked correctly and that I wasn't breaking any of the existing 20,000+ tests in the project.</p> The Contribution</h3> https://github.com/aws/aws-sdk-ruby/pull/3283</a></p> Here's the thing - I don't really know Ruby that well. But the codebase was well-organized and the patterns were clear enough that I could understand what needed to happen.</p> I submitted the PR with:</p> The missing implementation</li> Proper test coverage</li> Clear documentation of what was being added</li> </ul> The Response</h3> The response from the AWS team was exactly what you hope for in open source:</p> "Hey, thanks for opening a PR. I agree that we should support this and I may make some changes to this PR as well."</p> </blockquote> That's maintainer gold right there - acknowledgment that the gap was real and willingness to collaborate on getting it merged.</p> What I Learned</h3> This whole experience reinforced a few things for me:</p> Documentation gaps happen: Even in well-maintained projects like the AWS SDKs, there can be mismatches between what's documented and what's implemented.</p> Don't let unfamiliar languages stop you: I was able to contribute meaningfully to a Ruby project despite not being a Ruby developer. Good code organization and clear patterns make this possible.</p> Small changes can have big impact: This was maybe 10 lines of actual code, but it unblocked our deployment and will help other developers who hit the same issue.</p> The Bigger Picture</h3> This kind of contribution is exactly why I love working as a generalist. Instead of saying "that's not my language" or "someone else should fix the AWS SDK," I could trace the problem to its source and ship a fix.</p> The best part? Our Discourse deployment should work now, and hopefully other developers won't hit this same roadblock in the future.</p> Update</h3> Since writing this, the change has been expanded with additional tests and approved by the maintainers</a>. It's really rewarding to see a small contribution grow into something that's now part of the SDK itself. This is a great reminder that even small fixes matter -- they can make life easier for the next developer who comes along.</p> The Saga Continues</h3> This turned out to be just the beginning. After getting the feature merged, I discovered it didn't actually work due to credential chain precedence issues. Read more in Part 2</a> and Part 3</a>.</p> ChatGPT assisted Changelog - 34/52 Unknown — Fri, 22 Aug 2025 00:00:00 +0000 This week balanced travel research, disc golf writing edits, technical debugging, and creative design work. On the travel side, questions came up about flying with money internationally and how ATM fees might look in the Czech Republic with an OnPoint credit union card. You also researched the best European power adapters, checking Wirecutter's recommendations for reliable options.</p> In Shelltrax, you continued to refine autoplay. The play_next_track</code> function was revisited to keep the footer showing artist and song info, just as before. The main issue left was that the progress bar didn't carry over correctly between tracks when autoplay advanced.</p> On the creative side, you explored what the Discourse logo might look like if it had aged 100 years, and separately, how it could be reimagined if the company had started as a penpal or letter-writing business. Both ideas fit into your broader exploration of branding experiments.</p> The Swedish (and some German) study streak has been extended to 239 days in a row.</p> Overall, the week tied together preparations for international travel, cleanup work on ongoing projects, and a mix of technical and creative problem-solving.</p> ChatGPT assisted Changelog - 32+33/52 Unknown — Sun, 17 Aug 2025 00:00:00 +0000 Early August Projects</strong></p> The first week of August was centered on your Node-postgres-exporter work. You finished the conversion to ESM and TypeScript and started thinking about next steps. Around the same time, you were also looking into writing a Nix package for Discourse, asking how to handle complex setups that involve databases and services.</p> System and Config Troubles</strong></p> A fair amount of time went into NixOS. You ran into an error with nixos-option</code> and flakes not being found in .config/nix</code>, and later were debugging Git commit signing issues (wrong email in the commit vs author fields). You also asked about forcing Git to use a certain SSH key or email per repo. Other NixOS topics included setting up Wi-Fi on your Framework 16, writing custom modules (like for Kolide), installing packages for Python and Ruby in nix-shell, and configuring Starship with Nushell.</p> Hardware and Devices</strong></p> You were troubleshooting Librewolf not showing your Bluetooth headset mic, plus issues with Wi-Fi and Ethernet modules on the Framework. There was also a question about pinentry not working with GPG on NixOS. On the hardware front, you asked about pixel misalignment on your monitor and learned about TCON as a possible cause.</p> Lifestyle and Planning</strong></p> You asked about FSAs and their use. Travel came up too, with your upcoming Europe trip and looking for the best power adapters (especially for the Czech Republic).</p> Blogging and Writing</strong></p> Your NixOS daily driver series continued, with a post on getting Wi-Fi working on the Framework 16. You considered what direction to take the next entry. You also asked for an intro/about section to describe yourself, condensing it down to 5 sentences. In parallel, you've kept up with weekly summaries and changelog-style posts.</p> Miscellaneous</strong></p> Other threads included practicing Terraform and Nomad, CSS layout questions, and making Hyprland keybinds prompt for confirmation before closing a window. On the wearable side, your PineTime step counter broke and you asked about firmware, Gadgetbridge, and even writing your own step-tracking app in Rust or Kotlin.</p> ChatGPT assisted Changelog - 31/52 Unknown — Fri, 01 Aug 2025 00:00:00 +0000 Nix package development</strong></p> We discussed writing a Nix package for a complex project with multiple resources, using the Discourse install-cloud guide as a template to structure derivations and manage dependencies cleanly.</p> NixOS Wi-Fi on Framework 16</strong></p> We troubleshooted nmcli reporting the Intel AX210 as DOWN, enabled wireless in configuration.nix, and resolved common pitfalls to bring up the wireless interface successfully.</p> Git commit signing</strong></p> We covered forcing Git to use a specific SSH key for a given repository, how to resign commits, and how to update the commit email so that signatures appear valid.</p> Hyprland keybinds</strong></p> We added a custom Hyprland keybind to close the active window with a confirmation dialog, and refined the yes/no prompts and dialog appearance for better usability.</p> Terraform and Nomad learning</strong></p> We explored practical resources--sample projects, tutorials, and sandbox environments--to build hands-on experience with Terraform and Nomad orchestration.</p> Bluetooth audio input</strong></p> We investigated why LibreWolf failed to detect a Bluetooth headset mic, including how to identify the board, check firmware versions, and verify driver support.</p> Email server on NixOS</strong></p> We outlined setting up a mail server on NixOS and using Caddy to automate TLS certificate issuance for secure SMTP and IMAP provisioning.</p> Privacy-focused smartwatches</strong></p> We reviewed open-source options like the PineTime, diagnosed step-counter failures, checked return policies, and sketched a plan for a Rust-based long- term step tracker integrated with Gadgetbridge.</p> Swedish Studies</strong></p> 221 days in a row on Babbel. Listened to audio books as well this week.</p> Hyprland Tricks - Close Window Keybind With Confirmation Window Unknown — Mon, 28 Jul 2025 00:00:00 +0000 By default, hyprctl dispatch killactive</code> will instantly close your focused window. If you're like me and have ever yanked a terminal or browser window when you weren't ready, this tiny script adds a "Yes/No" confirmation window using Wofi.</p> </p> Create the Script</h3> For me, I will be adding this to ~/dotfiles/hypr/scripts/hypr-confirm-close</code>.</p> #!/usr/bin/env bash # prompt "Close window?" with Yes/No via wofi choice=$(printf "Yes\nNo" \ | wofi --dmenu --prompt="Close window?" --lines=5) [ "$choice" = "Yes" ] && hyprctl dispatch killactive </code></pre> Remember to make it executable. chmod +x ~/dotfiles/hypr/scripts/hypr-confirm-close</code></p> Bind the Key</h3> In your hyprland.conf</code>:</p> bind = $mod, q, exec, bash, ~/.config/hypr/scripts/hypr-confirm-close </code></pre> The filepath is different here because it will get copied from our ~/dotfiles</code> dir to the normal ~/.config</code> directory.</p> Reload:</p> hyprctl reload</code></p> Summary</h3> Now MOD+q</code> pops up a two-line menu and only when you select "Yes" will your window be closed.</p> NixOS as a daily driver or Zero to Nixty, part 9/? - Enabling Wi-Fi Unknown — Sun, 27 Jul 2025 00:00:00 +0000 I recently got a new Framework 16</a> (thanks Discourse!). In the previous post, we talked about encrypting the machine and refactoring our config into a modular layout. You can read about that and more in the NixOS As A Daily Driver</a> series.</p> Today I will be showing how I got Wi-Fi working because it did not work on NixOS by default. The Framework 16 ships with an Intel AX210 Wi-Fi module.</p> The Symptoms</h3> nmcli device status</code> shows my wlp2s0</code> as "DOWN"</li> ip link set wlp2s0 up</code> was not effective</li> nmtui</code> would show SSIDs but refused to connect</li> </ul> Steps To Fix</h3> Load the Intel driver</strong></p> The AX210 needs the iwlwifi</code> kernel module and firmware:</p> boot.kernelModules = [ "iwlwifi" ]; hardware.enableRedistributableFirmware = true; </code></pre> This ensures the driver is in my init-ramfs</code> and the firmware is present.</p> Explicitly define Wi-Fi backend</strong></p> networking.networkmanager.enable = true; networking.networkmanager.wifi.backend = "wpa_supplicant"; </code></pre> Full Minimal Config Snippet</h3> All in all, this is what I added:</p> # Load the Intel AX210 driver and firmware boot.kernelModules = [ "iwlwifi" ]; hardware.enableRedistributableFirmware = true; # Enable the wireless module and NM networking.networkmanager.enable = true; networking.networkmanager.wifi.backend = "wpa_supplicant"; </code></pre> Rebuild & Reboot</h3> Make sure all the new config will take hold by rebuilding and rebooting.</p> sudo nixos-rebuild switch sudo reboot now </code></pre> You can confirm everything worked by running: nmcli device status | grep wlp2s0</code></p> Victory!</h3> After rebooting, my iwlwifi</code> driver loaded, wlp2s0</code> came up, and nmtui</code> was able to both see and connect to the SSIDs.</p> ChatGPT assisted Changelog - 30/52 Unknown — Fri, 25 Jul 2025 00:00:00 +0000 Tech</h3> Waybar network module</strong></p> Discussions on adding an ethernet or wifi status module to Waybar configuration for Hyprland in NixOS.</p> Nixvim branch specification</strong></p> Explored how to pin a specific branch in nixvim and how imports resolve relative paths in modular NixOS configs.</p> Kolide nix-agent on NixOS</strong></p> Reviewed non-flake-based Kolide agent setup, module imports, time zone settings, and troubleshooting import errors.</p> Responsive CSS patterns</strong></p> Covered CSS techniques for responsive background images and use of the :before</code> pseudo-element to style boxes.</p> TUI music player pause fix</strong></p> Debugged keybinding logic in the Rust TUI music player, refining toggle_pause behavior to eliminate extra keystrokes.</p> Arch Linux vs NixOS installation</strong></p> Compared archinstall features, encryption support, and filesystem choices (btrfs vs ext4); discussed backup and fallback strategies.</p> Wi-Fi and GPG in NixOS</strong></p> Troubleshooted wifi connections via NetworkManager, git commit email issues, and GPG pinentry failures in a NixOS environment.</p> SSH key management</strong></p> Advised on forcing Git to use specific SSH keys per repository and evaluated ed25519 as the default key type.</p> Starship prompt in NixOS and Nushell</strong></p> Installed and configured Starship in NixOS, and explored Nushell integration. Need to fix path in Nushell.</p> Python and Ruby in nix-shell</strong></p> Set up nix-shell with Python packages, managed Ruby gems, and fixed pinentry and gemdir errors within shellHook workarounds.</p> Personal</h3> First Week at Discourse!</strong></p> The onboarding process has been very smooth and everyone is very welcoming. I am excited about my future there.</p> Swedish</strong></p> 215 days in a row.</p> Today is my first day at Discourse! Unknown — Mon, 21 Jul 2025 00:00:00 +0000 Today I am joining Discourse</a> as a software engineer on the infrastructure team.</p> Who is Discourse?</h3> Discourse is the 100% open source discussion platform built for the next decade of the Internet. We make it easy to have meaningful conversations and collaborate anytime, anywhere.</p> </blockquote> We are the home of ~22k communities across 23 countries and 13 timezones.</p> Why Discourse?</h3> I'm excited about working at Discourse for a number of reasons really.</p> Most of my tech and programming focused life has revolved around open source software and it's always been a dream to get paid to work on an open source software project.</p> </li> It's a software engineer role on the infrastructure team. I was introduced to DevOps work at my last job and fell down the rabbit hole. I love config based workflows so things like IaC and NixOS have really clicked.</p> </li> The company as a whole. This kind of goes with number 1 but I feel very aligned with Discourse as a company. We work in an async format while being completely remote. The company is very transparent, inclusive, and let's be real, the benefits are great.</p> </li> </ol> I think this can be a very important and fulfilling chapter of my professional and personal life and I'm looking forward to making the internet a better place through open source software.</p> This is the second time now I've lost a job then found a much, much better one. I think this is a valuable lesson to try and remember if I'm in that situation again.</p> If Discourse sounds like the place for you, see if we're hiring: https://discourse.org/jobs</a></p> NixOS as a daily driver or Zero to Nixty, part 8/? - Modular Config Unknown — Sun, 20 Jul 2025 00:00:00 +0000 Check out the whole series here:</p> NixOS as a Daily Driver - Zero to Nixty</a></p> Intro</h3> Today is all about configuration and setting up our new encrypted machine. As I stated at the end of the previous post, this didn't go as smoothly as I was hoping.</p> My plan was to just use labels when setting up the filesystems so my same exact configuration could be copied around. This plan was short-sighted for a number of reasons but it was definitely not going to work after seeing what the basic configuration looked like after installing with encryption enabled. The LUKS device setup is more complex than the normal, unencrypted filesystem config. There may be a way to use labels here but I don't really want to mess with that right now. I have an encrypted machine that boots so I'm going to leave it that way.</p> Breaking Config Into Modules</h3> After some thinking and research, I decided to refactor the way I store the config. I had been wanting to modularize it a bit anyway, so what better time than now.</p> First, I broke my config up into some modules in a common</code> directory.</p> nixos/ ├── common │ ├── base.nix │ ├── desktop.nix │ ├── packages.nix │ ├── services.nix │ ├── uefi.nix │ └── users.nix </code></pre> Then, I created a hosts</code> directory that includes a file for each machine. That file imports these basic modules and adds anything host specific like hostname.</p> nixos/ ├── hosts │ ├── framework-personal.nix │ ├── framework-work.nix │ └── macbook.nix </code></pre> One of those files looks like this:</p> { ... }: { imports = [ ../common/base.nix ../common/users.nix ../common/desktop.nix ../common/packages.nix ../common/services.nix ]; networking.hostName = "macbook"; } </code></pre> Then I just update the /etc/nixos/configuration.nix</code> that was created for me and import that one module. One of those files looks like this:</p> { config, pkgs, ... }: { imports = [ ./hardware-configuration.nix ./hosts/macbook.nix ]; # Replace actual UUID below boot.initrd.luks.devices."$UUID".device = "/dev/disk/by-uuid/$UUID"; # Do not change this value unless you know what you are doing! # This value does *not* affect the Nixpkgs version. It is used to determine # whether to enable software and configuration options that require backwards # compatibility with older NixOS releases. Changing it may result in a system # that cannot be upgraded or has other surprising consequences. system.stateVersion = "25.05"; } </code></pre> Complete New Machine Flow</h3> Now, my new machine flow looks something like this:</p> Install NixOS</p> </li> Boot up and open a dev shell:</p> nix-shell -p git rustup neovim</code></p> (We use git to check out config, rustup to install rust/dotter, and neovim for easier editing.)</p> </li> Check out my dotfiles through https for now. This way I don't need to create an SSH key and add it to Github yet:</p> git clone https://github.com/ducks/dotfiles.git</code></p> </li> Install latest Rust then dotter:</p> rustup install stable; cargo install dotter</code></p> </li> Checkout a new branch in my dotfiles dir and add a new host file</p> </li> Add a new local config for Dotter at</p> dotfiles/.dotter/local.toml</code></p> </li> Use the installed Dotter to deploy my dotfiles:</p> ~/.cargo/bin/dotter deploy</code></p> </li> Rebuild NixOS:</p> sudo nixos-rebuild switch</code></p> </li> Start Hypr:</p> Hyprland</code></p> </li> Celebrate! :tada:</p> </li> </ol> If everything went well, I am now sitting behind a duplicate of my other machines. This workflow might seem long but it really only takes 10-30 mins to do all this. It can obviously vary on your machine and build size. It's far easier than any other new machine flow I've tried. I've read about people using ansible to do this kind of thing but this just feels so clean and easy once you get around the rough edges.</p> I have executed this flow on 3 machines now and it's worked well. I had to make a few small changes like adding a ref</code> to a branch for NixVim, and I'm honestly not sure why that is. I don't think it has anything to do with my config as it was building before.</p> Summary</h3> In this post, I showed how I broke my NixOS config down into modules so they can be easily imported per host. I think this is a clean and reproducible way to store and share my NixOS config. I have all my base config in easy to use modules, then I can simply add any host specific setup to that single file.</p> Next Time</h3> At this point, things are feeling pretty good for my setup personally. I keep things pretty minimal so as long as I can navigate around with the correct keybinds and have basic tools like Nix/Neovim and Librewolf installed and setup, I'm mostly good to go. There are definitely some non-NixOS specific things I could pivot to to stick with the "Daily Driver" theme.</p> If you're reading this and have suggestions or you're curious about something, let me know: nixos@jakegoldsborough.com</a></p> ChatGPT assisted Changelog - 29/52 Unknown — Fri, 18 Jul 2025 00:00:00 +0000 NixOS Daily Driver and Dotfiles</h3> Continued refining NixOS setup and daily driver blog series</li> Modularized dotfiles using Dotter with template support</li> Adopted approach of letting NixOS generate base config, layering custom on top</li> Explored idea of a "LazyNix" dev toolkit using importable modules</li> Troubleshot and resolved GRUB and UEFI encryption setup issues</li> </ul> Framework Laptop and QMK Customization</h3> New laptop! Framework 16</li> Investigated Framework RGB keyboard and LED matrix customization</li> Confirmed QMK support and existence of Rust libraries (most tooling is in C)</li> Searched for examples and guides to interact with Framework's LED module</li> </ul> Task Management and Productivity Tools</h3> Looked into Rust-based TUI task managers like Taskwarrior</li> Reviewed Taskwarrior features like due dates, tags, and urgency scoring</li> Practiced adding and updating tasks with CLI syntax</li> </ul> Git and Hosting</h3> Managing personal site using two remotes, pushing to both for now</li> Long-term plan is to self-host once everything is working reliably</li> </ul> NixCon 2025 Planning</h3> Would like to attend NixCon in Rapperswil-Jona, Sept 5 to 7</li> </ul> Avatars and Stickers</h3> Tweaked Tux-human avatar</li> Looked for places to buy open source stickers that support the projects</li> </ul> Neovim, Fonts, and Waybar</h3> Set up Nixvim to remove trailing whitespace on save</li> Troubleshot font issue in WezTerm by refreshing font cache and restarting</li> Created toggleable Waybar for system stats using manual launch approach</li> </ul> Language Learning</h3> 210 days of Swedish in a row</li> Trying to pick some German back up for trip to Prague</li> </ul> NixOS as a daily driver or Zero to Nixty, part 7.5/? - Trial by Encrypted Fire Unknown — Sun, 13 Jul 2025 00:00:00 +0000 Intro</h3> So far in this series, we have:</p> installed NixOS</li> enabled a desktop environment</li> setup a user and some basic daily driving tools</li> added our config to version control</li> introduced NixVim, a declarative way to configure Neovim</li> learned about NixOS dev environments</li> </ul> Catch up here: NixOS Daily Driver series list</a></p> This post is a bit of a detour as we'll be completing a fresh reinstall to enable disk encryption. We will be getting back to our configuration soon though. The next post will show how to take our version controlled config and apply it to our new install.</p> Encryption</h3> But first, let's talk encryption. So far I have not been installing NixOS with the drive encrypted. I recently learned that my new job will require the machine used for work to have an encrypted drive. This is a good thing and I should have been defaulting to encrypting my drives. Even though it's good, it does add some complexity to our NixOS configuration. Because I was doing this for the first time, I decided to first test the encrypted installation on an old System76 netbook I have.</p> Manual Attempts with LUKS and LVM</h3> Initially I planned to just do this manually. I have installed NixOS manually every time so far, so I was hoping it would just be a few more steps. For the most part this was true, but I still ran into some issues.</p> To start, I used gparted</code>, mkfs</code>, and cryptsetup</code> to format the disk and create some LUKS</code> partitions.</p> Partitioning and LUKS encryption</h4> # Partition disk (example: /dev/sda) parted /dev/sda mklabel gpt parted /dev/sda mkpart ESP fat32 1MiB 512MiB parted /dev/sda set 1 boot on parted /dev/sda mkpart primary 512MiB 100% # Format boot partition mkfs.vfat -F32 /dev/sda1 # Encrypt root partition with LUKS cryptsetup luksFormat /dev/sda2 cryptsetup open /dev/sda2 cryptroot </code></pre> This all worked fine and I was able to set a password for the encrypted drive and then unlock it right after.</p> LVM</h4> Now use LVM to allow flexibility inside the encrypted container:</p> # Initialize LVM pvcreate /dev/mapper/cryptroot vgcreate vg /dev/mapper/cryptroot # Create logical volumes lvcreate -L 16G -n swap vg lvcreate -l 100%FREE -n root vg # Format filesystems mkfs.ext4 /dev/vg/root mkswap /dev/vg/swap </code></pre> Mounting for Installation</h4> Next was to mount our partitions for installation.</p> # Mount the root volume mount /dev/vg/root /mnt # Mount the EFI partition mkdir -p /mnt/boot mount /dev/sda1 /mnt/boot # Enable swap swapon /dev/vg/swap </code></pre> Configuration and Installation</h4> The next step was to generate the NixOS configuration for our mounted filesystem:</p> nixos-generate-config --root /mnt</code></p> When running this, NixOS will generate a basic configuration for you based on the disks you create and mount. This works well when creating an unencrypted drive and the boot, root, and swap partitions are all configured correctly. For whatever reason, the LUKS</code> devices do not get picked up by this. This means we'll have to manually update our configuration to include the LUKS</code> devices.</p> This is fine because from what I read in the docs, this isn't too complex. It should look something like this:</p> # Attempted configuration boot.initrd.luks.devices."cryptroot" = { device = "/dev/disk/by-uuid/XXXX"; }; </code></pre> The docs also mention adding a kernel module: boot.initrd.kernelModules = [ "cryptd" ];</code></p> After that, it was time to rebuild then reboot.</p> And, at first, success! During boot, I get asked for a password to open my encrypted drive.</p> But then... failure! The passphrase will not work. My first instinct was I fat fingered it but I tried multiple times and it would just not work.</p> Recovery</h4> Welp, time to boot into the live ISO again. I wanted to doublecheck all the config and make sure I didn't mess something up.</p> First, I needed to open the encrypted root partition: cryptsetup open /dev/sda2 cryptroot</code></p> This creates /dev/mapper/cryptroot</code> and gives access to what's inside.</p> Next, the volume groups needed activated:</p> vgscan vgchange -ay </code></pre> Then we mount some important directories:</p> mount /dev/vg/root /mnt mkdir -p /mnt/boot mount /dev/sda1 /mnt/boot </code></pre> Now, we'll use nixos-enter</code>. This gave me a shell inside the broken system -- same environment as if it had booted normally.</p> We can check our config files to make sure nothing looks off:</p> nano /etc/nixos/configuration.nix nano /etc/nixos/hardware-configuration.nix </code></pre> Unfortunately for me, I could not find anything wrong. In fact, I tried 3 fresh installs and could never get it working manually.</p> Graphical Installer</h3> After all that, I decided to just give up on the manual install and try the graphical installer. I should have probably started here but I didn't see a certain sentence in the wiki in time.</p> There are a few options for full disk encryption. The easiest way is to use the graphical installer and choose "encrypt" while doing the installation.</p> </blockquote> And ya know what, it was easy. So easy in fact, it worked the first time and I could instantly power up, enter my encrypted drive password, and be taken to the login console.</p> Outro</h3> This post was kind of a detour from the normal series as we reinstalled so we could encrypt the drive. In the next post, I will be going over how we can take the configuration we added to git in the previous posts and apply it to our new, freshly installed and encrypted system.</p> Spoiler: it does not go as smoothly as I had hoped.</p> ChatGPT assisted Changelog - 28/52 Unknown — Fri, 11 Jul 2025 00:00:00 +0000 20250704 - 20250711</h3> Cyberspace</h3> NixOS</h4> Published two posts in Daily Driver series. My late 2011 Macbook Pro running NixOs is already feeling ready for daily use really:</p> Part 5</a></li> Part 6</a></li> </ul> </li> Fighting encrypted disk installation. Installation seems fine but then I can't unlock drive to boot up.</p> </li> </ul> Meatspace</h3> Disc Golf</h4> Played Pier Park</li> Played Memorial Park</li> Published post about experience with UDisc regarding my open source library: Fairway Client Not Fair Enough</a></li> </ul> </li> </ul> Language Studies</h4> Swedish</strong></p> 204 day streak on Babbel. Did a few more lessons this week and not just review. Listened to some Radio Sweden på lätt Svenska (Radio Sweden in easy Swedish)</li> </ul> Czech/German</strong></p> I found out I'll be going to Prague in Sept so I may try to pick up a little Czech and brush up on German as many speak it there apparently.</li> </ul> Garden</h4> Harvested 3 squash</li> Blueberry bush is fruiting</li> Raspberry bush is flowering</li> Tomatoes are flowering/growing</li> New tomato and pepper starts are doing well</li> </ul> Music</h3> Listened to a lot of Top Dawg Entertainment this week - Kendrick Lamar, Ab-Soul, Doechii, Schoolboy-Q</li> </ul> NixOS as a daily driver or Zero to Nixty, part 6/? - Dev environment Unknown — Tue, 08 Jul 2025 00:00:00 +0000 Recap</h3> In the last post, we added some quality of life enhancements. This included key remapping and getting hypridle and hyprlock set up.</p> See that post here</a>.</p> Intro</h3> Today, I will be introducing NixVim</code> and show you how to set up some per-project development shells. The latter is a very powerful part of NixOS as you'll see.</p> NixVim</h3> NixVim is a project that lets you declaratively configure Neovim in Nix. No init.lua</code>, vimrc</code>, or plugin managers like Lazy or Packer.</p> It's part of a broader Nix-native ecosystem where tools, config, and dependencies are defined in one declarative, reproducible system.</p> I use and suggest this for a few reasons:</p> Fully Declarative Neovim Config</li> </ol> This means all your plugins, keymaps, etc are explicity defined. This will allow you to easily version it, share it, and reproduce it on another system.</p> Automatic Plugin Management</li> </ol> No need to install anything with a plugin manager or run :PackerInstall</code>, :LazySync</code> etc. When you build Nix, NixVim builds Neovim with all your plugins downloaded and ready.</p> Tight Integration with Nix packages</li> </ol> You can inherit pkgs to bring in dependencies like ripgrep</code>, lua-language-server</code>, or stylua</code> directly. No external npm</code>, cargo</code>, pip</code>, or language-specific managers needed.</p> Initial Config</h4> We are going to start small with our config and extend it further later.</p> { pkgs, ... }: { programs.nixvim = { enable = true; # Enable basic plugins plugins = { lualine.enable = true; # Statusline telescope.enable = true; # Fuzzy finder treesitter.enable = true; # Better syntax highlighting }; # Use a Gruvbox theme (optional) colorschemes.gruvbox.enable = true; # LSP support plugins.lsp = { enable = true; # Example LSP: Lua servers = { lua-ls.enable = true; } } # Keymap example keymaps = [ { mode = "n"; key = "<leader>ff"; action = "<cmd>Telescope find_files<CR>"; options = { desc = "Find files"; }; } ]; }; } </code></pre> Let's break this config down.</p> First, and most importantly, we enable Nixvim by setting programs.nixvim.enable</code> to true</code>. Then, we enable a few basic plugins through programs.nixvim.plugins</code>.</p> After that we enable the gruvbox</code> color scheme and setup some basic LSP support.</p> Finally, we setup a keymap for <leader>ff</code> that uses telescope</code> to find files.</p> nix-shell</code> - What is it?</h3> Now onto nix-shell</code>. nix-shell</code> is a tool that lets you temporarily enter a development environment defined by a Nix expression. Think of it as a lightweight, project-specific sandbox with all the tools and dependencies you need -- and nothing you don't. They are like Python virtual environments, but for any tool or language.</p> You can use nix-shell</code> to:</p> Spin up a shell with specific packages available</li> Test tools or languages without installing them system-wide</li> Set up consistent dev environments across machines or teams</li> </ul> Why Use It?</h4> If you've ever run into "works on my machine" issues, nix-shell</code> is the antidote. By declaring your environment as code, you get repeatable, deterministic setups every time -- no more dependency drift or missing tools.</p> It's also fantastic for trying out a new language or toolchain. Want to test something in Ruby, Rust, or Go? You can be up and running with just a few lines.</p> Example</h4> Here’s what a simple shell.nix</code> might look like for Rust development:</p> { pkgs ? import <nixpkgs> {} }: pkgs.mkShell { buildInputs = [ pkgs.rustc pkgs.cargo ]; } </code></pre> Run nix-shell</code> in that directory, and boom, you'll be dropped into a shell environment with rustc</code> and cargo</code> available but without being installed globally.</p> One-Off Shells</h4> In fact, you don't even need a shell.nix</code> file. You could run nix-shell -p nodejs</code> and you would be dropped into a shell with nodejs</code> installed locally, meaning it's not installed globally.</p> Overall, nix-shell</code> is one of the most powerful parts of Nix/NixOS.</p> Summary</h3> In this post, we have:</p> Enabled NixVim and set up a simple, usable Neovim config</li> Introduced nix-shell</code> and showed how it can be used to create temporary, repeatable dev environments</li> Explained how to launch one-off shells and why nix-shell</code> is so useful for development workflows</li> </ul> NixOS as a daily driver or Zero to Nixty, part 5/? - QoL enhancements Unknown — Mon, 07 Jul 2025 00:00:00 +0000 Recap</h3> In the last post, we successfully got our configuration stored in version control. This will make it very simple to pass our config around if needed. We also learned about Dotter, a dotfile configuration management tool, which we will be using again today.</p> See that post here</a></p> Intro</h3> Today, we will be covering a few quality of life enhancements. Those will include keyboard remapping and locking our screen after a certain amount of idle time.</p> Quality of life enhancements are things that while not strictly necessary, they make life much better.</p> Keyboard Remapping</h3> First, I'll show you how to remap keys. For me personally, this will include:</p> Caps Lock -> Esc when pressed</li> Caps Lock -> Control when held (and another key is pressed)</li> </ul> Caps Lock as Control when being held is a new change for me but I'm really enjoying it. It has opened up many more keybind options for me.</p> This remapping will be done using "Interception Tools"</p> Interception Tools</h4> Interception Tools</a> is a set of utilities to control and customize the behavior of keyboard input mappings.</p> It works at a lower level than tools like xcape</code> or xmodmap</code> which makes it one of the only options available for customizing keyboard behavior across X11, Wayland, and the Linux console.</p> Below is an example of mine. It's stored in ~/dotfiles/nixos/modules/interception-caps.nix</code>.</p> This config:</p> enables the services.interception-tools</code> module</li> adds a plugin called caps2esc</li> adds a udevmonConfig</code> file</li> </ul> { config, pkgs, ...}: let intercept = "${pkgs.interception-tools}/bin/intercept"; uinput = "${pkgs.interception-tools}/bin/uinput"; in { services.interception-tools = { enable = true; plugins = with pkgs; [ interception-tools-plugins.caps2esc ]; udevmonConfig = '' - JOB: "${intercept} -g $DEVNODE | ${pkgs.interception-tools-plugins.caps2esc}/bin/caps2esc -m 1 | ${uinput} -d $DEVNODE" DEVICE: EVENTS: EV_KEY: [KEY_CAPSLOCK, KEY_ESC] ''; }; } </code></pre> Let's breakdown what's happening here.</p> JOB</code> defines a processing pipeline for input events. Each matching device runs this chain of commands.</p> </li> ${intercept} -g $DEVNODE</code> reads events from the input device</p> intercept</code> is the main input capture tool</li> -g</code> ensures the device stays grabbed</li> </ul> </li> caps2esc -m 1</code> is what actually transform the Caps Lock input into our dual behavior</p> Tap/Press = Escape</li> Hold = Control</li> Note - Control is only emitted if another key is pressed. holding Caps Lock will not simply emit Control</li> </ul> </li> ${input} -d $DEVNODE</code> writes the transformed input back into the system using uinput</code> kernel device</p> </li> DEVICE</code> block filters which devices this pipelines applies to.</p> EV_KEY: [KEY_CAPSLOCK, KEY_ESC]</code> means this only runs for devices that emit Caps Locks or Escape key events</li> </ul> </li> </ul> In short, this config captures raw key events for Caps Lock and Escape, transforms them using the caps2esc plugin, and injects the new behavior back into the system -- all at a low level that works across Wayland, X11, and even TTYs.</p> The above is stored in a separate NixOS module and then imported in my main configuration:</p> imports = [ # Include the results of the hardware scan. /etc/nixos/hardware-configuration.nix /etc/nixos/modules/interception-caps.nix ]; </code></pre> Idle and Lock</h3> Next, we will set our machine up to first lock, then power the screen down after a certain amount of idle time.</p> This is done using Hyprland companion packages, hyprlock</code> and hypridle</code>.</p> You can install those by adding them to your package list:</p> environment.systemPackages = with pkgs; [ hypridle hyprlock ]; </code></pre> Hyperidle</h4> Save this config as: ~/dotfiles/hypr/hypridle.conf</code></p> Here is my current setup:</p> general { lock_cmd = hyprlock before_sleep_cmd = hyprlock after_sleep_cmd = hyprctl dispatch dpms on } listener { timeout = 300 on-timeout = hyprlock } listener { timeout = 330 on-timeout = hyprctl dispatch dpms off on-resume = hyprctl dispatch dpms on } </code></pre> This is telling hypridle</code> to run hyprlock</code> as the lock_cmd and right before sleep. Then after we wake, use hyprctl to turn the monitor back on.</p> Then we set up a few simple listeners. The first one is for 300 seconds (5 minutes) and simply runs hyprlock</code> on-timeout. Then, I have another for 330 seconds (5 minutes 30 seconds) that will shut my monitor off on-timeout, and turn it back on after resuming.</p> Reload hypr conf with hyprctl reload</code> and you should now have a functioning idle and lock screen.</p> Hyperlock</h4> Note: Hyprlock does not automatically create a config, and without one, hyprlock</code> will not render anything, meaning you will just see your screen, but it will be locked -- you will not be able to interact with it again until you enter your password and hit Enter.</p> We are also able to customize our lock screen some. This config will also live in the same directory as the other hyprland config files. ~/dotfiles/hypr/hyprlock.conf</code></p> Below is an example of mine. It looks similar to css styling but not exactly.</p> Here, I'm setting up a simple background color, an input field with a border, and a label that just outputs the time. I like to keep mine simple but you can add a background image, move the input box around, and do a lot more than I am.</p> You can find more in the docs here</a>. It covers all the available elements you can use to style your Hyprlock screen.</p> background { color = rgb(282828) # Gruvbox dark background blur_passes = 0 } input-field { font_color = rgb(ebdbb2) inner_color = rgb(282828) # Slightly lighter than background outer_color = rgb(928374) outline_thickness = 3 size = 500, 50 position = 0, -33% } label { text = cmd[update:1000] echo "<b><big> $(date +"%H:%M:%S") </big></b>" color = rgb(ebdbb2) font_size = 32 position = 0, 0 valign = center halign = center } </code></pre> After adding both files, remember to run dotter deploy</code>. This will add symlinks for our newly added files to our correct Hyprland config directory by default based on our Dotter config.</p> Fun Fact</h3> This post was written from NixOS!</p> Summary</h3> In this post, we have:</p> Configured some muscle memory engraved key remappings including: Caps Lock -> Esc when pressed</li> Caps Lock -> Control when held (and another key is pressed)</li> </ul> </li> Setup hypridle</code> to lock out computer after 5 minutes then turn the screen off 30 seconds after that.</li> Styled a simple hyprlock</code> screen that shows the time and an input box for our password</li> </ul> Next Time</h3> Next time will be all about development work. We will introduce Nixvim and nix shell</code>. Nix shells are development environments you can set up via config. They are very powerful and make developing on NixOS much easier.</p> Fairway Client Not Fair Enough for MyFrisbee Unknown — Sun, 06 Jul 2025 00:00:00 +0000 Takedown Request</h3> Recently, I've been writing about reverse engineering a unique data structure I found while investigating the UDisc web app. I also created a free and open source library called Fairway Client. It's a fair way for accessing UDisc's .data</code> endpoints - the same ones their own web app uses. These are public, unauthenticated endpoints available to any browser.</p> The only intent was curiosity and a belief in open, user-accessible data and software. People have asked for this kind of access before, and UDisc has repeatedly said no. So I decided to see for myself. The data was right there - how hard could it be?</p> Turns out, not very.</p> Much of this data is user-submitted</strong>, and in some cases, user-paid</strong>. UDisc does offer a CSV export, but come on - programming is about automation, not downloading spreadsheets.</p> I posted about my findings and tools on the UDisc forum. That didn't go well. First, I didn't realize posts were moderated so my comment never got posted and that's on me. Second, they weren't pleased. I received a sternly worded email asking me to remove both the blog series and the codebase.</p> I wasn't sure what to expect - but I was still disappointed. I was hoping for curiosity, maybe even appreciation. Instead, I got a takedown request.</p> They cited their ToS, but if offering a clean, read-only interface to user-owned public data violates the ToS, maybe it's the ToS that is wrong.</p> The the code is down. I will be obscuring the posts to not reveal details but I have spent time and effort on them so they will be staying up in some form.</p> It might be time to give disc golf metrix a shot: https://discgolfmetrix.com/</a></p> ChatGPT Changelog - 27/52 Unknown — Fri, 04 Jul 2025 00:00:00 +0000 NixOS & NixVim Work</h3> Fixed issues with interception</code> and remapping caps lock to esc on tap and ctrl on hold</li> Investigated how to migrate from LazyVim to NixVim in a non-flake setup and how to modularize configuration.</li> Installed Starship and worked through integration with Nushell on NixOS, resolving autocomplete issues related to Carapace and Fish.</li> PipeWire was installed and CLI methods for inspecting its settings were explored.</li> Requested a developer-friendly NixVim config with completions and LSP support for both Node.js and Rust.</li> Compared nix-shell and flakes, with interest in setting up per-project environments for tools like Zola, Node, and Rust.</li> </ul> UDisc Reverse Engineering</h3> Public GitHub repo and blog posts were removed following a takedown request from UDisc. Redacted versions will be reposted later.</li> </ul> Etsy and Woodworking</h3> Added chunky maple cooking utensil</li> Added 4 piece mixed hardwood coaster set</li> Working on utensil rest</li> Working on guitar body</li> </ul> Personal</h3> Swedish learning streak hit 198 days</li> Received an offer letter!</li> </ul> NixOS as a daily driver or Zero to Nixty, part 4/? - dotfile/config management Unknown — Fri, 27 Jun 2025 00:00:00 +0000 From TTY to Tiling</h3> In the last post, we enabled Hyprland and set it to run by default on login.</p> In this post, we will be taking a slight detour and will be going over how to manage your NixOS config in version control. This step might be overkill for some but it makes it so we can easily checkout our config on any machine and have a working NixOS install fairly quickly.</p> We will also cover a little Hyprland config at the end.</p> Introducing Dotter</h3> Dotter</a> is a dotfile manager and templater.</p> You have a repo of dotfiles and two main config files:</p> .dotter/global.toml</code></p> global config where you define "modules" and tell Dotter how to handle copying config.</li> commit to version control</li> </ul> .dotter/local.toml</code></p> Per machine file that tells dotter which config to load. The idea being you may have different config needs for linux, macos, or windows.</li> This file is not committed to git because local lets you switch configs per machine without affecting version control</li> </ul> Add a .gitignore</code> if not already present. Add a new line: .dotter/local.toml</code></p> After configuring everything, you simply run dotter deploy</code> and the config files are copied to the locations set in global.toml</code>.</p> It's a great project and I highly recommend it.</p> Moving NixOS Config to Dotfiles Repo</h3> The first thing we'll do is add a new directory in our dotfile repo. Then we'll need to open up our .dotter/global.toml</code> file and add our NixOS config paths. That looks like this for me:</p> [nixos.files] nixos = '/etc/nixos' </code></pre> In Dotter talk, this is setting up a "module" named nixos</code>. We are telling Dotter that this module's files will be located in the nixos</code> folder and need to be copied to /etc/nixos</code>.</p> Now you will need to move the current NixOS config from /etc/nixos/configuration.nix</code> to your new nixos</code> folder.</p> One other step will be to allow writes to your /etc/nixos</code> dir by running sudo chmod o+w /etc/nixos</code>.</p> One important configuration option to mention for Dotter is the default_target_type</code>. Because of the template functionality of Dotter, it can either physically copy your config, or simply create a symlink.</p> I prefer symlinks by default so I use this config option. In global.toml</code>, I set the following:</p> [settings] default_target_type = 'symbolic' </code></pre> More info about that can be found in the Dotter wiki</a>.</p> If you plan to use symlinks with Dotter, you will need to open up nixos/configuration.nix</code> and make the hardware-configuration.nix</code> import an absolute path instead of relative path.</p> Example:</p> # nixos/configuration.nix { config, pkgs, ... }: { imports = [ /etc/nixos/hardware-configuration.nix ]; } </code></pre> You will also need to add your .dotter/local.toml</code> file.</p> That will look something like this:</p> packages = [ 'cmus', 'git', 'hypr', 'nvim', 'nushell', 'starship', 'waybar', 'wezterm', 'wofi' ] </code></pre> This is telling Dotter which of the "packages" in your global.toml</code> should be copied. This helps allow us to define our complete config in one repo even if every host doesn't use every package. Each host will have a local.toml</code> that copies specific packages.</p> Now it's finally time to run dotter deploy</code>. This will do the important step of taking our local dotfiles and copying (or symlinking) to the dirs we specified. After running that command, you will see /etc/nixos/configuration.nix</code> is present again.</p> The moment of truth, time to rebuild. You can start by doing a dry run sudo nixos-rebuild dry-activate</code>. This will build the system and tell you what would happen. If that goes well, run sudo nixos-rebuild switch</code>. NixOS gives a lot of protection around broken config so it's unlikely anything should break here and if it does, there will be an error that tells you why.</p> Commit your configuration file and merge your branch back to main</code>.</p> Adding Hyprland Config to Dotfiles Repo</h3> We are now going to do the same with our Hyprland</code> config. The steps are pretty much the same minus some chmod</code> and file path updates.</p> First, create a new branch and check it out. Then we create a new directory that I simply called hypr</code>. Next, copy the current Hyprland</code> config from ~/.config/hypr</code> into this new dir.</p> Now we will need to add a little Dotter config:</p> [hypr.files] hypr = '~/.config/hypr' </code></pre> Again, in Dotter talk, we are creating a hypr</code> module. Then we tell Dotter that any files in our local hypr</code> dir need to be copied to ~/.config/hypr</code>.</p> Now it's time to run dotter deploy</code>. This will do the step of copying our local config to the correct path in ~/.config</code>.</p> Confirm that file got copied and then run hyprctl reload</code> to reload the hypr</code> config.</p> Congrats On Version Controlled Config</h3> Your dotfile repo should now look something like this:</p> dotfiles/ ├── .dotter/ │ ├── global.toml │ └── local.toml ├── hypr/ │ └── hyprland.conf └── nixos/ └── configuration.nix </code></pre> We have now added two sets of our config into version control. This will allow us to easily pass around our config to a new machine if needed, especially with NixOS and it's declarative config.</p> Next Time</h3> In the next post, I plan to get back to actually setting up NixOS for daily driver use. This will probably include some hypr</code> config and introducing Nixvim. Nixvim is a way to manage your neovim plugins in a NixOS-y way.</p> ChatGPT Changelog (fka Weekly Summary) - 26/52 Unknown — Fri, 27 Jun 2025 00:00:00 +0000 NixOS Workflow & Improvements</h2> Refined NixOS development workflow by exploring the use of nix-shell</code> and Flakes for environment isolation and reproducibility. Discussed how to structure shell files for separate projects (e.g. Rust/Zola vs. Node).</li> Discovered how tools like rustup</code> and volta</code> behave in Nix environments. You acknowledged that nix-shell</code> helps contain them safely, but the Nix-native approach may still be preferable long term.</li> Cleaned up a bug with nixvim</code> setup by updating to the latest version and resolving a plugin rename (coedium-vim</code> ➝ windsurf</code>).</li> Added Blueman via Nix, and experimented with different ways to start Waybar without tying up terminal (eventually using hyprctl dispatch exec</code>).</li> Successfully reversed trackpad scroll direction in Hyprland using overrides, and this worked well across setup.</li> </ul> GitVote & GPG Work</h2> Progressed gitvote</code> CLI and backend significantly: Implemented registration and GPG signature support.</li> Verified that voting model and simulation strategy still worked.</li> Explored commit signing, storing keys in-repo, and ensuring modular CLI support for different user flows.</li> </ul> </li> Began planning for how to handle edge cases like simultaneous votes and eventually tallying.</li> </ul> Blogging & Writing</h2> Continued work on NixOS daily driver series, planning to document how to set up Dotter and Hyprland cleanly from scratch before layering more config.</li> Reflected on privacy-focused analytics post, considering how to improve tracking and discussing stance on respecting blockers.</li> </ul> UDisc API & Wrapper Library</h2> Worked on orchestration pattern for the TypeScript UDiscAPI</code> class, ensuring everything flows through a clean and testable interface.</p> </li> Removed unnecessary loadFromFile</code> logic and moved toward using raw JSON inputs with explicit route extraction.</p> </li> Streamlined the construction flow:</p> const udisc = new UDisc(); const schemaMap = udisc.extractSchemaMap(raw); const eventListings = udisc.resolveKeyValuePairs('eventListing'); </code></pre> </li> </ul> Personal Progress</h2> Maintained streak of learning Swedish — now at 193 days in a row. Mostly review. Need to listen to more podcasts/books again.</li> Only played one round of disc golf this week</li> </ul> How I accidentally wrote my first Neovim plugin Unknown — Wed, 25 Jun 2025 00:00:00 +0000 Just Show Me The Code</h3> repo</a></p> The Problem</h3> There is a simple motion I use in Neovim often and I finally decided to do something about it.</p> That motion is breaking up single line imports into multiline imports.</p> Example:</p> This:</p> import { foo, bar, baz } from './utils';</code></p> Should become:</p> import { foo, bar, baz, } from './utils'; </code></pre> It's a tiny thing but something I do all the time in javascript, typescript, and rust. Even if it's less than 80 characters wide, I really like breaking multiple modules imports down to separate lines.</p> The First Approach: Regex (And Why It Worked)</h3> The very first version of Vandelay used simple Lua string matching:</p> local pattern = [[import%s*{%s*(.-)%s*}%s*from%s*(.*);]] local names, from = string.match(line, pattern) </code></pre> This captured two groups:</p> names</code> - the full list inside { ... }</code></li> from</code> - the source string</li> </ul> After capturing, it simply:</p> Split names</code> on commas into a table of individual imports</li> Trimmed whitespace</li> Reconstructed the formatted import line with newlines and indentation</li> </ul> Why It Worked</h4> The format of imports I wanted to modify was extremely predictable. I only cared about one specific form and I was only operating on one line at a time. Lua strings were simple and fast for this very specific case. This worked extremely well from the start and passed some simple tests that tests import structure.</p> Adding Treesitter (And Why It Didn't Work)</h3> I thought using Treesitter would make the plugin more robust. It sounded like a perfect fit: parse the full AST, extract imports properly, and avoid relying on fragile string patterns.</p> In practice, I quickly ran into problems:</p> Complex Treesitter queries for what seemed like simple tasks</li> Accidental full-line and full-file rewrites when I only wanted to touch one line</li> Query capture ordering issues that merged unrelated imports together</li> Inconsistent grammar across different Treesitter parser versions</li> Parser installation requirements that added more dependencies</li> Much more boilerplate code for very minimal benefit</li> </ul> Treesitter excels for full-file refactors, linters, or analysis tools. But for surgical, highly structured, one-line rewrites? It was overkill.</p> What I Learned</h3> Treesitter is powerful. But power doesn’t always equal simplicity</strong> — especially for narrowly scoped formatting tasks.</p> For this plugin, regex provided:</p> Faster iteration</li> Predictable behavior</li> No parser dependencies</li> Simple implementation</li> Easier testing</li> </ul> Sometimes simple string matching really is enough -- especially when your input format is highly constrained.</p> nvim-vandelay 1.0</h3> The end result became nvim-vandelay</code>.</p> A micro-plugin for formatting imports</li> Fully manual keybind control</li> Regex-powered single-line rewriting</li> Rust and JavaScript support out of the box</li> Fully tested via Plenary + CI</li> </ul> Here is another link to the repo: nvim-vandelay</a></p> Introducing Shelltrax - Or how I vibe programmed my way to a TUI music player Unknown — Tue, 24 Jun 2025 00:00:00 +0000 Shelltrax</h3> github</a></p> </p> I love the terminal and have dabbled in Rust since the very early days. I've been to 5 RustConfs, but my actual knowledge of Rust never really went past the basics. I come from a scripted language background, so while I understood</em> the ideas, I didn't really understand them in practice -- mostly because I hadn't personally suffered the pain points Rust tries to solve.</p> The only way for me to truly understand was to build something real. Not another tutorial. Not another toy example. Something I'd actually use.</p> cmus</h3> cmus</a> is a small, fast</em>, and powerful console music player for Unix-like operating systems and it's easily one of the apps I use most.</p> And like I mentioned above, I learn best by writing real tools so why not try to recreate one of my daily drivers? It seemed like the perfect mix of things to learn: input handling, TUI design, file scanning, metadata parsing, and real-time playback.</p> Stack and Structure</h3> I tried to keep the stack small, modern, and as "Rust-native" as possible:</p> ratatui</code> - TUI layout and rendering</li> crossterm</code> - keyboard input handling and terminal backend</li> walkdir</code> - recursive file scanning and directory walking</li> id3v2</code> and symphonia</code> - parsing audio metadata (ID3, Vorbis, FLAC, etc)</li> rodio</code> - audio playback</li> </ul> Together, these gave me a good spread of "real" Rust problems to tackle: filesystems, decoding binary formats, audio streaming, real-time UI state, and concurrency.</p> Interface Design</h3> From the start, I wanted it to feel very simple.</p> The interface is split into a few key views:</p> A library view</strong>, where I can browse artists, albums, and tracks</li> A file browser</strong>, which lets me scan new folders and import music to the library</li> A persistent footer</strong>, showing the current track, album, artist and a real-time progress bar while the song plays</li> </ul> Even building that much required learning how to manage state in a long-running TUI app, wire up input handling with crossterm</code>, and keep the UI responsive while streaming audio in the background.</p> What's Working</h3> Despite starting this as mostly an experiment to learn Rust, I now have a music player that:</p> Scans my local library for FLAC and MP3 files</li> Parses metadata (title, album, artist, album artist, etc) correctly using Symphonia</li> Sorts and groups tracks by album artist for proper browsing</li> Supports autoplay, automatically advancing to the next track</li> Displays a footer with current song info and a live progress bar</li> Supports pause and resume functionality with synchronized playback state</li> </ul> It's already become my daily music player, replacing cmus for my listening.</p> </p> Reflections</h3> The most valuable part of this project was finally experiencing what Rust is really trying to protect you from.</p> Shared state</strong>: Coordinating real-time playback state across multiple threads (UI thread, playback thread, decode thread) forced me to actually deal with ownership, borrowing, and synchronization directly.</li> Lifetimes</strong>: I finally had to understand where lifetimes mattered when dealing with borrowed references and streaming APIs.</li> Real-world edge cases</strong>: Dealing with weird metadata formats, malformed files, and partial decode failures showed me how fragile real-world data can be.</li> </ul> I've read about these things for years, but building Shelltrax forced me to feel the problems directly. That's what finally made the learning click.</p> Vibe programming</h3> There's a lot of discourse around "vibe programming" -- the idea of just writing code by intuition, following your gut, and iteratively figuring it out as you go. It sometimes gets a bad rap: "You're just hacking around without fully understanding the language or design."</p> But for me, vibe programming doesn't mean ignoring fundamentals. It means building something real, fast enough to stay motivated, but being careful enough to stop and actually understand why something works (or why it doesn't).</p> I could have read Rust books or done more exercises, but none of that would have taught me what happens when a real audio stream crosses threads and you forget to reset a state flag at just the right time. And I'll be honest, I didn't magically learn Rust completely and know how to handle every situation but I certainly have a much better idea than a few weeks ago.</p> Vibe programming can force you into real problems. If you stay curious and careful, those problems become extremely effective teachers.</p> Building a Fully Decentralized Voting System Using Just Git and Pull Requests Unknown — Mon, 23 Jun 2025 00:00:00 +0000 The Premise</h3> What if we could build a fully transparent, auditable, and tamper-evident voting system -- without any servers, centralized backend, or traditional databases?</p> The result is GitVote</strong> - a simple but powerful decentralized voting system that uses nothing but Git, pull requests, and a little bit of Rust.</p> Why Git?</h3> Git already gives us:</p> A fully distributed ledger</li> Immutable commit history</li> Branching and merging workflows</li> Forking for isolated participant actions</li> Cryptographic integrity through hashes and signatures</li> </ul> With all that, we're part of the way to a blockchain.</p> I wondered if I could build a voting system where Git itself is the storage layer, the consensus layer, and the audit trail.</p> The Design</h3> At a high level, GitVote works like this:</p> Proposals</strong> are created as dedicated Git branches</li> Votes</strong> are submitted as files inside pull requests.</li> Voter ID</strong> is tied to each voter's Git configuration (name and email)</li> Duplicate Voting</strong> is automatically prevented via CI checks</li> Immutable blocks</strong> are built from merged votes using deterministic hashing</li> Tally results</strong> can be generated entirely offline from the final ledger</li> </ul> There's no central database, API server, or backend. Everything happens inside of Git.</p> The Voting Flow</h3> Proposal Creation</h4> Each new proposal is created as a new Git branch, for example:</p> proposal/001-color-vote</code></p> A simple schema.json</code> file defines the allowed choices for that proposal:</p> { "allowed": ["blue", "purple", "green"] } </code></pre> Voter Submission</h4> Voters follow this flow:</p> Fork the governance repo</li> Clone their fork locally</li> Checkout the correct proposal branch</li> Run GitVote CLI tool to cast their vote: gitvote cast --choice purple</code></li> </ol> This will:</p> Write a new vote file into votes/</code> (one file per voter)</li> Commits the vote using their Git identity</li> Signs the commit (GPG coming soon)</li> Prepares the branch for submission</li> </ul> Push their branch back to their fork</li> Open a pull request into the upstream proposal branch</li> </ol> Vote Validation</h4> Every pull request triggers CI which runs: gitvote validate</code></p> This will validate:</p> The vote file format</li> Compliance with the allowed schema</li> No duplicate voters (one voter, one vote)</li> </ul> Invalid votes fail the CI and will not be merged</p> Merging & Chain Building</h4> Once a valid PR is merged, CI will automatically run: gitvote build-chain</code></p> This scans all merged vote files and creates an immutable hash-linked chain of blocks stored as plain JSON:</p> blocks/ block-0000.json block-0001.json ... </code></pre> Each block includes:</p> The vote choice</li> The voter identity</li> The original timestamp of the vote</li> The Cryptographic hash linking it to the previous block</li> </ul> Tallying Votes</h4> At any time, anyone can run: gitvote tally</code></p> This reads the blocks/</code> directory and generates a full tally of the current vote state:</p> Vote Tally: purple votes: 3 red votes: 2 Total unique voters: 5 </code></pre> No external system is needed to calculate the results — everything lives entirely inside Git.</p> The Tech Stack</h3> Rust for the core CLI, gitvote</code></li> Github Actions for CI validation and chain building</li> Git itself as the distributed backend</li> </ul> Security</h3> Voter ID is tied to each user's Git config (user.name</code> and user.email</code>)</li> CI fully enforces schema validation and prevents voter duplication</li> All votes are auditable forever via immutable commit history</li> The chain is fully deterministic and reproducible offline</li> The ledger can be archived back into main</code> for permanent recordkeeping</li> </ul> The Benefits</h3> Simplicity:</strong> No central server or complex infrastructure</li> Transparency:</strong> Every vote and rule is visible to all voters</li> Auditability:</strong> Anyone can verify the ledger at any time</li> Offline verifiability:</strong> The full vote chain is just a Git repo</li> </ul> Future Plans</h3> There are a number of interesting enhancements that could be made here I think:</p> GPG signature enforcement</li> Anonymous but verifiable voting via zero-knowledge proofs</li> Weighted or ranked ballots</li> Multi-proposal governance workflow</li> </ul> For now, GitVote is a minimal, functioning, fully decentralized voting system.</p> The Code/Demo</h3> You can find the CLI here: GitVote CLI</a></p> You can find a test governance repo here: gitvote-test</a></p> By going to actions</a>, you can see the various CI workflows that run during the voting process.</p> First, I submit a valid vote for purple</strong></li> Then, I attempt to vote again for green</strong>, which correctly fails due to duplicate voter prevention</li> Finally, I simulate a new voter by spoofing a different Git identity (via git config</code>), submit a vote for blue</strong>, and the vote passes validation</li> </ul> Closing Thoughts</h3> What originally started as an idea for "Gitcoin" and wanting to learn more about blockchains turned into a fully functional, fully auditable governance platform -- all built entirely on top of Git (and Rust).</p> It was pretty satisfying to turn pull requests, branch protections, and hash-linked commits into a simple, verifiable voting process.</p> The Accidental Complexity of Doing The Right Thing or The Pain of Setting Up Privacy-Focused Analytics (2025 Edition) Unknown — Sun, 22 Jun 2025 00:00:00 +0000 Introduction</h3> As I've mentioned in the past, I’ve been writing and blogging more, and I became curious if anyone was actually reading my posts.</p> Before I go any further, I need to make it clear that I am very privacy-focused. I hate logging, tracking, fingerprinting, or any kind of unnecessary data collection. A user’s data is theirs -- I have no interest in storing anything about them. I just want a basic count of which pages are being visited.</p> Naturally, I asked ChatGPT for recommendations based on my current setup.</p> I'm already using Caddy as my web server and TLS manager, so the first suggestion was straightforward: just enable HTTP access logs and analyze them.</p> Attempt 1: Server-side access logs (Caddy)</h3> The basic flow here would be:</p> enable http logs in Caddy</li> scrape log file</li> count requests as rough pageviews</li> </ul> In theory, this sounded perfect. I wasn’t looking for fancy dashboards or detailed metrics -- just simple counts of which pages were being hit. Plain log files should be more than enough.</p> Caddy, by default, doesn't actually log HTTP requests unless you configure it to. More surprisingly, in many builds of Caddy (especially those provided by package managers), the http.handlers.log</code> module isn’t even included.</p> At first I thought I was on the wrong version, but after some digging, I realized that full HTTP access logging in Caddy requires building your own custom binary with xcaddy</code></a> to enable the logging module. This felt like massive overkill for something as basic as HTTP request logging.</p> After trying multiple versions, failing to get access logs working, and realizing that Caddy’s modular architecture was actively getting in my way, I gave up on this approach.</p> I asked ChatGPT for other options.</p> Attempt 2: Goatcounter via Docker</h3> The next recommendation was to use a dedicated privacy-first analytics tool. Several good open-source options exist: GoatCounter</a>, Plausible, and Umami.</p> After doing a bit of research, GoatCounter stood out. It’s fully open-source, extremely privacy-focused, lightweight, and seems purpose-built for people like me who just want simple pageview counts without any tracking nonsense.</p> Even better, GoatCounter has Docker images available.</p> But of course — the Docker image that used to be hosted on Docker Hub was no longer available. The project had moved its images to GitHub Container Registry (GHCR), and GHCR was returning permission errors when I tried to pull the image anonymously. Apparently GHCR increasingly requires authentication even for public images, depending on Docker version, client configuration, and random GitHub API mood swings.</p> Attempt 3: Building my own Goatcounter Docker image</h3> After that, I decided to just build the image myself.</p> GoatCounter publishes a Dockerfile in the repo, so this should be straightforward:</p> git clone https://github.com/arp242/goatcounter.git docker build -t goatcounter:local . </code></pre> The Dockerfile requires Docker BuildKit support, and uses newer Dockerfile features like --exclude</code>, which aren't supported by Docker’s legacy builder. I had to enable BuildKit, but enabling BuildKit required docker-buildx</code>, which wasn’t installed by default on my Arch system.</p> Once I installed docker-buildx</code>, I ran the build again. This time, it started pulling Go modules but failed with timeouts halfway through the build.</p> I retried. And retried. BuildKit timeouts, network flakiness, CDN rate limiting -- you name it. What should have been a 30-second build turned into multiple rounds of fighting with Docker’s build system and Go’s module proxy ecosystem.</p> At this point, Docker was no longer simplifying anything — it was actively making everything worse.</p> Attempt 4: Running GoatCounter directly</h3> By this point I was fully in "I don’t even care anymore" mode.</p> GoatCounter is a Go program that ships prebuilt binaries. I could just download the standalone Linux binary and run it behind Caddy directly, without Docker at all.</p> Except even that wasn't as straightforward as it should have been.</p> The download URL on GitHub releases points to a gzip-compressed file. I accidentally downloaded it and tried running it directly without decompressing it first, leading to confusing shell errors ("command not found" as it tried to parse the binary as text). Once I properly decompressed it, I finally had a functioning ELF binary.</p> I ran goatcounter serve</code>, initialized the SQLite database, and got it fully running behind Caddy with one reverse proxy entry. TLS worked automatically, and finally, my simple analytics system was live.</p> Observations</h3> Docker was supposed to make self-hosting trivial. But broken registries, permission issues, changing build standards, and fragmented tooling made things much harder. Self-hosted projects often don't have the resources to maintain registry hosting, Docker images, and packaging across multiple platforms. The friction involved in doing things ethically discourages people from even trying privacy-respecting solutions.</p> It's no surprise so many people just give up and paste Google Analytics into their site -- it's not better technology, it's easier deployment.</p> Conclusions</h3> Privacy-first analytics tools absolutely exist — GoatCounter is an excellent project, and I’m very happy with it now that it’s running.</p> But the tooling friction creates artificial barriers that discourage adoption. Ironically, it's often easier to deploy privacy-invasive analytics than privacy-respecting ones.</p> There’s a huge opportunity here to improve the ecosystem:</p> Smarter build tooling</li> Better Docker automation</li> Easier packaging of self-hostable apps</li> (Maybe even a tool that turns install instructions into Dockerfiles automatically — but that’s a post for another day...)</li> </ul> If we want ethical software to be the default, we need to make it easier, not harder.</p> Edit (20250526)</h3> There IS</strong> a Docker Image</h4> Welp, naturally, after all of this — the registry issues, the broken builds, the manual binary install — I found out there is</em> a Docker image for GoatCounter:</p> arp242/goatcounter</a></p> (Yes, maintained by the actual author.)</em></p> Apparently I was just one docker pull</code> away the whole time.</p> :facepalm:</p> node-postgres-exporter — A Lightweight, Configurable PostgreSQL Prometheus Exporter Unknown — Fri, 20 Jun 2025 00:00:00 +0000 I’m releasing a small project I’ve been building:</p> node-postgres-exporter</code>, is a lightweight Prometheus exporter for PostgreSQL, written in Node.js.</p> The goal: build a fully configurable exporter that supports multiple databases, dynamic custom metrics, and solid production fault tolerance — while keeping the design modular and simple to operate.</p> There are excellent existing exporters in the ecosystem — but many of them require full privilege access, tightly coupled SQL views, or lack flexible multi-database support.</p> This exporter aims to solve a more targeted problem:</p> Support multiple independent PostgreSQL instances</li> Expose core database metrics (connections, size, etc.)</li> Allow fully configurable, per-database custom metrics via JSON</li> Provide basic fault isolation so partial database failures don't block full scrapes</li> Expose Prometheus-friendly endpoints with modern HTTP APIs</li> </ul> Key Features</h3> Node.js + Express based architecture</li> Uses pg</code></a> for database access via dedicated connection pools per database</li> Uses prom-client</code></a> for full Prometheus metric management</li> Simple configuration via JSON files (databases.json</code> and queries.json</code>)</li> API key authentication (Bearer token) for securing metrics endpoint</li> Graceful shutdown handling for safe database pool cleanup</li> Fully Dockerized with ready-to-run docker-compose</code> setup for local testing</li> Includes health endpoints: /healthz</code>, /readyz</code>, /livez</code>, /configz</code></li> </ul> Metric Types Supported</h3> PostgreSQL connection counts</li> Per-database size metrics</li> Custom query metrics with support for Gauge</code> and Counter</code> types</li> Exporter self-metrics: scrape duration, error tracking, scrape lockouts, etc.</li> </ul> Dynamic Query Configuration</h3> One of the core design goals for node-postgres-exporter</code> was flexibility without requiring code changes. To achieve this, all custom metric definitions are fully externalized via configuration files.</p> queries.json</code></p> Custom metrics are defined in a simple queries.json</code> file, allowing operators to add new metrics by writing plain SQL queries without modifying or redeploying the exporter. Each query entry includes:</p> name</code> – the Prometheus metric name</p> help</code> – description for the metric</p> type</code> – gauge or counter</p> labels</code> – array of columns to extract as metric labels</p> query</code> – the raw SQL statement to run against the target database</p> [ { "name": "active_users", "help": "Number of active users", "type": "gauge", "labels": ["status"], "query": "SELECT status, COUNT(*)::int FROM users GROUP BY status" } ] </code></pre> On each scrape, the exporter executes the configured queries, extracts label values from the row fields, and populates the Prometheus metric accordingly.</p> Fault Tolerance and Isolation</h3> Another design goal was to handle database failures gracefully. If one database becomes unavailable (network issue, restart, maintenance), the exporter:</p> Continues scraping all healthy databases</li> Exposes scrape success/failure per database as dedicated metrics (pg_scrape_success</code>)</li> Never fails the entire scrape due to single database issues</li> </ul> Internally, this is implemented using:</p> Promise.allSettled()</code> to concurrently scrape databases while isolating failures</li> Explicit error metric tracking</li> Per-database scrape duration timing</li> </ul> Example Use Case</h3> This design fits environments where:</p> You manage multiple distinct PostgreSQL instances</li> You have limited privilege access on some databases</li> You want metrics to be purely driven by SQL queries without deeper system integration</li> </ul> What it’s not trying to be</h3> A full replacement for highly privileged exporters like the canonical postgres_exporter</code></a></li> A deep SQL monitoring agent requiring superuser roles or heavy introspection</li> </ul> This exporter is intentionally simple, safe, and scoped</strong> — easy to audit and deploy.</p> Roadmap / Future Ideas</h3> There’s plenty of room for future enhancement:</p> Hot-reload support for queries and DB configs</li> JSON schema validation on configuration files</li> Cardinality protection on dynamic label sets</li> Additional metric types (Histogram</code>, Summary</code>)</li> Publish Docker images to container registries</li> Integration with secret management for DB credentials</li> </ul> Source Code</h3> Repo available here: https://github.com/ducks/node-postgres-exporter</a></p> A Side Benefit</h3> Although this started as part of an audition project, I ended up building something I’d absolutely consider productionizing for real-world use cases — and more importantly, something I can showcase as a clean systems-level engineering project.</p> ChatGPT Changelog (fka Weekly Summary) - 25/52 Unknown — Fri, 20 Jun 2025 00:00:00 +0000 Weekly Summary — 2025-06-13 to 2025-06-20</h2> Accomplishments</h3> Shelltrax TUI</h4> Continued refinement of Shelltrax (TUI music player).</li> Autoplay behavior adjustments: added logic to handle album track advancement.</li> Made progress on Symphonia integration for FLAC and seeking support.</li> </ul> open-udisc-api</h4> Further decoding work on Remix-style .data</code> format.</li> Continued schema-indexed record handling.</li> Published part 4 of your UDisc reverse engineering blog series.</li> Meta post idea evolving for later publication.</li> </ul> node-postgres-exporter</h4> Built a lightweight node-postgres-exporter</code></a> for Prometheus.</li> </ul> NixOS</h4> Ongoing modular NixOS configuration improvements.</li> TTY-first daily driver series is slowly building up. New post soon.</li> </ul> Swedish studies</h4> Hit 186 days in a row on Babbel.</li> Published “Typing Swedish with US Keyboard” blog post.</li> </ul> TODOs</h3> ShellTrax TUI</h4> Fix footer (currently doesn't update with next song, and progress is not perfect)</li> Fix broken metadata parsing</li> </ul> open-udisc-api</h4> Figure out what post 5 should be about</li> </ul> NixOS</h4> Write next post about hyprland and other config updates</li> </ul> Swedish studies</h4> Listen to more audiobooks this week</li> Do more than bare minimum reviews</li> </ul> ChatGPT Changelog (fka Weekly Summary) - 24/52 Unknown — Fri, 13 Jun 2025 00:00:00 +0000 Happy Friday the 13th!</h3> I have decided to slightly change up my personal weekly summary posts.</p> I have been using ChatGPT more and more and really find it to be an important tool. It saves me so much time with debugging error messages and digging through docs. It can also keep very good track of what I've been working on and thinking about. Because of this, I have decided to update the way I do the weekly summary. I am going to let ChatGPT generate a personal changelog of everything I have been working on. It's not perfect so I do have to edit it some but it still does a better job than I could ever do.</p> So with that, here is my weekly ChatGPT changelog:</p> Accomplishments (Since June 7)</h3> UDisc API / Blog Series</h4> Published Part 4 of the blog series: deep dive into smartLayouts</code> and holes</code>.</li> Improved deepHydrate</code>, began resolving issues with arrays of unresolved IDs.</li> Continued resolving schema-indexed keys (e.g. _254: 270</code>) for clarity.</li> Added blog link to open-udisc-api</code> README.</li> Cleaned up TypeScript types and debugged schema hydration logic.</li> </ul> Infra & DevOps</h4> Set up Gitea using a Linux service.</li> Implemented a Git pre-push hook to filter Zola drafts before publishing.</li> Decided to drop OpenAPI support for the current API project.</li> </ul> PostgreSQL Exporter</h4> Deployed a general-purpose PostgreSQL -> Prometheus exporter.</li> Added /metrics</code>, /livez</code>, /readyz</code>, and /configz</code> endpoints.</li> Configured basic token authentication.</li> Documented endpoints and auth in the README.</li> </ul> NixOS / Hyprland</h4> Diagnosed Hyprland reload issues involving exec-once</code> behavior.</li> Installed and confirmed use of: wezterm</li> dunst</li> hypridle</li> bibata-cursor-theme</li> </ul> </li> Explored xcursor previews and how to apply cursor themes via Nix.</li> Set up Waybar with Gruvbox-inspired CSS.</li> </ul> Miscellaneous</h4> Continued Swedish learning streak (currently 179+ days).</li> Expanded concept for a first-person disc golf course viewer.</li> Researched 360-degree and panoramic photo capture on Android/GrapheneOS.</li> </ul> To-Do / Improvements</h3> UDisc API + Blog</h4> Fix unresolved arrays in deepHydrate</code>, such as targetPositionLabels</code>.</li> Begin drafting a "meta" post summarizing the UDisc reverse-engineering series.</li> Write additional parts exploring fields like dogleg</code> or obLines</code>.</li> Explore creating a visualizer for hydrated course data.</li> </ul> Infra / Self-Hosting</h4> Document the Gitea systemd service setup.</li> Write a blog post about using Git hooks to manage Zola drafts.</li> </ul> NixOS / Hyprland</h4> Investigate why exec-once</code> commands don't rerun on hyprctl reload</code>.</li> Continue refining modular environment.systemPackages</code> layout.</li> Extend daily-driver blog series for NixOS on MacBook hardware.</li> </ul> Portfolio + Sharing</h4> Add README links or badges to published blog posts.</li> Write a post about decoding custom schema formats in APIs.</li> Share blog content on Hacker News, Lobsters, or relevant communities.</li> </ul> Typing åäö in Hyprland: A US, Mac-style Keyboard Guide Unknown — Thu, 12 Jun 2025 00:00:00 +0000 Intro</h3> As I've mentioned in the previous GPT Changelog nee Weekly Summary, I have been learning Swedish for over 6 months now. I'm getting pretty good at listening and reading, but I have been doing very little speaking and typing practice. I would like to change that by building muscle memory through proper Swedish typing.</p> Enabling in Hyprland</h3> Like many things in the Linux world, there is more than one way to do this. The easiest way would just be to use the GUI menu and add the keyboard. I would prefer to keep this declarative and inside some config files so it's more easily reproducible.</p> Instead, I will add some config to Hyprland to enable this. This config will:</p> enable the Swedish kb_layout</code></li> add the US variant for the Swedish layout</li> sets rctrl</code> as the key that toggles between layouts</li> sets ralt</code> as the modifier key for Swedish keys</li> </ul> input { kb_layout = us,se kb_variant = ,us kb_options = grp:rctrl_toggle,lv3:ralt_switch } </code></pre> Save the config and reload the hypr config: hyprctl reload</code></p> What is the US variant?</h3> Before testing it out, I should explain what the US variant is.</p> The Swedish (US)</strong> layout — sometimes referred to as "Swedish for US keyboards" — is a variant of the traditional Swedish keyboard layout that’s specifically designed for people using US physical keyboards</strong>. It allows you to type Swedish characters like å</code>, ä</code>, and ö</code> without rearranging the rest of your familiar QWERTY key positions.</p> This layout keeps the standard US punctuation and symbol positions intact</strong> — like /</code>, @</code>, ;</code>, and "</code> — while introducing the necessary Swedish characters via the Right Alt key</strong> (also called AltGr</code> in XKB terminology).</p> Unlike the default Swedish layout</strong>, which assumes a physical keyboard with keys labeled for Swedish (and repositions many punctuation marks), the Swedish (US)</strong> layout overlays the Swedish characters on a standard US keyboard. This makes it ideal for:</p> Swedish learners or expats using American keyboards</li> Developers or typists who need occasional access to å</code>, ä</code>, and ö</code></li> Anyone who doesn’t want to remap common keys like @</code>, |</code>, or /</code></li> </ul> In practice, this means you keep your normal US key behavior, and just use Right Alt as a modifier</strong> to access Swedish characters:</p> Right Alt + w</code> = å</li> Right Alt + '</code> = ä</li> Right Alt + ;</code> = ö</li> </ul> And uppercase versions with Shift.</p> If you’re used to US QWERTY and want to type Swedish without sacrificing developer-friendly symbols, Swedish (US)</strong> is the best option available — and it integrates smoothly into Linux environments like Hyprland when configured correctly.</p> 🇸🇪 Swedish (US) Layout – Character Cheat Sheet</h3> Character</th> Key Combo</th> Notes</th> </tr> </thead> å</td> Right Alt + w</kbd></td> Lowercase å</td> </tr> Å</td> Right Alt + Shift</kbd> + w</kbd></td> Uppercase Å</td> </tr> ä</td> Right Alt + '</kbd></td> Apostrophe key</td> </tr> Ä</td> Right Alt + Shift</kbd> + '</kbd></td> Shift + Apostrophe</td> </tr> ö</td> Right Alt + ;</kbd></td> Semicolon key</td> </tr> Ö</td> Right Alt + Shift</kbd> + ;</kbd></td> Shift + Semicolon</td> </tr> </tbody> </table> Conclusion</h3> You should now have a working Hyprland config that will allow you to type Swedish on a Mac-style, US variant keyboard.</p> Weekly Summary - 23/52 Unknown — Sat, 07 Jun 2025 00:00:00 +0000 Accomplishments</h3> Reverse Engineering UDisc API</h4> Published Part 3 of blog series on Course</code> and CourseDetails</code> structure.</li> Drafted outline for Part 4, focused on smartLayouts</code> and hole</code> info.</li> Renamed resolveSchemaMap</code> to a clearer, more specific function name.</li> Improved nested hydration using deepHydrate</code> for decoding nested data.</li> Considered naming conventions like courseWithDetails</code> for client API.</li> Decided to provide a client library first, rather than a full backend.</li> </ul> TypeScript Module and Publishing</h4> Adopted YYYYMMDD</code> format for versioning with semantic meaning.</li> Resolved JSON parsing and bundling issues in the TypeScript setup.</li> Held off on publishing to npm, but prepared module for later release.</li> </ul> Static Site and Blogging</h4> Fixed insecure site warning by enabling HTTPS on GitHub Pages.</li> Designed favicons and tried different accent colors and sizes.</li> Planned a meta-post to tie the blog series together conceptually.</li> </ul> NixOS Daily Driver Series</h4> Published Part 3 of your NixOS daily driver blog series.</li> Started exploring ideas for better display managers like Lemurs.</li> </ul> Gitea Self-Hosting</h4> Setup Gitea as Linux service.</li> Resolved SSH cloning issues by switching to internal SSH service.</li> Researched CI/CD via Woodpecker</li> </ul> Swedish Language Learning</h4> Reached 179-day streak learning Swedish using Babbel.</li> </ul> To-Do / Next Steps</h3> UDisc Blog Series</h4> Write and publish Part 4 about smartLayouts</code>, holes</code>, and tees</code>.</li> Create a meta-post summarizing the series with internal references.</li> Explore building a schema or data visualizer for reader clarity.</li> </ul> open-udisc-api Module</h4> Prepare for npm publishing (README, exports</code>, format cleanup).</li> Write more Vitest-based tests using mock data to avoid real API calls.</li> Add inline documentation and usage examples to client methods.</li> </ul> NixOS Configuration</h4> Start Lemurs setup for display management.</li> Write Part 4 of the daily driver series covering service setup.</li> Explore modularizing environment.systemPackages</code> further.</li> </ul> Gitea Enhancements</h4> Consider automating deployment with Git hooks or CI.</li> </ul> Additional Ideas</h4> Write a short post explaining UDisc .data</code> format independently.</li> Research legality of wrapper libraries for non-public data APIs.</li> Consider writing a proxy or wrapper API as a hosted endpoint.</li> </ul> NixOS as a daily driver on a late 2011 Macbook Pro, part 3/? - user, WM, tools Unknown — Thu, 05 Jun 2025 00:00:00 +0000 Recap</h4> See Part 2</a> where I cover installation and basic configuration.</p> Outline</h4> Things we will be covering in this post:</p> adding a non-root user with sudo access</li> installing a window manager - Hyprland</li> installing some tools - neovim, git, waybar, wezterm</li> </ul> Install a Text Editor</h4> First things first, let's install a better text editor to make our configuration updating easier.</p> You will have to use nano</code> for this. Open /etc/nixos/configuration.nix</code> and add the following:</p> programs.neovim = { enable = true; defaultEditor = true; }; </code></pre> Use ctrl+o</code> then ctrl+x</code> to write and exit nano.</p> Then run nixos-rebuild switch</code>. NixOS will rebuild your config and return you to a terminal. You should now be able to start neovim by running nvim</code>.</p> Adding a User</h4> Now that we can edit files easier, let's add a non-root user.</p> users.users.disco = { isNormalUser = true; extraGroups = [ "wheel" # Allows sudo access "networkmanager" # Allows controlling network "audio" # Audio device access "video" # Video devices (e.g. backlight, GPU) "input" # For input devices like keyboard/mouse config ]; }; </code></pre> Again, save and exit and then rebuild:</p> nixos-rebuild switch</code></p> After successfully rebuilding, you will need to set a password for the new user. For me that's:</p> passwd disco</code></p> Then you can exit</code> and login as your new sudo accessible user.</p> Enable Network Tools</h4> This will enable tools like nmtui</code> to allow for easier network setup.</p> networking.networkmanager.enable = true;</code></p> Install a Window Manager and Daily Driver Tools</h4> I am using Hyprland</a>. Hyprland is a dynamic Wayland compositor that supports tiling, floating, and hybrid layouts.</p> Add the following to your /etc/nixos/configuration.nix</code>. This enables Hyprland along with XDG portals, which are required for features like file pickers, screen sharing, and communication between sandboxed apps (especially Flatpaks and browsers).</p> programs.hyprland.enable = true; xdg.portal = { enable = true; wlr.enable = true; extraPortals = [ pkgs.xdg-desktop-portal-hyprland ]; }; </code></pre> Before rebuilding this time though, we will also install some daily driver tools.</p> One reason for this is that Hyprland</code> uses the kitty</code> terminal by default.</p> Look for this line in your /etc/nixos/configuration.nix</code> file:</p> environment.systemPackages = with pkgs; [ </code></pre> You will likely find this commented out with wget</code> listed as a package.</p> Expand on that section so it becomes:</p> environment.systemPackages = with pkgs; [ kitty # needed by Hyprland by default wget hyprpaper # background utility for Hyprland hyprlock # screen lock utility for Hyprland librewolf # privacy focused browser based on firefox wofi # needed by Hyprland by default git waybar # status bar for Hyprland wezterm ]; </code></pre> Some tools like neovim</code> and hyprland</code> have official NixOS modules, which let you enable them declaratively using enable = true;</code>. Other tools (like git</code> or librewolf</code>) don’t have modules and should be added directly to environment.systemPackages</code>.</p> Now it's time to rebuild. Again, this is done by: sudo nixos-rebuild switch</code>.</p> You can now manually start Hyprland</code> by running: exec Hyprland</code></p> You will be greeted with nothing but a random wallpaper supplied by Hyprland.</p> A couple important default keybinds are:</p> SUPER + q - opens terminal</li> SUPER + r - opens wofi app runner</li> </ul> Starting Hyprland on Login</h4> Let's make Hyprland</code> start on login. Create a ~/.bash_profile</code> file if it doesn't exist and add this:</p> if [ -z "$DISPLAY" ] && [ "$(tty)" = "/dev/tty1" ]; then exec Hyprland fi </code></pre> Summary</h4> In this post, we have:</p> added a non-root user and set their password</li> installed a window manager, Hyprland</code>, and set it to start on login</li> installed multiple important daily driver tools like git and librewolf</li> </ul> Next Time</h4> In Part 4, we'll continue to configure Hyprland</code>: adding keybindings, wallpapers, waybar, and maybe even a lockscreen.</p> NixOS as a daily driver on a late 2011 Macbook Pro, part 2/? - Installation, Basic Configuration Unknown — Wed, 04 Jun 2025 00:00:00 +0000 See Part 1</a> where I cover why you would want to run NixOS as a daily driver.</p> In this post, we will cover installation on a personal machine and setting up a basic configuration file.</p> Just as a note, for this specific post I am using:</p> efi</li> minimal ISO</li> dd (tool to write ISO)</li> </ul> See https://nixos.org/manual/nixos/stable/#ch-installation</a> for a full installation guide.</p> Installation</h4> Because Nix and Nixpkgs can be installed on almost any Linux distro, it's possible to install NixOS from inside an existing Linux install. You can even install it in place on the same partition. https://nixos.org/manual/nixos/stable/#sec-installing-from-other-distro</a></p> We will keep it simple and focus on using an ISO on a USB drive.</p> ISO</h4> Go to https://nixos.org/download/#nixos-iso</a> to download the ISO of your choice. If you are a newer user, you should probably pick graphical as it will help guide you along. I have Linux experience so I will be using the minimal version.</p> Next, insert your USB drive and look for it using lsblk</code>. Make sure it's not mounted: sudo umount /dev/sdX*</code>. Then use dd</code> to write the ISO to your drive:</p> sudo dd bs=4M conv=fsync oflag=direct status=progress if=<path-to-image> of=/dev/sdX</code></p> Now it's time to boot.</p> You will be greeted with nothing but a terminal. You will be automatically logged in as the nixos</code> user and have sudo access without a password.</p> Networking</h4> You will need a connection to the internet to download various things needed for the install. The easiest way is to just use a wired connection if possible. If you need wireless, it takes a little setup. The minimal installer does not ship with the correct firmware for my wireless card so I'm forced to use a wired connection. The wireless setup doesn't look difficult and instructions can be found here: https://nixos.org/manual/nixos/stable/#sec-installation-manual-networking</a></p> Partitioning and formatting</h4> The minimal NixOS install doesn't do any partitioning or formatting so that needs to be done manually.</p> First, you will need to partition:</p> Create a GPT partition table</li> </ol> parted /dev/sda -- mklabel gpt</code></p> Add the root partition. This will fill the disk except for the end part, where the swap will live, and the space left in front (512MiB) which will be used by the boot partition.</li> </ol> parted /dev/sda -- mkpart root ext4 512MB -8GB</code></p> Next, add a swap partition. The size required will vary according to needs, here a 8GB one is created.</li> </ol> parted /dev/sda -- mkpart swap linux-swap -8GB 100%</code></p> Finally, the boot partition. NixOS by default uses the ESP (EFI system partition) as its /boot</code> partition. It uses the initially reserved 512MiB at the start of the disk.</li> </ol> parted /dev/sda -- mkpart ESP fat32 1MB 512MB parted /dev/sda -- set 3 esp on </code></pre> Now, you need to format those partitions:</p> For initialising Ext4</code> partitions: mkfs.ext4</code>. It is recommended that you assign a unique symbolic label to the file system using the option -L label</code>, since this makes the file system configuration independent from device changes. For example:</li> </ol> mkfs.ext4 -L nixos /dev/sda1</code></p> For creating swap partitions: mkswap. Again it’s recommended to assign a label to the swap partition: -L label</code>. For example:</li> </ol> mkswap -L swap /dev/sda2</code></p> For creating boot partitions: mkfs.fat</code>. Again it’s recommended to assign a label to the boot partition: -n label</code>. For example:</li> </ol> mkfs.fat -F 32 -n boot /dev/sda3</code></p> Installation</h4> Mount the target file system on which NixOS should be installed on /mnt</code>, e.g.</li> </ol> mount /dev/disk/by-label/nixos /mnt</code></p> Mount the boot file system on /mnt/boot, e.g.</li> </ol> mkdir -p /mnt/boot mount -o umask=077 /dev/disk/by-label/boot /mnt/boot </code></pre> (optional) If your machine has a limited amount of memory, you may want to activate swap devices now (swapon device). The installer (or rather, the build actions that it may spawn) may need quite a bit of RAM, depending on your configuration.</li> </ol> swapon /dev/sda2</code></p> You now need to create a file /mnt/etc/nixos/configuration.nix</code> that specifies the intended configuration of the system. This is because NixOS has a declarative configuration model: you create or edit a description of the desired configuration of your system, and then NixOS takes care of making it happen.</p> The command nixos-generate-config</code> can generate an initial configuration file for you:</p> </li> </ol> nixos-generate-config --root /mnt</code></p> This command will also create a file at /mnt/etc/nixos/hardware-configuration.nix</code>. This includes important config for your filesystems among other things. While NixOS should handle this, it can't hurt to double check just to make sure things are defined correctly.</p> Most of the default config will be commented out, but a basic configuration.nix</code> file will look something like this:</p> { config, pkgs, ... }: { imports = [ ./hardware-configuration.nix ]; boot.loader.systemd-boot.enable = true; boot.loader.efi.canTouchEfiVariables = true; # Macbook Pro wireless firmware nixpkgs.config = { allowUnfree = true; }; services.openssh.enable = true; system.stateVersion = "25.05"; # Adjust to match your NixOS version } </code></pre> Note for UEFI users: You must select a boot-loader, either systemd-boot or GRUB. The recommended option is systemd-boot: set the option boot.loader.systemd-boot.enable</code> to true. nixos-generate-config</code> should do this automatically for new configurations when booted in UEFI mode.</p> Install! This step can take some time depending on your machine.</li> </ol> nixos-install</code></p> As the last step, nixos-install will ask you to set the password for the root user, e.g.</li> </ol> setting root password... New password: *** Retype new password: *** </code></pre> If everything went well, it's time to reboot</code>.</li> </ol> Summary</h4> That's it for this post and the installation and basic configuration of NixOS.</p> Next Time</h4> In the next installment, we'll create a non-root user, configure the Hyprland window manager, and install some key daily-driver tools including Neovim, Git, and LibreWolf.</p> How Vulfmon Inspired Me to Learn to Weave Unknown — Sat, 31 May 2025 00:00:00 +0000 Who is Vulfmon</h4> Vulfmon is the alter ego/moniker of Vulfpeck leader Jack Stratton. He sometimes shoots videos in a room with various art on the walls. In the video for Alone Again, Naturally</a>, I noticed a weaving that I loved:</p> </p> Lucky for me, I just happened to have access to a loom and yarn. Like any new skill, it was a bit awkward to start and honestly, my first one was rough. I stuck with it though and have made many better ones including six inspired by Vulfmon:</p> Vulfmon - gold 1</strong> </p> Vulfmon - gold, orange, brown 1</strong> </p> Vulfmon - green 1</strong> </p> Vulfmon - gold 2</strong> </p> Mini Vulfmon - purple 1</strong> </p> Mini Vulfmon - orange 1</strong> </p> Weekly Summary - 22/52 Unknown — Fri, 30 May 2025 00:00:00 +0000 Another pretty decent week. Mostly concentrated on job hunt and API inspection.</p> Things I did:</p> worked more on some API inspection. published two posts on it. working on lib. Part 1 - Courses</a></li> Part 2 - Search</a></li> </ul> </li> continued Swedish language studies - 172 days in a row</li> sent out 13 applications</li> </ul> Things that I didn't get to work on much:</p> rust</li> gitea server</li> nixos setup</li> rockpro64 setup</li> </ul> Deploying a Zola static site to a custom domain with Github Actions Unknown — Sat, 24 May 2025 00:00:00 +0000 As I've been searching for a new gig, I've gotten the urge to write a bit more about some of the stuff I'm up to to help make myself stand out. I really like using the fewest tools as needed so I knew a static site generator was what I wanted. I also like to use Rust based tools when possible.</p> Searching for Rust static site generators lead me to Zola</a>.</p> Some of the top advertised features are no dependencies, blazingly fast, and easy to use. Those sound great to me.</p> Set up Zola site</h3> While this isn't a few blown Zola tutorial, I did want to include a few things.</p> After installing Zola, you can simply run zola init myblog</code>.</p> You'll be asked a few questions and a base site will be setup for you.</p> ├── config.toml ├── content ├── sass ├── static ├── templates └── themes </code></pre> Without going too deep, your CommonMark pages will go in content</code>, Tera/HTML templates in templates</code>, and any css/js/images or other static content will go in static</code>.</p> SASS is enabled by default but can be disabled. I am not currently using SASS personally.</p> Running zola build</code> will build the site and output it a directory called public</code>.</p> Here is a link to a complete overview:</p> https://www.getzola.org/documentation/getting-started/overview/</a></p> Push to Github & Create Github Actions workflow</h3> After getting your content written, site styled, and ready for deployment, it's time to push to Github. Create a repo and push it to a main</code> branch (exclude the public</code> directory).</p> Next, we will setup the actual workflow to take our input files, setup zola, build the site, and commit it to the correct branch.</p> Create a file at .github/workflows/deploy.yml</code> and insert this:</p> name: Deploy Zola to GitHub Pages on: push: branches: [main] jobs: build-deploy: runs-on: ubuntu-latest steps: - name: Check out source uses: actions/checkout@v4 - name: Install Zola run: | curl -L https://github.com/getzola/zola/releases/download/v0.20.0/zola-v0.20.0-x86_64-unknown-linux-gnu.tar.gz -o zola.tar.gz tar -xzf zola.tar.gz sudo mv zola /usr/local/bin/ - name: Build site run: zola build - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./public publish_branch: gh-pages force_orphan: true </code></pre> This setups up a workflow that:</p> watches for pushes to main branch</li> checks out the zola source and installs it</li> builds your site using zola build</li> uses github pages plugin to push public</code> output dir to a gh-pages</code> branch</li> </ul> You will also need to go to your repos settings and look for the actions section to enable write permissions.</p> Push this up and watch the build by going to your repo and clicking the "Actions" tab. You will see a workflow that you can click into and see build and deploy jobs.</p> If everything goes well, you can now visit your site by filling in your values:</p> https://${username}.github.io/${repo}</p> Add Custom Domain (optional)</h3> After you have the initial workflow working, you will need to configure some Github settings for a custom domain.</p> First, run echo "yourdomain.com" > static/CNAME</code> and commit this file. Next, go to your Github repo's "Pages" setting and add the domain name.</p> Configure DNS (optional)</h3> If using a custom domain, you will also need to setup DNS. Go to your domain settings and add 4 A records for Github pages:</p> A @ 185.199.108.153 A @ 185.199.109.153 A @ 185.199.110.153 A @ 185.199.111.153 </code></pre> Setup any subdirectories you might want.</p> You may need to give this step some extra time to update before you can see your new site at your custom URL. Other times it's nearly instant so your results may vary.</p> Profit</h3> That's basically it for a basic setup. You should now have a static site setup at a custom domain that gets automatically built by just pushing a branch.</p> While simple, this is a complete setup that let's you create and deploy content to your own URL with ease.</p> Weekly Summary - 21/52 Unknown — Fri, 23 May 2025 00:00:00 +0000 This has been a pretty productive week.</p> Things that were good:</p> RockPro64 boots again! Blog post coming...</li> continued Swedish language studies - 165 days</li> started work on some API inspection. Another blog post coming...</li> figured out nixos/hyprland boot issue</li> </ul> Things that could be better:</p> didn't work on much rust</li> can't get gitea ssh setup on VPS</li> broke wood router part so had to buy new one to work on utensil rest</li> </ul> NixOS as a daily driver on a late 2011 Macbook Pro, part 1/? - What and why? Unknown — Sun, 18 May 2025 00:00:00 +0000 First, it's worth explaining what NixOS is and why I or anyone would want to run it as a daily driver.</p> But even before diving into NixOS, we have to talk about Nix.</p> Nix</h3> Nix is a package manager that is purely functional and creates reproducible builds specified in the Nix Expression Language. Nix expressions are functions that take dependencies as arguments which creates a derivation</em> that specifies a reproducible build environment. Nix then stores the results of the build at unique address specified by a hash of the complete dependency tree. This is known as the Nix store and it's immutable which allows atomic upgrades, rollbacks, and simultaneous installations of packages with different versions.</p> NixOS</h3> NixOS is an operating system that is built on top of Nix and the idea of purely functional package management. Packages are never overwritten once built. If you change the Nix expression for a package, it will be rebuilt, and stored under a new address with a new hash, preventing interference with an old version.</p> NixOS takes this a step further and applies this to configuration. By building your entire system from a Nix expression, NixOS ensures that your old configuration is never overwritten which allows for easy rollbacks. One big caveat of this is the elimination of "global" directores such as /bin</code>, /lib</code>, /usr</code>, etc. All packages are kept in /nix/store</code> under a hashed address. (One exception is a symlink /bin/sh</code> to Bash in the Nix store). There is a /etc</code> for system-wide config but many of those files are symlinks to files in the Nix store.</p> Everything in NixOS is built by the Nix package manager. This includes the kernel, applications, system packages, and configuration.</p> To configure NixOS, you have a file at /etc/nixos/configuration.nix</code>. You will setup everything from your boot devices to what services you want to run.</p> Here is a minimal config that enables sshd:</p> { boot.loader.grub.device = "/dev/sda"; fileSystems."/".device = "/dev/sda1"; services.sshd.enable = true; } </code></pre> More on this later though.</p> Why?</h3> Now the whys. I think many of them speak for themselves but here are mine:</p> Rollbacks</strong></p> This one is very big especially when learning about a new, drastically different OS like Nix. Because old config is never overwritten, you can easily cause a breaking change without being worried about how to fix it (unless maybe it's bootloader related). In fact, old configs are listed in the boot menu.</p> Reproducible Build Configurations</strong></p> Kind of like a rollback but starting from scratch. You can take the configuration.nix</code> file, copy to another machine, rebuild, and you will have the same applications, services, and configuration as before.</p> Ad-hoc shell environments</strong></p> In a "Nix shell", you can use any program that is packaged with Nix without needing to install permanently.</p> For example, you can run nix-shell -p git neovim node</code> and you will be dropped into a shell with those applications installed. This may take some time depending on the applications installed.</p> It's a new way to think</strong></p> Honestly, I just like trying new stuff, especially when it's done in a new way. Linux has mostly been the same for a long time now, so it's refreshing to see a new way of doing it that also improves on an already solid OS. I also have really fallen in love with DevOps/IaC type of work, and NixOS definitely scratches that itch.</p> Next time</h3> In the next post, I will go over how to install NixOS and maybe a bit of the configuration.</p> Weekly Summary - 20/52 Unknown — Fri, 16 May 2025 00:00:00 +0000 I am starting a weekly summary/reflection series that will be a high level view of things I have worked on or fixed or just things I want to track or note.</p> Things I enjoyed:</p> deployed this site</li> got an old raspberry pi running again</li> started back into some rust learnings with blockchain, TUI, and MQTT hacking 1</a></sup> 2</a></sup> 3</a></sup></li> started working on a walnut utensil rest</li> applied to 10 jobs</li> </ul> Things I did not enjoy:</p> seemingly bricked my RockPro64 as it won't boot past a black screen. ordered an adapater to help debug at a lower level.</li> rejected from multiple jobs</li> felt very confused by some of the rust learnings. makes sense in pieces but hard to see as the whole picture just yet</li> confirmed old fitbit can't be flashed with any open source/non-fitbit software</li> </ul> ^1</sup>https://ratatui.rs/concepts/application-patterns/the-elm-architecture/</a></p> </div> ^2</sup>https://github.com/veeso/tui-realm/tree/main</a></p> </div> ^3</sup>https://github.com/bytebeamio/rumqtt</a></p> </div>

Jake Goldsborough

replaybook: Incident Replay Trainer for Infrastructure

Software Doesn't Have to Justify Itself, or the Joy of Useless Programming

What "what if" gets you</h2> My favorite projects almost never start with a problem statement. They start with "what if."</p>

discourse-manager: A Community Management Sim Inside Discourse

The code</h2> It's a Discourse plugin, so the setup is what you'd expect:</p>

jolteon: An LLM Routing Proxy for Discourse

Links</h2> discourse-ai</a> - the Discourse AI plugin jolteon fronts</li> vLLM</a> - the inference backend</li> </ul>

mini_racer on NixOS: Three Things That Were Wrong

Yapper, or: just ask the bots

What the protocol actually is</h2> This is the part I think matters more than the forum.</p> When I was first building this, the framing was "a forum for agents." It got sharper while I was working. Here's the version I'd defend:</p>

Six records, two bugs, one refactor: a day with ARF

Claude assisted Changelog - 23/52

A tiny name.com CLI, and what nushell saves you

JSON in, tables out</h2> The name.com API returns JSON for everything. Listing records gives you back a structure like:</p>

Auditing a Squarespace 7.0 site before migrating to 7.1

Building a Travel Itinerary Plugin Inside Discourse

The Other Stuff</h2> A few smaller things that made the plugin feel like a real tool.</p>

Building a Screenshot Pipeline for Discourse Plugins

The architecture</h2> The tool ships a reusable GitHub Actions workflow</strong>. Plugins opt in by adding ~12 lines of YAML to their own .github/workflows/</code>:</p>

Playwright's Chromium doesn't run on NixOS</h3> Discourse uses Playwright for system specs. The first time I tried the tool locally, the Capybara driver tried to launch Chromium and got:</p>

When patchelf stopped working on Claude Code

Gotcha #2: Claude Code is a multi-call binary</h2> Claude Code's shell integration installs functions for find</code>, grep</code>, and ugrep</code>:</p>

Six numbers from my blog's analytics

A 'Was this helpful?' button for a static blog

The shape</h2> Three new files plus three small edits to existing templates.</p>

Try it</h2> There's one at the bottom of this post. If this was useful, click it.</p> I'll know whether the post landed because the dashboard will tell me. Not in pageviews. In helpful-blog-2026-was-this-helpful-button</code>.</p>

Running Claude Code on NixOS

How the patch works</h2> The interesting bit is the patch_binary</code> function. Given a path to an ELF binary, it asks Nix for the path to its</em> dynamic linker and the libraries the binary will need, then rewrites the binary in place:</p>

Links</h2> claude-nixos</a></li> NixOS Wiki: Packaging/Binaries</a> - the canonical write-up of the four fix-it options</li> nix-ld</a> - the system-wide alternative</li> </ul>

shellbooks: A Terminal Audiobook Player

The Stack</h2> ratatui</code> and crossterm</code> for the TUI</li> rodio</code> and symphonia</code> for audio playback</li> id3</code> for mp3 tags, mp4ameta</code> for m4b tags and chapter atoms</li> walkdir</code> for the file browser</li>

Interface</h2> Three views, swapped with 1</code> / 2</code> / 3</code>:</p>

Links</h2> shellbooks</a></li> shelltrax</a> - the music player it descends from</li> shellcast</a> - the podcast player it descends from</li> </ul>

isitreal.estate: Crowd-Sourced Reviews for Real Estate Listings

The code</h2>
It's a Discourse plugin, so the setup is what you'd expect:</p>
`cd /var/www/discourse/plugins git clone https://github.com/ducks/discourse-manager bundle exec rake db:migrate </code></pre> Then go to /play</code>.</p>Source at github.com/ducks/discourse-manager</a>.</p>`

`Links</h2> discourse-ai</a> - the Discourse AI plugin jolteon fronts</li> vLLM</a> - the inference backend</li> </ul>`

The Other Stuff</h2>
A few smaller things that made the plugin feel like a real tool.</p>

Try it</h2>
There's one at the bottom of this post. If this was useful, click it.</p>
I'll know whether the post landed because the dashboard will tell me. Not in pageviews. In `helpful-blog-2026-was-this-helpful-button</code>.</p>`

`Links</h2> claude-nixos</a></li> NixOS Wiki: Packaging/Binaries</a> - the canonical write-up of the four fix-it options</li> nix-ld</a> - the system-wide alternative</li> </ul>`

`Links</h2> shellbooks</a></li> shelltrax</a> - the music player it descends from</li> shellcast</a> - the podcast player it descends from</li> </ul>`