tinct

Tinct

An extensible colour palette generator and theme manager for unified theming across your entire environment

Generate colour palettes from multiple sources (images, remote JSON/CSS themes, manual lists) with intelligent categorisation, role hints, weighting, and positional extraction. Apply them consistently to terminals, window managers, text editors, notification daemons, and even external LED lighting. Built with Go and designed for extensibility.

Features

• Multiple Input Sources: Extract from images, fetch from remote JSON/CSS, or provide manual colour lists
• Role Hints & Weighting: Override auto-categorisation with explicit role assignments and colour importance weights
• Positional Extraction: Extract edge/corner colours from images for ambient lighting and LED synchronization
• Smart Categorisation: Auto-assigns background, foreground, accent, and semantic colours with WCAG contrast checking
• Theme-Aware: Detects or forces dark/light themes with accessibility compliance
• Highly Extensible: Plugin system for inputs (image, remote JSON/CSS, file) and outputs (applications, LED devices)
• External Device Support: Send colours to LED strips, smart lights, and other RGB peripherals
• Unified Theming: Apply consistent colour schemes across your entire environment

Quick Start

Installation

Arch Linux (AUR):

# Using yay
yay -S tinct-bin

# Using paru
paru -S tinct-bin

From Go:

go install github.com/jmylchreest/tinct/cmd/tinct@latest

From source:

git clone https://github.com/jmylchreest/tinct.git
cd tinct && go build -o tinct ./cmd/tinct

Basic Usage

# Add official plugin repository (for external plugins)
tinct plugins repo add official https://github.com/jmylchreest/tinct-plugins

# Extract and preview colours from image
tinct extract --preview wallpaper.jpg

# Generate themes from local wallpaper
tinct generate -i image -p ~/Pictures/wallpaper.jpg -o all

# Use Catppuccin Mocha theme from remote JSON
tinct generate -i remote-json \
  --remote-json.url "https://raw.githubusercontent.com/catppuccin/palette/main/palette.json" \
  --remote-json.query "colors.mocha" \
  -o all

# Generate image with Google Gemini and apply theme (requires API key)
export GOOGLE_API_KEY="AIzaSyC7xM4deUpK3Y.eX4MPleHiJkL"
tinct generate -i google-genai \
  --prompt "beautiful sunset over the rolling mountains and vineyards of tuscany" \
  -o all

# Preview categorized palette with role assignments
tinct extract --categorise --preview wallpaper.jpg

Available Plugins

Input Plugins

Output Plugins

Terminals:

Window Managers & Compositors:

Bars & Notifications:

Launchers:

Editors & Multiplexers:

External Devices & Custom:

• Write custom output plugins to control LED strips (e.g., WLED, Philips Hue, Govee)
• Use ambient edge/corner extraction to sync bias lighting with your wallpaper
• Support for any device with a JSON/HTTP API or command-line interface

See Plugin Wishlist for planned plugins and External Plugins Guide for creating device controllers.

Note on Plugin Templates: The current application plugin templates are based on online examples and personal configurations. They may benefit from refactoring for broader adoption. Contributions are significantly welcome, especially for plugins that make sense to be shipped and managed as part of Tinct. If you have expertise with any of these applications or want to add support for new ones, please see Contributing.

Template Functions Reference

Tinct uses Go templates for generating configuration files. Templates have access to the colour palette and various helper functions.

Common Template Functions

Colour Format Functions

Alpha Channel Functions

Iteration

{{- range .AllColours }}
colour{{ .Index }} = {{ .Colour | hex }}
{{- end }}

Available Fields: .Index, .Colour, .Role, .Luminance, .Weight

See Template Guide for complete documentation.

Plugin Development

Tinct supports two types of plugins:

• Built-in plugins (Go): Compiled into the main binary for maximum performance
• External plugins (Any language): Standalone executables using JSON-stdio or gRPC protocols

For detailed plugin development guides:

