docsgetting started

Install

One command wires ttheme into the terminals you use. It asks a few questions, shows every file it is about to change, and writes nothing until you say yes.

on this page

What you need
Run init
Start using it
Update
Without questions
By hand
From a checkout
When something goes wrong

What you need

Node 22 or newer, for npx.
zsh, which macOS ships. Your own shell can be zsh, bash or fish: bash and fish get the ttheme command too, and it runs through zsh.
A terminal ttheme wires: Ghostty (and cmux), iTerm2, kitty, Alacritty, Rio, Contour, WezTerm (and Kaku), Windows Terminal, Warp, Konsole or Terminal.app. Terminal support says what each one can show.

Run init

❯ npx @kecan0406/ttheme@latest init

It asks, in this order:

Which terminals to wire. The one you are in comes preselected.
Which mode to show the palettes in: auto, light or dark. Every palette comes in both. auto follows your system's appearance and is offered where Ghostty, iTerm2, kitty or WezTerm is wired.
Which catalogs to install. space marks a catalog and enter moves on. You can add or drop single palettes later.
Whether to use them. With one palette picked, whether every tab uses it. With several, whether to pick the default in ttheme afterwards.
Whether to add the palette skill to your coding agents, when it finds Claude Code or another agent's folder. Ask the agent for a character's palette and it measures the colors on official art.

Then it lists every file it will change and the settings its own files carry, and asks once more. Cancelling before that changes nothing. What changed explains that list.

Start using it

❯ exec zsh  # the ttheme command in this tab
❯ ttheme  # pick a palette

From bash, run exec bash -l; from fish, exec fish. New tabs pick ttheme up by themselves. iTerm2, Konsole, Terminal.app and Contour read their profiles only when they start, so quit and reopen them once.

Next: your first palette.

Update

❯ ttheme update

This installs the newest ttheme and keeps your terminals, palettes, pins and settings. Running init again does the same: it offers to update in place. Once a day ttheme checks npm by itself and says when a newer version is out.

Without questions

init --yes (or -y) answers every question for you. Over an install it updates in place and keeps everything. On a first install it wires the terminal you are in and installs no palettes, so your colors stay as they are until you pick one. Without a terminal to ask in, init stops unless it has --yes.

By hand

Each release carries one archive per terminal, holding the theme files alone. Copy a palette's file into your terminal's themes folder and point your config at it:

❯ curl -L https://github.com/kecan0406/ttheme/releases/latest/download/ttheme-ghostty.tar.gz | tar xz
❯ cp ghostty/themes/ttheme-miku.* ~/.config/ghostty/themes/

Terminal	Archive	Then
Ghostty	`ttheme-ghostty.tar.gz`	`theme = ttheme-miku.dark`, or `theme = light:ttheme-miku.light,dark:ttheme-miku.dark`
kitty	`ttheme-kitty.tar.gz`	`include themes/ttheme-miku.dark.conf`
Alacritty	`ttheme-alacritty.tar.gz`	`import = ["~/.config/alacritty/themes/ttheme-miku.dark.toml"]` under `[general]`
WezTerm	`ttheme-wezterm.tar.gz`	`config.color_scheme = "ttheme-miku.dark"`
iTerm2	`ttheme-iterm2.tar.gz`	open a `.itermcolors` to add it to Settings › Profiles › Colors
Windows Terminal	`ttheme-windows-terminal.tar.gz`	copy `ttheme.json` into `%LOCALAPPDATA%\Microsoft\Windows Terminal\Fragments\ttheme\`
Warp	`ttheme-warp.tar.gz`	copy a `ttheme-miku.dark.*.yaml` into `~/.warp/themes/`
Konsole	`ttheme-konsole.tar.gz`	copy the `.colorscheme` into `~/.local/share/konsole/` and pick it in the profile

Most terminals get each palette in both modes, .dark and .light.

A palette installed by hand stays one palette: switching per tab, pins, pictures and the rest need init.

From a checkout

❯ mise install && bun install
❯ mise run build  # the same files, into dist/
❯ mise run bin:build && node bin/ttheme.js init

mise run sandbox tries a checkout in a throwaway home first.

When something goes wrong

❯ ttheme info  # what a bug report needs
❯ npx @kecan0406/ttheme@latest info  # the same, before ttheme is set up
❯ TTHEME_DEBUG=1 ttheme use miku  # where an error came from

Report a bug with the output of ttheme info: it names ttheme's version, your system, shell and terminal, the terminals you wired and the settings you changed, so nothing has to be typed by hand.