Kitout Mac setup as declared state

Declare your Mac setup. Apply only what changed.

Kitout checks YAML against the Mac in front of you, shows a readable plan, and applies only the resources that need work.

Install Kitout See the first run
$ kitout apply

Status remains read-only. Apply always rechecks current state before changing anything.

kitout apply 2 changed · 2 unchanged 
$ kitout apply

Kitout is planning changes for your Mac setup...
Config: ./kitout.yaml

> Inspecting Homebrew packages...
> Checking directory: ~/.config...

Applying changes:
> Installing formula gh...
> Cloning repository ~/code/example...

✓ done brew: gh — installed formula
✓ done repo: ~/code/example — cloned repository
✓ ok directory: ~/.config — directory exists
✓ ok cask: ghostty — cask is installed

Summary: 2 changed, 2 unchanged
current state checked needed changes applied
Apply rechecks state, makes the needed changes, and leaves a readable result for every declared resource.

Install Kitout.

Homebrew is the shortest path. Build from source when you are working on Kitout itself or want to inspect the code first.

Homebrew 
brew tap vwall/kitout
brew install kitout
Build from source 
git clone https://github.com/vwall/kitout.git
cd kitout
go install ./cmd/kitout

Your first Kitout run.

Initialize a config, check prerequisites, inspect current state, preview planned changes, then apply when you are ready.

  1. 1

    Create the config

    Create or reuse ./kitout.yaml in the setup repo.

    kitout init
  2. 2

    Check prerequisites

    Check macOS, Homebrew, Git, shell, config validity, and paths.

    kitout doctor
  3. 3

    Inspect current state

    See satisfied, missing, changed, skipped, and failed resources.

    kitout status
  4. 4

    Preview before apply

    Preview changes without filesystem writes or shell execution.

    kitout apply --dry-run
  5. 5

    Apply reviewed changes

    Recheck current state and apply only the resources that need work.

    kitout apply

Other config: --config /path/to/kitout.yaml · Detailed guide: first real run

YAML that explains itself.

A small config can describe the tools, files, repositories, and safeguards that make a Mac feel like yours. Keep it in any setup repository—dotfiles or otherwise. Relative paths resolve from the folder containing the selected config, not from your shell's working directory.

kitout.yaml 
version: 1

brew:
  packages:
    - git
    - gh
    - asdf
  casks:
    - font-monaspace-nf

asdf:
  plugins:
    - name: nodejs
      url: https://github.com/asdf-vm/asdf-nodejs.git
      versions:
        - 24.18.0
  tool_versions:
    - path: ~/.tool-versions
      tools:
        nodejs: 24.18.0

directories:
  - ~/code
  - ~/.config

repos:
  - path: ~/code/example
    url: git@github.com:example/example.git

symlink_groups:
  - source_root: ./home
    target_root: "~"
    target_prefix: "."
    paths:
      - zshrc
      - gitconfig

security:
  filevault:
    required: true
  firewall:
    enabled: true

Every run stays inspectable.

Kitout uses the same plain language from the first check through apply, so current state, planned work, completed changes, and blockers remain easy to distinguish.

Status names current state

Every resource reports satisfied, missing, changed, skipped, or failed.

Preview names planned work

See the intended changes without filesystem writes or shell execution.

Apply reports the result

Only resources that need work are applied, and risky changes ask first.

Doctor explains blockers

Prerequisites fail early with a concrete next step instead of noisy checks.

fail: Homebrew Homebrew is not available

fix: Install Homebrew, then rerun kitout doctor.

fail: Path permissions 1 configured write target(s) may not be writable

fix: Fix ownership or permissions for the listed paths, then rerun kitout doctor.

Agent context, when you want it.

Agent guidance is optional. Add it to a setup repo when Codex or another coding agent needs durable context without permission to make hidden changes.

Optional agent setup 
kitout init --agents
kitout context
kitout status --json
kitout explain 'symlink:/Users/example/.zshrc'
context

Lists declared resources and safe commands without live checks.

json

Feeds stable status reports to agents and other tools.

approval

Real apply, shell resources, and risky changes stay human-approved.

Optional workflow: agent context guide · Release: latest release

Go deeper in the docs.

Follow the practical guides, read the complete command and config references, or inspect the architecture behind each resource.