kitout-recipes

A cookbook of reusable kitout steps for common macOS workstation tasks — the things without a dedicated step type, so people keep rewriting the same defaultbrowser/duti/defaults snippets from scratch.

Each recipe is browse-and-copy: read it, copy it into your own config, own it. kitout never downloads or runs anything from here — no fetch command, no remote execution. Every recipe ships with docs, a test, and an honest Security note.

New to kitout? A recipe is a step you paste into your kitout.toml — see the manifest reference.

How to use a recipe

1. Open recipes/<name>/ and read its README.md — especially Requirements and Security.
2. If it's a script recipe, copy <name>.sh into your config's steps/ dir.
3. Paste the [[step]] from step.toml into your manifest; adjust id/needs and any hardcoded value (which browser, which name) to taste.
4. kitout plan to preview, kitout apply to converge.

Recipes

Recipe	Step	What it does
1password-ssh-agent	block-in-file	Route SSH authentication through the 1Password SSH agent so your key
accent-color	defaults	Set the macOS accent color (buttons, selected controls, checkboxes)
agents-md-global	block-in-file	Seed a global AGENTS.md — the house rules every coding agent reads
app-firewall	script	Enable macOS's built-in application firewall and stealth mode.
asdf	block-in-file	Activate asdf — the multi-language version manage
atuin	block-in-file	Initialize Atuin — a SQLite-backed replacement for y
auto-security-updates	script	Enable automatic installation of Apple's security updates — without
aws-profile	block-in-file	Scaffold a named AWS profile in ~/.aws/config — region, output format,
bat-config	block-in-file	Configure bat's color theme and make i
bun	command-if-missing	Install bun — the fast, all-in-one JavaScript/TypeScri
caps-to-control	script	Remap Caps Lock → Control, and make it stick across reboots.
cargo-env	block-in-file	Source Rust's own ~/.cargo/env file — the shell wiring that puts `carg
claude-statusline	json-merge	Seed a Claude Code status line — model, context-window usage, and cu
codex-statusline	toml-merge	Seed the Codex CLI TUI status line — the footer showing model, appro
colima	script	Start Colima as your local Docker
commit-signing-1password	script	Sign your git commits and tags with an SSH key that lives in **1Password
commit-signing-gpg	script	Sign your git commits and tags with a GPG key — the classic path to
commit-signing-ssh	script	Sign your git commits and tags with an SSH key — the modern, no-GPG
computer-name	script	Set the Mac's name consistently — macOS stores it in three places th
custom-dns	script	Set the DNS resolvers for a network service (Wi-Fi, Ethernet, …) to
dark-mode-auto	script	Set the macOS system appearance to Auto (light by day, dark by night
debloat-apple-apps	absent	Remove Apple's bundled iLife apps (GarageBand, iMovie) that most dev mac
default-archive	script	Set the default app that opens .zip archives — route them to Keka, The
default-browser	script	Set your default web browser.
default-editor	script	Open text and source-code files in your editor (VS Code, Sublime, Zed, …
default-image-viewer	script	Set the default app that opens images (Preview, XnView, Acorn, …) instea
default-mail	script	Set your default mailto: client — the app that opens when you click
default-pdf	script	Set the default app that opens PDFs (Preview, Skim, a browser, …).
default-terminal	script	Make your terminal the default app for shell scripts (so double-clicking
deno	command-if-missing	Install Deno — a JavaScript/TypeScript/WebAssembly r
direnv-hook	block-in-file	Hook direnv into zsh so per-directory .envrc fil
disable-autocorrect	defaults	Turn off macOS's "smart" text substitutions — the ones that mangle code
disable-startup-chime	script	Silence the macOS startup chime — the sound the Mac plays at power-o
dock-items	script	Curate the macOS Dock — pin the apps you want, remove the ones you don't
dock-magnification	defaults	Turn on Dock magnification: icons grow as the pointer passes over them,
dock-minimal	defaults	A minimal, stay-out-of-the-way Dock: auto-hide with **no reveal dela
expanded-save-panels	defaults	Make macOS Save and Print dialogs open in their expanded for
fast-keyboard	defaults	Make the keyboard repeat as fast as macOS allows, and turn a held key in
filevault-enable	script	Enable FileVault — full-disk encryption of the startup volume.
finder-power-user	defaults	A sensible Finder preference set for people who live in the filesystem.
fnm	block-in-file	Activate fnm (Fast Node Manager) — a fa
fzf-setup	script	Enable fzf's zsh integration — the **
gatekeeper-on	script	Ensure Gatekeeper is enabled — the safe direction only. This recipe
gh-cli-config	script	Set sane GitHub CLI (gh) defaults, idempoten
git-commit-template	script	Seed a Conventional Commits skeleton as your global git commit messa
git-conditional-identity	script	Use your personal git identity everywhere, except under ~/work/, where
git-delta	script	Render git diffs through [delta
git-lfs	script	Enable Git LFS for your user by installing its gl
git-maintenance	script	Enable git's background maintenance for a repo — `git maintenance st
git-sensible-defaults	script	A set of opinionated global git config defaults most people set eventu
gitignore-global	script	Install a curated global gitignore (OS cruft, editor/IDE dirs, local
gpg-tty	block-in-file	Point GPG's pinentry at your current terminal, so passphrase prompts sho
hosts-block	script	Manage a small, user-editable ad/tracker blocklist in /etc/hosts —
hot-corners	defaults	Assign screen-corner actions (Mission Control, Lock Screen, Desktop, etc
jenv	block-in-file	Activate jenv — a lightweight Java version manage
krew	script	Install krew, the plugin manager for `kubect
kubectl-context	script	Set your default kubectl context to a named context that already lives
less-config	block-in-file	Sensible default flags for less — raw colors survive, short output doe
lockscreen-immediate	script	Require your password immediately when the screen locks or the scree
menu-bar-autohide	defaults	Auto-hide the menu bar, reclaiming that strip of screen until you move t
menu-clock	defaults	Force a 24-hour clock in the menu bar (and everywhere macOS formats
mise	block-in-file	Activate mise — the polyglot runtime version man
mission-control-defaults	defaults	Keep your Spaces in a stable, predictable order and group windows by app
modern-cli-aliases	block-in-file	Swap the classic CLI tools for their modern replacements in interactive
natural-scroll-off	defaults	Turn off "natural" scrolling — scrolling down moves you down the page/co
npm-global-prefix	block-in-file	Point npm's global install prefix at a directory you own, so `npm in
oh-my-zsh	script	Install Oh My Zsh unattended into ~/.oh-my-zsh, wi
pipx	script	Put pipx's app directory (~/.local/bin) on you
pnpm-home	block-in-file	Put pnpm's global bin directory (PNPM_HOME) on PATH, so packages ins
pre-commit-global	script	Make every future git init/git clone install [pre-commit
press-and-hold-off	defaults	Disable the hold-a-key accent-character popover — holding a key repe
proxy-env	block-in-file	Seed proxy environment-variable placeholders into ~/.zshrc — comme
pyenv	script	Set up pyenv — the Python version mana
rbenv	block-in-file	Initialize rbenv — the Ruby version ma
rclone-remote	block-in-file	Scaffold the shell environment rclone needs to unl
reduce-motion	defaults	Turn on Reduce Motion: cuts the zoom/parallax/Spaces-switch animatio
reduce-transparency	defaults	Turn on Reduce transparency — make the menu bar, Dock, sidebars, Not
remote-login-off	script	Ensure Remote Login (macOS's built-in SSH server, sshd) is off
restic-scaffold	block-in-file	Scaffold the shell environment restic needs — repo
rosetta	script	Install Rosetta 2 on Apple Silicon so x86_64-only apps and tools run
rustup	command-if-missing	Install rustup — the official Rust toolchain instal
screenshots	script	Save screenshots to ~/Screenshots instead of littering the Desktop
scroll-bars-always	defaults	Always show scroll bars, instead of macOS hiding them until you scroll (
sdkman	block-in-file	Wire SDKMAN! — the SDK manager for Java, Kotlin, Gr
shared-skills-dirs	script	One shared home for agent skills — drop a skill once, every coding a
sleep-settings	script	Set display/disk sleep timers and disable Power Nap, via pmset.
ssh-config-github	script	Add a ready-to-use github.com Host block to ~/.ssh/config and **
ssh-keepalive	block-in-file	Stop idle SSH sessions from dropping — a Host * block with keepali
ssh-key	script	Generate a personal ed25519 SSH key if you don't have one, then load
stage-manager-off	defaults	Turn Stage Manager off — the same switch as the Control Center toggl
starship-preset	script	Seed ~/.config/starship.toml with one of [Starship
tap-to-click	defaults	Enable tap-to-click — tap the trackpad to click, no physical press n
tfenv	script	Install tfenv, a Terraform version m
three-finger-drag	defaults	Enable three-finger drag — sweep three fingers on the trackpad to dr
time-machine-exclusions	script	Exclude dev-cruft directories (caches, build output) from Time Machine s
tmux-tpm	script	Install the [Tmux Plugin Manager (TPM)
touchid-sudo	script	Authenticate sudo with Touch ID (and a paired Apple Watch, if you
uv	command-if-missing	Install uv — Astral's fast, Rust-built Pyt
volta	block-in-file	Wire Volta — a JavaScript tool manager that pins
vscode-extensions	script	Install a user-editable list of VS Code extensions, idempotently.
vscode-settings	json-merge	Seed a handful of sane defaults into VS Code's user settings.json
xcode-command-line-tools	script	Ensure the Xcode Command Line Tools — clang, make, git, system
zoxide	block-in-file	Initialize zoxide — a smarter `
zsh-history-opts	block-in-file	A big, shared, deduplicated zsh command history — every session sees eve

This is a machine-drafted catalog, adversarially reviewed and gated (shellcheck + kitout validate on every recipe). Privileged/destructive ones warrant a read before you rely on them.

Contributing

See RECIPE-FORMAT.md. A recipe needs docs, a test.bats, and a ## Security section, and must pass shellcheck + its test in CI. PRs welcome — recipes that run on other people's machines get reviewed accordingly.