<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Riel Joseph</title>
    <description>The latest articles on DEV Community by Riel Joseph (@rieljdev).</description>
    <link>https://dev.to/rieljdev</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F606133%2Fd1ce9785-2dc9-488f-83eb-d7938cc24e3d.jpg</url>
      <title>DEV Community: Riel Joseph</title>
      <link>https://dev.to/rieljdev</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/rieljdev"/>
    <language>en</language>
    <item>
      <title>Building kakemono: A Wallpaper Manager That Comes With Me to Any OS</title>
      <dc:creator>Riel Joseph</dc:creator>
      <pubDate>Wed, 11 Nov 2026 04:22:22 +0000</pubDate>
      <link>https://dev.to/rieljdev/building-kakemono-a-wallpaper-manager-that-comes-with-me-to-any-os-3agp</link>
      <guid>https://dev.to/rieljdev/building-kakemono-a-wallpaper-manager-that-comes-with-me-to-any-os-3agp</guid>
      <description>&lt;p&gt;&lt;strong&gt;TL;DR&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;kakemono is a wallpaper manager for macOS, Linux and Windows. A small daemon downloads wallpapers from Wallhaven, Unsplash, Reddit, Bing, NASA's Astronomy Picture of the Day, any web page, or your own folders, and changes the wallpaper on a timer&lt;/li&gt;
&lt;li&gt;One Rust binary is both the daemon and the command-line tool. A Tauri app adds a tray icon, a thumbnail picker and a settings window&lt;/li&gt;
&lt;li&gt;It started as a macOS-only Go app. I rewrote it in Rust so it keeps working if I ever move to Linux or Windows&lt;/li&gt;
&lt;li&gt;The code is public at &lt;a href="https://github.com/RielJ/kakemono" rel="noopener noreferrer"&gt;github.com/RielJ/kakemono&lt;/a&gt;. The kakemono site, &lt;a href="https://kakemono.rielj.xyz" rel="noopener noreferrer"&gt;kakemono.rielj.xyz&lt;/a&gt;, has install steps for all three systems: Homebrew on macOS, Scoop on Windows, the AUR on Arch Linux, or a download&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fquv8yw9ulantsqgqunvb.gif" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fquv8yw9ulantsqgqunvb.gif" alt="Demo: turning on a Wallhaven source in Settings, opening the picker, and clicking a thumbnail to set it as the wallpaper" width="559" height="363"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;The demo turns on a Wallhaven search in Settings, opens the picker, and clicks a thumbnail. The new wallpaper is set before the Settings window closes.&lt;/p&gt;

&lt;h2&gt;
  
  
  How it started
&lt;/h2&gt;

&lt;p&gt;Linux has &lt;a href="https://github.com/varietywalls/variety" rel="noopener noreferrer"&gt;Variety&lt;/a&gt;. It's a plain little app that does one job well. You give it a list of sources, it downloads images in the background, and every half hour your desktop changes. If you liked the last one, you step back to it. If you hated it, you trash it.&lt;/p&gt;

&lt;p&gt;I wanted that on my Mac, so I wrote &lt;code&gt;wallpaperd&lt;/code&gt;: a Go daemon with a command-line client, six image sources, and a Unix socket. I wired it into &lt;a href="https://github.com/FelixKratz/SketchyBar" rel="noopener noreferrer"&gt;sketchybar&lt;/a&gt;, so my menu bar showed the current wallpaper and had next and previous buttons. I used it every day.&lt;/p&gt;

&lt;p&gt;The code had a weak spot, though. It set the wallpaper by running &lt;code&gt;osascript&lt;/code&gt; and asking System Events, which needs the Automation permission. It checked for dark mode by running &lt;code&gt;defaults read&lt;/code&gt;. Everything that touched the desktop went through another program, and every one of those programs exists only on macOS.&lt;/p&gt;

&lt;p&gt;I keep thinking about moving to Linux one day. If I do, I want my wallpaper setup to come with me, and I'd like it on a Windows machine too. So I asked my coding agent whether I should rewrite the app in Rust.&lt;/p&gt;

&lt;p&gt;Its first answer was no. The app sleeps 99.9% of the time, Go handles timers and sockets well, and nobody would notice the speed difference. That's fair. But I didn't care about speed. I cared about two things: no dependence on other apps, and one codebase for three operating systems. With those goals, Rust and Tauri made sense, and the rewrite began.&lt;/p&gt;

&lt;p&gt;I also needed a new name. &lt;code&gt;wallpaperd&lt;/code&gt; is very close to &lt;a href="https://github.com/danyspin97/wpaperd" rel="noopener noreferrer"&gt;wpaperd&lt;/a&gt;, an existing Rust wallpaper daemon for Wayland. A kakemono is a Japanese hanging scroll, a picture on the wall that people swap out with the seasons. That's close enough to what the app does.&lt;/p&gt;

&lt;h2&gt;
  
  
  What it does
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Sources.&lt;/strong&gt; Wallhaven and Unsplash searches, a subreddit, Bing's daily images, NASA's APOD archive back to 1995, the images on any web page, and local folders. You can add the same type more than once, for example two Wallhaven searches.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Rotation.&lt;/strong&gt; By default the wallpaper changes every 30 minutes. A background downloader fetches one new image every 10 minutes and keeps the download folder under 500 MB, oldest files first. It never deletes favorites.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;History, favorites and trash.&lt;/strong&gt; &lt;code&gt;kakemono prev&lt;/code&gt; goes back. &lt;code&gt;favorite&lt;/code&gt; copies the current image to a favorites folder. &lt;code&gt;trash&lt;/code&gt; moves it out and sets the next one, and the picker can undo that.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Light and dark.&lt;/strong&gt; When the system switches theme, kakemono can set a new wallpaper and prefer images that suit the theme.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Filters.&lt;/strong&gt; The settings copy Variety's "When possible, use images that..." section: landscape only, or at least 80% of the screen resolution.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The picker is a strip of thumbnails along one edge of the screen. It has five tabs: Sources, Downloaded, Local, Favorites and Cache. The Sources tab shows previews from your online sources without downloading anything. A click downloads the full image and sets it. Every action has a key, so I rarely touch the mouse.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F6e11gyabw59sr4umy87v.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F6e11gyabw59sr4umy87v.jpg" alt="The picker: a strip of wallpaper thumbnails at the top of the screen, with tabs on the left and the selected Wallhaven image outlined in blue" width="800" height="129"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;The settings window lists the sources in one table. You turn each one on or off, and "Use Only These" limits rotation to the ones you selected.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F63lq9eze453jywzkh5re.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F63lq9eze453jywzkh5re.jpg" alt="The kakemono Settings window with four Wallhaven sources, one enabled, and the &amp;quot;When possible, use images that...&amp;quot; filters below" width="800" height="576"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  How it's built
&lt;/h2&gt;

&lt;p&gt;There are two programs. &lt;code&gt;kakemono&lt;/code&gt; is the daemon and the CLI in one binary. &lt;code&gt;kakemono-ui&lt;/code&gt; is the Tauri app. Both talk to the daemon in newline-delimited JSON over a Unix socket, or a named pipe on Windows. That means you can script it with &lt;code&gt;nc&lt;/code&gt; or &lt;code&gt;jq&lt;/code&gt;, and my sketchybar plugin still works.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;kakemono next ────┐
tray, picker, ────┼──▶ socket (named pipe on Windows) ──▶ daemon
settings          │                                        │
sketchybar ───────┘                                        ├─ sources: download images
                                                           ├─ engine: rotation, history, cache
                                                           └─ platform: set the wallpaper
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;The Rust workspace has eight crates: &lt;code&gt;protocol&lt;/code&gt;, &lt;code&gt;config&lt;/code&gt;, &lt;code&gt;engine&lt;/code&gt;, &lt;code&gt;sources&lt;/code&gt;, &lt;code&gt;platform&lt;/code&gt;, &lt;code&gt;fs&lt;/code&gt;, &lt;code&gt;cli&lt;/code&gt; and &lt;code&gt;ui&lt;/code&gt;. Only &lt;code&gt;platform&lt;/code&gt; knows which OS it's on.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Setting the wallpaper&lt;/strong&gt; is the part that differs most between systems:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;On macOS, kakemono calls &lt;code&gt;NSWorkspace setDesktopImageURL:forScreen:&lt;/code&gt; through &lt;a href="https://github.com/madsmtm/objc2" rel="noopener noreferrer"&gt;objc2&lt;/a&gt;, once for each screen. No &lt;code&gt;osascript&lt;/code&gt;, and no Automation permission. One catch: macOS has no API that sets every Space, so only the current Space on each screen changes.&lt;/li&gt;
&lt;li&gt;On Windows, it uses the &lt;code&gt;IDesktopWallpaper&lt;/code&gt; COM interface from the &lt;a href="https://github.com/microsoft/windows-rs" rel="noopener noreferrer"&gt;windows&lt;/a&gt; crate.&lt;/li&gt;
&lt;li&gt;Linux has no single API, so kakemono detects the session. It checks for a desktop environment (GNOME, KDE, XFCE and others), then for a wallpaper daemon that's already running (&lt;code&gt;swww&lt;/code&gt;, &lt;code&gt;hyprpaper&lt;/code&gt;), then the compositor (Hyprland, Sway, niri), then X11 tools like &lt;code&gt;feh&lt;/code&gt;. That covers 17 backends. &lt;code&gt;kakemono detect&lt;/code&gt; tells you which one it picked and why. If yours isn't covered, you can set your own command.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;The tools:&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Part&lt;/th&gt;
&lt;th&gt;Tools&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Daemon and CLI&lt;/td&gt;
&lt;td&gt;Rust, tokio, clap, reqwest with rustls, serde, tracing&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Native APIs&lt;/td&gt;
&lt;td&gt;objc2 (macOS), windows-rs (Windows), zbus for D-Bus (Linux)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;App&lt;/td&gt;
&lt;td&gt;Tauri 2, React 19, TypeScript, Tailwind CSS 4, Vite&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Tests&lt;/td&gt;
&lt;td&gt;cargo test, insta snapshots, Vitest, Testing Library&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;CI and releases&lt;/td&gt;
&lt;td&gt;GitHub Actions on macOS, Linux and Windows, Docker, QEMU&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;
&lt;h2&gt;
  
  
  How I built it
&lt;/h2&gt;

&lt;p&gt;I built kakemono with coding agents in &lt;a href="https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent" rel="noopener noreferrer"&gt;Pi&lt;/a&gt;. First, four models each wrote a plan, and I merged the best parts into one. Next, I wrote short contracts for the pieces that crates share: the config format, the platform API and the source interface. Then subagents built slices against those contracts in parallel, each in its own git worktree, which I wrote about in &lt;a href="https://rielj.xyz/blog/building-pi-git-worktrees-parallel-ai-agents" rel="noopener noreferrer"&gt;my pi-git-worktrees post&lt;/a&gt;. The rewrite took 152 commits over two days.&lt;/p&gt;

&lt;p&gt;Three things kept the rewrite honest:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Golden fixtures from the Go app.&lt;/strong&gt; Before writing any Rust, I recorded what the Go daemon sent and received on its socket, and how it read its config. The Rust tests replay those recordings, so the new daemon had to answer the way the old one did.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Lots of tests.&lt;/strong&gt; There are 1,422 Rust tests and 392 frontend tests. The source tests replay recorded HTTP responses, so they never hit Wallhaven or Reddit.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Testing on systems I don't own.&lt;/strong&gt; GitHub Actions tests every push on macOS, Linux and Windows. I also wanted to catch failures before pushing, so the Linux checks run locally in Docker. The Windows checks run in a Windows 11 ARM virtual machine on my M4 MacBook, through QEMU and Apple's Hypervisor framework. A script installs Windows from an answer file with no clicks, runs the same tests CI runs, and shuts the VM down.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;One surprise came at the end. I downloaded the first release on my other laptop, and macOS said the app "is damaged and can't be opened". It wasn't damaged. The app isn't signed with an Apple Developer ID, so macOS blocks it when it's downloaded from the internet. The fix is one command, and it's in the install steps below.&lt;/p&gt;
&lt;h2&gt;
  
  
  How to use it
&lt;/h2&gt;

&lt;p&gt;The quickest way is your system's package manager:&lt;br&gt;
&lt;/p&gt;
&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# macOS, with Homebrew&lt;/span&gt;
brew install --cask rielj/tap/kakemono

&lt;span class="c"&gt;# Arch Linux, from the AUR&lt;/span&gt;
yay -S kakemono-bin

&lt;span class="c"&gt;# Windows, with Scoop&lt;/span&gt;
scoop bucket add rielj https://github.com/RielJ/scoop-bucket
scoop install rielj/kakemono
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;You can also download an installer from the &lt;a href="https://github.com/RielJ/kakemono/releases" rel="noopener noreferrer"&gt;Releases&lt;/a&gt; page: a &lt;code&gt;.dmg&lt;/code&gt; for macOS, a &lt;code&gt;.deb&lt;/code&gt;, &lt;code&gt;.rpm&lt;/code&gt; or AppImage for Linux, and a setup &lt;code&gt;.exe&lt;/code&gt; for Windows. If you download the macOS app instead of using Homebrew, clear the quarantine flag before you open it, because the build isn't signed:&lt;br&gt;
&lt;/p&gt;
&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;xattr -dr com.apple.quarantine /Applications/kakemono.app
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;On Windows, SmartScreen warns about an unknown publisher. Click More info, then Run anyway. The &lt;a href="https://kakemono.rielj.xyz/install/" rel="noopener noreferrer"&gt;install guide&lt;/a&gt; has step-by-step instructions for each system.&lt;/p&gt;

&lt;p&gt;Open the app. It starts the daemon and puts an icon in the menu bar, tray or notification area. From there you can open Settings, add a source, and open the picker.&lt;/p&gt;

&lt;p&gt;If you prefer the terminal:&lt;br&gt;
&lt;/p&gt;
&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;kakemono service install   &lt;span class="c"&gt;# start the daemon at login&lt;/span&gt;
kakemono next              &lt;span class="c"&gt;# set a new wallpaper now&lt;/span&gt;
kakemono prev              &lt;span class="c"&gt;# go back to the previous one&lt;/span&gt;
kakemono favorite          &lt;span class="c"&gt;# keep this one&lt;/span&gt;
kakemono trash             &lt;span class="c"&gt;# never show this one again&lt;/span&gt;
kakemono pause             &lt;span class="c"&gt;# stop rotating; `kakemono resume` starts again&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;Sources live in &lt;code&gt;~/.config/kakemono/config.toml&lt;/code&gt;, one &lt;code&gt;[[sources]]&lt;/code&gt; table each:&lt;br&gt;
&lt;/p&gt;
&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight toml"&gt;&lt;code&gt;&lt;span class="k"&gt;[daemon]&lt;/span&gt;
&lt;span class="na"&gt;interval&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"30m"&lt;/span&gt;

&lt;span class="k"&gt;[[sources]]&lt;/span&gt;
&lt;span class="na"&gt;id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"wh-nature"&lt;/span&gt;
&lt;span class="na"&gt;type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"wallhaven"&lt;/span&gt;
&lt;span class="na"&gt;location&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"nature"&lt;/span&gt;

&lt;span class="k"&gt;[[sources]]&lt;/span&gt;
&lt;span class="na"&gt;id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"pictures"&lt;/span&gt;
&lt;span class="na"&gt;type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"folder"&lt;/span&gt;
&lt;span class="na"&gt;location&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"~/Pictures/Wallpapers"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;On Linux, run &lt;code&gt;kakemono detect&lt;/code&gt; once to see which backend it picked. If the wallpaper doesn't change, &lt;code&gt;kakemono doctor&lt;/code&gt; prints the session, the command it would run, and what the daemon is doing.&lt;/p&gt;

&lt;p&gt;The &lt;a href="https://kakemono.rielj.xyz" rel="noopener noreferrer"&gt;kakemono docs&lt;/a&gt; have every command and config key. If you try it and something breaks on your desktop, please open an issue.&lt;/p&gt;


&lt;div class="ltag-github-readme-tag"&gt;
  &lt;div class="readme-overview"&gt;
    &lt;h2&gt;
      &lt;img src="https://assets.dev.to/assets/github-logo-5a155e1f9a670af7944dd5e12375bc76ed542ea80224905ecaf878b9157cdefc.svg" alt="GitHub logo"&gt;
      &lt;a href="https://github.com/RielJ" rel="noopener noreferrer"&gt;
        RielJ
      &lt;/a&gt; / &lt;a href="https://github.com/RielJ/kakemono" rel="noopener noreferrer"&gt;
        kakemono
      &lt;/a&gt;
    &lt;/h2&gt;
    &lt;h3&gt;
      Free wallpaper manager for macOS, Windows and Linux. New wallpapers from Wallhaven, Unsplash, Reddit, Bing, NASA APOD, any web page or your own folders, with a tray picker and a timer.
    &lt;/h3&gt;
  &lt;/div&gt;
  &lt;div class="ltag-github-body"&gt;
    
&lt;div id="readme" class="md"&gt;&lt;p&gt;
  
    
    &lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fraw.githubusercontent.com%2FRielJ%2Fkakemono%2FHEAD%2Fcrates%2Fui%2Fsrc-tauri%2Ficons%2F128x128%402x.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fraw.githubusercontent.com%2FRielJ%2Fkakemono%2FHEAD%2Fcrates%2Fui%2Fsrc-tauri%2Ficons%2F128x128%402x.png" alt="kakemono" width="96"&gt;&lt;/a&gt;
  
&lt;/p&gt;
&lt;div class="markdown-heading"&gt;
&lt;h2 class="heading-element"&gt;kakemono&lt;/h2&gt;
&lt;/div&gt;

&lt;p&gt;
  &lt;a href="https://github.com/RielJ/kakemono/releases/latest" rel="noopener noreferrer"&gt;&lt;img src="https://camo.githubusercontent.com/dc16b92815a47018697acf07a227f6ca23f097b460b7e01355241b6f416fd63d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f5269656c4a2f6b616b656d6f6e6f3f7374796c653d666f722d7468652d6261646765266c6162656c3d52656c6561736526636f6c6f723d316131613161" alt="Latest release"&gt;&lt;/a&gt;
  &lt;a href="https://github.com/RielJ/kakemono/actions/workflows/ci.yml" rel="noopener noreferrer"&gt;&lt;img src="https://camo.githubusercontent.com/cc85f2f29ed3c03abef3b98065ed6aba58a1b054f6208bb6aed42063db6237fb/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f5269656c4a2f6b616b656d6f6e6f2f63692e796d6c3f6272616e63683d6d61696e267374796c653d666f722d7468652d6261646765266c6162656c3d4349" alt="CI status"&gt;&lt;/a&gt;
  &lt;a rel="noopener noreferrer nofollow" href="https://camo.githubusercontent.com/918b76217f10c09e0243746e0b26a0673e283932ccad166a7a2bc4b21f274338/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6d61634f532532302537432532304c696e757825323025374325323057696e646f77732d3161316131613f7374796c653d666f722d7468652d6261646765"&gt;&lt;img src="https://camo.githubusercontent.com/918b76217f10c09e0243746e0b26a0673e283932ccad166a7a2bc4b21f274338/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6d61634f532532302537432532304c696e757825323025374325323057696e646f77732d3161316131613f7374796c653d666f722d7468652d6261646765" alt="macOS, Linux, and Windows"&gt;&lt;/a&gt;
  &lt;a href="https://github.com/RielJ/kakemono/LICENSE" rel="noopener noreferrer"&gt;&lt;img src="https://camo.githubusercontent.com/fefa3b62e61a5143b4120a1efe8cf439c1562aa95a55bf64a4e2d8e4448876e9/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d3161316131613f7374796c653d666f722d7468652d6261646765" alt="MIT license"&gt;&lt;/a&gt;
&lt;/p&gt;

&lt;p&gt;
  &lt;strong&gt;A free wallpaper manager for macOS, Linux, and Windows.&lt;/strong&gt;&lt;br&gt;
  New wallpapers from Wallhaven, Unsplash, Reddit, Bing, NASA APOD, any web page, or your own folders
&lt;/p&gt;

&lt;p&gt;
  &lt;a href="https://kakemono.rielj.xyz" rel="nofollow noopener noreferrer"&gt;&lt;strong&gt;Documentation&lt;/strong&gt;&lt;/a&gt; ·
  &lt;a href="https://kakemono.rielj.xyz/install/" rel="nofollow noopener noreferrer"&gt;Install&lt;/a&gt; ·
  &lt;a href="https://kakemono.rielj.xyz/reference/configuration/" rel="nofollow noopener noreferrer"&gt;Configuration&lt;/a&gt; ·
  &lt;a href="https://github.com/RielJ/kakemono/CONTRIBUTING.md" rel="noopener noreferrer"&gt;Contributing&lt;/a&gt;
&lt;/p&gt;

&lt;p&gt;&lt;a rel="noopener noreferrer" href="https://github.com/RielJ/kakemono/docs/demo.gif"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fraw.githubusercontent.com%2FRielJ%2Fkakemono%2FHEAD%2Fdocs%2Fdemo.gif" alt="Demo: turn on a Wallhaven source in Settings, open the picker, and click a preview to set it as the wallpaper."&gt;&lt;/a&gt;&lt;/p&gt;




&lt;p&gt;kakemono changes your wallpaper when you ask, or on a timer. It keeps a history you can step back through, saves favorites, and can pick dark images in dark mode and light images in light mode.&lt;/p&gt;

