Introducing Utilz: A Simple Script Framework for macOS

Source: Photo by Gabriel Heinzer on Unsplash

[ED: If you have a messy ~/bin directory full of scripts you've been dragging around for years, this might be for you.]

The Itch

I've been using Claude Code to help me automate various macOS tasks - setting desktop backgrounds, managing folder icons, clipboard operations, that sort of thing. Over the years I've accumulated a collection of scripts in my ~/bin directory that I drag from machine to machine. You probably have something similar.

The problem was that my ~/bin was a mess. Scripts from 2015 sitting next to scripts from last week. Some had help text, some didn't. Some I remembered how to use, some required reading the source. No tests, inconsistent error handling, and every time I set up a new machine I'd spend time figuring out which scripts actually still worked.

I wanted something simple:

Consistent help documentation across all scripts
A way to test that things actually work
Shared utility functions so I'm not copy-pasting the same error handling code
Easy to clone to a new machine and have everything just work
Room to add new scripts without creating more mess

I didn't need a package manager or a plugin system or cloud sync. Just some basic scaffolding to keep things tidy.

The Solution

Hence: Utilz was born.

It's a bash framework built around a single dispatcher pattern. All utilities are symlinks to one dispatcher script (bin/utilz), which routes to the appropriate implementation. Think of it as a command palette for your personal automation.

# All these are the same executable
bin/utilz -> dispatcher
bin/clipz -> utilz
bin/macoz -> utilz
bin/gitz -> utilz

When you run clipz copy, the dispatcher detects you invoked it as "clipz" and executes opt/clipz/clipz with your arguments.

What's Inside

The framework provides a few utilities I've built so far:

clipz - Cross-platform clipboard operations (macOS/Linux)
macoz - macOS utilities (set desktop background, set folder icons)
cryptz - Quick file encryption/decryption wrapper around openssl
gitz - Git helpers (recursive repository status)
mdagg - Markdown aggregator for combining multiple files
retry - Retry commands until they succeed

Each utility gets:

Automatic help text from markdown files
A testing framework (BATS)
Shared functions for logging, error handling, YAML parsing
Consistent command-line interface

The Nice Parts

The thing I like most is how easy it is to add new utilities. There's a generator:

utilz generate:utility myutil "Does something useful"

This creates the boilerplate: implementation file, tests, help documentation, and symlink. You just fill in the logic.

All utilities share a common library (opt/utilz/common.sh) with functions for logging, dependency checking, and help rendering. No more copying error handling code between scripts.

Testing Matters

Every utility has tests. This was the thing that surprised me most - how much peace of mind comes from being able to run utilz test and know everything still works. GitHub Actions runs the full test suite on both Ubuntu and macOS on every push.

When I port this to a new machine, I can verify that all my clipboard utilities work, my git helpers function, and my encryption wrapper hasn't broken. It's a small thing, but it eliminates the "does this still work?" question.

The Practical Bit

Here's what setup looks like:

git clone https://github.com/matthewsinclair/utilz.git
cd utilz
export UTILZ_HOME="$PWD"
export PATH="$UTILZ_HOME/bin:$PATH"

# Verify everything works
utilz doctor
utilz test

That's it. All your scripts available, all documentation accessible via utilz help, all tests passing.

Trade-offs

This isn't trying to be comprehensive. It's bash scripts for personal automation. No Windows support. No elaborate packaging. No plugin marketplace. It does one thing: provides scaffolding for organizing personal utilities in a way that makes them maintainable across machines.

If you're looking for a professional CLI framework, there are better options. If you want to clean up your messy ~/bin directory and have tests for your automation scripts, this might work for you.

The Claude Code Angle

I built this with Claude Code doing the heavy lifting. It helped structure the dispatcher, wrote the test harness, generated documentation, and set up CI/CD. The interesting part was collaborating on the design - I knew what I wanted, Claude Code knew how to implement it cleanly.

This feels like a good use case for AI-assisted development: taking a clear but informal idea ("I want my scripts organized") and turning it into something structured without over-engineering it.

Using It

The code is on GitHub: matthewsinclair/utilz

If you have a collection of scripts you've been dragging around and want to tidy them up, take a look. Fork it, adapt it, make it yours. The framework is intentionally simple - read the code, understand it, modify it.

I'm finding it useful. Maybe you will too.

Regards,
M@

[ED: If you'd like to sign up for this content as an email, click here to join the mailing list.]

First published on matthewsinclair.com and cross-posted on Medium.