# Irix on Your Terminal in Ten Minutes

Irix is a palette, not a theme: five chambers of four hues each, twelve shades per hue, dark and light siblings for every one of them.
This tutorial walks the whole loop once — install, look at the palette, paint your terminal with it, wire it into your prompt, glance at the HUD, then flip the whole thing to light — so you have a working mental model before you go reaching for the how-to guides.

Everything below was run from a checkout of this repository.
Skim ahead to [](#install) for why that's the recommended path right now rather than a packaged install.

(install)=
## Install

```sh
git clone <this repository> irix && cd irix
uv sync
```

```{note}
A published `uv tool install irix` exists on PyPI and does work — it currently ships the `colorcode` console script (matching this doc's own [index page](index.md) usage note) plus `promptcode`.
It predates this repository's `irix`, `kittyhud`, and `themecode` scripts, so it can't carry you through this whole tutorial yet.
Until a fresh release ships, run everything here as `uv run <script>` from a checkout, as below.
```

From here on, every command is `uv run <script>` from the repo root.
If you'd rather not prefix every call, `uv tool install .` from the checkout puts `irix`, `colorcode`, `promptcode`, `kittyhud`, and `themecode` on your `PATH` — drop the `uv run` prefix in that case.
`irix generate`/`irix check` still want to run from inside a checkout either way (they write into/diff against the repo's own `out/`); `irix deploy`, `colorcode`, `promptcode`, and `kittyhud` don't care where you run them from.

## See the palette

`irix targets` lists every one of the engine's 24 registered targets — one row per application it knows how to paint, with the filename(s) each mode renders:

```sh
uv run irix targets
```

```text
alacritty    terminals   dark=terminals/alacritty.toml, light=terminals/alacritty-light.toml
...
kitty        terminals   dark=terminals/kitty.conf, light=terminals/kitty-light.conf
...
swatches     web         dark=web/irix-dark-swatches.svg, light=web/irix-light-swatches.svg
...
```

For something you can actually look at, generate the swatch sheets — a 20-hue x 12-shade grid, one SVG per mode:

```sh
uv run irix generate swatches --out /tmp/irix-palette
```

Open `/tmp/irix-palette/web/irix-dark-swatches.svg` (and its `-light` sibling) in a browser or image viewer.
Every hue-shade address you'll see anchored throughout this tutorial — `slate-shape1`, `cyan-sign1`, `jade-text1` — is a labeled cell on that sheet.

## Deploy a terminal theme

`irix deploy <target>` copies a target's already-generated artifacts from the packaged `out/` tree to that application's real config location.
Kitty is the engine's reference target, so it's the cleanest first deploy:

```sh
uv run irix deploy kitty --dry --verbose
```

```{warning}
Run the dry version first and read it.
`irix deploy kitty` writes straight to `$XDG_CONFIG_HOME/kitty/kitty.conf` — kitty's *primary* config filename — with a colors-only file (foreground/background, tab bar, `color0`-`color15`, marks).
If you already have a kitty.conf with fonts, keybindings, or other settings, a real (non-`--dry`) deploy overwrites it outright; there's no merge.
Back up an existing `kitty.conf` first, or point `XDG_CONFIG_HOME` at a scratch directory the way this tutorial does below.
```

Dropping `--dry` performs the copy for real (sandboxed here so nothing touches a real home directory):

```sh
export XDG_CONFIG_HOME=/tmp/irix-sandbox/.config
uv run irix deploy kitty --verbose
```

```text
copied .../out/terminals/kitty.conf -> /tmp/irix-sandbox/.config/kitty/kitty.conf
copied .../out/terminals/kitty-light.conf -> /tmp/irix-sandbox/.config/kitty/kitty-light.conf
```

Two files land side by side: `kitty.conf` (the one kitty actually reads) and `kitty-light.conf` (the light sibling, deployed alongside it but not auto-selected — kitty itself has no dark/light switch).
See [](#switch-to-light) below for what to do with that second file, and [](howto-deploy.md) for the full per-application rundown — including the `ghostty` and `alacritty` variants, which follow the same shape (`ghostty` even renames the files into kitty's `themes/` convention: `themes/irix-dark`, `themes/irix-light`, no extension).

## Wire colorcode and promptcode into a zsh prompt

`colorcode` sets the terminal *background* by directory/command trigger; `promptcode` renders a compressed, colored *path segment* for the prompt line itself.
Both are meant to be called from a zsh `precmd` hook, once per prompt.

A minimal wiring, verified end to end in a real zsh session:

```zsh
# ~/.zshrc
autoload -Uz add-zsh-hook

_irix_precmd() {
  local exit_status=$?  # capture first -- anything else here clobbers $?
  colorcode -d "$PWD" -n "${history[$HISTCMD]:-}" -s "$exit_status" 2>/dev/null &!
  PROMPT="$(promptcode --fmt zsh) %# "
}
add-zsh-hook precmd _irix_precmd
```

A few things worth knowing about that snippet:

- `colorcode` is backgrounded and disowned (`&!`) so a slow trigger lookup never stalls your
  prompt; it talks to the terminal directly via an OSC 11 escape, so it doesn't need to hand
  anything back to the shell.
- `${history[$HISTCMD]:-}` passes the *whole* last command line, not just the command word —
  fine, because `colorcode`'s command triggers are prefix-matched regexes (`^git` still
  matches `git commit -m wip`).
- `promptcode --fmt zsh` emits real zsh prompt-expansion syntax (`%F{#RRGGBB}...%f`) as a
  plain string. Because the string is built and assigned to `PROMPT` directly inside the hook
  function — not embedded as `$SOME_VAR` inside a `PROMPT='...'` literal — this works with or
  without `setopt PROMPT_SUBST`.

With no trigger config at all, `colorcode -c slate` still works as an explicit, no-surprises demo:

```sh
uv run colorcode -c slate -v
```

```text
Applying color: 'slate' -> '#18191B'
```

Trigger configs (directory/command rules) are covered in [](howto-deploy.md); the shell section there also has the `fzf`/`lsd`/`starship`/`delta`/`btop` companions that round out a terminal built on the same palette.

## See the HUD

`kittyhud` paints a small five-cell bar — one cell per Irix chamber — in the corner of a Kitty window, highlighting whichever chamber your current directory's index digit belongs to (`_2_documents` lights the third cell, and so on):

```sh
uv run kittyhud
uv run kittyhud --clear   # remove just this HUD
```

```{note}
`kittyhud` is Kitty-only in effect, not by refusal: it always writes Kitty's graphics-protocol escape codes, with no check for whether you're actually inside Kitty.
Inside Kitty you get the HUD; in any other terminal the bytes are silently ignored (verified: running it in a plain terminal produces no visible output and no error).
`--clear` is always safe to run.
```

(switch-to-light)=
## Switch to light

Every one of the 24 targets renders both modes, and `colorcode`/`promptcode`/`kittyhud` all resolve which one to use through the same precedence: an explicit `--mode` flag wins, then `$IRIX_MODE`, then `dark`.

```sh
IRIX_MODE=light uv run promptcode --path . --fmt plain
uv run promptcode --path . --fmt ansi --mode dark    # explicit --mode wins over $IRIX_MODE
```

Set it once for a whole session and every one of those tools follows:

```sh
export IRIX_MODE=light
uv run colorcode -c slate -v
```

```text
Applying color: 'slate' -> '#F9F9FB'
```

(compare that against dark slate's `#18191B` from earlier — same address, the palette's other half.)

`irix generate`/`irix check`/`irix deploy` take their own `--mode {dark,light,both}` flag instead — it's a build-time artifact selector, independent of `$IRIX_MODE`, and defaults to `both`.
That's *why* `kitty-light.conf` was already sitting next to `kitty.conf` after the plain `irix deploy kitty` above: both modes deploy together unless you narrow it.

Getting each individual application (vim, sublime, vscode, the browser userstyles, ...) to actually pick up its light sibling — since most of them, kitty included, have no built-in dark/light switch of their own — is the whole subject of [](howto-modes.md).

## Where to go next

- [](howto-deploy.md) — every family (terminals, shell, editors, portable/web), what deploys
  where, what's generate-only.
- [](howto-modes.md) — the dark/light switch, end to end, per application.
- [](howto-new-target.md) — adding a 25th target to the engine.