&lt;p&gt;&lt;/p&gt;&lt;div class="table-wrapper-paragraph"&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;br&gt;&lt;table&gt;

&lt;thead&gt;

&lt;tr&gt;

&lt;/tr&gt;

&lt;/thead&gt;

&lt;tbody&gt;

&lt;tr&gt;

&lt;td&gt;&lt;strong&gt;Sources&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;Wallhaven, Unsplash, Reddit, Bing, NASA APOD, web pages and feeds, and your own folders. Paste a Wallhaven or Reddit search URL and kakemono uses its filters.&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;&lt;strong&gt;Picker&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;A strip of previews from the menu bar or a shortcut. Click one to set it.&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;&lt;strong&gt;History&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;Step back and forward through past wallpapers, favorite the good ones, trash the bad ones.&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;&lt;strong&gt;Scriptable&lt;/strong&gt;&lt;/td&gt;

&lt;td&gt;One binary is the daemon and the command-line tool. Hooks run on every change, and a local socket speaks JSON.&lt;/td&gt;

&lt;/tr&gt;

&lt;/tbody&gt;

&lt;/table&gt;&lt;/div&gt;&lt;p&gt;&lt;/p&gt;
&lt;div class="markdown-heading"&gt;…&lt;/div&gt;&lt;/div&gt;
&lt;br&gt;
  &lt;/div&gt;
&lt;br&gt;
  &lt;div class="gh-btn-container"&gt;&lt;a class="gh-btn" href="https://github.com/RielJ/kakemono" rel="noopener noreferrer"&gt;View on GitHub&lt;/a&gt;&lt;/div&gt;
&lt;br&gt;
&lt;/div&gt;
&lt;br&gt;





&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://rielj.xyz/blog/building-kakemono-cross-platform-wallpaper-manager" rel="noopener noreferrer"&gt;rielj.xyz&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>rust</category>
      <category>tauri</category>
      <category>opensource</category>
      <category>showdev</category>
    </item>
    <item>
      <title>Building Nyx: A Tailwind CSS Formatter &amp; Linter</title>
      <dc:creator>Riel Joseph</dc:creator>
      <pubDate>Wed, 11 Nov 2026 04:22:06 +0000</pubDate>
      <link>https://dev.to/rieljdev/building-nyx-a-tailwind-css-formatter-linter-emj</link>
      <guid>https://dev.to/rieljdev/building-nyx-a-tailwind-css-formatter-linter-emj</guid>
      <description>&lt;p&gt;&lt;strong&gt;TL;DR&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Nyx is a CLI that canonicalizes non-standard Tailwind CSS classes and sorts them using Tailwind's official ordering&lt;/li&gt;