• Built-in Plugin Development - Creating Go plugins
• External Plugin Development - Creating plugins in any language (Bash, Python, etc.)

Plugin Management

# List available plugins
tinct plugins list

# Install external plugin
tinct plugins install <github-user>/<repo> [<ref>]

# Add plugin repository
tinct plugins repo add <name> <url>

# Sync lock file with installed plugins
tinct plugins sync

# Enable/disable plugins
export TINCT_ENABLED_PLUGINS="hyprland,kitty"

Plugin Lock File Configuration

Tinct uses a lock file (.tinct-plugins.json) to manage plugin state and configuration. The lock file is searched in the following order:

1. Current directory (./.tinct-plugins.json)
2. Home directory (~/.tinct-plugins.json)

Lock File Structure:

{
  "version": "1",
  "enabled_plugins": [
    "image",
    "hyprland",
    "kitty"
  ],
  "disabled_plugins": [
    "waybar"
  ],
  "external_plugins": {
    "notify-send": {
      "name": "notify-send",
      "path": "/home/user/.local/share/tinct/plugins/notify-send.py",
      "type": "output",
      "version": "1.0.0",
      "description": "Send desktop notifications",
      "source": {
        "type": "local",
        "path": "./contrib/plugins/output/notify-send.py"
      },
      "installed_at": "2024-01-15T10:30:00Z"
    }
  }
}

Configuration Fields:

External Plugin Metadata:

Priority Order:

1. Lock file settings (highest priority)
2. Environment variables (TINCT_ENABLED_PLUGINS, TINCT_DISABLED_PLUGINS)
3. Plugin defaults (lowest priority)

Plugin-Specific Configuration

Plugins can store configuration in the lock file under the config field. This configuration is applied automatically when the plugin is used.

Image Plugin Configuration:

The image input plugin supports deterministic k-means clustering via seed configuration:

{
  "external_plugins": {
    "image": {
      "name": "image",
      "type": "input",
      "config": {
        "seed": {
          "mode": "content",
          "value": null
        }
      }
    }
  }
}

Seed Modes:

Example: Manual Seed Configuration

{
  "config": {
    "seed": {
      "mode": "manual",
      "value": 42
    }
  }
}

Or via command-line flags:

# Use content-based seed (default)
tinct generate -i image -p wallpaper.jpg --image.seed-mode content

# Use filepath-based seed
tinct generate -i image -p wallpaper.jpg --image.seed-mode filepath

# Use manual seed
tinct generate -i image -p wallpaper.jpg --image.seed-mode manual --image.seed-value 42

# Use random seed (non-deterministic)
tinct generate -i image -p wallpaper.jpg --image.seed-mode random

How Configuration is Passed to Plugins:

1. Built-in Plugins: CLI flags (e.g., --image.seed-mode) are parsed and applied directly
2. External Plugins: Configuration is passed via JSON on stdin during plugin initialization
3. Lock File Config: Merged with CLI flags (CLI flags take precedence)

Environment Variables:

# Enable only specific plugins (whitelist mode)
export TINCT_ENABLED_PLUGINS="image,hyprland,kitty"

# Disable specific plugins (blacklist mode)
export TINCT_DISABLED_PLUGINS="waybar,dunst"

Documentation

• Theme Cookbook: Ready-to-use commands for popular themes (Catppuccin, Dracula, Tokyo Night, Nord, Gruvbox, and more)
• Template Guide: Comprehensive template reference and customization guide
• Plugin Development: Create custom input/output plugins
• Plugin Hooks: Pre/post-execution hooks
• External Plugins: Write plugins in any language
• Setup Guide: Detailed installation and configuration
• Development Guide: Contributing and architecture

Examples

Generate themes from wallpaper

# Extract colours and apply to all configured applications
tinct generate -i image -p ~/Pictures/wallpaper.jpg -o all

# hyprpaper plugin automatically:
# - Generates wallpaper config with preload/wallpaper directives
# - Applies wallpaper immediately (if hyprpaper is running)
# - Updates all monitors or preserves existing assignments

