Skip to content

AGENTS.md

Latest commit

 

History

History
99 lines (67 loc) · 4.53 KB

AGENTS.md

File metadata and controls

99 lines (67 loc) · 4.53 KB
Raw

AGENTS.md

Guidance for AI coding agents working in this repository.

Project overview

This repo collects terminal color schemes and generates them for 30+ targets (iTerm2, Alacritty, Kitty, WezTerm, VS Code, Windows Terminal, etc.). Source themes live in yaml/ (.yml, preferred for new themes) and schemes/ (.itermcolors, for themes exported directly from iTerm2). Everything else under format directories (alacritty/, kitty/, wezterm/, …) is generated output.

Repository layout

Path Purpose
yaml/ Preferred source for new themes (Gogh-based YAML format)
schemes/ iTerm2 .itermcolors source files (use when exporting from iTerm2)
tools/ Generation scripts, converters, and Jinja2 templates
tools/templates/ Per-format Jinja2 templates
screenshots/ Auto-generated theme preview images

Setup

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Python version: see .python-version (currently 3.10). Docker alternative: ./generate-all.sh.

Activate the venv before running commands below (source .venv/bin/activate), or prefix with .venv/bin/python.

Common commands

# Generate all themes for all formats
cd tools && python gen.py

# Generate one theme (preferred while iterating)
cd tools && python gen.py -s "Your Theme Name"

# Generate one format template only
cd tools && python gen.py -t kitty

# Full local pipeline (macOS; regenerates all themes, Terminal profiles, screenshots, README)
./generate-all-nodocker.sh

# Check WCAG contrast (default threshold 1.75, matches gen.py)
python tools/wcag_check.py -s "Your Theme Name"
python tools/wcag_check.py --schemes-dir schemes   # all schemes

# YAML themes: generate .itermcolors first, then check
cd tools && python gen.py -s "Your Theme Name"
python tools/wcag_check.py -s "Your Theme Name"

# Visual preview (display-only truecolor; does not change terminal palette)
python tools/preview_theme.py -s "Your Theme Name"

Adding a new theme

Prefer YAML unless the theme is being exported directly from iTerm2.

YAML (default)

  1. Create yaml/Your Theme Name.yml following yaml/README.md. Use the display name as the filename — spaces are fine; do not slugify or use underscores.
  2. Convert from other formats if needed: tools/kitty_to_yaml.py, tools/ghostty_to_yaml.py.
  3. Regenerate with cd tools && python gen.py -s "Your Theme Name".

iTerm2 export (when applicable)

  1. Export from iTerm2 and add schemes/Your Theme Name.itermcolors.
  2. Regenerate with cd tools && python gen.py -s "Your Theme Name".

For both paths: optionally update CREDITS.md, and do not hand-edit files in generated format directories. See README.md (Contribute) for full details.

Adding a new output format

  1. Create a Jinja2 template in tools/templates/ using placeholders documented in README.md (Contribute → How to add new template).
  2. Test with cd tools && python gen.py -t <template-name>.
  3. Update requirements.txt or .python-version only if dependencies change.

Important rules

  • Prefer YAML for new themes. Add yaml/*.yml unless the source is a direct iTerm2 export.
  • Edit sources, not outputs. Change yaml/ or schemes/, then regenerate. Never manually patch hundreds of generated theme files.
  • Use selective generation (-s, -t) when working on a single theme or format to avoid long runtimes.
  • Theme naming. Name source files as the display name (yaml/Catppuccin Mocha.yml, schemes/SpaceGray Eighties.itermcolors). No slugifying or underscores. YAML name: must match the filename if set. Quote names with spaces in CLI commands.
  • Avoid unrelated changes. This repo is large; keep diffs focused on the task (one theme, one template, one tool fix).
  • README screenshots are auto-generated by tools/generate_screenshots_readme.py; do not hand-edit the screenshots section in README.md.
  • Disclose agent usage. Note AI agent involvement in commit messages and PR descriptions. Agent-generated code and themes are welcome; the user may remove the disclosure if they prefer.

CI behavior

GitHub Actions (.github/workflows/generate-all.yml) regenerates themes and screenshots on pushes to master that touch schemes/, yaml/, or screenshots/README.md. PRs should include source changes; generated artifacts may be updated by CI.

Further reading

  • README.md — installation, contribution workflow, and template placeholder reference
  • yaml/README.md — YAML source format
  • CREDITS.md — theme attribution