&lt;li&gt;Powered by &lt;code&gt;@tailwindcss/oxide&lt;/code&gt; and &lt;code&gt;@tailwindcss/node&lt;/code&gt; internals — always in sync with your Tailwind version&lt;/li&gt;
&lt;li&gt;Supports 24+ file formats, smart caching, and shorthand collapsing (&lt;code&gt;mt-2 mr-2 mb-2 ml-2&lt;/code&gt; → &lt;code&gt;m-2&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;Install with &lt;code&gt;npm install -g @rielj/nyx&lt;/code&gt; and run &lt;code&gt;nyx check --fix src/&lt;/code&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Requirements:&lt;/strong&gt; Node.js 18+, Tailwind CSS v4&lt;/p&gt;




&lt;p&gt;If you've used Tailwind CSS for any non-trivial project, you've probably encountered a few annoyances:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Classes written in inconsistent order across files&lt;/li&gt;
&lt;li&gt;Arbitrary values like &lt;code&gt;h-[72px]&lt;/code&gt; when a standard utility &lt;code&gt;h-18&lt;/code&gt; exists&lt;/li&gt;
&lt;li&gt;Bracket syntax like &lt;code&gt;[display:_flex]&lt;/code&gt; when you could just write &lt;code&gt;flex&lt;/code&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;I built &lt;strong&gt;Nyx&lt;/strong&gt; to fix all of this — a CLI that canonicalizes non-standard class names and sorts them according to Tailwind's official ordering convention. It supports 24+ file formats and plugs directly into Tailwind v4's internals.&lt;/p&gt;

&lt;h2&gt;
  
  
  The Problem
&lt;/h2&gt;

&lt;p&gt;Tailwind CSS is incredibly flexible. You can express the same thing in multiple ways:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight css"&gt;&lt;code&gt;&lt;span class="cm"&gt;/* All equivalent */&lt;/span&gt;
&lt;span class="nt"&gt;h-&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;72px&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;         &lt;span class="cm"&gt;/* arbitrary value */&lt;/span&gt;
&lt;span class="nt"&gt;h-18&lt;/span&gt;             &lt;span class="cm"&gt;/* standard utility */&lt;/span&gt;

&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nt"&gt;display&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="nt"&gt;_flex&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;  &lt;span class="cm"&gt;/* arbitrary property */&lt;/span&gt;
&lt;span class="nt"&gt;flex&lt;/span&gt;             &lt;span class="cm"&gt;/* standard utility */&lt;/span&gt;

&lt;span class="nt"&gt;tw-bg-red-500&lt;/span&gt;   &lt;span class="cm"&gt;/* prefixed (non-standard) */&lt;/span&gt;
&lt;span class="nt"&gt;bg-red-500&lt;/span&gt;      &lt;span class="cm"&gt;/* standard */&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Across a team, this leads to inconsistent code. PR reviews devolve into "use the standard class" comments. And class order? Complete chaos.&lt;/p&gt;

&lt;p&gt;Existing tools like Prettier's Tailwind plugin handle sorting, but &lt;strong&gt;none&lt;/strong&gt; handle canonicalization — converting non-standard classes to their canonical form.&lt;/p&gt;

&lt;h2&gt;
  
  
  How Nyx Works
&lt;/h2&gt;

&lt;p&gt;The core pipeline is straightforward:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Input Files → Scanner → Design System → Diagnostics → Reporter → Fixer
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  1. Scanning
&lt;/h3&gt;

&lt;p&gt;Nyx uses &lt;code&gt;@tailwindcss/oxide&lt;/code&gt;'s &lt;code&gt;Scanner&lt;/code&gt; to extract class candidates with precise byte positions from source files. This is the same scanner Tailwind uses internally, so it handles every syntax variation out of the box.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;Scanner&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@tailwindcss/oxide"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;scanner&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Scanner&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;detectSources&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;base&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;candidates&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;scanner&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getCandidatesWithPositions&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;content&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;extension&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The scanner returns each class candidate with its exact offset in the file, which we convert to line/column numbers for diagnostic reporting.&lt;/p&gt;

&lt;h3&gt;
  
  
  2. Canonicalization
&lt;/h3&gt;

&lt;p&gt;This is the part that makes Nyx different. We load Tailwind's design system using &lt;code&gt;@tailwindcss/node&lt;/code&gt; and call &lt;code&gt;canonicalizeCandidates()&lt;/code&gt; — an internal API that resolves any class to its canonical form:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;__unstable__loadDesignSystem&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@tailwindcss/node"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;designSystem&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;__unstable__loadDesignSystem&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;css&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;base&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// Returns the canonical version if one exists&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;canonical&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;designSystem&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;candidateParser&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;canonicalizeCandidates&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;candidate&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;remValue&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;config&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;rem&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;When the canonical form differs from what was written, Nyx generates a diagnostic:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;src/components/Button.tsx:12:5
  ✗ h-[72px] is not canonical
  → Use h-18 instead
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  3. Sorting
&lt;/h3&gt;

&lt;p&gt;For class sorting, Nyx extracts &lt;code&gt;class&lt;/code&gt; and &lt;code&gt;className&lt;/code&gt; attributes from the source, then sorts using one of two strategies:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Tailwind strategy&lt;/strong&gt; (default) — uses the design system's &lt;code&gt;getClassOrder()&lt;/code&gt; which returns &lt;code&gt;bigint&lt;/code&gt; ordering values matching Tailwind's official convention:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;tailwindSort&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;classes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;designSystem&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;DesignSystem&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;designSystem&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getClassOrder&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;known&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;bigint&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="kt"&gt;unknown&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;cls&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="n"&gt;classes&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;match&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;find&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;c&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;c&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="n"&gt;cls&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;match&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="n"&gt;known&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;match&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;unknown&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;cls&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="n"&gt;known&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sort&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kt"&gt;unknown&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;known&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;cls&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;cls&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Alphabetical strategy&lt;/strong&gt; — simple &lt;code&gt;localeCompare()&lt;/code&gt; sorting. Deterministic and easy to reason about.&lt;/p&gt;

&lt;p&gt;Unknown classes (custom utilities not in the design system) are preserved at the start of the list.&lt;/p&gt;

&lt;h3&gt;
  
  
  4. Smart Caching
&lt;/h3&gt;

&lt;p&gt;For large codebases, Nyx implements file-level caching stored at &lt;code&gt;node_modules/.cache/nyx/cache.json&lt;/code&gt;. Each entry tracks:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;File mtime and size&lt;/li&gt;
&lt;li&gt;A SHA256 hash of the config + CSS content&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If nothing changed, the file is skipped entirely. Cache auto-invalidates when you update your Tailwind config, change your CSS entry point, or upgrade Nyx.&lt;/p&gt;

&lt;h2&gt;
  
  
  File Format Support
&lt;/h2&gt;

&lt;p&gt;One thing I wanted to get right was broad file format support. Nyx works with:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Category&lt;/th&gt;
&lt;th&gt;Formats&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Web&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;.html&lt;/code&gt;, &lt;code&gt;.jsx&lt;/code&gt;, &lt;code&gt;.tsx&lt;/code&gt;, &lt;code&gt;.vue&lt;/code&gt;, &lt;code&gt;.svelte&lt;/code&gt;, &lt;code&gt;.astro&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Server Templates&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;.erb&lt;/code&gt;, &lt;code&gt;.ejs&lt;/code&gt;, &lt;code&gt;.hbs&lt;/code&gt;, &lt;code&gt;.php&lt;/code&gt;, &lt;code&gt;.blade.php&lt;/code&gt;, &lt;code&gt;.twig&lt;/code&gt;, &lt;code&gt;.njk&lt;/code&gt;, &lt;code&gt;.liquid&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Templating&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;.pug&lt;/code&gt;, &lt;code&gt;.slim&lt;/code&gt;, &lt;code&gt;.haml&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Documents&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;.mdx&lt;/code&gt;, &lt;code&gt;.md&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Other&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;.rs&lt;/code&gt;, &lt;code&gt;.ex&lt;/code&gt;, &lt;code&gt;.heex&lt;/code&gt;, &lt;code&gt;.clj&lt;/code&gt;, &lt;code&gt;.cljs&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;This is possible because &lt;code&gt;@tailwindcss/oxide&lt;/code&gt;'s scanner already handles class extraction across all these formats — Nyx just needs to pass the correct file extension.&lt;/p&gt;

&lt;h2&gt;
  
  
  Usage
&lt;/h2&gt;

&lt;p&gt;Install globally or as a dev dependency:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;npm install -g @rielj/nyx
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then run it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# Scaffold config&lt;/span&gt;
nyx init

&lt;span class="c"&gt;# Check for issues (lint + format)&lt;/span&gt;
nyx check src/

&lt;span class="c"&gt;# Auto-fix everything&lt;/span&gt;
nyx check --fix src/

&lt;span class="c"&gt;# Just lint (canonicalization only)&lt;/span&gt;
nyx lint src/

&lt;span class="c"&gt;# Just format (sorting only)&lt;/span&gt;
nyx format --fix src/
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Configuration lives in &lt;code&gt;nyx.config.json&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"$schema"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"./node_modules/@rielj/nyx/schema.json"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"css"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"src/styles/main.css"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"rem"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;16&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"strategy"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"tailwind"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"collapse"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"cache"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;--collapse&lt;/code&gt; flag is one of my favorites — it converts longhand utilities to shorthand:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;mt-2 mr-2 mb-2 ml-2  →  m-2
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Technical Decisions
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Why Tailwind v4 internals?&lt;/strong&gt; I could have reimplemented class parsing and ordering from scratch, but that would be fragile and immediately outdated whenever Tailwind ships new utilities. By using &lt;code&gt;@tailwindcss/oxide&lt;/code&gt; and &lt;code&gt;@tailwindcss/node&lt;/code&gt; directly, Nyx is always in sync with whatever Tailwind version you're running.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Why not a Prettier plugin?&lt;/strong&gt; Prettier plugins run inside Prettier's AST pipeline, which limits what you can do. Canonicalization requires resolving classes against the full Tailwind design system — something that doesn't fit naturally into a formatting pass. A standalone CLI gives more control and better error reporting.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Why citty for the CLI?&lt;/strong&gt; Lightweight, typed, and supports subcommands cleanly. No need for heavy frameworks like &lt;code&gt;commander&lt;/code&gt; or &lt;code&gt;yargs&lt;/code&gt; for a tool this focused.&lt;/p&gt;

&lt;h2&gt;
  
  
  What's Next
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;IDE integration&lt;/strong&gt; — VS Code extension with inline diagnostics&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Watch mode&lt;/strong&gt; — auto-fix on save&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Custom rules&lt;/strong&gt; — let users define their own canonical mappings&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Check it out on &lt;a href="https://github.com/rielj/nyx" rel="noopener noreferrer"&gt;GitHub&lt;/a&gt; and let me know what you think.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://rielj.xyz/blog/building-nyx-tailwind-css-formatter" rel="noopener noreferrer"&gt;rielj.xyz&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>tailwindcss</category>
      <category>tooling</category>
      <category>typescript</category>
      <category>opensource</category>
    </item>
    <item>
      <title>Building pi-git-worktrees: Parallel AI Agent Sessions with Git Worktrees</title>
      <dc:creator>Riel Joseph</dc:creator>
      <pubDate>Wed, 11 Nov 2026 04:21:39 +0000</pubDate>
      <link>https://dev.to/rieljdev/building-pi-git-worktrees-parallel-ai-agent-sessions-with-git-worktrees-28jp</link>
      <guid>https://dev.to/rieljdev/building-pi-git-worktrees-parallel-ai-agent-sessions-with-git-worktrees-28jp</guid>
      <description>&lt;p&gt;&lt;strong&gt;TL;DR&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;pi-git-worktrees is a Pi coding agent extension that spawns parallel AI agents, each in its own git worktree&lt;/li&gt;
&lt;li&gt;Uses tmux's hidden sessions and &lt;code&gt;display-popup&lt;/code&gt; for seamless viewing without leaving your terminal&lt;/li&gt;
&lt;li&gt;Full orchestration with fan-out / wait / gather pattern — dispatch work and collect results&lt;/li&gt;
&lt;li&gt;Live status widgets show real-time busy/idle state via heartbeat monitoring&lt;/li&gt;
&lt;li&gt;Install with &lt;code&gt;npm install -g pi-git-worktrees&lt;/code&gt;
&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fsiz6cur28u88o98dz0it.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fsiz6cur28u88o98dz0it.webp" alt="Main session orchestrating 4 worktree agents in parallel" width="800" height="520"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Main session orchestrating 4 worktree agents — sending dual reviews to all in parallel, with live status widget showing each agent's activity.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;If you've used &lt;a href="https://github.com/mariozechner/pi-coding-agent" rel="noopener noreferrer"&gt;Pi coding agent&lt;/a&gt; for any non-trivial project, you've probably wished you could have multiple agents working on different tasks simultaneously. Fix the auth bug in one session, add tests in another, update docs in a third — all without context-switching.&lt;/p&gt;

&lt;p&gt;I built &lt;strong&gt;pi-git-worktrees&lt;/strong&gt; to make this possible. It spawns multiple Pi agents, each running in its own isolated git worktree on a dedicated branch, all orchestrated from your main session.&lt;/p&gt;

&lt;h2&gt;
  
  
  The Problem
&lt;/h2&gt;

&lt;p&gt;Working with a single AI agent is inherently sequential. You ask it to fix a bug, wait for it to finish, then ask it to write tests, wait again, then update docs. Even when tasks are independent, you're bottlenecked on one conversation.&lt;/p&gt;

&lt;p&gt;The obvious solution is "just open multiple terminals," but that creates its own problems:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;No coordination — agents might conflict on the same files&lt;/li&gt;
&lt;li&gt;No visibility — you can't see what all agents are doing at a glance&lt;/li&gt;
&lt;li&gt;No orchestration — you can't dispatch work and collect results programmatically&lt;/li&gt;
&lt;li&gt;Git conflicts — multiple agents editing the same branch is a recipe for disaster&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Git worktrees solve the filesystem isolation problem elegantly. Each worktree is a separate checkout of your repo on its own branch. Combined with tmux for session management, you get true parallel agent execution.&lt;/p&gt;

&lt;h2&gt;
  
  
  Architecture
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fqur66a7mkg965jztxrrk.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fqur66a7mkg965jztxrrk.webp" alt="Floating tmux popup showing a worktree agent working autonomously" width="800" height="520"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Floating tmux popup showing a worktree agent running a dual code review, merging changes, and pushing — all autonomously.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;The extension manages everything through a hidden tmux session called &lt;code&gt;_pi-wt&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;┌─────────────────────────────────────────────┐
│  Main Pi Session                            │
│                                             │
│  ┌─ Widget ──────────────────────────────┐  │
│  │ ● main    ∴ fix-auth   ∴ add-tests   │  │
│  │  idle      running      running       │  │
│  └───────────────────────────────────────┘  │
│                                             │
│  Tools: wt_new, wt_send, wt_wait,           │
│         wt_gather, wt_context               │
└───────────┬─────────────┬───────────────────┘
            │ tmux        │ tmux
            │ send-keys   │ send-keys
            ▼             ▼
┌───────────────┐ ┌───────────────┐
│ _pi-wt:fix-auth│ │ _pi-wt:add-tests│
│ Pi agent      │ │ Pi agent      │
│ Own branch    │ │ Own branch    │
│ Own worktree  │ │ Own worktree  │
└───────────────┘ └───────────────┘
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Each worktree agent runs as a named window inside the hidden &lt;code&gt;_pi-wt&lt;/code&gt; tmux session. Your own tmux sessions are never touched.&lt;/p&gt;

&lt;h2&gt;
  
  
  How It Works
&lt;/h2&gt;

&lt;h3&gt;
  
  
  1. Spawning a Worktree
&lt;/h3&gt;

&lt;p&gt;When you create a worktree (via &lt;code&gt;wt_new&lt;/code&gt; tool or &lt;code&gt;/wt-new&lt;/code&gt; command), several things happen:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Git worktree creation&lt;/strong&gt; — &lt;code&gt;git worktree add&lt;/code&gt; creates an isolated checkout on a new branch&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Session seeding&lt;/strong&gt; — a Pi session file is created with the task as the first user message&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;tmux window spawn&lt;/strong&gt; — a new window is created in the hidden &lt;code&gt;_pi-wt&lt;/code&gt; session, running Pi inside it&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Registry update&lt;/strong&gt; — the worktree metadata is recorded in &lt;code&gt;.pi/wt-agents/registry.json&lt;/code&gt;
&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The slug generation strips stop words and creates a clean identifier:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="no"&gt;STOP_WORDS&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nb"&gt;Set&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;
  &lt;span class="s2"&gt;"a"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"an"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"the"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"to"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"in"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"on"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"at"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"of"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"for"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"and"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"or"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"is"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"it"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"be"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"do"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"with"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"this"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"that"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;slugFromTask&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;task&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;words&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;task&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toLowerCase&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;replace&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="o"&gt;^&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;z0&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mi"&gt;9&lt;/span&gt;\&lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;g&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;""&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;split&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;\&lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="o"&gt;+/&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;w&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;w&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="no"&gt;STOP_WORDS&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;has&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;w&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;words&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;slice&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;4&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"-"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="s2"&gt;"worktree"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  2. tmux Session Management
&lt;/h3&gt;

&lt;p&gt;The tmux layer is the core infrastructure. All worktree agents live as windows in a single pool session:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="no"&gt;POOL_SESSION&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"_pi-wt"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;ensurePoolSession&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="k"&gt;void&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nf"&gt;execFileSync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"tmux"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"has-session"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"-t"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="no"&gt;POOL_SESSION&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;stdio&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"ignore"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nf"&gt;execFileSync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"tmux"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
      &lt;span class="s2"&gt;"new-session"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"-d"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"-s"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="no"&gt;POOL_SESSION&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"-x"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"200"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"-y"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"50"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="c1"&gt;// Prevent auto-destroy when all windows close&lt;/span&gt;
    &lt;span class="nf"&gt;execFileSync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"tmux"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
      &lt;span class="s2"&gt;"set-option"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"-t"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="no"&gt;POOL_SESSION&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"destroy-unattached"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"off"&lt;/span&gt;
    &lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;stdio&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"ignore"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Viewing a worktree opens a floating popup via &lt;code&gt;tmux display-popup&lt;/code&gt;. This overlays your current pane without switching windows or sessions. Dismiss the popup and you're back to main — the worktree agent keeps running.&lt;/p&gt;

&lt;h3&gt;
  
  
  3. Heartbeat Monitoring
&lt;/h3&gt;

&lt;p&gt;Each worktree agent writes heartbeat files (JSON, updated every 2 seconds) to a shared directory. The main session polls these to detect busy/idle state:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;~/.pi-git-worktrees/
├── fix-auth.json     ← { "busy": true, "ts": 1714012345678 }
├── add-tests.json    ← { "busy": false, "ts": 1714012345680 }
└── ...
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This feeds the live status widget that renders above your input — horizontal boxes showing each worktree's current state.&lt;/p&gt;

&lt;h3&gt;
  
  
  4. The Orchestration Pattern
&lt;/h3&gt;

&lt;p&gt;The real power is in orchestration. The agent can use a fan-out / wait / gather pattern:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Fan-out&lt;/strong&gt; — dispatch independent tasks to worktrees:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;wt_new("fix auth bug",       branch: "fix/auth")
wt_new("add API tests",      branch: "feat/api-tests")
wt_new("update docs",        branch: "chore/docs-update")
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Wait&lt;/strong&gt; — poll heartbeats until all worktrees are idle:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;wt_wait()  →  checks every 3s until all agents finish
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Gather&lt;/strong&gt; — compile context from all worktrees into a single report:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;wt_gather()  →  extracts structured summaries from session files
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The main agent can then synthesize results, identify conflicts, and coordinate merges.&lt;/p&gt;

&lt;h3&gt;
  
  
  5. Communication
&lt;/h3&gt;

&lt;p&gt;Sending follow-up instructions to a running worktree uses &lt;code&gt;tmux send-keys&lt;/code&gt; to deliver text directly to the agent's input:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;sendKeysToSession&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;sessionName&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="k"&gt;void&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nf"&gt;execFileSync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"tmux"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
    &lt;span class="s2"&gt;"send-keys"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"-t"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="sb"&gt;`${POOL_SESSION}:${sessionName}`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"Enter"&lt;/span&gt;
  &lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This lets the main session redirect, refine, or add context to any running agent mid-task.&lt;/p&gt;

&lt;h2&gt;
  
  
  The Interactive Panel
&lt;/h2&gt;

&lt;p&gt;The &lt;code&gt;/worktrees&lt;/code&gt; command opens a full interactive panel with keyboard navigation:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;↑&lt;/code&gt;/&lt;code&gt;↓&lt;/code&gt; — navigate between worktrees&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;←&lt;/code&gt;/&lt;code&gt;→&lt;/code&gt; — switch tabs (Worktrees / Actions / Settings)&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;n&lt;/code&gt; — create new worktree&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;s&lt;/code&gt; — send message to selected worktree&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;m&lt;/code&gt; — merge worktree branch back&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;d&lt;/code&gt; — remove worktree&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;c&lt;/code&gt; — import context&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This is built using Pi's TUI component system, rendering directly in the terminal with full keyboard event handling.&lt;/p&gt;

&lt;h2&gt;
  
  
  Technical Decisions
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Why tmux hidden sessions?&lt;/strong&gt; I considered running agents as background processes, but tmux gives you free interactivity — you can view, interact with, and debug any agent by opening a popup. Background processes would need a custom TUI for I/O.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Why file-based heartbeats?&lt;/strong&gt; IPC via Unix sockets or named pipes would be more efficient, but file-based heartbeats are dead simple, work across process boundaries, and survive agent restarts. The 2-second polling interval is fast enough for human perception.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Why a single pool session?&lt;/strong&gt; Having one &lt;code&gt;_pi-wt&lt;/code&gt; session with named windows is cleaner than creating separate tmux sessions per worktree. It simplifies lifecycle management and makes &lt;code&gt;display-popup&lt;/code&gt; targeting straightforward.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Why registry.json?&lt;/strong&gt; Git worktrees are stateless from Pi's perspective — we need metadata like task descriptions, branch names, creation times, and session file paths. A simple JSON registry in &lt;code&gt;.pi/wt-agents/&lt;/code&gt; tracks this without external dependencies.&lt;/p&gt;

&lt;h2&gt;
  
  
  What's Next
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Worktree profiles&lt;/strong&gt; — automatically detect project type and configure agents accordingly&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Conflict detection&lt;/strong&gt; — warn when two worktrees modify the same files&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Auto-merge strategies&lt;/strong&gt; — smart merge ordering based on dependency analysis&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Resource limits&lt;/strong&gt; — cap concurrent worktrees based on system resources&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Check it out on &lt;a href="https://github.com/rielj/pi-git-worktrees" rel="noopener noreferrer"&gt;GitHub&lt;/a&gt; and let me know what you think. Install with:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;npm install -g pi-git-worktrees
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;






&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://rielj.xyz/blog/building-pi-git-worktrees-parallel-ai-agents" rel="noopener noreferrer"&gt;rielj.xyz&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>typescript</category>
      <category>aiagents</category>
      <category>tmux</category>
      <category>git</category>
    </item>
    <item>
      <title>Building pi-image-preview: Inline Image Previews with Kitty Graphics in tmux</title>
      <dc:creator>Riel Joseph</dc:creator>
      <pubDate>Wed, 11 Nov 2026 04:21:27 +0000</pubDate>
      <link>https://dev.to/rieljdev/building-pi-image-preview-inline-image-previews-with-kitty-graphics-in-tmux-a27</link>
      <guid>https://dev.to/rieljdev/building-pi-image-preview-inline-image-previews-with-kitty-graphics-in-tmux-a27</guid>
      <description>&lt;p&gt;&lt;strong&gt;TL;DR&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;pi-image-preview renders inline image thumbnails above the editor in Pi coding agent&lt;/li&gt;
&lt;li&gt;Uses the kitty graphics protocol with Unicode placeholders (&lt;code&gt;U=1&lt;/code&gt;) for pane-aware rendering&lt;/li&gt;
&lt;li&gt;Full tmux support — images appear/disappear correctly when switching panes&lt;/li&gt;
&lt;li&gt;Paste an image with &lt;code&gt;Ctrl+V&lt;/code&gt;, see a preview, submit and it's attached to your message&lt;/li&gt;
&lt;li&gt;Install with &lt;code&gt;pi install npm:pi-image-preview&lt;/code&gt;
&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F35tj7bsht8abqp6r49im.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F35tj7bsht8abqp6r49im.webp" alt="pi-image-preview rendering inline image thumbnails above the editor" width="800" height="498"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Inline image preview rendered above the Pi editor using the kitty graphics protocol inside tmux.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Terminal-based coding agents are powerful, but they have a blind spot: images. When you're working with screenshots, UI mockups, or debugging visual output, pasting an image path and hoping the AI understands is suboptimal. You want to &lt;em&gt;see&lt;/em&gt; the image right there in your terminal.&lt;/p&gt;

&lt;p&gt;I built &lt;strong&gt;pi-image-preview&lt;/strong&gt; to solve this for &lt;a href="https://github.com/mariozechner/pi-coding-agent" rel="noopener noreferrer"&gt;Pi coding agent&lt;/a&gt;. It renders inline image thumbnails above the editor using the kitty graphics protocol — and it works inside tmux, which is where the real engineering challenge was.&lt;/p&gt;

&lt;h2&gt;
  
  
  The Problem
&lt;/h2&gt;

&lt;p&gt;Terminal image rendering sounds simple until you try it inside tmux. The standard kitty graphics protocol renders pixels at absolute terminal positions. This means:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;An image rendered in pane 1 is still visible when you switch to pane 2 ("ghosting")&lt;/li&gt;
&lt;li&gt;Scrolling doesn't move the image — it stays at its absolute position&lt;/li&gt;
&lt;li&gt;tmux has no knowledge of the rendered pixels — they exist outside its text buffer&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;For a coding agent where you're constantly switching context, this is unusable.&lt;/p&gt;

&lt;h2&gt;
  
  
  The Unicode Placeholder Protocol
&lt;/h2&gt;

&lt;p&gt;Kitty's answer to this is the &lt;strong&gt;Unicode placeholder protocol&lt;/strong&gt; (&lt;code&gt;U=1&lt;/code&gt;). Instead of rendering pixels directly, it works in two steps:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Transmit&lt;/strong&gt; the image data with the &lt;code&gt;U=1&lt;/code&gt; flag — kitty stores the image but doesn't render it&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Output Unicode characters&lt;/strong&gt; (&lt;code&gt;U+10EEEE&lt;/code&gt; with combining diacritics) where the image should appear&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;These characters are regular text from tmux's perspective. They live in the text buffer. When you switch panes, tmux swaps the buffer — placeholders disappear — image disappears. Switch back — placeholders redrawn — image reappears. No ghosting.&lt;/p&gt;

&lt;p&gt;Here's how the extension detects whether to use this protocol:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;detectImageProtocol&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;ImageProtocol&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;caps&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;getCapabilities&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;caps&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;images&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;caps&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;images&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="c1"&gt;// pi-tui returns null inside tmux — check if the outer terminal is kitty&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;inTmux&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="o"&gt;!!&lt;/span&gt;&lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;TMUX&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt;
    &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;TERM&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toLowerCase&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="s2"&gt;""&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;startsWith&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"tmux"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;inTmux&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;KITTY_WINDOW_ID&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt;
        &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;TERM_PROGRAM&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toLowerCase&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="s2"&gt;""&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s2"&gt;"kitty"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="s2"&gt;"kitty"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="c1"&gt;// ghostty and wezterm also support kitty graphics in tmux&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;termProgram&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;TERM_PROGRAM&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toLowerCase&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="s2"&gt;""&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;termProgram&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s2"&gt;"ghostty"&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;GHOSTTY_RESOURCES_DIR&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
      &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="s2"&gt;"kitty"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;termProgram&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s2"&gt;"wezterm"&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;WEZTERM_PANE&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
      &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="s2"&gt;"kitty"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This was necessary because &lt;code&gt;pi-tui&lt;/code&gt; (Pi's terminal UI library) conservatively returns &lt;code&gt;images: null&lt;/code&gt; inside tmux. But since we specifically use the Unicode placeholder protocol which is designed for tmux, we can safely detect kitty-in-tmux ourselves.&lt;/p&gt;

&lt;h2&gt;
  
  
  Architecture
&lt;/h2&gt;

&lt;p&gt;The extension plugs into Pi's extension API and manages images through three components:&lt;/p&gt;

&lt;h3&gt;
  
  
  1. Image Detection &amp;amp; Polling
&lt;/h3&gt;

&lt;p&gt;A 250ms poll loop watches the editor text for image file paths:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="no"&gt;IMAGE_PATH_RE&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt;
  &lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;?:~&lt;/span&gt;\&lt;span class="o"&gt;/|&lt;/span&gt;\&lt;span class="p"&gt;.&lt;/span&gt;\&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;\&lt;span class="o"&gt;/|&lt;/span&gt;\&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="o"&gt;^&lt;/span&gt;\&lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="o"&gt;*?&lt;/span&gt;&lt;span class="s2"&gt;"&amp;lt;&amp;gt;|][^\s:*?"&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&amp;gt;|&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="o"&gt;*&lt;/span&gt;\&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;?:&lt;/span&gt;&lt;span class="n"&gt;png&lt;/span&gt;&lt;span class="o"&gt;|&lt;/span&gt;&lt;span class="n"&gt;jpe&lt;/span&gt;&lt;span class="o"&gt;?&lt;/span&gt;&lt;span class="n"&gt;g&lt;/span&gt;&lt;span class="o"&gt;|&lt;/span&gt;&lt;span class="n"&gt;gif&lt;/span&gt;&lt;span class="o"&gt;|&lt;/span&gt;&lt;span class="n"&gt;webp&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;?=&lt;/span&gt;\&lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="o"&gt;|&lt;/span&gt;$&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;gi&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;When you paste an image with &lt;code&gt;Ctrl+V&lt;/code&gt;, Pi saves the clipboard to a temp file and inserts the path into the editor. The extension detects the path, reads the file, and triggers a preview render.&lt;/p&gt;

&lt;h3&gt;
  
  
  2. Image Content Pipeline
&lt;/h3&gt;

&lt;p&gt;Reading and resizing images is handled asynchronously to keep the UI responsive:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;readImageContentFromPathAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;filePath&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;ImageContent&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;looksLikeImagePathAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;filePath&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;stat&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;fsp&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;stat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;filePath&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;stat&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;size&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="no"&gt;MAX_IMAGE_FILE_SIZE&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// 50MB limit&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;mimeType&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;inferMimeType&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;filePath&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;bytes&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;fsp&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;readFile&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;filePath&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"image"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;bytes&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toString&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"base64"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;mimeType&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The extension leverages Pi's built-in WASM image resizer for efficient thumbnailing. It dynamically loads the resizer from Pi's distribution:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;loadPiImageResizer&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;ImageResizer&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nb"&gt;require&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;createRequire&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;import&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;meta&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;url&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;piEntry&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;require&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;resolve&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"@mariozechner/pi-coding-agent"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;distDir&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;path&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;dirname&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;piEntry&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;moduleUrl&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;pathToFileURL&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="n"&gt;path&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;distDir&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"utils"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"image-resize.js"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;href&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;mod&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="k"&gt;import&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;moduleUrl&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;mod&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;resizeImage&lt;/span&gt; &lt;span class="o"&gt;?&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;image&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;resized&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;mod&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;resizeImage&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;image&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"image"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;resized&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;mimeType&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;resized&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;mimeType&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  3. The Gallery Renderer
&lt;/h3&gt;

&lt;p&gt;Multiple images display side-by-side in a horizontal layout. The gallery calculates dimensions and renders using Pi's widget system:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="no"&gt;THUMB_MAX_WIDTH&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;25&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;  &lt;span class="c1"&gt;// columns&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="no"&gt;THUMB_MAX_ROWS&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;15&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;   &lt;span class="c1"&gt;// cap height&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="no"&gt;GAP&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;               &lt;span class="c1"&gt;// columns between images&lt;/span&gt;

&lt;span class="c1"&gt;// Monotonic counter for kitty image IDs&lt;/span&gt;
&lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="n"&gt;nextImageId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;allocateImageId&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;number&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;nextImageId&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;nextImageId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;nextImageId&lt;/span&gt; &lt;span class="o"&gt;%&lt;/span&gt; &lt;span class="mh"&gt;0xffffff&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// wrap at 16M, skip 0&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Image IDs use a monotonic counter instead of random values. Early versions used &lt;code&gt;Math.random() * 254&lt;/code&gt;, which caused birthday-paradox collisions — two images occasionally getting the same ID, corrupting the display. The monotonic counter with the full 24-bit kitty range (1–16,777,215) eliminates this.&lt;/p&gt;

&lt;h2&gt;
  
  
  The Input Transform
&lt;/h2&gt;

&lt;p&gt;When you submit a message, the extension intercepts the input event and transforms it:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Strip image paths&lt;/strong&gt; from the text (the user doesn't want raw paths in their message)&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Attach images&lt;/strong&gt; as content blocks to the message&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Clear the preview widget&lt;/strong&gt;&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;This is done via Pi's &lt;code&gt;input&lt;/code&gt; event transform API:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nc"&gt;InputResult&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt;
  &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;action&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"continue"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;   &lt;span class="c1"&gt;// pass through unchanged&lt;/span&gt;
  &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;action&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"handled"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;    &lt;span class="c1"&gt;// consumed, don't send&lt;/span&gt;
  &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;action&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"transform"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="n"&gt;images&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;ImageContent&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The transform strips the file paths and returns the cleaned text with images attached — so the AI model receives both the text and the actual image data.&lt;/p&gt;

&lt;h2&gt;
  
  
  Screenshot Integration
&lt;/h2&gt;

&lt;p&gt;The extension also upgrades tool results from Pi's screenshot tool. When an agent takes a screenshot, the result normally contains just an image content block. The extension hooks into the &lt;code&gt;tool_result&lt;/code&gt; event and adds an inline preview, so you see the screenshot rendered in the terminal immediately.&lt;/p&gt;

&lt;h2&gt;
  
  
  Technical Decisions
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Why kitty graphics over iTerm2/Sixel?&lt;/strong&gt; Kitty's Unicode placeholder protocol is the only one that works correctly inside tmux. iTerm2's inline images and Sixel both render at absolute positions and ghost across panes. The tradeoff is terminal compatibility — kitty, ghostty, and wezterm only.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Why poll at 250ms instead of watching file events?&lt;/strong&gt; The editor text changes come from Pi's internal state, not the filesystem. File watchers (&lt;code&gt;fs.watch&lt;/code&gt;) wouldn't catch clipboard pastes that go through Pi's editor. Polling the editor text is the reliable approach, and 250ms is imperceptible.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Why dynamic WASM resizer loading?&lt;/strong&gt; Bundling an image resizer would bloat the extension. Pi already ships with a WASM-based resizer for its own image handling. Dynamically loading it via &lt;code&gt;createRequire&lt;/code&gt; means zero additional dependencies while getting efficient native-speed resizing.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Why &lt;code&gt;U+10EEEE&lt;/code&gt; specifically?&lt;/strong&gt; This is kitty's designated Unicode placeholder codepoint. It lives in a Private Use Area (Supplementary PUA-B) so it never conflicts with real text. Combined with combining diacritical marks that encode the image ID and position, each cell "knows" which piece of which image it represents.&lt;/p&gt;

&lt;h2&gt;
  
  
  Limitations
&lt;/h2&gt;

&lt;p&gt;A few honest limitations worth noting:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Kitty-family terminals only&lt;/strong&gt; — no support for iTerm2, Alacritty, or vanilla Terminal.app&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Fixed thumbnail size&lt;/strong&gt; — 25 columns wide, not yet configurable&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;GIF animation&lt;/strong&gt; — only the first frame renders&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;SSH sessions&lt;/strong&gt; — kitty graphics don't survive SSH unless you use &lt;code&gt;kitten ssh&lt;/code&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  What's Next
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Configurable thumbnail sizes&lt;/strong&gt; — let users set max width/height&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Image selection/navigation&lt;/strong&gt; — click or keyboard-navigate between multiple images&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;GIF animation support&lt;/strong&gt; — render animated GIFs frame-by-frame&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Sixel fallback&lt;/strong&gt; — for terminals that support Sixel but not kitty graphics&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Check it out on &lt;a href="https://github.com/rielj/pi-image-preview" rel="noopener noreferrer"&gt;GitHub&lt;/a&gt; and install with:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;pi install npm:pi-image-preview
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;






&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://rielj.xyz/blog/building-pi-image-preview-kitty-graphics-in-tmux" rel="noopener noreferrer"&gt;rielj.xyz&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>typescript</category>
      <category>terminal</category>
      <category>kitty</category>
      <category>tmux</category>
    </item>
    <item>
      <title>Building profile-rag: A Chatbot About My Work That Cites Its Sources</title>
      <dc:creator>Riel Joseph</dc:creator>
      <pubDate>Wed, 11 Nov 2026 04:21:11 +0000</pubDate>
      <link>https://dev.to/rieljdev/building-profile-rag-a-chatbot-about-my-work-that-cites-its-sources-410j</link>
      <guid>https://dev.to/rieljdev/building-profile-rag-a-chatbot-about-my-work-that-cites-its-sources-410j</guid>
      <description>&lt;p&gt;&lt;strong&gt;TL;DR&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;profile-rag answers questions about my work from sources I reviewed and approved: my resume, project READMEs, blog posts, and GitHub contributions&lt;/li&gt;
&lt;li&gt;Every answer links to the excerpts it used. If the sources don't cover a question, it says so instead of guessing&lt;/li&gt;
&lt;li&gt;It's built on RAG (retrieval-augmented generation). The section below explains RAG with diagrams, no machine-learning background needed&lt;/li&gt;
&lt;li&gt;It caught a misleading line in my own resume&lt;/li&gt;
&lt;li&gt;The code is public: &lt;a href="https://github.com/rielj/profile-rag" rel="noopener noreferrer"&gt;github.com/rielj/profile-rag&lt;/a&gt;
&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fznqp6nmo63bx9yhwm1wo.gif" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fznqp6nmo63bx9yhwm1wo.gif" alt="A question about my Docker work at Cashflowy" width="760" height="578"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;A question about my Docker work at Cashflowy. The answer streams in as the model writes it, then the cited excerpts appear below.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;A chatbot that answers questions about you sounds simple: give a language model your resume and let people ask. The trouble is that a language model will answer anyway, whether or not it knows. Ask about a project it hasn't seen and it fills the gap with something plausible. For a page that speaks for me, a plausible guess is worse than no answer.&lt;/p&gt;

&lt;p&gt;So I set three rules before writing any code:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Answer only from documents I have read and approved.&lt;/li&gt;
&lt;li&gt;Show the excerpts behind every answer, so a reader can check them.&lt;/li&gt;
&lt;li&gt;When the documents don't cover a question, say so.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  How RAG works, in plain terms
&lt;/h2&gt;

&lt;p&gt;RAG stands for &lt;em&gt;retrieval-augmented generation&lt;/em&gt;. The name describes the three steps: &lt;strong&gt;retrieve&lt;/strong&gt; relevant text, &lt;strong&gt;augment&lt;/strong&gt; the question with it, then &lt;strong&gt;generate&lt;/strong&gt; an answer. Think of the difference between a closed-book and an open-book exam.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fopb810w61mb6cjakx0c0.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fopb810w61mb6cjakx0c0.jpg" alt="A plain chatbot answers from memory, like a closed-book exam" width="800" height="467"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;A plain chatbot answers from memory, like a closed-book exam. RAG looks the answer up first and shows where it found it, like an open-book exam.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;A plain chatbot sits a closed-book exam. It answers from whatever it absorbed in training, which doesn't include my resume. A RAG app sits an open-book exam: before answering, it looks up the relevant pages and hands them to the model with the question. The model then writes its answer from those pages, and the app can show you which pages it used.&lt;/p&gt;

&lt;p&gt;That leaves two problems: building the library, and finding the right pages in it quickly.&lt;/p&gt;

&lt;h3&gt;
  
  
  Step 1: Build the library
&lt;/h3&gt;

&lt;p&gt;Before anyone asks a question, the documents are prepared once.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fg4bll98hzr8l5u9rdov1.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fg4bll98hzr8l5u9rdov1.jpg" alt="Building the library happens once, before anyone asks anything" width="800" height="245"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Building the library happens once, before anyone asks anything. Only sources that pass review get in. Edit an approved file and its approval goes stale, so indexing stops until it's reviewed again.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;The &lt;strong&gt;review&lt;/strong&gt; step is the one I care most about. Each source gets copied into the project and I read it in a terminal session: it highlights anything that looks like an email address, phone number, secret, or internal hostname, then asks five privacy questions. Only a source that gets "yes" to all five can be approved. The approval records a fingerprint of the file (its SHA-256 hash). If I edit the file later, the fingerprint no longer matches, and indexing refuses to run until I review it again. Nothing reaches the library without passing through me.&lt;/p&gt;

&lt;p&gt;Approved documents are then &lt;strong&gt;split&lt;/strong&gt; into chunks, small passages of a few paragraphs each. A chunk is cut at a heading and keeps its full heading path, such as "Cashflowy › What Riel worked on › Docker builds and deployment". Headings often name the company or project that the paragraph below never repeats, so keeping them makes the chunk findable.&lt;/p&gt;

&lt;h3&gt;
  
  
  Step 2: Turn meaning into numbers
&lt;/h3&gt;

&lt;p&gt;Computers can't compare meanings directly, but they can compare numbers. An &lt;strong&gt;embedding model&lt;/strong&gt; reads a chunk and produces a list of 768 numbers that describe what it's about. Chunks about similar things get similar numbers. I run the embedding model (&lt;code&gt;nomic-embed-text&lt;/code&gt;) locally with Ollama, so my documents don't leave my machine for this step.&lt;/p&gt;

&lt;p&gt;You can picture those numbers as coordinates on a map:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fb9jq21kdxwfwqhvk5axk.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fb9jq21kdxwfwqhvk5axk.jpg" alt="Embedding places every chunk on a map where similar meanings sit close together" width="800" height="372"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Embedding places every chunk on a map where similar meanings sit close together. The real map has 768 directions, not 2. A question is placed on the same map, and the search returns the chunks nearest to it, even if they use different words.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;A question gets turned into numbers the same way and dropped onto the same map. The chunks closest to it are the ones most likely to answer it. That's why this kind of search finds "pip to uv migration" when you ask about "faster Docker builds": the words differ, but the meaning is close.&lt;/p&gt;

&lt;h3&gt;
  
  
  Step 3: Search two ways, then merge
&lt;/h3&gt;

&lt;p&gt;Meaning search has a weak spot: exact names. A question about "pgvector" or "PR #1158" is best served by plain keyword matching. So the app runs both searches and merges the results.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ftqnlmwwhqi4s6j5bmwpj.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ftqnlmwwhqi4s6j5bmwpj.jpg" alt="Two searches run side by side, then their rankings are merged" width="800" height="528"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Two searches run side by side, then their rankings are merged. A chunk earns 1 ÷ (60 + its place in a list, counting from 0) from each list it appears in. Chunks that both searches like rise to the top. The lists are an illustration; the scores are the real formula.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;The merge is called &lt;em&gt;reciprocal rank fusion&lt;/em&gt;. It ignores the raw scores of the two searches, which aren't comparable, and uses only each chunk's position in each list. A chunk near the top of both lists beats a chunk at the top of only one. On my labeled test questions this hybrid search put the first relevant chunk higher than meaning search alone: its MRR (a score for how high the first right answer ranks) went from 0.512 to 0.611.&lt;/p&gt;

&lt;p&gt;The top 8 chunks go to the model.&lt;/p&gt;

&lt;h3&gt;
  
  
  Step 4: Answer, or say so
&lt;/h3&gt;

&lt;p&gt;The model gets the question, the 8 excerpts, and a short set of rules. Then the app checks what it wrote.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fk1cl6sg7oghbeg6z78iq.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fk1cl6sg7oghbeg6z78iq.jpg" alt="The model's reply has to pass every check before you see it as an answer" width="800" height="359"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The model's reply has to pass every check before you see it as an answer. While it's being written, the page shows the text as a draft without citation links. The checks run once the reply is complete.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Each excerpt is labeled with whose words it is. My resume is a &lt;em&gt;self-report&lt;/em&gt;, a project README describes a &lt;em&gt;project&lt;/em&gt;, and a recommendation would be a &lt;em&gt;third party&lt;/em&gt;. The model has to keep those apart, so answers read "According to Riel's resume, …" rather than turning a project's feature list into a claim about what I personally built. The rules also tell it that text inside an excerpt is data, not instructions, so a document can't take over the prompt.&lt;/p&gt;

&lt;p&gt;The reply must be a structured object: either &lt;code&gt;answered&lt;/code&gt; with the answer and the IDs of the excerpts it cites, or &lt;code&gt;unknown&lt;/code&gt; with a reason. A reply in any other shape is thrown away. So is a reply that cites an excerpt it was never given, because a made-up citation is a made-up answer.&lt;/p&gt;

&lt;p&gt;Here's what a passing answer looks like. The numbers in brackets link to the excerpts listed below the answer:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fwo5rkjyn5ztmk5vtsn5k.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fwo5rkjyn5ztmk5vtsn5k.jpg" alt="An answer about Cashflowy Docker builds, with three cited sources listed under it" width="800" height="1259"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;And here's a question the sources don't cover:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F0ymwxxzha79mqk7u10vs.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F0ymwxxzha79mqk7u10vs.jpg" alt="The app replying &amp;quot;Not in the evidence&amp;quot; to a question about my favorite pizza topping" width="799" height="258"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  What it's built with
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Part&lt;/th&gt;
&lt;th&gt;Tools&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Library&lt;/td&gt;
&lt;td&gt;Postgres with pgvector, for both the embeddings and the keyword index&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Embeddings&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;nomic-embed-text&lt;/code&gt; v1.5 through Ollama, on my machine&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Answer chain&lt;/td&gt;
&lt;td&gt;LangChain, with Pydantic models for the reply format&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Model calls&lt;/td&gt;
&lt;td&gt;
&lt;a href="https://github.com/mariozechner/pi-coding-agent" rel="noopener noreferrer"&gt;Pi coding agent&lt;/a&gt;, started fresh for each question with no tools, no session file, and no project settings&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;API&lt;/td&gt;
&lt;td&gt;FastAPI, with typed responses that the frontend's types are generated from&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Page&lt;/td&gt;
&lt;td&gt;React and TypeScript on Vite&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Tests&lt;/td&gt;
&lt;td&gt;pytest, Vitest, and Playwright, using a fake model and fake embeddings so they run without either&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Running each question in a fresh Pi process with everything switched off is deliberate. The model sees the question and the excerpts and nothing else, and no copy of the conversation is saved to disk.&lt;/p&gt;

&lt;h2&gt;
  
  
  Measuring instead of guessing
&lt;/h2&gt;

&lt;p&gt;It's easy to make a RAG app look good on a demo question. To know whether it actually finds the right passages, I wrote a set of test questions over my real sources and labeled which passages answer each one: 34 answerable questions plus 5 that the sources can't answer. The app's &lt;code&gt;eval&lt;/code&gt; command runs every question and scores the search.&lt;/p&gt;

&lt;p&gt;That's how I picked the search method. Meaning search and hybrid search found the same share of the labeled passages: on average, 78% of the passages that answer a question were in its top 8 (recall@8 of 0.779). Hybrid ranked the first right passage higher, so it became the default. A third method, MMR, which trades relevance for variety, scored lower on both and stayed off.&lt;/p&gt;

&lt;p&gt;The same approach settled a bigger question. I also built an "agent" version with LangGraph: it asks the model to grade the retrieved excerpts and, if they look weak, rewrites the question and searches again. It sounds smarter, so I measured it. On the 14 questions of the fictional example profile, the agent answered exactly the same questions as the plain pipeline, but made 36 model calls instead of 14. Its rewrites never changed an outcome. The plain pipeline stays the default, and the agent stays in the code, with a written note to test it again on the larger set of questions about my real sources.&lt;/p&gt;

&lt;h2&gt;
  
  
  Making it stream
&lt;/h2&gt;

&lt;p&gt;The first version showed nothing until the full answer was ready, which felt slow. Most chat apps show text as it's written, so I added that.&lt;/p&gt;

&lt;p&gt;There was one complication. The model doesn't write plain text; it writes a structured object like &lt;code&gt;{"status": "answered", "answer": "…", "citations": [...]}&lt;/code&gt;. Showing that raw would be ugly. So the server reads the half-finished object as it arrives, pulls out only the growing &lt;code&gt;answer&lt;/code&gt; text, and sends each new piece to the page as one line of JSON in a streamed response.&lt;/p&gt;

&lt;p&gt;The citation checks can only run on the complete reply. So while the text streams, the page labels it a draft ("Writing… Sources are checked when the answer is complete") and shows no citation links. When the reply is done and checked, the page swaps in the final answer with its sources. If the check fails, the draft disappears and the page shows the failure instead. You never get a checked-looking answer that wasn't checked.&lt;/p&gt;

&lt;h2&gt;
  
  
  The bug it found in my resume
&lt;/h2&gt;

&lt;p&gt;The most useful thing profile-rag did was tell me something about my own resume.&lt;/p&gt;

&lt;p&gt;I asked it how much faster I made the Docker builds at Cashflowy. It answered "about 2.5 seconds", citing my resume and my portfolio. Both said that, because I had rewritten the line a few days earlier. But the Cashflowy repository told a different story:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Moving the project from pip to uv cut Docker builds with no cache from &lt;strong&gt;about 28 minutes to about 2.5 minutes&lt;/strong&gt;. That's the real speedup.&lt;/li&gt;
&lt;li&gt;A later multi-stage Dockerfile cut the build context by 93% and the images by 29%, but didn't make builds faster.&lt;/li&gt;
&lt;li&gt;"2.5 seconds" was the time of a build that reuses cached layers. Nobody had measured that before the change, so it isn't an improvement at all.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The app had done its job: it reported what the sources said, and it showed me exactly which sources said it. The sources were wrong. I corrected the line on my resume and my portfolio, added the repository's measurements to my Cashflowy work notes, re-reviewed all three sources, and rebuilt the index. Now the same question gets the answer in the video above, citing three sources, and it explains why the 2.5-second figure doesn't count.&lt;/p&gt;

&lt;p&gt;A RAG app can't be more accurate than its library. Citations don't make the answers true, but they make every answer traceable to the line that produced it, and that's what let me find the mistake.&lt;/p&gt;

&lt;h2&gt;
  
  
  What's next
&lt;/h2&gt;

&lt;p&gt;profile-rag runs on one machine, for one owner. It has no login and no rate limit, so it isn't on the open internet yet. A public version needs a per-visitor rate limit and a spending cap on the model provider before anything else. Until then, the repository includes a fictional profile (Dana Whitlock) so anyone can run the whole app locally with &lt;code&gt;make demo&lt;/code&gt;, no private data needed.&lt;/p&gt;

&lt;p&gt;The code, the architecture notes, and the evaluation reports are on GitHub: &lt;a href="https://github.com/rielj/profile-rag" rel="noopener noreferrer"&gt;github.com/rielj/profile-rag&lt;/a&gt;.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://rielj.xyz/blog/building-profile-rag-cited-answers" rel="noopener noreferrer"&gt;rielj.xyz&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>rag</category>
      <category>ai</category>
      <category>python</category>
      <category>langchain</category>
    </item>
    <item>
      <title>Building QuickPOS: A Point of Sale for Small Food Businesses in the Philippines</title>
      <dc:creator>Riel Joseph</dc:creator>
      <pubDate>Wed, 11 Nov 2026 04:20:57 +0000</pubDate>
      <link>https://dev.to/rieljdev/building-quickpos-a-point-of-sale-for-small-food-businesses-in-the-philippines-4cog</link>
      <guid>https://dev.to/rieljdev/building-quickpos-a-point-of-sale-for-small-food-businesses-in-the-philippines-4cog</guid>
      <description>&lt;p&gt;&lt;strong&gt;TL;DR&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;QuickPOS is a point-of-sale system for small food businesses: a register, a kitchen display, cash shifts with PIN sign-in, sales history with voids and refunds, inventory, and daily reports&lt;/li&gt;
&lt;li&gt;It runs in the browser. The API is Hono and tRPC on Cloudflare Workers, the data is in Turso (SQLite), and the web app is a React SPA&lt;/li&gt;
&lt;li&gt;Checkout is safe to retry. If the connection drops halfway through a charge, trying again returns the first result instead of ringing up the sale twice&lt;/li&gt;
&lt;li&gt;Permissions, stock changes and optional features each have one shared definition that the web app and the API both use&lt;/li&gt;
&lt;li&gt;I'm preparing it for a pilot with one counter-service food merchant. The code is private, so this post shows it through screenshots, a demo and diagrams&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fig4jtoqrf6marw78lau9.gif" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fig4jtoqrf6marw78lau9.gif" alt="A cashier picks egg and add-on options for a Tapsilog, takes ₱500 cash and sees the change, and the order shows up on the kitchen display" width="720" height="450"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;A cashier picks egg and add-on options for a Tapsilog, takes ₱500 cash and sees the change, and the order shows up on the kitchen display. The store, staff and menu are made up for the demo.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Why I built it
&lt;/h2&gt;

&lt;p&gt;Small food stalls and counter-service shops in the Philippines often run on a notebook, a calculator and a cash box. The POS systems built for them are usually priced and designed for bigger restaurants, and many of them assume things that don't hold at a small counter: that prices exclude tax, that the Internet is always up, or that one person does everything.&lt;/p&gt;

&lt;p&gt;I wanted to build one that fits how these shops actually work, and to build it the way I'd build software I'm paid to maintain. That second goal shaped most of the decisions in this post.&lt;/p&gt;

&lt;h2&gt;
  
  
  What it does
&lt;/h2&gt;

&lt;p&gt;The core is the part a merchant uses every day:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Area&lt;/th&gt;
&lt;th&gt;What it covers&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Register&lt;/td&gt;
&lt;td&gt;Cart, add-ons and modifiers, cash and other payments, receipts&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Kitchen&lt;/td&gt;
&lt;td&gt;A display that shows each ticket from pending to ready&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Shifts&lt;/td&gt;
&lt;td&gt;Open with a PIN and a starting cash count, close and count the drawer&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Sales history&lt;/td&gt;
&lt;td&gt;Order list, voids and refunds&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Daily totals&lt;/td&gt;
&lt;td&gt;Sales summary, shift report, payment types&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Access&lt;/td&gt;
&lt;td&gt;Owner, admin and cashier roles, staff PINs&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Around that core are optional modules: tables, inventory and purchasing, customers and loyalty, time clock and payroll, advanced reports, and the audit log. Each one can be switched off, which matters more than it sounds. I'll come back to it.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Flev54ln2aiyaagr08nyr.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Flev54ln2aiyaagr08nyr.jpg" alt="The register with menu items on the left and a cart on the right, including a Tapsilog with &amp;quot;Sunny side up, Extra rice&amp;quot; and a total of ₱375.00" width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  How it's built
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fvdnw5gmjp4taci9gpyit.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fvdnw5gmjp4taci9gpyit.jpg" alt="One pnpm monorepo" width="799" height="361"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;One pnpm monorepo. The web app and the API both import the shared package, so a price rule, a permission or a module switch has one definition. The Rust coordinator is the start of offline mode and is paused until the pilot needs it.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;It's my third attempt at the stack. The first version used TanStack Start with Postgres, the second moved the data to Convex, and in April 2026 I rebuilt it as a plain React SPA talking to a Hono and tRPC API on Cloudflare Workers, with Turso for storage. The SPA and tRPC split was the one that stuck: the API types flow into the web app, the Zod schemas live in one shared package, and Workers plus Turso cost close to nothing while there's one merchant.&lt;/p&gt;

&lt;p&gt;The repository has about 975 unit and integration tests (Vitest) and 116 browser tests (Playwright) across the register, kitchen display, roles and module switches.&lt;/p&gt;

&lt;h2&gt;
  
  
  A charge must happen exactly once
&lt;/h2&gt;

&lt;p&gt;The scariest bug a POS can have is charging twice, or losing a sale the customer already paid for. Both come from the same moment: the cashier taps Charge, the network is slow, nothing seems to happen, and they tap again.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F9aufb08f37uqw2sm9l6d.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F9aufb08f37uqw2sm9l6d.jpg" alt="The register makes one key per charge and keeps it until the charge succeeds or the cashier dismisses it" width="800" height="359"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The register makes one key per charge and keeps it until the charge succeeds or the cashier dismisses it. A retry with the same key gets the stored answer back, so a slow network can't ring up a sale twice.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Every money-moving call (creating an order, completing it, and refunding it) goes through one wrapper, &lt;code&gt;withIdempotency&lt;/code&gt;. The register makes a key for the charge and reuses it on every retry. The server stores the response under that key the first time, and any repeat with the same key and the same cart gets the stored response back. A repeat with the same key and a &lt;em&gt;different&lt;/em&gt; cart is refused, because that's a bug, not a retry.&lt;/p&gt;

&lt;p&gt;Two smaller decisions back this up. The web app never retries a money mutation on its own; a retry is always the cashier pressing Retry in the checkout dialog. And the server checks whether an order is already finalized before completing it, which covers the rare case of two truly simultaneous requests.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F7jqnyjyx1xxc24zm84ww.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F7jqnyjyx1xxc24zm84ww.jpg" alt="The checkout dialog with ₱500.00 cash tendered, ₱125.00 change due, and a Charge ₱375.00 button" width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Whose drawer is this money in?
&lt;/h2&gt;

&lt;p&gt;At the end of a shift, the cashier counts the drawer and QuickPOS compares it with what it expected. That only means something if every sale lands in the right shift.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F2nlhmiqi9et2acaky2yt.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F2nlhmiqi9et2acaky2yt.jpg" alt="The client never says which shift a sale belongs to" width="800" height="475"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The client never says which shift a sale belongs to. The server works it out from the register and the device that activated it, so a browser that only knows a register id can't put money in someone else's drawer.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;The rule I settled on is that the client never names a shift. It sends the register and the device, and the server works out the open shift from those. A register is activated on one browser by an owner, so knowing a register's id isn't enough to put money in it.&lt;/p&gt;

&lt;p&gt;PINs get the care you'd give passwords, because a four-to-six-digit PIN is easy to guess. They're hashed with PBKDF2, failed attempts are rate-limited per store, and every attempt is logged. The rate limit lives in Workers KV rather than in memory: a Worker runs as many separate isolates, and an in-memory counter would let someone spread guesses across them.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fi3h3ggrfplgw4c3pa1e2.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fi3h3ggrfplgw4c3pa1e2.jpg" alt="The Close Shift dialog: ₱4,000.00 expected in the drawer, ₱3,980 counted, a −₱20.00 difference flagged for review, and a PIN pad" width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Paid and cooked are different things
&lt;/h2&gt;

&lt;p&gt;In a counter-service shop, customers usually pay first and wait for their food. My first version of orders had one status, so completing the payment also closed the order, and the ticket left the kitchen board before anyone had cooked it.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F4iedma8wbnj48525wnso.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F4iedma8wbnj48525wnso.jpg" alt="An order has two states that move on their own" width="799" height="311"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;An order has two states that move on their own. Before the split, paying for an order took it off the kitchen board, so a counter that takes payment first lost the ticket before anyone cooked it.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;The fix was to give the order two states that move on their own. The cashier moves payment; the kitchen moves fulfillment. The kitchen can only move a ticket forward, and only Cancel closes both, because cancelling also has to put the stock back. A migration closed the tickets for old paid orders so the kitchen board didn't fill up with history.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fi00wcsd18ug2k29d38yj.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fi00wcsd18ug2k29d38yj.jpg" alt="The kitchen display with paid tickets marked New, Preparing and Ready, one with the order note &amp;quot;No onions on the adobo&amp;quot;" width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  One rule, one place
&lt;/h2&gt;

&lt;p&gt;By late 2026 the code had grown to about 85,000 lines of TypeScript, and I ran an architecture review over it. It found three rules that were each written in several places, and all three had already caused bugs.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fadqvdk8g1967wrvn6i4w.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fadqvdk8g1967wrvn6i4w.jpg" alt="Three rules that used to be written more than once" width="799" height="404"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Three rules that used to be written more than once. Each one now lives in a single module that both sides call, and the old way of doing it is the thing the docs tell you not to do.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Permissions.&lt;/strong&gt; The web app decided what to show, and the API decided what to allow, each with its own checks. They disagreed: some screens showed buttons the API then refused, and some hid things the API would have allowed. Now there's one access policy in the shared package, with 25 named capabilities like &lt;code&gt;products.edit&lt;/code&gt; and &lt;code&gt;reports.export&lt;/code&gt;. The API enforces it and the web app reads the same rule. A misspelled capability is a type error.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Stock.&lt;/strong&gt; More than a dozen API routes wrote stock levels directly. Some skipped the movement history, so the history didn't add up to the stock. Products could exist with no stock row at all, and replacing a product's variants deleted the product's own stock. Now one module, the stock ledger, is the only code that writes stock, and it writes the new count and the reason for the change in the same transaction.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Optional features.&lt;/strong&gt; A pilot merchant should see only what they use, but switching a feature off used to mean finding its links, routes and API procedures by hand. Now each module has one switch in the shared package. Turning it off hides the menu entry, redirects its pages, and makes the API refuse the procedures it owns. Nothing is deleted, so turning it back on is a one-line change.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F36r3z32ot08halyds7ob.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F36r3z32ot08halyds7ob.jpg" alt="Editing a custom Inventory Clerk role, with permissions grouped by area such as Point of Sale, Orders and Products" width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Decisions for a Philippine pilot
&lt;/h2&gt;

&lt;p&gt;The module switches made the pilot scoping concrete. For a counter-service food merchant, I'm turning off tables, customers and loyalty, the time clock and payroll, and discounts for now. The kitchen display stays on.&lt;/p&gt;

&lt;p&gt;Tax is off too, and the reason is specific to the Philippines. QuickPOS's tax rates add tax on top of the price, but prices here are shown VAT-inclusive, and most small merchants aren't VAT-registered. Adding tax at the register would charge customers more than the menu says.&lt;/p&gt;

&lt;p&gt;I also wrote down the rules for while the pilot runs. New features are frozen, and only what blocks the merchant's day gets fixed. Correctness safeguards are never cut: accurate totals, authorization, duplicate-sale protection, and recovery from failed requests. And AI stays out of the checkout path, so a model outage can never stop a sale.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fwyfk29v7ykfec49ic6yl.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fwyfk29v7ykfec49ic6yl.jpg" alt="The orders list, where each order shows a payment status and a kitchen status, including one cancelled and one refunded order" width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  What about brownouts?
&lt;/h2&gt;

&lt;p&gt;Power and Internet outages are common enough here that a POS needs an answer for them. I've designed offline mode and built its core, but I've paused it until the pilot shows how much it's needed.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fk0o3ze9mqb3mx2kkzrgr.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fk0o3ze9mqb3mx2kkzrgr.jpg" alt="The offline design, for brownouts and outages of up to eight hours" width="800" height="383"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The offline design, for brownouts and outages of up to eight hours. The cashier device keeps the record, the kitchen display follows it over the store's own Wi-Fi or a phone hotspot, and the cloud catches up later. The core and its tests exist; the Android shell doesn't yet.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;The design has the cashier device act as the store's coordinator. It writes every sale to a local, signed, append-only event log before confirming it, and the kitchen display follows that log over the store's Wi-Fi or a phone hotspot. When the Internet comes back, the events sync to the cloud, and any conflict goes to a review list instead of overwriting data.&lt;/p&gt;

&lt;p&gt;The core is a Rust crate of about 2,600 lines with 65 tests. It covers the event log in SQLite, Ed25519 signatures, the kitchen board rebuilt from events, QR pairing, and a LAN transport with TLS pinned to the cashier's certificate. The same test vectors run in Rust and TypeScript, so both sides agree on what a signed event looks like. The scope is deliberately narrow: no official receipts, no loyalty redemption and no menu changes while offline, and GCash or Maya payments are recorded as checked by the cashier but not confirmed.&lt;/p&gt;

&lt;h2&gt;
  
  
  What's next
&lt;/h2&gt;

&lt;p&gt;The next step is the merchant visit. I'll watch how they work today and fill in the parts of the pilot plan I've left blank: which device they'll use, which modules they need, and what the first improvement should be. The goal is small on purpose: one merchant runs a normal day on QuickPOS, records sales, corrects mistakes, and reconciles the drawer at close.&lt;/p&gt;

&lt;p&gt;If you run a small food business in the Philippines and want to try it, or you just want to talk about POS software, &lt;a href="mailto:bulaybulay.rielj@gmail.com"&gt;send me a message&lt;/a&gt;.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://rielj.xyz/blog/building-quickpos-point-of-sale" rel="noopener noreferrer"&gt;rielj.xyz&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>typescript</category>
      <category>react</category>
      <category>cloudflare</category>
      <category>trpc</category>
    </item>
    <item>
      <title>Building Rolecraft: A Job-Application Assistant That Can't Invent Your Experience</title>
      <dc:creator>Riel Joseph</dc:creator>
      <pubDate>Wed, 11 Nov 2026 04:20:45 +0000</pubDate>
      <link>https://dev.to/rieljdev/building-rolecraft-a-job-application-assistant-that-cant-invent-your-experience-2b71</link>
      <guid>https://dev.to/rieljdev/building-rolecraft-a-job-application-assistant-that-cant-invent-your-experience-2b71</guid>
      <description>&lt;p&gt;&lt;strong&gt;TL;DR&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Rolecraft reads public job boards, tells me which jobs can actually hire someone in the Philippines, and ranks them against my experience&lt;/li&gt;
&lt;li&gt;For a job I pick, it drafts a tailored resume, cover letter and form answers. Every sentence about me has to cite a fact I confirmed, and a checker rejects any number, skill or name the cited fact doesn't contain&lt;/li&gt;
&lt;li&gt;It never submits anything. I review, export, and apply by hand&lt;/li&gt;
&lt;li&gt;It runs on my own machine: Bun, Hono, Postgres and a React SPA, with a Chrome extension that fills forms but never presses Submit&lt;/li&gt;
&lt;li&gt;The code is public: &lt;a href="https://github.com/RielJ/rolecraft-ai" rel="noopener noreferrer"&gt;github.com/RielJ/rolecraft-ai&lt;/a&gt;
&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fmo1wz2e8yzquuovm659l.gif" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fmo1wz2e8yzquuovm659l.gif" alt="Triage from the keyboard, save a job, and draft for it" width="760" height="475"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Triage from the keyboard, save a job, and draft for it. The demo runs on a fictional profile (Maria Santos) and recorded job data, with a scripted AI provider. I scripted it to slip one unbacked sentence into the cover letter, so you can see the checker catch it.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Why I built it
&lt;/h2&gt;

&lt;p&gt;Job hunting from the Philippines for remote work has two annoying problems.&lt;/p&gt;

&lt;p&gt;The first is that "remote" often doesn't mean remote for me. A posting says remote, and three paragraphs down it says "US only" or "must be based in the EU". Reading every posting to the end to find that sentence takes most of the time.&lt;/p&gt;

&lt;p&gt;The second is AI writing tools. Ask one to tailor a resume and it will happily write that you "led a team of 12" or "cut costs by 40%". It sounds great, and it isn't true. If a recruiter asks about that number, you lose the job, and you deserve to.&lt;/p&gt;

&lt;p&gt;So I wanted a tool that does the tedious parts and is strict about the one thing that matters: nothing goes into a draft that I didn't say first.&lt;/p&gt;

&lt;h2&gt;
  
  
  The loop
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F7qtm6vcs58myp23xqadh.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F7qtm6vcs58myp23xqadh.jpg" alt="The whole loop" width="800" height="261"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The whole loop. Rolecraft does the reading, ranking, drafting and tracking. It never submits an application: the red step is always you.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;That's the whole product. Most of the engineering went into making each step trustworthy, so the rest of this post walks through the parts I find most interesting.&lt;/p&gt;

&lt;h2&gt;
  
  
  Finding jobs I can actually take
&lt;/h2&gt;

&lt;p&gt;Refresh pulls from five built-in boards (Remotive, RemoteOK, We Work Remotely, Himalayas and Jobicy) and any company boards I add on Greenhouse, Lever, Ashby, Workable, Recruitee or SmartRecruiters.&lt;/p&gt;

&lt;p&gt;Each posting goes through an ordered list of eligibility rules, and the first hit wins. Exclusion runs before inclusion, so "Remote (US only)" never gets read as "remote". Every verdict shows the phrase that triggered it, which means I can check it in a second instead of rereading the posting. An optional AI pass can resolve the unclear ones, but only by quoting a phrase that appears word for word in the description. A verdict without a real quote gets thrown away.&lt;/p&gt;

&lt;p&gt;Then each job gets a level: Strong, Possible or Weak. The level comes from title fit, required skills covered by my confirmed facts, seniority, years and eligibility. It's recomputed on every read, so confirming a new fact changes the ranking on the next page load.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fb1xbqjmu9zj71nkc7xkx.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fb1xbqjmu9zj71nkc7xkx.jpg" alt="The Matches inbox with jobs grouped by match level, and one job open in the reading pane" width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The Matches inbox. &lt;code&gt;j&lt;/code&gt; and &lt;code&gt;k&lt;/code&gt; move, &lt;code&gt;s&lt;/code&gt; saves, &lt;code&gt;d&lt;/code&gt; dismisses with a reason.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Drafts that can't make things up
&lt;/h2&gt;

&lt;p&gt;This is the core of the app. My CV and any notes I add are split into short facts, one claim each. A new fact starts as pending. Only facts I confirm ever reach a prompt.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ff9q7o4mm1plelbq3e48s.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ff9q7o4mm1plelbq3e48s.jpg" alt="The Profile's Facts page, listing confirmed facts FACT-1 to FACT-7 grouped by employer, and the skills used for matching" width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Confirmed facts for the demo profile, grouped by where they came from.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ftvryoczqjdkddxvl4wys.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ftvryoczqjdkddxvl4wys.jpg" alt="A claim reaches a draft only through a fact you confirmed" width="800" height="627"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;A claim reaches a draft only through a fact you confirmed. Anything the checker can't trace back to a cited fact becomes a blank for you to fill, and the gate won't export a file that still has one.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;The prompt lists every confirmed fact as &lt;code&gt;FACT-1&lt;/code&gt;, &lt;code&gt;FACT-2&lt;/code&gt; and so on, and the model has to end each sentence about me with the markers that back it. When it needs something the facts don't have, it writes a blank like &lt;code&gt;[[years of Kubernetes experience]]&lt;/code&gt; instead of guessing.&lt;/p&gt;

&lt;p&gt;Then &lt;code&gt;checkDraft&lt;/code&gt; reads the result one sentence at a time, against only the facts that sentence cites:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fl91ffbleavi7w9ns1pss.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fl91ffbleavi7w9ns1pss.jpg" alt="The checker reads one sentence at a time against only the facts that sentence cites" width="799" height="361"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The checker reads one sentence at a time against only the facts that sentence cites. These examples use a made-up fact.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;A failing draft gets one retry with the problems listed. Whatever still fails becomes a &lt;code&gt;[[Check this: …]]&lt;/code&gt; blank. And the gate, which runs on the server for every export, won't let a file out while it has a blank in it.&lt;/p&gt;

&lt;p&gt;I measured this before trusting it. The repository has an evaluation set of eligibility and drafting cases. The recorded run with the default light model reported 0 missed exclusions and 0 invented claims, and the run exits with an error if either number goes above zero.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fipxe9sgoafkxklnjdh01.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fipxe9sgoafkxklnjdh01.jpg" alt="A drafted cover letter with one sentence highlighted, a &amp;quot;Check this sentence&amp;quot; box below it, and Copy text and Download PDF disabled" width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The scripted AI added "I also cut cloud hosting costs by 35% in one quarter." No confirmed fact says that, so the sentence is highlighted, it shows up under Needs your input, and Copy text and Download PDF stay disabled until I rewrite or remove it.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;One more detail I like: when a draft is saved, it stores the text of every fact it cited. If I later edit or delete that fact, the file shows as outdated and names the change, so an old draft can't quietly keep a claim I've since corrected.&lt;/p&gt;

&lt;h3&gt;
  
  
  Tailoring the resume
&lt;/h3&gt;

&lt;p&gt;The tailored resume isn't written from scratch. It starts from my base CV, and the model proposes a list of edits to numbered lines: rewrite the summary, reorder, reword, remove or add a line, or add a project the CV lacks. Before I see them, the app drops any edit that brings in a tool, number or name its facts don't have. I keep or undo each remaining change, and the resume is always the base CV plus the changes I kept.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fkgz9d82qx0ewxurc7z1l.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fkgz9d82qx0ewxurc7z1l.jpg" alt="The tailoring view listing a reorder, a reword and an added project, each with Keep and Undo buttons and the requirement it targets" width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Each change names the requirement it targets. "Asked for, not on your CV" lists what the posting wants that no fact covers, instead of inventing it.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Refresh can't touch your work
&lt;/h2&gt;

&lt;p&gt;Refresh writes to the database a lot, and it runs unattended. A bug there could wipe my board or my drafts. Code review isn't a strong enough guard for that, so I let Postgres enforce it.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F4apad2c3tm47qmqyur6g.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F4apad2c3tm47qmqyur6g.jpg" alt="Refresh runs every transaction as a Postgres role with narrow grants" width="800" height="353"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Refresh runs every transaction as a Postgres role with narrow grants. A bug in the sync code can't edit your board or files; the database refuses the write. A test runs Refresh in six scenarios and compares a hash of every other table before and after.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Refresh gets its database handle from one function that runs each transaction as the &lt;code&gt;hb_sync&lt;/code&gt; role. An architecture test stops the sync module from importing the normal connection. A job that has an application on my board can't be deleted either, because of a foreign key, so even a wrong cleanup query can't remove it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Three checks I added recently
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Is the posting still open?&lt;/strong&gt; It's a waste to spend AI money drafting for a job that closed last week. Before any model call, a draft now fetches the posting.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fs4d99i5ddyg11846rbox.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fs4d99i5ddyg11846rbox.jpg" alt="Before any AI spend, a draft fetches the posting" width="799" height="315"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Before any AI spend, a draft fetches the posting. Only clear evidence of a closed job blocks it. Anything uncertain lets the draft go ahead, because a slow or blocked page doesn't prove the job is gone.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;The hard part was deciding what &lt;em&gt;doesn't&lt;/em&gt; count as closed. My first version also trusted stored metadata: an expiry date from the board, or the fact that a board stopped listing the job. Neither proves anything. Boards drop jobs that are still open, and companies extend deadlines. So a fresh check of the URL now wins over anything cached, and only a 404, a closure notice in the page's main heading, or an expired structured posting for the same title and company stops the draft.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fjuho3l5rmuey5mffq2hk.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fjuho3l5rmuey5mffq2hk.jpg" alt="A job's Drafts tab with all three files still unwritten and a message that the posting appears closed and no AI tokens were spent" width="800" height="500"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Draft all on a posting whose page says the job is no longer available. Nothing gets written, and nothing is spent.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Do the match levels mean anything?&lt;/strong&gt; A ranking is only useful if Strong jobs do better than Weak ones. Each time I mark a job applied, the app now records the match level at that moment. The Board shows how often each level reached an interview. It hides the rates until at least 10 applications have a result, and it doesn't count pending applications as failures. I'd rather see "not enough data" than a confident percentage built on four data points.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fuolj5bd1ube2iugyeooy.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fuolj5bd1ube2iugyeooy.jpg" alt="The Board with Saved, Applied, Interviewing, Offer and Closed columns, and the Match levels and outcomes table showing 3/10 resolved instead of a rate" width="800" height="475"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;With demo data, no level has 10 resolved applications yet, so the table shows "3/10 resolved" instead of a percentage.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;"Doubled" is a number too.&lt;/strong&gt; The citation checker already caught "40%" when the fact said "12 services". It didn't catch "doubled deploy frequency", because there's no digit in it. Words like doubled, halved and tripled are claims about numbers, so they now need a cited fact that supports them, through the same retry and blank path as every other check.&lt;/p&gt;

&lt;h2&gt;
  
  
  How the code is organised
&lt;/h2&gt;

&lt;p&gt;Server and SPA share one TypeScript codebase, split into layers.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fyp5hr53xna0ztwed01w0.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fyp5hr53xna0ztwed01w0.jpg" alt="One TypeScript codebase for server and SPA" width="799" height="367"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;One TypeScript codebase for server and SPA. An architecture test reads every import and fails the build when a layer reaches past the ones it may use. The SPA gets server types only through import type.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;The rules aren't a convention. &lt;code&gt;test/architecture.test.ts&lt;/code&gt; scans every import in &lt;code&gt;src/&lt;/code&gt; and fails the build when a layer imports something it may not. It also forbids the clock and randomness in the domain layer, so callers pass &lt;code&gt;now&lt;/code&gt; in and every rule is testable with a fixed date.&lt;/p&gt;

&lt;p&gt;Other choices that paid off:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Bun and Hono&lt;/strong&gt; for the server. One process serves the API and the built SPA. The SPA gets typed API calls through Hono's client, with only &lt;code&gt;import type&lt;/code&gt; crossing the layers.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Zod everywhere data enters.&lt;/strong&gt; Request bodies, environment variables, job-board payloads and AI replies all go through a schema. The same enum arrays build both the Zod schemas and the database CHECK constraints.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Numbered decisions.&lt;/strong&gt; &lt;code&gt;docs/DECISIONS.md&lt;/code&gt; has 86 of them, and code comments cite them as "decision 58". When I wonder why something works the way it does, the answer has an address.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Tests at three levels.&lt;/strong&gt; About 1,900 app tests, most of the service tests against a real Postgres. 370 more cover the Chrome extension, and 63 Playwright tests drive the SPA against recorded job data and a scripted AI provider.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Using an architecture review to guide two refactors
&lt;/h2&gt;

&lt;p&gt;After a few weeks of features, some modules had grown in awkward ways. To find them I ran &lt;a href="https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture" rel="noopener noreferrer"&gt;improve-codebase-architecture&lt;/a&gt;, an agent skill from Matt Pocock's skills collection that I keep in my dotfiles. It reads the recent commit history to find the files that change most, walks the code looking for friction, and writes an HTML report of "deepening" candidates. A deep module hides a lot of behaviour behind a small interface. A shallow one makes every caller know its internals.&lt;/p&gt;

&lt;p&gt;The report uses a small vocabulary on purpose: module, interface, seam, depth, locality and leverage. Each candidate gets a before and after diagram, a problem, a solution, and a deletion test: would deleting this concentrate complexity or just move it around?&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F85lwfywt3q898n2y5r1a.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F85lwfywt3q898n2y5r1a.jpg" alt="A card from the architecture review report, with before and after diagrams for separating match evaluation from reading-pane enrichment" width="800" height="668"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;One card from the generated report.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;It found two candidates worth doing, and I redrew both for this post in the same style.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Match evaluation.&lt;/strong&gt; To record the match level when I apply for a job, the board code called the function that builds the whole reading pane. That loaded source listings and searched for duplicate jobs, inside the status-change transaction, only to read &lt;code&gt;.level&lt;/code&gt; off the result.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fifuf8sxrvrk2s6nxqckf.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fifuf8sxrvrk2s6nxqckf.jpg" alt="Recording an application needs one thing: the job's match level" width="800" height="428"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Recording an application needs one thing: the job's match level. It used to get it by building the whole reading pane, including source listings and duplicate hints, inside the status-change transaction. After the change, list, reading pane and the application snapshot share one match-evaluation interface, and only the reading pane adds display extras.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Output writes.&lt;/strong&gt; A file's text changes in four ways: my edits, filling blanks, accepting tailoring changes, and a fresh draft. Each one has to clear the "reviewed" mark, recompute style warnings, keep or drop the tailoring, and either keep or retake the citation snapshots. Each writer knew those rules for itself.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fjn0avhbg9u4046ooyrar.jpg" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fjn0avhbg9u4046ooyrar.jpg" alt="Four ways a file's text can change, and each one knew which other fields had to change with it" width="799" height="486"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Four ways a file's text can change, and each one knew which other fields had to change with it. Now each caller names where the text came from, and one module decides the rest. An architecture test refuses any other module that writes a file body or its citations.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Both refactors went test-first. I pinned the current behaviour with tests through the public operations, moved the code, and ran the same tests again. For output writes, the architecture test now also refuses any other module that writes a file body or its citation rows, so the rule can't drift back.&lt;/p&gt;

&lt;p&gt;The report was also useful for what it told me &lt;em&gt;not&lt;/em&gt; to change. It looked at the project-evidence code that reads commits from GitHub and from local folders, and said to leave it: two real adapters already justify that seam. Without that note I'd probably have "cleaned it up".&lt;/p&gt;

&lt;h2&gt;
  
  
  What's next
&lt;/h2&gt;

&lt;p&gt;Rolecraft is a personal tool first. It has no login, and it should never be on the open internet, because anyone who reaches it could read your profile or spend your AI budget. The README explains how to run your own copy with Docker Compose.&lt;/p&gt;

&lt;p&gt;The next real test is the one in &lt;code&gt;docs/MVP.md&lt;/code&gt;: three real applications through the loop, with no more than five minutes of edits on each resume. I'll find out whether the match levels predict anything once enough of those come back.&lt;/p&gt;

&lt;p&gt;The code, the decisions and the architecture notes are on GitHub: &lt;a href="https://github.com/RielJ/rolecraft-ai" rel="noopener noreferrer"&gt;github.com/RielJ/rolecraft-ai&lt;/a&gt;.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://rielj.xyz/blog/building-rolecraft-job-applications-without-invented-claims" rel="noopener noreferrer"&gt;rielj.xyz&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>typescript</category>
      <category>bunjs</category>
      <category>postgres</category>
    </item>
    <item>
      <title>Fix Tailwind CSS Canonical Classes in Neovim with One Keymap</title>
      <dc:creator>Riel Joseph</dc:creator>
      <pubDate>Wed, 11 Nov 2026 04:19:46 +0000</pubDate>
      <link>https://dev.to/rieljdev/fix-tailwind-css-canonical-classes-in-neovim-with-one-keymap-5hap</link>
      <guid>https://dev.to/rieljdev/fix-tailwind-css-canonical-classes-in-neovim-with-one-keymap-5hap</guid>
      <description>&lt;p&gt;&lt;strong&gt;TL;DR&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Tailwind CSS LSP suggests canonical class replacements but only one at a time&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;apply_all_tailwind_actions_buffer()&lt;/code&gt; fixes every non-canonical class in the buffer with one keypress&lt;/li&gt;
&lt;li&gt;Reverse-sorting edits by position prevents offset corruption&lt;/li&gt;
&lt;li&gt;Map it to &lt;code&gt;&amp;lt;leader&amp;gt;lt&lt;/code&gt; and never manually fix a canonical class again&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Requirements:&lt;/strong&gt; Neovim 0.9+, Tailwind CSS v4, &lt;code&gt;tailwindcss-language-server&lt;/code&gt;&lt;/p&gt;




&lt;p&gt;Tailwind CSS v4 introduced canonical class suggestions — the LSP tells you when &lt;code&gt;h-[72px]&lt;/code&gt; should be &lt;code&gt;h-18&lt;/code&gt;, or when &lt;code&gt;[display:_flex]&lt;/code&gt; should just be &lt;code&gt;flex&lt;/code&gt;. The problem is, fixing them one by one through code actions is painfully slow.&lt;/p&gt;

&lt;p&gt;I wrote two Lua functions that fix &lt;strong&gt;all&lt;/strong&gt; canonical class diagnostics in a buffer with a single keypress.&lt;/p&gt;




&lt;h2&gt;
  
  
  The Problem
&lt;/h2&gt;

&lt;p&gt;When Tailwind CSS LSP detects a non-canonical class, it shows a diagnostic:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;The class `h-[72px]` can be written as `h-18`
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The built-in fix is to hover each diagnostic, open the code action menu, and select "Replace with...". In a file with 30+ non-canonical classes, this takes forever.&lt;/p&gt;

&lt;p&gt;I wanted &lt;code&gt;&amp;lt;leader&amp;gt;lt&lt;/code&gt; to fix the entire buffer at once.&lt;/p&gt;




&lt;h2&gt;
  
  
  The Solution
&lt;/h2&gt;

&lt;p&gt;There are two approaches, each solving a different scope:&lt;/p&gt;

&lt;h3&gt;
  
  
  1. Buffer-wide Fix via Diagnostics (Recommended)
&lt;/h3&gt;

&lt;p&gt;This function reads all diagnostics in the current buffer, filters for &lt;code&gt;suggestCanonicalClasses&lt;/code&gt;, parses the "old → new" class names from the diagnostic message, and applies all replacements in one pass.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight lua"&gt;&lt;code&gt;&lt;span class="k"&gt;function&lt;/span&gt; &lt;span class="nc"&gt;M&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;apply_all_tailwind_actions_buffer&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;local&lt;/span&gt; &lt;span class="n"&gt;bufnr&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;api&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;nvim_get_current_buf&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

  &lt;span class="k"&gt;local&lt;/span&gt; &lt;span class="n"&gt;all_diagnostics&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;diagnostic&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;bufnr&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="c1"&gt;#all_diagnostics == 0 then&lt;/span&gt;
    &lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;notify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"No diagnostics found in buffer"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;log&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;levels&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;INFO&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;

  &lt;span class="c1"&gt;-- Filter for suggestCanonicalClasses diagnostics&lt;/span&gt;
  &lt;span class="c1"&gt;-- Message format: "The class `X` can be written as `Y`"&lt;/span&gt;
  &lt;span class="k"&gt;local&lt;/span&gt; &lt;span class="n"&gt;edits&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;_&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;diag&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="nb"&gt;ipairs&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;all_diagnostics&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;diag&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;code&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="s2"&gt;"suggestCanonicalClasses"&lt;/span&gt;
      &lt;span class="k"&gt;or&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;diag&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;message&lt;/span&gt; &lt;span class="k"&gt;and&lt;/span&gt; &lt;span class="n"&gt;diag&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;message&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="nf"&gt;match&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"can be written as"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;then&lt;/span&gt;
      &lt;span class="k"&gt;local&lt;/span&gt; &lt;span class="n"&gt;old_class&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;new_class&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt;
        &lt;span class="n"&gt;diag&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;message&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="nf"&gt;match&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"The class `([^`]+)` can be written as `([^`]+)`"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
      &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;old_class&lt;/span&gt; &lt;span class="k"&gt;and&lt;/span&gt; &lt;span class="n"&gt;new_class&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
        &lt;span class="n"&gt;table&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;insert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;edits&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
          &lt;span class="n"&gt;lnum&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;diag&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;lnum&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
          &lt;span class="n"&gt;col&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;diag&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;col&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
          &lt;span class="n"&gt;end_lnum&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;diag&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;end_lnum&lt;/span&gt; &lt;span class="k"&gt;or&lt;/span&gt; &lt;span class="n"&gt;diag&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;lnum&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
          &lt;span class="n"&gt;end_col&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;diag&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;end_col&lt;/span&gt; &lt;span class="k"&gt;or&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;diag&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;col&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="c1"&gt;#old_class),&lt;/span&gt;
          &lt;span class="n"&gt;old_class&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;old_class&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
          &lt;span class="n"&gt;new_class&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;new_class&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
      &lt;span class="k"&gt;end&lt;/span&gt;
    &lt;span class="k"&gt;end&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;

  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="c1"&gt;#edits == 0 then&lt;/span&gt;
    &lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;notify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"No canonical class fixes found"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;log&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;levels&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;INFO&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;

  &lt;span class="c1"&gt;-- Sort in reverse order so edits don't shift positions&lt;/span&gt;
  &lt;span class="n"&gt;table&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sort&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;edits&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;function&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;lnum&lt;/span&gt; &lt;span class="o"&gt;~=&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;lnum&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
      &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;lnum&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;lnum&lt;/span&gt;
    &lt;span class="k"&gt;end&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;col&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;col&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

  &lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;notify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="n"&gt;string&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;format&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"Applying %d Tailwind CSS fixes..."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;#edits),&lt;/span&gt;
    &lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;log&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;levels&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;INFO&lt;/span&gt;
  &lt;span class="p"&gt;)&lt;/span&gt;

  &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;_&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;edit&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="nb"&gt;ipairs&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;edits&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
    &lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;api&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;nvim_buf_set_text&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
      &lt;span class="n"&gt;bufnr&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;edit&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;lnum&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;edit&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;col&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;edit&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;end_lnum&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;edit&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;end_col&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;edit&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;new_class&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  2. Current Line Fix via LSP Code Actions
&lt;/h3&gt;

&lt;p&gt;This function requests code actions from the Tailwind CSS LSP for the current line and applies all "Replace with" actions automatically:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight lua"&gt;&lt;code&gt;&lt;span class="k"&gt;local&lt;/span&gt; &lt;span class="k"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;collect_and_apply_tailwind_edits&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;bufnr&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;results&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;local&lt;/span&gt; &lt;span class="n"&gt;all_edits&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;client_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="nb"&gt;pairs&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;results&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
    &lt;span class="k"&gt;local&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;lsp&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get_client_by_id&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;client_id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt; &lt;span class="k"&gt;and&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;name&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="s2"&gt;"tailwindcss"&lt;/span&gt; &lt;span class="k"&gt;and&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;result&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
      &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;_&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;action&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="nb"&gt;ipairs&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;action&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;title&lt;/span&gt; &lt;span class="k"&gt;and&lt;/span&gt; &lt;span class="n"&gt;action&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;title&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="nf"&gt;match&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"^Replace with"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
          &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;action&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;edit&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
            &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;action&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;edit&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;changes&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
              &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;_&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;edits&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="nb"&gt;pairs&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;action&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;edit&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;changes&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
                &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;_&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;edit&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="nb"&gt;ipairs&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;edits&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
                  &lt;span class="n"&gt;table&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;insert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;all_edits&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;edit&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
                &lt;span class="k"&gt;end&lt;/span&gt;
              &lt;span class="k"&gt;end&lt;/span&gt;
            &lt;span class="k"&gt;end&lt;/span&gt;
            &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;action&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;edit&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;documentChanges&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
              &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;_&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;change&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="nb"&gt;ipairs&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;action&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;edit&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;documentChanges&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
                &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;change&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;edits&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
                  &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;_&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;edit&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="nb"&gt;ipairs&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;change&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;edits&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
                    &lt;span class="n"&gt;table&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;insert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;all_edits&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;edit&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
                  &lt;span class="k"&gt;end&lt;/span&gt;
                &lt;span class="k"&gt;end&lt;/span&gt;
              &lt;span class="k"&gt;end&lt;/span&gt;
            &lt;span class="k"&gt;end&lt;/span&gt;
          &lt;span class="k"&gt;end&lt;/span&gt;
        &lt;span class="k"&gt;end&lt;/span&gt;
      &lt;span class="k"&gt;end&lt;/span&gt;
    &lt;span class="k"&gt;end&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;

  &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="c1"&gt;#all_edits == 0 then&lt;/span&gt;
    &lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;notify&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"No 'Replace with' actions available"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;log&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;levels&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;INFO&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;

  &lt;span class="c1"&gt;-- Sort reverse to preserve positions&lt;/span&gt;
  &lt;span class="n"&gt;table&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;sort&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;all_edits&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;function&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;local&lt;/span&gt; &lt;span class="n"&gt;a_line&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;range&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;start&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;line&lt;/span&gt;
    &lt;span class="k"&gt;local&lt;/span&gt; &lt;span class="n"&gt;b_line&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;range&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;start&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;line&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;a_line&lt;/span&gt; &lt;span class="o"&gt;~=&lt;/span&gt; &lt;span class="n"&gt;b_line&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
      &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;a_line&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;b_line&lt;/span&gt;
    &lt;span class="k"&gt;end&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;range&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;start&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;character&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;range&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;start&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;character&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

  &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;_&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;edit&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="nb"&gt;ipairs&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;all_edits&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
    &lt;span class="k"&gt;local&lt;/span&gt; &lt;span class="n"&gt;start_line&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;edit&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;range&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;start&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;line&lt;/span&gt;
    &lt;span class="k"&gt;local&lt;/span&gt; &lt;span class="n"&gt;start_col&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;edit&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;range&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;start&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;character&lt;/span&gt;
    &lt;span class="k"&gt;local&lt;/span&gt; &lt;span class="n"&gt;end_line&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;edit&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;range&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"end"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;line&lt;/span&gt;
    &lt;span class="k"&gt;local&lt;/span&gt; &lt;span class="n"&gt;end_col&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;edit&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;range&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"end"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;character&lt;/span&gt;
    &lt;span class="k"&gt;local&lt;/span&gt; &lt;span class="n"&gt;new_text&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;split&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;edit&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;newText&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"\n"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;plain&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;api&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;nvim_buf_set_text&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;bufnr&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;start_line&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;start_col&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;end_line&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;end_col&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;new_text&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;

&lt;span class="k"&gt;function&lt;/span&gt; &lt;span class="nc"&gt;M&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;apply_all_tailwind_actions&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;local&lt;/span&gt; &lt;span class="n"&gt;bufnr&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;api&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;nvim_get_current_buf&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

  &lt;span class="k"&gt;local&lt;/span&gt; &lt;span class="n"&gt;context&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;diagnostics&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;lsp&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;diagnostic&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get_line_diagnostics&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;bufnr&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;triggerKind&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;lsp&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;protocol&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;CodeActionTriggerKind&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Invoked&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="k"&gt;local&lt;/span&gt; &lt;span class="n"&gt;params&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;lsp&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;util&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;make_range_params&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"utf-16"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="n"&gt;params&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;context&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;context&lt;/span&gt;

  &lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;lsp&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;buf_request_all&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;bufnr&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"textDocument/codeAction"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;params&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;function&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;results&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="nf"&gt;collect_and_apply_tailwind_edits&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;bufnr&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;results&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;






&lt;h2&gt;
  
  
  Keymaps
&lt;/h2&gt;

&lt;p&gt;Add these to your Neovim config:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight lua"&gt;&lt;code&gt;&lt;span class="c1"&gt;-- Fix all canonical classes in the current buffer&lt;/span&gt;
&lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;keymap&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;set&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"n"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"&amp;lt;leader&amp;gt;lt"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"&amp;lt;cmd&amp;gt;lua require('your.lsp.handlers').apply_all_tailwind_actions_buffer()&amp;lt;CR&amp;gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;noremap&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;silent&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;desc&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Fix all Tailwind canonical classes (buffer)"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="c1"&gt;-- Fix Tailwind classes on the current line via code actions&lt;/span&gt;
&lt;span class="n"&gt;vim&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;keymap&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;set&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"n"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"&amp;lt;leader&amp;gt;lT"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"&amp;lt;cmd&amp;gt;lua require('your.lsp.handlers').apply_all_tailwind_actions()&amp;lt;CR&amp;gt;"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;noremap&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;silent&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;desc&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Fix Tailwind canonical classes (line)"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;






&lt;h2&gt;
  
  
  How It Works
&lt;/h2&gt;

&lt;p&gt;The key insight is that Tailwind CSS LSP diagnostics follow a predictable message format:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;The class `h-[72px]` can be written as `h-18`
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The buffer-wide function:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Pulls all diagnostics from &lt;code&gt;vim.diagnostic.get(bufnr)&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;Filters for diagnostics with code &lt;code&gt;suggestCanonicalClasses&lt;/code&gt; (or matching the message pattern as a fallback)&lt;/li&gt;
&lt;li&gt;Extracts the old and new class names using Lua pattern matching&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Sorts edits in reverse order&lt;/strong&gt; (bottom-right to top-left) — this is critical because applying an edit changes byte offsets for everything after it&lt;/li&gt;
&lt;li&gt;Applies each replacement using &lt;code&gt;nvim_buf_set_text&lt;/code&gt;
&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The reverse-sort trick is the same technique used by LSP servers when applying workspace edits — it guarantees that earlier edits don't invalidate the positions of later ones.&lt;/p&gt;




&lt;h2&gt;
  
  
  Before &amp;amp; After
&lt;/h2&gt;

&lt;p&gt;Before pressing &lt;code&gt;&amp;lt;leader&amp;gt;lt&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight html"&gt;&lt;code&gt;&lt;span class="nt"&gt;&amp;lt;div&lt;/span&gt; &lt;span class="na"&gt;class&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"h-[72px] w-[100%] m-[16px] p-[8px] [display:_flex]"&lt;/span&gt;&lt;span class="nt"&gt;&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;After:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight html"&gt;&lt;code&gt;&lt;span class="nt"&gt;&amp;lt;div&lt;/span&gt; &lt;span class="na"&gt;class&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s"&gt;"h-18 w-full m-4 p-2 flex"&lt;/span&gt;&lt;span class="nt"&gt;&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Every non-canonical class in the buffer is fixed instantly.&lt;/p&gt;




&lt;p&gt;You can find my full Neovim config in my &lt;a href="https://github.com/RielJ/dotfiles/tree/master/nvim/.config/nvim" rel="noopener noreferrer"&gt;dotfiles on GitHub&lt;/a&gt;.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://rielj.xyz/blog/neovim-tailwind-canonical-classes" rel="noopener noreferrer"&gt;rielj.xyz&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>tailwindcss</category>
      <category>neovim</category>
      <category>tooling</category>
      <category>typescript</category>
    </item>
    <item>
      <title>How I Let My QA Tester Run Our Full Stack App Without Any Dev Experience</title>
      <dc:creator>Riel Joseph</dc:creator>
      <pubDate>Wed, 11 Nov 2026 04:19:15 +0000</pubDate>
      <link>https://dev.to/rieljdev/how-i-let-my-qa-tester-run-our-full-stack-app-without-any-dev-experience-iim</link>
      <guid>https://dev.to/rieljdev/how-i-let-my-qa-tester-run-our-full-stack-app-without-any-dev-experience-iim</guid>
      <description>&lt;p&gt;&lt;strong&gt;TL;DR&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Non-technical QA testers shouldn't need to understand Docker, git, or package managers to test your app&lt;/li&gt;
&lt;li&gt;I first tried a fully Dockerized setup with ngrok tunnels — it worked but was painfully slow&lt;/li&gt;
&lt;li&gt;I then built a single bash script that checks/installs prerequisites, checks out branches, runs migrations, and starts everything&lt;/li&gt;
&lt;li&gt;The QA tester runs one command and gets the full stack running locally&lt;/li&gt;
&lt;li&gt;Self-updating script distributed via a GitHub Gist&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Requirements&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;macOS (uses Homebrew for dependency management)&lt;/li&gt;
&lt;li&gt;A project with separate frontend and backend directories&lt;/li&gt;
&lt;li&gt;Basic terminal access (just enough to paste a command)&lt;/li&gt;
&lt;/ul&gt;




&lt;h2&gt;
  
  
  The Problem
&lt;/h2&gt;

&lt;p&gt;Our QA tester doesn't have a dev background. They're great at finding bugs, writing test cases, and verifying features — but asking them to run &lt;code&gt;git checkout&lt;/code&gt;, install runtime dependencies, set up virtual environments, start Docker containers, run database migrations, and then start multiple services? That's a full day of onboarding that ends in frustration.&lt;/p&gt;

&lt;p&gt;The "normal" answer is a staging environment. But staging deployments aren't instant — you push a branch, wait for CI to build, wait for the deploy to finish, and only then can QA start testing. For a quick bug fix, that's 10-15 minutes of dead time. Multiply that by every branch that needs testing and it adds up fast. And if two people need to test different branches? You're either queuing or spinning up multiple staging environments.&lt;/p&gt;

&lt;p&gt;I needed a way for them to test any branch of our app with &lt;strong&gt;one command&lt;/strong&gt;, instantly, without waiting for a deploy. No dev knowledge required.&lt;/p&gt;

&lt;h2&gt;
  
  
  Attempt 1: Docker Compose + ngrok
&lt;/h2&gt;

&lt;p&gt;My first idea was to containerize everything and expose it through an ngrok tunnel. The QA tester wouldn't even need to clone the repo — they'd just open a URL.&lt;/p&gt;

&lt;p&gt;The setup used Docker Compose to orchestrate all the services:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;db&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;postgres:17&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_DB&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;app_db&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_USER&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;app_user&lt;/span&gt;
      &lt;span class="na"&gt;POSTGRES_PASSWORD&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;localdev123&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;postgres_data:/var/lib/postgresql/data&lt;/span&gt;
    &lt;span class="na"&gt;healthcheck&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;test&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"CMD-SHELL"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"pg_isready -U app_user -d app_db"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
      &lt;span class="na"&gt;interval&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;5s&lt;/span&gt;
      &lt;span class="na"&gt;timeout&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;5s&lt;/span&gt;
      &lt;span class="na"&gt;retries&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;5&lt;/span&gt;

  &lt;span class="na"&gt;redis&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;redis:6&lt;/span&gt;
    &lt;span class="na"&gt;healthcheck&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;test&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"CMD"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"redis-cli"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"ping"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
      &lt;span class="na"&gt;interval&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;5s&lt;/span&gt;
      &lt;span class="na"&gt;timeout&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;5s&lt;/span&gt;
      &lt;span class="na"&gt;retries&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;5&lt;/span&gt;

  &lt;span class="na"&gt;backend&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;build&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;context&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;../backend&lt;/span&gt;
    &lt;span class="na"&gt;env_file&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;backend.env.docker&lt;/span&gt;
    &lt;span class="na"&gt;depends_on&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;db&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;condition&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;service_healthy&lt;/span&gt;
      &lt;span class="na"&gt;redis&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;condition&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;service_healthy&lt;/span&gt;
    &lt;span class="na"&gt;command&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
      &lt;span class="s"&gt;sh -c "npm install &amp;amp;&amp;amp;&lt;/span&gt;
             &lt;span class="s"&gt;npm run migrate &amp;amp;&amp;amp;&lt;/span&gt;
             &lt;span class="s"&gt;npm start"&lt;/span&gt;

  &lt;span class="na"&gt;frontend&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;build&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;context&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;../frontend&lt;/span&gt;
      &lt;span class="na"&gt;dockerfile&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;../docker-environment/Dockerfile.frontend&lt;/span&gt;
    &lt;span class="na"&gt;env_file&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;frontend.env&lt;/span&gt;

  &lt;span class="na"&gt;nginx&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;nginx:alpine&lt;/span&gt;
    &lt;span class="na"&gt;ports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s2"&gt;"3000:80"&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;./nginx.conf:/etc/nginx/conf.d/default.conf&lt;/span&gt;
    &lt;span class="na"&gt;depends_on&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;backend&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;frontend&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;An nginx reverse proxy sat in front to route &lt;code&gt;/api&lt;/code&gt; to the backend and everything else to the frontend:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight nginx"&gt;&lt;code&gt;&lt;span class="n"&gt;server&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;listen&lt;/span&gt; &lt;span class="mi"&gt;80&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="n"&gt;location&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;api&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;proxy_pass&lt;/span&gt; &lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//backend:8000;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="nc"&gt;Host&lt;/span&gt; $&lt;span class="n"&gt;host&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="no"&gt;X&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Real&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="no"&gt;IP&lt;/span&gt; $&lt;span class="n"&gt;remote_addr&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="n"&gt;location&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;proxy_pass&lt;/span&gt; &lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="c1"&gt;//frontend:8080;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="nc"&gt;Host&lt;/span&gt; $&lt;span class="n"&gt;host&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="nc"&gt;Upgrade&lt;/span&gt; $&lt;span class="n"&gt;http_upgrade&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;proxy_set_header&lt;/span&gt; &lt;span class="nc"&gt;Connection&lt;/span&gt; &lt;span class="s2"&gt;"upgrade"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then a start script would build everything and optionally open an ngrok tunnel:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;#!/bin/bash&lt;/span&gt;
docker compose -f docker-compose.qa.yml up --build -d

&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"Waiting for services to start..."&lt;/span&gt;
sleep 10

&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"QA environment is ready at http://localhost:3000"&lt;/span&gt;

&lt;span class="c"&gt;# Optional: expose via ngrok&lt;/span&gt;
&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="nb"&gt;command&lt;/span&gt; -v ngrok &lt;span class="o"&gt;&amp;amp;&amp;gt;&lt;/span&gt; /dev/null&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
    &lt;span class="nb"&gt;read&lt;/span&gt; -p &lt;span class="s2"&gt;"Start ngrok tunnel? (y/N): "&lt;/span&gt; -n 1 -r
    &lt;span class="nb"&gt;echo&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="o"&gt;[&lt;/span&gt;&lt;span class="o"&gt;[&lt;/span&gt; &lt;span class="nv"&gt;$REPLY&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt;~ ^&lt;span class="o"&gt;[&lt;/span&gt;Yy&lt;span class="o"&gt;]&lt;/span&gt;$ &lt;span class="o"&gt;]&lt;/span&gt;&lt;span class="o"&gt;]&lt;/span&gt;&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
        ngrok http 3000
    &lt;span class="k"&gt;fi&lt;/span&gt;
&lt;span class="k"&gt;fi&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Why I Moved Away From This
&lt;/h3&gt;

&lt;p&gt;It worked. The QA tester could open an ngrok URL and test. But there were real problems:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;ngrok was painfully slow&lt;/strong&gt; — API calls that took 50ms locally took 500ms+ through the tunnel. The app felt broken even when it wasn't.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Free ngrok URLs change every session&lt;/strong&gt; — the QA tester had to get a new URL from me every time.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;I had to run it on my machine&lt;/strong&gt; — since the QA tester didn't have Docker, I was the one running the Docker stack and keeping the tunnel alive. Defeating the purpose.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Debugging was harder&lt;/strong&gt; — logs were buried inside containers, and the QA tester couldn't share their browser console easily.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The Docker approach is still useful for CI/CD or staging environments, but for day-to-day QA testing, I needed something that ran on the tester's own machine.&lt;/p&gt;

&lt;h2&gt;
  
  
  Attempt 2: The QA Runner Script
&lt;/h2&gt;

&lt;p&gt;The better approach: a single bash script that sets up &lt;em&gt;everything&lt;/em&gt; on the QA tester's machine. They don't need to understand what it's doing — they just run it.&lt;/p&gt;

&lt;h3&gt;
  
  
  Design Principles
&lt;/h3&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Zero prior knowledge required&lt;/strong&gt; — the script checks for every prerequisite and installs what's missing&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;One command to start&lt;/strong&gt; — &lt;code&gt;./qa-runner.sh -f main -b main&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Safe by default&lt;/strong&gt; — destructive operations (like wiping the database) require explicit flags and confirmation&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Self-updating&lt;/strong&gt; — the script can update itself from a Gist&lt;/li&gt;
&lt;/ol&gt;

&lt;h3&gt;
  
  
  Prerequisite Checking
&lt;/h3&gt;

&lt;p&gt;The script checks for every tool it needs and installs missing ones automatically:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;check_homebrew&lt;span class="o"&gt;(&lt;/span&gt;&lt;span class="o"&gt;)&lt;/span&gt; &lt;span class="o"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; ! &lt;span class="nb"&gt;command&lt;/span&gt; -v brew &lt;span class="o"&gt;&amp;amp;&amp;gt;&lt;/span&gt; /dev/null&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
        &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"Homebrew is not installed!"&lt;/span&gt;
        &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"Please install it by running:"&lt;/span&gt;
        &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s1"&gt;'/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"'&lt;/span&gt;
        &lt;span class="nb"&gt;return&lt;/span&gt; 1
    &lt;span class="k"&gt;fi&lt;/span&gt;
    &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"Homebrew is installed"&lt;/span&gt;
&lt;span class="o"&gt;}&lt;/span&gt;

check_docker&lt;span class="o"&gt;(&lt;/span&gt;&lt;span class="o"&gt;)&lt;/span&gt; &lt;span class="o"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; ! &lt;span class="nb"&gt;command&lt;/span&gt; -v docker &lt;span class="o"&gt;&amp;amp;&amp;gt;&lt;/span&gt; /dev/null&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
        &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"Installing Docker Desktop via Homebrew..."&lt;/span&gt;
        brew install --cask docker
        &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"Please open Docker Desktop, complete setup, then run this script again."&lt;/span&gt;
        &lt;span class="nb"&gt;return&lt;/span&gt; 1
    &lt;span class="k"&gt;fi&lt;/span&gt;

    &lt;span class="c"&gt;# Check if Docker daemon is actually running&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; ! docker info &lt;span class="o"&gt;&amp;amp;&amp;gt;&lt;/span&gt; /dev/null&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
        &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"Docker Desktop is not running. Starting it..."&lt;/span&gt;
        open -a Docker

        &lt;span class="c"&gt;# Wait for it to be ready&lt;/span&gt;
        &lt;span class="kd"&gt;local&lt;/span&gt; &lt;span class="nv"&gt;attempt&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;1
        &lt;span class="k"&gt;while&lt;/span&gt; ! docker info &lt;span class="o"&gt;&amp;amp;&amp;gt;&lt;/span&gt; /dev/null&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
            &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="o"&gt;[&lt;/span&gt; &lt;span class="nv"&gt;$attempt&lt;/span&gt; -ge 60 &lt;span class="o"&gt;]&lt;/span&gt;&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
                &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"Docker failed to start"&lt;/span&gt;
                &lt;span class="nb"&gt;return&lt;/span&gt; 1
            &lt;span class="k"&gt;fi&lt;/span&gt;
            sleep 2
            &lt;span class="o"&gt;(&lt;/span&gt;&lt;span class="o"&gt;(&lt;/span&gt;attempt++&lt;span class="o"&gt;)&lt;/span&gt;&lt;span class="o"&gt;)&lt;/span&gt;
        &lt;span class="k"&gt;done&lt;/span&gt;
    &lt;span class="k"&gt;fi&lt;/span&gt;
&lt;span class="o"&gt;}&lt;/span&gt;

