colorant

Per-directory terminal theme switcher with system dark/light mode support.

colorant walks up from your current directory looking for a .colorantrc file and applies the theme it describes to your terminal. When you cd out of the tree, the theme resets. When the OS flips between dark and light, the active theme follows on the next shell prompt.

Status

Early development. Supported terminals: Ghostty and iTerm2 on macOS, driven from zsh. Other terminals (Kitty, WezTerm, Alacritty), shells, and OSes will land incrementally.

Install

Three install paths, all of which ship the same colorant binary built for both Intel and Apple Silicon Macs.

Homebrew

brew install farmisen/tap/colorant

The tap is auto-added on first install. Easiest path if you already use Homebrew.

Shell installer

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/farmisen/colorant/releases/latest/download/colorant-installer.sh | sh

No Rust toolchain or Homebrew required. Detects your architecture, downloads the matching binary, and verifies its checksum. Installs to $CARGO_HOME/bin (typically ~/.cargo/bin) — make sure that's on your $PATH. To install elsewhere, set COLORANT_INSTALL_DIR=/some/path before running.

From source (cargo)

For Rust developers, or to pin a specific version:

# latest main
cargo install --git https://github.com/farmisen/colorant.git

# pinned to a release tag
cargo install --git https://github.com/farmisen/colorant.git --tag v0.7.0

Installs to ~/.cargo/bin/colorant.

Verifying downloads

Each release publishes a .sha256 file alongside every archive, plus an aggregated sha256.sum. If you download a tarball directly (rather than via the shell installer, which verifies for you), check it with:

shasum -a 256 -c colorant-aarch64-apple-darwin.tar.xz.sha256

Quick start

# 1. Wire the zsh hook into your shell, then restart your shell.
echo 'eval "$(colorant init zsh)"' >> ~/.zshrc
exec zsh

# 2. Install the bundled palettes into your themes dir. (`colorant themes list`
#    enumerates what's available; `--all` copies every bundled palette.)
colorant themes install --all

# 3. Tag a directory with that palette.
cd ~/work/myproject
echo 'extends = catppuccin-mocha' > .colorantrc

# 4. cd back in (or just press Enter at the prompt) to see the theme apply.
cd .

The hook fires on every cd and on every prompt redraw, so themes update both when you change directories and when macOS flips dark/light mode — the latter applies on your next prompt (your next command or Enter press).

Commands

colorant --help is the canonical reference. The subcommands:

The apply command is what the shell hook calls on every chpwd / precmd; you generally don't need to invoke it manually unless debugging.

Environment variables

• COLORANT_MODE=dark|light — force a specific mode, bypassing macOS dark/light detection.

Config files

colorant reads up to three config files, all optional. See examples/ for annotated templates of the two main ones.

Palettes (.colorant) — flat color sets. No modes, no inheritance. Live under ~/.config/colorant/themes/. Examples ship in this repo: catppuccin-mocha.colorant, gruvbox-light.colorant, tokyo-night.colorant, and a dozen more.

# tokyo-night.colorant
fg     = #c0caf5
bg     = #1a1b26
cursor = #c0caf5
tab_bg = #1a1b26    # iTerm2-only; ignored on Ghostty.
color0 = #15161e
# ...

Per-directory config (.colorantrc) — the file you author per project. Picks parent palettes (globally or per-mode), and optionally overrides specific keys.

# ~/work/myproject/.colorantrc
extends.dark  = tokyo-night
extends.light = catppuccin-latte

# Project-wide override regardless of mode
fg = #ffffff

[dark]
# In dark mode only, recolor the cursor
cursor = #ff00ff

Global config (~/.config/colorant/config.toml) — applied when no .colorantrc is found while walking up from the current directory. Without it, colorant apply emits a terminal reset when no rc is found.

default_theme = "catppuccin-mocha"

# When true (default), if a theme doesn't set `tab_bg`, the iTerm2 tab
# color is derived from `bg` so the tab matches the terminal background.
# Set to false to leave the tab color alone unless a theme names it.
tab_follows_window = true

Tab color and tmux

iTerm2 is the only currently-supported terminal that exposes a runtime tab-color API (via OSC 1337 ; SetColors=tab=...). Inside tmux, that sequence is dropped by default — add set -g allow-passthrough on to ~/.tmux.conf to let it through. The standard fg/bg/cursor/palette sequences keep working either way (tmux handles them internally). Ghostty has no equivalent runtime API today, so colorant doesn't emit anything tab-related on Ghostty.

Uninstall

Match the method you used to install:

# Installed via Homebrew
brew uninstall colorant
brew untap farmisen/tap        # optional, removes the tap

# Installed via cargo install
cargo uninstall colorant

# Installed via shell installer
rm ~/.cargo/bin/colorant       # or wherever COLORANT_INSTALL_DIR pointed

Then remove the shell hook line from ~/.zshrc:

eval "$(colorant init zsh)"

Optionally clear the config dir and any palettes you downloaded:

rm -rf ~/.config/colorant

License

MIT. See LICENSE.