Usuba is a local model trained on, and built for, Omarchy.

Why it’s called Usuba

AI can struggle building Omarchy plugins

Omarchy changes fast. So fast that it outpaces model development, leaving them to guess. We’re closing that gap for Omarchy developers.

• 26 full plugins from a description
• 6 add a panel to a bar widget
• 12 pieces of larger multi-file plugins
• 5 broken manifests to fix

How the 49 test prompts are built, and what counts as working.

Top 6 reasons models struggle

• Inventing APIs that don’t exist

  Calls like Commons.exec or Quickshell.Clipboard that Omarchy doesn’t have.

• Faking the data

  Hardcoded or simulated values instead of real readings.

• Buttons that do nothing

  Clicks that only log to the console.

• Using outdated configs

  Writing old Hyprland .conf syntax into Quattro’s Lua config files.

• Guessing helper script commands

  Calling script subcommands that don’t exist, like tablet.py options.

• Rambling without finishing

  Answers loop, or get cut off before the plugin is complete.

Two parts, one job

Usuba is two complementary parts. Each one covers what the other can’t, and each one makes the other better.

• Available now

  The scripts

  • Plain Python, not AI. These are programmed tests, so the same plugin gets the same answer every time.
  • They load an Omarchy plugin in a real Omarchy environment and run rule checks over its code, then hand back a detailed report: load errors, crashes, missing files, invented APIs, wrong config format and risky commands.
  • Fast, deterministic and free. They exist today.
• In training

  The model

  • A small model, based on Qwen 3.5 9B and about 5.5 GB, trained only on Omarchy plugin data. It runs free and locally on an Omarchy laptop, with no graphics card and no cloud.
  • It does the actual reviewing. It takes the scripts’ report, plus the plugin’s code and what it shows on screen, and judges what the scripts can’t: whether the plugin really works, whether the data is real or faked, whether the buttons do anything, whether it breaks in use, and what Omarchy’s plugin reviewer would flag.
  • Then it explains what to fix. It’s in training now: built to do this, not proven at it.

Free, local, private. No frontier API bill, and nothing leaves your machine.

Usuba Checker Scripts Available now

Plain Python, not AI. Point it at a plugin and it runs the tests: it loads the plugin in a real Omarchy environment, checks the code against the Standard, and tells you what to fix.

• Reads the code

  Flags invented APIs, missing helper scripts, made-up command flags and fake data.

• Runs it for real

  Loads the plugin in a real Omarchy shell and catches load errors and crashes.

• Explains every problem

  Each one comes with a rule id, a plain reason and a fix hint.

• Warns before it fails

  Risky commands a plugin may need are warnings. Only clearly destructive ones, like deleting your home folder, fail.

• Follows a public standard

  The rules are written up as an open standard for what a working Omarchy plugin is.

• Matches real hardware

  It agrees with a laptop running Omarchy on all 90 plugins in our answer key.

$ usuba check ./dropbox-widget
✗ USB-H02   Shows storage numbers, but Dropbox isn’t installed.
  fix: detect Dropbox first, and show an empty state without it.
✗ USB-B02   Calls xdotool, which doesn’t exist on Omarchy.
  fix: use hyprctl for window info instead.
⚠ USB-S01   Writes outside the plugin directory (~/.cache/dropbox-widget). Review it.

2 problems, 1 warning

Usuba Checker Model In training

The Usuba Checker Model is trained only on Omarchy plugins we’ve verified with the scripts and tested on real Omarchy hardware. It is built to review a plugin the way an experienced Omarchy reviewer would: not just that it loads, but that it really works.

• Based on Qwen 3.5 9B
• Runs at 4-bit, about 5.5 GB of weights
• On a typical 32 GB laptop, no graphics card
• Trained only on Omarchy plugin data
• 1,400+ published plugins swept so far

The Usuba Checker Model is in training. There are no published model results yet.

How Usuba is built

Usuba isn’t trained on what models already write. It’s trained on what actually runs on Omarchy.

1. 1Collect pluginsEvery Omarchy plugin we can find, from GitHub and the plugin catalog.
2. 2Run themEach one through the Checker Scripts, and on a real Omarchy laptop.
3. 3Mine what brokeGitHub issues and plugin review comments, read for how plugins really fail.
4. 4Write it downEvery real failure becomes a rule in the Standard and a training example.
5. 5Train the modelThe Usuba Checker Model learns from verified plugins and real failures.

Why not just…

The three shortcuts people ask about, and what each one misses.

• Why not write a better prompt?

  • A prompt can’t tell the model whether its plugin actually loads, renders or responds.
  • Omarchy changes too fast for any fixed prompt to keep up.
  • Even with a good prompt, models fill gaps with confident guesses.

• Why not use an agent skill?

  • A skill helps, and we use one, but it still needs a frontier model to run it.
  • Strong models improved a lot with feedback. Weaker models learned to fool the checks instead.
  • A skill gives the model facts, not the judgment to spot fake data or dead buttons.

• Why not use a better model?

  • The best model we tested got only 21 of 49 plugins working on the first try.
  • Frontier models cost money per use, need the cloud, and send your code out.
  • Usuba is built to run free on your laptop, with nothing leaving your machine.

Thanks to Omacom Sponsors

Usuba is an independent project made possible in particular by a few of the following Omacom Foundation sponsors.

• The Omacom Foundation

  The Omacom Foundation funds the Omarchy stack Usuba builds on, including Hyprland, Quickshell and mise. Thank you for funding tools the rest of us get to use for free.

• Inspired by Coinbase

  Brian Armstrong wrote about fine-tuning an open-weight model on internal data at Coinbase. Usuba is the same idea at a smaller scale: a specialist model trained on real Omarchy plugin data.

• Hosted by Cloudflare

  This website is hosted by Cloudflare.

• Smoke tested on Dell hardware

  Hardware smoke testing was done on a Dell Latitude laptop.

• Tasks on Fizzy by 37signals

  Agent work on this project is managed using Fizzy.

• Models that helped build this

  Meta, SpaceXSI, OpenRouter and OpenAI models all helped build this.

Usuba is an independent project. It is not affiliated with, or endorsed by, the Omacom Foundation.