check_node&lt;span class="o"&gt;(&lt;/span&gt;&lt;span class="o"&gt;)&lt;/span&gt; &lt;span class="o"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; ! &lt;span class="nb"&gt;command&lt;/span&gt; -v node &lt;span class="o"&gt;&amp;amp;&amp;gt;&lt;/span&gt; /dev/null&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
        brew install node@&lt;span class="nv"&gt;${REQUIRED_NODE_VERSION}&lt;/span&gt;
        &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"export PATH=\"/opt/homebrew/opt/node@${REQUIRED_NODE_VERSION}/bin:\$PATH\""&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&amp;gt;&lt;/span&gt; ~/.zshrc
        &lt;span class="kd"&gt;export&lt;/span&gt; &lt;span class="nv"&gt;PATH&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"/opt/homebrew/opt/node@${REQUIRED_NODE_VERSION}/bin:$PATH"&lt;/span&gt;
    &lt;span class="k"&gt;fi&lt;/span&gt;

    &lt;span class="kd"&gt;local&lt;/span&gt; &lt;span class="nv"&gt;version&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nv"&gt;$(&lt;/span&gt;node -v &lt;span class="o"&gt;|&lt;/span&gt; sed &lt;span class="s1"&gt;'s/v//'&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; cut -d&lt;span class="s1"&gt;'.'&lt;/span&gt; -f1&lt;span class="o"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="o"&gt;[&lt;/span&gt; &lt;span class="s2"&gt;"$version"&lt;/span&gt; -lt &lt;span class="s2"&gt;"$REQUIRED_NODE_VERSION"&lt;/span&gt; &lt;span class="o"&gt;]&lt;/span&gt;&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
        &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"Node.js version too old, upgrading..."&lt;/span&gt;
        brew install node@&lt;span class="nv"&gt;${REQUIRED_NODE_VERSION}&lt;/span&gt;
    &lt;span class="k"&gt;fi&lt;/span&gt;
