Kaizen is an opinionated, keyboard-driven developer environment manager for macOS and Linux. It installs native packages, runtime tools, and dotfiles from one feature configuration.

Its components are deliberately small:

• Python 3.11+ orchestrates the workflow;
• Homebrew, dnf, or apt installs system packages;
• mise installs runtimes and global development tools;
• chezmoi renders and applies dotfiles.

Requires Git and curl. The installer reuses Python 3.11+ when available or installs an isolated Python 3.12 runtime through standalone uv.

curl -fsSL https://raw.githubusercontent.com/artawower/kaizen/master/install.sh | sh

The remote script clones Kaizen to ~/.local/share/kaizen, creates ~/.config/kaizen/config.toml, configures chezmoi, and installs a ~/.local/bin/kaizen wrapper pinned to the selected Python interpreter. Native package managers are checked only by commands that use them. On macOS, Kaizen offers to run the official Homebrew installer when required.

On a first install, the script opens the generated config in your editor ($VISUAL, $EDITOR, or vi) so you can replace the placeholder identity and enable features. After you save and quit, the installer offers to run kaizen sync immediately. A config still containing placeholder values falls back to manual instructions, as do sessions without a controlling TTY. If you decline the prompt or skip editing, run later:

kaizen sync

If ~/.local/bin is not yet on PATH, the installer prints the equivalent command with its full path.

features/<name>/
  packages.toml
  mise.toml
  post_install.py
  variants/<name>/
    packages.toml
    mise.toml
    post_install.py

dotfiles/             # chezmoi source
dotfiles/.chezmoidata.toml
config.example.toml
kaizen.py

Only packages.toml is required. The remaining feature and variant files are optional.

kaizen              # show command help and documentation
kaizen docs         # show documentation and local paths
kaizen install      # install packages and tools without applying dotfiles
kaizen sync         # install dependencies and apply dotfiles
kaizen update       # upgrade native packages, mise tools, and feature integrations
kaizen self-update  # fast-forward a managed installation from its remote branch
kaizen bump         # developer: update mise pins in feature-local manifests
kaizen capture      # developer: re-add known mutable dotfiles to the source
kaizen status       # show installation mode, source, features, and tools

Running kaizen without arguments is safe: it prints help instead of changing the system. The same output is available through kaizen help and kaizen --help. Interactive help, documentation, status, warnings, and errors use restrained ANSI colors. Colors are disabled for pipes, redirects, TERM=dumb, and NO_COLOR.

kaizen self-update updates only remote installations created by the installer. It refuses development checkouts, detached branches, and installations with local changes. Run kaizen sync separately after an update.

kaizen install performs these steps:

1. Validate enabled features, selected variants, and user dependencies.
2. Install feature and user packages with the native package manager.
3. Merge feature and user tools into the generated mise config and install them.
4. Install missing feature integrations without refreshing existing ones.

It does not generate the chezmoi data overlay or apply dotfiles. kaizen sync validates the same inputs, generates the overlay, runs the dependency workflow, and then runs chezmoi apply.

kaizen update upgrades native packages and mise tools, then refreshes enabled feature integrations. Helix Steel fetches and rebuilds only when its source revision changes; Forge packages are reinstalled only when their remote revision changes.

Committed defaults live in dotfiles/.chezmoidata.toml. Machine-local overrides live in ~/.config/kaizen/config.toml:

layout = "colemak"

[ui]
font_size = 16

[features]
core = true
frontend = true
helix = true
tiling = true

[helix]
variant = "standard"

[tiling]
variant = "yabai"

[kaizen.shortcuts]
"nav.down" = ["n"]
"nav.up" = ["e"]

[models]
default = "anthropic/claude-sonnet-4-6"

Kaizen recursively merges dictionaries. Scalars and lists replace their default values, so every setting, model, and shortcut can be overridden.

Additional machine-local packages and mise tools can be declared in ~/.config/kaizen/dependencies.toml:

[tools]
node = "22"
"npm:typescript" = "latest"

[macos]
brew = ["jq", "shellcheck"]
cask = ["zed"]

[macos.brew_args]
jq = ["--HEAD"]

[linux]
dnf = ["jq", "ShellCheck"]
apt = ["jq", "shellcheck"]
flatpak = ["dev.zed.Zed"]

The file is optional. Kaizen validates it before making changes, installs its native packages after enabled feature packages, and gives its [tools] entries precedence over feature mise versions. Kaizen does not modify this user-owned file during bump.

Before applying dotfiles, Kaizen links the user config as the ignored dotfiles/.chezmoidata/99-user.toml. Chezmoi reads this overlay automatically, so direct chezmoi diff and chezmoi apply commands always use current values.

A feature with variants reads its base manifest and the selected variant:

features/tiling/packages.toml
features/tiling/variants/yabai/packages.toml

Select it in the user config:

[features]
tiling = true

[tiling]
variant = "yabai"

Available tiling variants are aerospace, glazewm, komorebi, and yabai. Helix supports standard (official release) and steel (plugin-enabled fork). Changing a variant does not uninstall packages from the previously selected variant.

• chezmoi
• mise
• Homebrew