Where I build and maintain the tools that run my machine.
A personal collection of macOS automation scripts, AI agent tooling, and anything else that makes my setup work smarter. Equal parts reference for myself and resource for anyone who finds it useful.
git clone git@github.com:mustafa.shoaib/workshop.git <repo root>
cd <repo root>
bash setup.sh
source ~/.zshrc
While it runs, setup.sh shows each step’s progress live, then collapses every successful step to one summary line. The full detail of the last run, including every tool’s own output, is written to ~/.workshop-setup.log.
setup.sh first checks for Xcode Command Line Tools. If they’re missing, it stops and tells you to run xcode-select --install yourself, then re-run it.
Everything beyond a small core is opt-in. The core always runs: the Xcode check, Homebrew with fzf and gh, and a check for Docker. On the first run, a menu lists the optional components, all unticked:
| Component | What it sets up |
|---|---|
| Shell | Prompt, aliases, git functions and db/ tools, loaded from ~/.zshrc, plus a global gitignore for .dbtoolsrc |
| Node | nvm and a default Node version (also installed when Claude or VS Code is picked, since both need it) |
| Hammerspoon | Hotkeys and app automation |
| BetterMouse | Mouse and keyboard remaps |
| Claude | CLAUDE.md, skills, permissions and the video-vision MCP server |
| VS Code | Settings, keybindings and extensions |
| Chrome | The Keepa price-history extension |
| AltTab | A headless window switcher that runs at login (macos/alt-tab/) |
| Scripts | The PDF invoice tools in scripts/ |
Your picks are saved in ~/.config/workshop/components, and later runs reuse them without asking. Components you didn’t pick show as skipped -- not selected.
bash setup.sh --choose shows the menu again, with your previous picks ticked.bash setup.sh --all installs everything without the menu, and leaves your saved picks as they are.Any machine-specific config can still live in ~/.zshrc alongside it as normal.
Each directory has its own README with the full detail — this is just the map.
| Directory | What’s there |
|---|---|
shell/ |
Entry point sourced by ~/.zshrc, general aliases, prompt |
db/ |
Docker/Alembic DB tooling (ddb, dmig) — config-driven, plus a gitignored slot for machine-specific hook implementations |
git/ |
Fzf-powered git functions: branch, rebase, push, PR checkout, and a GitHub/SSH helper (gtools) |
hammerspoon/ |
macOS automation — hotkeys, Finder shortcuts, login hooks |
vscode/ |
Synced settings and keybindings, the extension list, and two custom extensions |
chrome/keepa-lookup/ |
Chrome extension — one-click jump from an Amazon listing to its Keepa price-history page |
ai/ |
Global Claude instructions, symlinked to ~/.claude/CLAUDE.md so changes stay version-controlled |
macos/alt-tab/ |
Headless, two-shortcut fork of AltTab — built and installed automatically by setup.sh |
macos/bettermouse/ |
Version-controlled BetterMouse config export — currently also carries the screenshot/recording shortcuts Hammerspoon can’t handle right now |
macos/manual-setup.md |
macOS settings that can’t be automated — check this on any new machine |
macos/screen-recording-internal-audio.md |
Free screen recording with internal computer audio, using BlackHole |
scripts/ |
Standalone utility scripts, on $PATH automatically via shell/init.zsh |
More to come as the workshop grows.