&lt;span class="o"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Each check follows the same pattern: check if it exists, install if not, verify the version. The QA tester sees green checkmarks or gets clear instructions for anything that needs manual action (like opening Docker Desktop for the first time).&lt;/p&gt;

&lt;h3&gt;
  
  
  Branch Management
&lt;/h3&gt;

&lt;p&gt;The QA tester specifies which branches to test — usually a feature branch for either the frontend or backend:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;update_branch&lt;span class="o"&gt;(&lt;/span&gt;&lt;span class="o"&gt;)&lt;/span&gt; &lt;span class="o"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;local&lt;/span&gt; &lt;span class="nv"&gt;dir&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nv"&gt;$1&lt;/span&gt;
    &lt;span class="kd"&gt;local&lt;/span&gt; &lt;span class="nv"&gt;branch&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nv"&gt;$2&lt;/span&gt;
    &lt;span class="kd"&gt;local&lt;/span&gt; &lt;span class="nv"&gt;name&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nv"&gt;$3&lt;/span&gt;

    &lt;span class="nb"&gt;cd&lt;/span&gt; &lt;span class="s2"&gt;"$dir"&lt;/span&gt;
    git fetch --all --prune

    &lt;span class="k"&gt;if&lt;/span&gt; ! git rev-parse --verify &lt;span class="s2"&gt;"origin/$branch"&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;gt;&lt;/span&gt; /dev/null&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
        &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"Branch '$branch' does not exist!"&lt;/span&gt;
        git branch -r &lt;span class="o"&gt;|&lt;/span&gt; grep -v HEAD &lt;span class="o"&gt;|&lt;/span&gt; sed &lt;span class="s1"&gt;'s/origin\//  /'&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; head -20
        &lt;span class="nb"&gt;exit&lt;/span&gt; 1
    &lt;span class="k"&gt;fi&lt;/span&gt;

    &lt;span class="c"&gt;# Stash local changes so we don't lose anything&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="o"&gt;[&lt;/span&gt; -n &lt;span class="s2"&gt;"$(git status --porcelain)"&lt;/span&gt; &lt;span class="o"&gt;]&lt;/span&gt;&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
        git stash push -m &lt;span class="s2"&gt;"Auto-stash by qa-runner on $(date)"&lt;/span&gt;
    &lt;span class="k"&gt;fi&lt;/span&gt;

    git checkout &lt;span class="s2"&gt;"$branch"&lt;/span&gt; 2&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;/dev/null &lt;span class="o"&gt;||&lt;/span&gt; git checkout -b &lt;span class="s2"&gt;"$branch"&lt;/span&gt; &lt;span class="s2"&gt;"origin/$branch"&lt;/span&gt;
    git pull origin &lt;span class="s2"&gt;"$branch"&lt;/span&gt;

    &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"$name is on branch '$branch' ($(git rev-parse --short HEAD))"&lt;/span&gt;
    &lt;span class="nb"&gt;cd&lt;/span&gt; ..