Use Catppuccin Mocha theme

# Fetch Catppuccin Mocha from remote JSON and apply to all apps
tinct generate -i remote-json \
  --remote-json.url "https://raw.githubusercontent.com/catppuccin/palette/main/palette.json" \
  --remote-json.query "colors.mocha" \
  -o all

# Apply to specific applications only
tinct generate -i remote-json \
  --remote-json.url "https://raw.githubusercontent.com/catppuccin/palette/main/palette.json" \
  --remote-json.query "colors.mocha" \
  -o hyprland,kitty,waybar,walker

Generate with AI (Google Gemini)

# Set up your Google API key (get one from https://aistudio.google.com/apikey)
export GOOGLE_API_KEY="AIzaSyC7x8K9mN3pQ2rT5vW8yZ1aBcDeFgHiJkL"

# Generate image with Gemini Imagen and extract colours
tinct generate -i google-genai \
  --prompt "beautiful sunset over the rolling mountains and vineyards of tuscany" \
  -o all

# The google-genai plugin:
# - Generates an image using Google's Imagen model
# - Saves the image to your pictures directory
# - Automatically extracts colours from the generated image
# - Provides the image path to wallpaper plugins (hyprpaper, hyprlock)

Ambient LED Lighting / External Devices

# Extract edge/corner colours for synchronized LED bias lighting
tinct generate -i image -p wallpaper.jpg \
  --image.extractAmbience \
  --image.ambienceRegions 8 \
  --preview

# WLED monitor ambient lighting (see contrib/plugins/output/wled-ambient.sh)
tinct generate -i image -p wallpaper.jpg \
  --image.extractAmbience \
  --image.ambienceRegions 8 \
  -o wled-ambient \
  --plugin-args 'wled-ambient={"host":"192.168.1.100","segments":[0]}'

# OpenRGB keyboard/mouse lighting (see contrib/plugins/output/openrgb-peripheral.sh)
tinct generate -i image -p wallpaper.jpg \
  -o openrgb-peripheral \
  --plugin-args 'openrgb-peripheral={"devices":["keyboard","mouse"]}'

Positional colours (topLeft, top, topRight, left, right, bottomLeft, bottom, bottomRight) are automatically extracted and categorized when --image.extractAmbience is enabled. These can be consumed by custom output plugins to control:

• LED strips: WLED, Govee, Philips Hue (see wled-ambient.sh example)
• RGB peripherals: Keyboards, mice, case lighting via OpenRGB (see openrgb-peripheral.sh example)
• Smart lights: HomeKit, Home Assistant integrations

Example plugins demonstrating device control are in contrib/plugins/output/. See External Plugins Guide for writing your own device controllers.

With Plugin Hooks

# Reload Kitty after generating theme
tinct generate -i image -p wallpaper.jpg -o kitty --kitty.reload

Project Structure

tinct/
├── cmd/tinct/              # CLI entry point
├── internal/
│   ├── colour/             # Colour extraction & categorisation
│   ├── plugin/             # Plugin system
│   │   ├── input/          # Input plugins
│   │   ├── output/         # Output plugins
│   │   └── manager/        # Plugin management
│   └── cli/                # Command handlers
├── docs/                   # Documentation
├── contrib/                # Plugin development guides
└── testdata/               # Test fixtures

Architecture

Tinct uses a flexible plugin architecture that makes it easy to:

• Add new input sources (image formats, remote APIs, databases)
• Add new output targets (applications, devices, services)
• Customise colour extraction and categorisation logic
• Integrate with external tools and workflows

Plugins can be written in any language using the external plugin interface (stdin/stdout JSON protocol) or as native Go plugins for maximum performance.

License

MIT License - see LICENSE file.

Author

John Mylchreest

• Email: jmylchreest@gmail.com
• GitHub: @jmylchreest

Contributing

Contributions welcome! See Development Guide and Plugin Development Guide.

Made with Go 1.25+