&lt;span class="o"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If the branch doesn't exist, it shows available branches instead of a cryptic git error. Local changes get stashed automatically so nothing is lost.&lt;/p&gt;

&lt;h3&gt;
  
  
  Starting Everything
&lt;/h3&gt;

&lt;p&gt;The script starts all services as background processes and shows a clean summary:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;run_services&lt;span class="o"&gt;(&lt;/span&gt;&lt;span class="o"&gt;)&lt;/span&gt; &lt;span class="o"&gt;{&lt;/span&gt;
    &lt;span class="c"&gt;# Start database and cache (Docker)&lt;/span&gt;
    &lt;span class="nb"&gt;cd&lt;/span&gt; &lt;span class="s2"&gt;"$BACKEND_DIR"&lt;/span&gt;
    docker compose -f &lt;span class="s2"&gt;"$DOCKER_COMPOSE_FILE"&lt;/span&gt; up -d
    &lt;span class="nb"&gt;cd&lt;/span&gt; ..

    &lt;span class="c"&gt;# Wait for DB to be ready&lt;/span&gt;
    &lt;span class="k"&gt;while&lt;/span&gt; ! docker compose -f &lt;span class="s2"&gt;"$DOCKER_COMPOSE_FILE"&lt;/span&gt; &lt;span class="nb"&gt;exec&lt;/span&gt; -T db pg_isready &lt;span class="o"&gt;&amp;amp;&amp;gt;&lt;/span&gt;/dev/null&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
        sleep 1
    &lt;span class="k"&gt;done&lt;/span&gt;

    &lt;span class="c"&gt;# Start backend&lt;/span&gt;
    &lt;span class="nb"&gt;cd&lt;/span&gt; &lt;span class="s2"&gt;"$BACKEND_DIR"&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nv"&gt;$BACKEND_START_CMD&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&lt;/span&gt;
    &lt;span class="nv"&gt;BACKEND_PID&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nv"&gt;$!&lt;/span&gt;
    &lt;span class="nb"&gt;cd&lt;/span&gt; ..

    &lt;span class="c"&gt;# Start frontend&lt;/span&gt;
    &lt;span class="nb"&gt;cd&lt;/span&gt; &lt;span class="s2"&gt;"$FRONTEND_DIR"&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nv"&gt;$FRONTEND_START_CMD&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&lt;/span&gt;
    &lt;span class="nv"&gt;FRONTEND_PID&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nv"&gt;$!&lt;/span&gt;
    &lt;span class="nb"&gt;cd&lt;/span&gt; ..

    &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"Services are running!"&lt;/span&gt;
    &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"  Frontend: http://localhost:${FRONTEND_PORT}"&lt;/span&gt;
    &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"  Backend:  http://localhost:${BACKEND_PORT}"&lt;/span&gt;
    &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;""&lt;/span&gt;
    &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"Press Ctrl+C to stop all services"&lt;/span&gt;

    &lt;span class="c"&gt;# Clean shutdown on Ctrl+C&lt;/span&gt;
    &lt;span class="nb"&gt;trap&lt;/span&gt; cleanup SIGINT SIGTERM
    &lt;span class="nb"&gt;wait&lt;/span&gt;
&lt;span class="o"&gt;}&lt;/span&gt;

cleanup&lt;span class="o"&gt;(&lt;/span&gt;&lt;span class="o"&gt;)&lt;/span&gt; &lt;span class="o"&gt;{&lt;/span&gt;
    &lt;span class="nb"&gt;kill&lt;/span&gt; &lt;span class="nv"&gt;$FRONTEND_PID&lt;/span&gt; &lt;span class="nv"&gt;$BACKEND_PID&lt;/span&gt; 2&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;/dev/null
    &lt;span class="nb"&gt;cd&lt;/span&gt; &lt;span class="s2"&gt;"$BACKEND_DIR"&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; docker compose -f &lt;span class="s2"&gt;"$DOCKER_COMPOSE_FILE"&lt;/span&gt; down
    &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"All services stopped"&lt;/span&gt;
    &lt;span class="nb"&gt;exit&lt;/span&gt; 0
&lt;span class="o"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;trap&lt;/code&gt; ensures a clean shutdown — killing background processes and stopping Docker containers when the tester presses Ctrl+C.&lt;/p&gt;

&lt;h3&gt;
  
  
  Database Management
&lt;/h3&gt;

&lt;p&gt;Sometimes the QA tester needs a fresh database (testing onboarding flows) or seeded test data:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# Fresh database — wipes everything and reruns migrations&lt;/span&gt;
./qa-runner.sh -f main -b main --fresh

&lt;span class="c"&gt;# Fresh database with test data&lt;/span&gt;
./qa-runner.sh -f main -b main --fresh --seed

&lt;span class="c"&gt;# Nuclear option — removes all dependencies too&lt;/span&gt;
./qa-runner.sh -f main -b main --reset-all
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Destructive operations show a warning and require confirmation:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;confirm_action&lt;span class="o"&gt;(&lt;/span&gt;&lt;span class="o"&gt;)&lt;/span&gt; &lt;span class="o"&gt;{&lt;/span&gt;
    &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"WARNING: $1"&lt;/span&gt;
    &lt;span class="nb"&gt;read&lt;/span&gt; -p &lt;span class="s2"&gt;"Are you sure? (y/N): "&lt;/span&gt; -n 1 -r
    &lt;span class="nb"&gt;echo&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="o"&gt;[&lt;/span&gt;&lt;span class="o"&gt;[&lt;/span&gt; ! &lt;span class="nv"&gt;$REPLY&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt;~ ^&lt;span class="o"&gt;[&lt;/span&gt;Yy&lt;span class="o"&gt;]&lt;/span&gt;$ &lt;span class="o"&gt;]&lt;/span&gt;&lt;span class="o"&gt;]&lt;/span&gt;&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
        &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"Cancelled."&lt;/span&gt;
        &lt;span class="nb"&gt;exit&lt;/span&gt; 0
    &lt;span class="k"&gt;fi&lt;/span&gt;
&lt;span class="o"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="o"&gt;[&lt;/span&gt; &lt;span class="s2"&gt;"$FRESH_DATABASE"&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt; &lt;span class="o"&gt;]&lt;/span&gt;&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
    confirm_action &lt;span class="s2"&gt;"This will ERASE ALL DATA in your local database!"&lt;/span&gt;
&lt;span class="k"&gt;fi&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Self-Updating
&lt;/h3&gt;

&lt;p&gt;The script is hosted as a GitHub Gist. When the QA tester runs &lt;code&gt;./qa-runner.sh --update&lt;/code&gt;, it downloads the latest version and replaces itself:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nv"&gt;GIST_RAW_URL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"https://gist.githubusercontent.com/your-user/abc123/raw/qa-runner.sh"&lt;/span&gt;

update_script&lt;span class="o"&gt;(&lt;/span&gt;&lt;span class="o"&gt;)&lt;/span&gt; &lt;span class="o"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;local&lt;/span&gt; &lt;span class="nv"&gt;temp_file&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nv"&gt;$(&lt;/span&gt;mktemp&lt;span class="o"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; curl -fsSL &lt;span class="s2"&gt;"$GIST_RAW_URL"&lt;/span&gt; -o &lt;span class="s2"&gt;"$temp_file"&lt;/span&gt;&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
        &lt;span class="c"&gt;# Verify it's actually a script, not an HTML error page&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; head -1 &lt;span class="s2"&gt;"$temp_file"&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; grep -q &lt;span class="s2"&gt;"^#!/bin/bash"&lt;/span&gt;&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
            &lt;span class="kd"&gt;local&lt;/span&gt; &lt;span class="nv"&gt;new_version&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nv"&gt;$(&lt;/span&gt;grep &lt;span class="s2"&gt;"^SCRIPT_VERSION="&lt;/span&gt; &lt;span class="s2"&gt;"$temp_file"&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; cut -d&lt;span class="s1"&gt;'"'&lt;/span&gt; -f2&lt;span class="o"&gt;)&lt;/span&gt;
            &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="o"&gt;[&lt;/span&gt; &lt;span class="s2"&gt;"$new_version"&lt;/span&gt; != &lt;span class="s2"&gt;"$SCRIPT_VERSION"&lt;/span&gt; &lt;span class="o"&gt;]&lt;/span&gt;&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;then&lt;/span&gt;
                cp &lt;span class="s2"&gt;"$temp_file"&lt;/span&gt; &lt;span class="s2"&gt;"$0"&lt;/span&gt;
                chmod +x &lt;span class="s2"&gt;"$0"&lt;/span&gt;
                &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"Updated to version $new_version"&lt;/span&gt;
            &lt;span class="k"&gt;else&lt;/span&gt;
                &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"Already on latest version"&lt;/span&gt;
            &lt;span class="k"&gt;fi&lt;/span&gt;
        &lt;span class="k"&gt;fi&lt;/span&gt;
    &lt;span class="k"&gt;fi&lt;/span&gt;
    rm &lt;span class="s2"&gt;"$temp_file"&lt;/span&gt;
&lt;span class="o"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is a nice trick — the script checks that the downloaded file actually starts with &lt;code&gt;#!/bin/bash&lt;/code&gt; before replacing itself. This prevents a failed download (which might return an HTML error page) from bricking the script.&lt;/p&gt;

&lt;h2&gt;
  
  
  The QA Tester's Workflow
&lt;/h2&gt;

&lt;p&gt;Here's what the tester's daily workflow looks like now:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# First time setup (one-time)&lt;/span&gt;
&lt;span class="c"&gt;# 1. Clone both repos into a folder&lt;/span&gt;
&lt;span class="c"&gt;# 2. Download the script from the Gist&lt;/span&gt;
&lt;span class="c"&gt;# 3. Make it executable: chmod +x qa-runner.sh&lt;/span&gt;

&lt;span class="c"&gt;# Daily testing&lt;/span&gt;
./qa-runner.sh -f feature/new-login -b main

&lt;span class="c"&gt;# Testing a backend change&lt;/span&gt;
./qa-runner.sh -f main -b fix/api-validation

&lt;span class="c"&gt;# Need fresh test data&lt;/span&gt;
./qa-runner.sh -f main -b main --fresh --seed

&lt;span class="c"&gt;# Something went wrong, nuclear reset&lt;/span&gt;
./qa-runner.sh -f main -b main --reset-all

&lt;span class="c"&gt;# Stop everything&lt;/span&gt;
./qa-runner.sh --stop
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;They don't need to know what a package manager is, what migrations are, or how Docker works. They paste a command, wait for green checkmarks, and open &lt;code&gt;localhost:3000&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Which Approach Should You Use?
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;Staging Deploy&lt;/th&gt;
&lt;th&gt;Docker + Tunnel&lt;/th&gt;
&lt;th&gt;Local Runner Script&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Wait time&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;10-15 min per deploy&lt;/td&gt;
&lt;td&gt;Build time + tunnel latency&lt;/td&gt;
&lt;td&gt;Seconds (already running)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;QA needs to install tools&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;No (if you host it)&lt;/td&gt;
&lt;td&gt;Yes (automated)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Performance&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Full speed&lt;/td&gt;
&lt;td&gt;Slow (tunnel overhead)&lt;/td&gt;
&lt;td&gt;Native speed&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;QA independence&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Medium (waits for deploys)&lt;/td&gt;
&lt;td&gt;Low (depends on you)&lt;/td&gt;
&lt;td&gt;High (runs on their machine)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Branch switching&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;New deploy cycle&lt;/td&gt;
&lt;td&gt;Rebuild containers&lt;/td&gt;
&lt;td&gt;Git checkout + restart&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Parallel testing&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Need multiple environments&lt;/td&gt;
&lt;td&gt;One tunnel at a time&lt;/td&gt;
&lt;td&gt;Each tester runs their own&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Setup complexity&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;High (CI/CD pipeline)&lt;/td&gt;
&lt;td&gt;High (Dockerfiles, nginx)&lt;/td&gt;
&lt;td&gt;Medium (one bash script)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Best for&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Final verification, demos&lt;/td&gt;
&lt;td&gt;Remote testers, CI/CD&lt;/td&gt;
&lt;td&gt;Day-to-day QA testing&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Staging environments are the standard answer, but they're &lt;strong&gt;slow feedback loops&lt;/strong&gt; — every branch change means another deploy cycle. The Docker + tunnel approach removes the deploy wait but introduces tunnel latency and keeps QA dependent on you. The local script gives QA &lt;strong&gt;full independence&lt;/strong&gt; with native speed.&lt;/p&gt;

&lt;h2&gt;
  
  
  Lessons Learned
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Don't make QA depend on you&lt;/strong&gt; — if the tester needs to ask you to start the environment, you're the bottleneck&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Install tools for them&lt;/strong&gt; — prerequisite checkers that auto-install save hours of back-and-forth&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Safe defaults, explicit destruction&lt;/strong&gt; — never wipe data without &lt;code&gt;--fresh&lt;/code&gt; and a confirmation prompt&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Show what's happening&lt;/strong&gt; — colored output with checkmarks and progress indicators builds trust. The tester knows the script is working, not hanging&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Self-update mechanism&lt;/strong&gt; — distributing the script via a Gist with &lt;code&gt;--update&lt;/code&gt; means you can push fixes without the tester doing anything&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The whole script is about 800 lines of bash. It took a day to write and has saved weeks of "hey, can you help me set up the app?" messages.&lt;/p&gt;

&lt;p&gt;The full source for both approaches (local runner script + Docker environment) is on GitHub: &lt;a href="https://github.com/RielJ/qa-runner" rel="noopener noreferrer"&gt;RielJ/qa-runner&lt;/a&gt;&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://rielj.xyz/blog/qa-runner-script-non-technical-testers" rel="noopener noreferrer"&gt;rielj.xyz&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>bash</category>
      <category>devops</category>
      <category>qa</category>
      <category>dx</category>
    </item>
    <item>
      <title>Neovim Treesitter highlighting with sql generic types (Typescript)</title>
      <dc:creator>Riel Joseph</dc:creator>
      <pubDate>Wed, 29 Oct 2025 23:22:52 +0000</pubDate>
      <link>https://dev.to/rieljdev/neovim-treesitter-highlighting-with-sql-generic-types-typescript-4lh1</link>
      <guid>https://dev.to/rieljdev/neovim-treesitter-highlighting-with-sql-generic-types-typescript-4lh1</guid>
      <description>&lt;p&gt;If you’ve ever written raw SQL queries inside TypeScript template literals, you probably love Treesitter’s syntax highlighting for embedded languages like:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;result&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;sql&lt;/span&gt;&lt;span class="s2"&gt;`SELECT * FROM users`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;But what happens when your code starts getting fancy — say, using &lt;strong&gt;generic calls&lt;/strong&gt;, &lt;strong&gt;non-null assertions&lt;/strong&gt;, or &lt;strong&gt;different helper functions&lt;/strong&gt; like &lt;code&gt;tx.sql&lt;/code&gt; or &lt;code&gt;sql&amp;lt;User&amp;gt;&lt;/code&gt;?&lt;/p&gt;

&lt;p&gt;By default, Treesitter doesn’t inject SQL highlighting in these more complex patterns.&lt;br&gt;
In this post, we’ll fix that by writing a &lt;strong&gt;custom Treesitter injection query&lt;/strong&gt; to handle generic TypeScript expressions with &lt;code&gt;sql&lt;/code&gt; and &lt;code&gt;tx&lt;/code&gt;.&lt;/p&gt;


&lt;h2&gt;
  
  
  The Problem
&lt;/h2&gt;

&lt;p&gt;Neovim’s Treesitter injection for SQL works great in the simplest case:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;users&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;sql&lt;/span&gt;&lt;span class="s2"&gt;`SELECT * FROM users`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;…but once you introduce &lt;strong&gt;TypeScript generics&lt;/strong&gt; or &lt;strong&gt;non-null assertions&lt;/strong&gt;, highlighting breaks:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// Generic instantiation&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;result&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;sql&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;User&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="s2"&gt;`SELECT * FROM users`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// Non-null expression&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;result&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;sql&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;User&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;!&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="s2"&gt;`SELECT * FROM users`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The reason?&lt;br&gt;
Treesitter doesn’t recognize that &lt;code&gt;sql&amp;lt;User&amp;gt;&lt;/code&gt; (an &lt;code&gt;instantiation_expression&lt;/code&gt;) still represents a function call for the purpose of language injection.&lt;/p&gt;


&lt;h2&gt;
  
  
  The Fix: Custom Treesitter Injection Query
&lt;/h2&gt;

&lt;p&gt;To solve this, we extend Neovim’s built-in SQL injection rules using a custom &lt;strong&gt;&lt;code&gt;.scm&lt;/code&gt;&lt;/strong&gt; query file.&lt;/p&gt;

&lt;p&gt;Create a file at:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;~/.config/nvim/queries/typescript/injections.scm
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Paste this code:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;;; Extend built-in injections
(call_expression
  function: (non_null_expression
    (instantiation_expression
      (await_expression
        (identifier) @_name)))
  arguments: (template_string) @injection.content
  (#eq? @_name "sql")
  (#set! injection.language "sql")
  (#set! injection.include-children))

;; Handle simpler variants like sql`...` and await sql`...`
(call_expression
  function: [
    (identifier) @_name
    (await_expression (identifier) @_name)
    (instantiation_expression function: (identifier) @_name)
  ]
  arguments: (template_string) @injection.content
  (#eq? @_name "sql")
  (#set! injection.language "sql")
  (#set! injection.include-children))

;; Support tx`...` and tx&amp;lt;User&amp;gt;`...`
(call_expression
  function: (non_null_expression
    (instantiation_expression
      (await_expression
        (identifier) @_name)))
  arguments: (template_string) @injection.content
  (#eq? @_name "tx")
  (#set! injection.language "sql")
  (#set! injection.include-children))

;; Handle simpler variants for tx as well
(call_expression
  function: [
    (identifier) @_name
    (await_expression (identifier) @_name)
    (instantiation_expression function: (identifier) @_name)
  ]
  arguments: (template_string) @injection.content
  (#eq? @_name "tx")
  (#set! injection.language "sql")
  (#set! injection.include-children))
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;






&lt;h2&gt;
  
  
  What This Query Does
&lt;/h2&gt;

&lt;p&gt;Let’s break it down.&lt;/p&gt;

&lt;p&gt;Treesitter parses TypeScript code into syntax nodes like:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;call_expression&lt;/code&gt; — a function call (&lt;code&gt;sql\&lt;/code&gt;...``)&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;instantiation_expression&lt;/code&gt; — a generic function call (&lt;code&gt;sql&amp;lt;User&amp;gt;&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;await_expression&lt;/code&gt; — for &lt;code&gt;await sql\&lt;/code&gt;...``&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;template_string&lt;/code&gt; — your backticked SQL string&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;We’re telling Treesitter:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;“Whenever you see a &lt;code&gt;call_expression&lt;/code&gt; whose function name is &lt;code&gt;sql&lt;/code&gt; or &lt;code&gt;tx&lt;/code&gt;, treat the argument (a template string) as SQL content.”&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;The &lt;code&gt;#set! injection.language "sql"&lt;/code&gt; command tells Neovim to apply SQL highlighting within that string.&lt;/p&gt;

&lt;p&gt;We also include multiple variations to cover:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;sql\&lt;/code&gt;...``&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;await sql\&lt;/code&gt;...``&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;sql&amp;lt;User&amp;gt;\&lt;/code&gt;...``&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;await sql&amp;lt;User&amp;gt;\&lt;/code&gt;...``&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;tx\&lt;/code&gt;...``&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;await tx&amp;lt;User&amp;gt;\&lt;/code&gt;...``&lt;/li&gt;
&lt;/ul&gt;




&lt;h2&gt;
  
  
  Testing It
&lt;/h2&gt;

&lt;p&gt;Once you’ve saved the query, restart Neovim and open a TypeScript file containing SQL template strings.&lt;/p&gt;

&lt;p&gt;Try all these patterns:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;a&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;sql&lt;/span&gt;&lt;span class="s2"&gt;`SELECT * FROM users`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;b&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;sql&lt;/span&gt;&lt;span class="s2"&gt;`SELECT * FROM posts`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;c&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;sql&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;User&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="s2"&gt;`SELECT * FROM users`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;d&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;tx&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;Post&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="s2"&gt;`SELECT * FROM posts`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;e&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;tx&lt;/span&gt;&lt;span class="s2"&gt;`SELECT * FROM comments`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If everything worked, your SQL inside backticks should now be properly highlighted in &lt;strong&gt;all cases&lt;/strong&gt;.&lt;/p&gt;




&lt;h2&gt;
  
  
  Bonus Tip: Reload Queries Without Restarting Neovim
&lt;/h2&gt;

&lt;p&gt;You can quickly reload queries after editing them using:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight viml"&gt;&lt;code&gt;&lt;span class="p"&gt;:&lt;/span&gt;TSBufReload
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;or restart Treesitter highlighting manually with:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight viml"&gt;&lt;code&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="k"&gt;edit&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;






&lt;h2&gt;
  
  
  Conclusion
&lt;/h2&gt;

&lt;p&gt;By extending Treesitter’s injection rules, we’ve made Neovim smart enough to recognize complex TypeScript SQL calls — even with generics, awaits, or alternate function names.&lt;/p&gt;

&lt;p&gt;This small tweak can massively improve readability and developer experience when working with query-heavy TypeScript codebases.&lt;/p&gt;




&lt;p&gt;&lt;strong&gt;TL;DR&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Create &lt;code&gt;queries/typescript/injections.scm&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;Paste the SQL injection query above&lt;/li&gt;
&lt;li&gt;Enjoy perfect SQL highlighting for all your &lt;code&gt;sql&lt;/code&gt; and &lt;code&gt;tx&lt;/code&gt; template strings&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>sql</category>
      <category>tooling</category>
      <category>typescript</category>
    </item>
    <item>
      <title>Solana Raydium SDK Swap Example Typescript with Magic SDK</title>
      <dc:creator>Riel Joseph</dc:creator>
      <pubDate>Wed, 05 Jun 2024 06:03:11 +0000</pubDate>
      <link>https://dev.to/rieljdev/solana-raydium-sdk-swap-example-typescript-with-magic-sdk-1hc7</link>
      <guid>https://dev.to/rieljdev/solana-raydium-sdk-swap-example-typescript-with-magic-sdk-1hc7</guid>
      <description>&lt;h3&gt;
  
  
  Solana Raydium SDK Swap Example in TypeScript with Magic SDK
&lt;/h3&gt;

&lt;p&gt;In this tutorial, we'll demonstrate how to perform a token swap on Solana using the Raydium SDK in TypeScript. Additionally, we'll show how to use the Magic SDK for signing transactions. We'll also include a method to convert SOL to lamports using Solana's web3.js library.&lt;/p&gt;

&lt;h2&gt;
  
  
  Prerequisites
&lt;/h2&gt;

&lt;p&gt;Ensure you have the following installed:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Node.js and npm&lt;/li&gt;
&lt;li&gt;Magic SDK&lt;/li&gt;
&lt;li&gt;Solana web3.js&lt;/li&gt;
&lt;li&gt;Raydium SDK&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Step 1: Install Required Libraries
&lt;/h2&gt;

&lt;p&gt;First, install the necessary libraries:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;npm &lt;span class="nb"&gt;install&lt;/span&gt; @solana/web3.js @raydium-io/raydium-sdk @magic-sdk/admin
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Step 2: Import Necessary Modules
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;Connection&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;PublicKey&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;SystemProgram&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;TransactionInstruction&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;LAMPORTS_PER_SOL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;ComputeBudgetProgram&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;VersionedTransaction&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;TransactionMessage&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;@solana/web3.js&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;Liquidity&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;@raydium-io/raydium-sdk&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nx"&gt;Magic&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;@magic-sdk/admin&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Step 3: Setup Magic SDK and Solana Connection
&lt;/h2&gt;

&lt;p&gt;Initialize the Magic SDK and Solana connection:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;magic&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Magic&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;YOUR_MAGIC_API_KEY&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="c1"&gt;// Replace with your Magic API key&lt;/span&gt;
  &lt;span class="na"&gt;extensions&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
   &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;SolanaExtension&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
     &lt;span class="na"&gt;rpcUrl&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;YOUR RPC URL&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// Replace with your RPC URL&lt;/span&gt;
   &lt;span class="p"&gt;})&lt;/span&gt;
  &lt;span class="p"&gt;],&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt; 
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;connection&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Connection&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;YOUR RPC URL&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="c1"&gt;// Replace with your RPC URL&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;wallet&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;magic&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;wallet&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// Magic wallet instance&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Step 4: Helper Functions
&lt;/h2&gt;

&lt;h4&gt;
  
  
  Add Priority Instructions (Optional)
&lt;/h4&gt;

&lt;p&gt;You can omit this part if the &lt;code&gt;makeSwapInstructionSimple&lt;/code&gt; already has a builtin setup for priority instructions.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;addPriorityInstructions&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;instructions&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;TransactionInstruction&lt;/span&gt;&lt;span class="p"&gt;[]):&lt;/span&gt; &lt;span class="nx"&gt;TransactionInstruction&lt;/span&gt;&lt;span class="p"&gt;[]&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;modifyComputeUnits&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;ComputeBudgetProgram&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;setComputeUnitLimit&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;units&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;1000000&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;addPriorityFee&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;ComputeBudgetProgram&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;setComputeUnitPrice&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt; &lt;span class="na"&gt;microLamports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;1000&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="nx"&gt;instructions&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;unshift&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;modifyComputeUnits&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;addPriorityFee&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;instructions&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h4&gt;
  
  
  Create Fee Transfer Instruction (Optional)
&lt;/h4&gt;

&lt;p&gt;If you want to have a fee usage mechanism you can add the instruction that is returned in this function.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;createFeeTransferInstruction&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;amount&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;feeWallet&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;PublicKey&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;userWallet&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;PublicKey&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;TransactionInstruction&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;feeAmount&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ceil&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;amount&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mf"&gt;0.0005&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;feeAmountInLamports&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;feeAmount&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="nx"&gt;LAMPORTS_PER_SOL&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;SystemProgram&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;transfer&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="na"&gt;fromPubkey&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;userWallet&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;toPubkey&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;feeWallet&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;lamports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;feeAmountInLamports&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;```



## Step 5: Perform Swap Transaction

Integrate the helper functions to perform the swap:



```&lt;/span&gt;&lt;span class="nx"&gt;typescript&lt;/span&gt;
&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;performSwap&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="nx"&gt;amountIn&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nx"&gt;minAmountOut&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;number&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nx"&gt;poolKeys&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;any&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nx"&gt;userTokenAccounts&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;any&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nx"&gt;feeWallet&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;PublicKey&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nx"&gt;fixedSide&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;any&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;swapTransaction&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;Liquidity&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;makeSwapInstructionSimple&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
    &lt;span class="nx"&gt;connection&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nx"&gt;poolKeys&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;userKeys&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="na"&gt;tokenAccounts&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;userTokenAccounts&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="na"&gt;owner&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;wallet&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;publicKey&lt;/span&gt;
    &lt;span class="p"&gt;},&lt;/span&gt;
    &lt;span class="nx"&gt;amountIn&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="na"&gt;amountOut&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;minAmountOut&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nx"&gt;fixedSide&lt;/span&gt;
  &lt;span class="p"&gt;});&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;recentBlockhash&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;connection&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getLatestBlockhash&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;instructions&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;swapTransaction&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;innerTransactions&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;].&lt;/span&gt;&lt;span class="nx"&gt;instructions&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;Boolean&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;feeTransferInstruction&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;createFeeTransferInstruction&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;amountIn&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;feeWallet&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;wallet&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;publicKey&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="nx"&gt;instructions&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;feeTransferInstruction&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

  &lt;span class="nx"&gt;instructions&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;addPriorityInstructions&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;instructions&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;versionedTransaction&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;VersionedTransaction&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;TransactionMessage&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
      &lt;span class="na"&gt;payerKey&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;wallet&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;publicKey&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="na"&gt;recentBlockhash&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;recentBlockhash&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;blockhash&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="na"&gt;instructions&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;instructions&lt;/span&gt;
    &lt;span class="p"&gt;}).&lt;/span&gt;&lt;span class="nf"&gt;compileToV0Message&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
  &lt;span class="p"&gt;);&lt;/span&gt;

  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;signedTransaction&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;magic&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;wallet&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;signTransaction&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;versionedTransaction&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;signedTransaction&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; 
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Step 6: Example Usage
&lt;/h2&gt;

&lt;p&gt;Call the performSwap function with the necessary parameters:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;async &lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;amountInSOL&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// Example amount in SOL&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;amountInLamports&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;amountInSol&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="nx"&gt;LAMPORTS_PER_SOL&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;minAmountOut&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;500000&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// Example minimum amount out&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;poolKeys&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{};&lt;/span&gt; &lt;span class="c1"&gt;// Replace with actual pool keys&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;userTokenAccounts&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{};&lt;/span&gt; &lt;span class="c1"&gt;// Replace with actual user token accounts&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;feeWallet&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;PublicKey&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;YOUR_FEE_WALLET_ADDRESS&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="c1"&gt;// Replace with your fee wallet address&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;fixedSide&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{};&lt;/span&gt; &lt;span class="c1"&gt;// Replace with actual fixed side information&lt;/span&gt;

  &lt;span class="k"&gt;try&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;signedTransaction&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;performSwap&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
      &lt;span class="nx"&gt;amountInLamports&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nx"&gt;minAmountOut&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nx"&gt;poolKeys&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nx"&gt;userTokenAccounts&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nx"&gt;feeWallet&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nx"&gt;fixedSide&lt;/span&gt;
    &lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;log&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Signed Transaction:&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;signedTransaction&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;signature&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;connection&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nf"&gt;sendRawTransaction&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;Buffer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="k"&gt;from&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;swapTransaction&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;rawTransaction&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;base64&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;recentBlockhashForSwap&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;connection&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getLatestBlockhash&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;finalized&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;confirmation&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;connection&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;confirmTransaction&lt;/span&gt;&lt;span class="p"&gt;({&lt;/span&gt;
      &lt;span class="na"&gt;signature&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;...&lt;/span&gt;&lt;span class="nx"&gt;recentBlockhashForSwap&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;},&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;confirmed&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;confirmation&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;err&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Error buying token:&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;confirmation&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;err&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;log&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Confirmed! Transaction ID:&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;`https://solscan.io/tx/&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;


  &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;catch &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;error&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Error performing swap:&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;error&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;})();&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Conclusion
&lt;/h2&gt;

&lt;p&gt;In this guide, we've shown how to perform a token swap using the Raydium SDK with the Magic SDK for transaction signing in TypeScript. We also included how to convert SOL to lamports and add a priority fee to your transactions. This approach ensures that your swaps are processed efficiently while also including a usage fee.&lt;/p&gt;

</description>
      <category>web3</category>
      <category>solana</category>
      <category>magicsdk</category>
      <category>raydiumsdk</category>
    </item>
  </channel>
</rss>
