Kitchn

Strict Corporate Design Enforcement for your System.

"Single Source of Truth". One config change propagates to Shells, Scripts, Logs, GUIs, and TUI apps instantly. Now with C-API support for C++, Python, and more.

 Mission

Kitchn unifies the theming and configuration of your entire ecosystem (e.g., Hyprland, Waybar, Alacritty). Instead of editing 10 different config files to change a color or font, you edit one central configuration. Kitchn then propagates these changes to all your installed applications ("Ingredients") via powerful templates.

With the new C-ABI Compatible Core, Kitchn is no longer just a CLI tool—it's a system-wide SDK that can be embedded into any application.

 Installation

Option A: One-liner (Recommended)

curl -fsSL https://raw.githubusercontent.com/ryugen-io/kitchN/master/install.sh | bash

Option B: Specific Version

curl -fsSL https://raw.githubusercontent.com/ryugen-io/kitchN/master/install.sh | bash -s -- v0.2.0

Option C: From Source

git clone https://github.com/ryugen-io/kitchN.git
cd kitchn
just install

Option D: Manual Download

Download the latest release from the Releases page, extract and run:

tar xzf kitchn-v*.tar.gz
cd kitchn-v*/
./install.sh

All methods will:

Create ~/.config/kitchn/ with default configurations.
Install binaries (kitchn, kitchn-log) to ~/.local/bin/.
Install FFI library (libkitchn_ffi.so) to ~/.local/lib/kitchn/.

Important

Ensure ~/.local/bin is in your $PATH.

Quick Start

Get up and running in 3 steps:

# 1. Install Kitchn
curl -fsSL https://raw.githubusercontent.com/ryugen-io/kitchN/master/install.sh | bash

# 2. Stock an example ingredient
kitchn stock ./assets/ingredients/waybar.ing

# 3. Apply all ingredients
kitchn cook

Typical Workflow

Edit your theme in ~/.config/kitchn/theme.toml
Run kitchn cook to apply changes
Done! All configured apps update automatically

Creating Your Own Ingredient

# Create a new ingredient file
cat > my-app.ing << 'EOF'
[package]
name = "my-app-theme"
version = "0.1.0"

[[templates]]
target = "~/.config/my-app/colors.conf"
content = """
background = "{{ colors.bg }}"
foreground = "{{ colors.fg }}"
accent = "{{ colors.primary }}"
"""

[hooks]
reload = "pkill -USR1 my-app"
EOF

# Stock and cook
kitchn stock my-app.ing
kitchn cook

Project Structure

.
├── crates/
├── crates/
│   ├── k-lib/           # Core Logic (Rust 2024)
│   ├── k-ffi/           # FFI Interface (Rust 2021, C-ABI)
│   ├── k-bin/           # CLI wrapper (`kitchn`)
│   └── k-log/           # Logging CLI (`kitchn-log`)
├── include/             # Generated C headers (kitchn.h)
├── assets/
│   ├── ingredients/     # Example .ing files
│   ├── examples/        # C++, Python, Rust integration examples
├── Cargo.toml           # Workspace config
└── justfile             # Command runner

 Core Architecture

graph TD
    %% Nodes
    CLI(k-bin <br> Binary)
    Log(k-log <br> Binary)
    Lib(k-lib <br> Rust Crate)
    FFI(k-ffi <br> Rust Crate)
    Headers(kitchn.h <br> C Header)
    DB[(Pastry DB <br> Sled/KV)]
    Config[Configuration <br> TOML]
    
    %% Relationships
    CLI -->|Uses| Lib
    CLI -->|Invokes| Log
    CLI -->|Reads| Config
    Lib -->|Manages| DB
    Log -->|Uses| Config
    FFI -->|Exposes| Lib
    FFI -->|Generates| Headers
    
    %% Subgraphs for logic
    subgraph Core Logic
        Lib
        DB
    end
    
    subgraph Interfaces
        CLI
        FFI
        Headers
    end
    
    subgraph Support
        Log
        Config
    end
    
    %% Styling
    style CLI fill:#f9f,stroke:#333,stroke-width:2px,color:#000
    style Lib fill:#bbf,stroke:#333,stroke-width:4px,color:#000
    style FFI fill:#bfb,stroke:#333,stroke-width:2px,color:#000
    style DB fill:#ff9,stroke:#333,stroke-width:1px,color:#000
    style Log fill:#fbb,stroke:#333,stroke-width:1px,color:#000

Logic: k-lib (Rust 2024) handles all processing, rendering, and logic.
Interface: k-ffi (Rust 2021) provides a stable C-ABI and auto-generates kitchn.h using cbindgen.
Storage: Ingredients are ingested into a high-performance binary database (pastry.bin) located in ~/.local/share/kitchn/, ensuring instant access and clean storage.

 The "Sweet Dracula" Standard

Kitchn enforces a strict, vibrant Dracula palette across your system:

Color	Hex	Role	Usage
Background	`#282a36`	Canvas	Windows, Terminals, Editors
Current	`#44475a`	Selection	Active lines, Hover states
Foreground	`#f8f8f2`	Text	Main content text
Purple	`#bd93f9`	Primary	Accents, Borders, Keywords
Pink	`#ff79c6`	Secondary	Highlights, Strings, Urgent
Green	`#50fa7b`	Success	Validations, ok, diff(+)
Red	`#ff5555`	Error	Failures, deletions, diff(-)
Orange	`#ffb86c`	Warning	Constants, Escapes, Notes
Cyan	`#8be9fd`	Info	Metadata, Types, Links

 Integration & FFI

kitchn_lib exposes a C-ABI compatible interface, allowing you to use Kitchn's configuration, logging, and packaging logic in other languages.

C / C++

Include the header and link against the library:

#include "kitchn.h"

KitchnContext* ctx = kitchn_context_new();
kitchn_context_set_app_name(ctx, "MyApp");
kitchn_log_preset(ctx, "boot_ok", NULL);
kitchn_context_free(ctx);

Python

Use ctypes to load the shared library:

import ctypes
lib = ctypes.CDLL("libkitchn_ffi.so")
ctx = lib.kitchn_context_new()

Examples

Run the built-in examples to see it in action:

just examples
# OR specific ones:
just example-cpp
just example-python
just example-rust

Commands

Ingredient Management

# Install a single ingredient or .bag package
kitchn stock ./assets/ingredients/waybar.ing
kitchn stock ./my-theme.bag

# List all stocked ingredients
kitchn pantry

# Cook (apply) all ingredients to the system
kitchn cook

# Clean (remove) all ingredients from pantry
kitchn pantry clean

# Enable/Disable ingredients
kitchn pantry disable waybar-theme
kitchn pantry enable waybar-theme

Packaging

# Wrap multiple .ing files into a portable .bag package
kitchn wrap ./my-ingredients/

# Specify custom output path
kitchn wrap ./my-ingredients/ --output ./my-theme.bag

Performance Optimization

# Pre-compile config files into binary format for faster startup
kitchn bake

Tip

Run kitchn bake after changing your configuration files (theme.toml, icons.toml, etc.) to cache them for instant loading.

Logging

# Ad-hoc logging
kitchn-log error SYSTEM "Database connection failed"

# Using a preset
kitchn-log boot_ok

App-Scoped Logging

You can configure Kitchn to organize logs by application name in layout.toml:

path_structure = "{year}/{month}/{app}/{scope}"
app_name = "kitchn" # Default app name

Override the app name via CLI:

kitchn-log boot_ok --app MyApp

 Debugging

Kitchn includes a powerful debug mode to diagnose failing hooks or configuration issues.

kitchn --debug

This will spawn a separate terminal window (prioritizing rio, alacritty, kitty) that streams verbose logs, including:

Exact commands executed by hooks
Stdout/Stderr from hooks (even if empty)
Configuration files loaded
Tera template context keys

You can also attach it to specific commands:

kitchn cook --debug
kitchn bake --debug

 Robustness

Kitchn enforces a Single Instance Policy using OS-level file locking (flock). This ensures that only one instance manages the pantry or system configuration at a time, preventing database corruption and conflicts.

Automatic Cleanup: If Kitchn crashes, the kernel releases the lock immediately.
Non-Blocking: A second instance will fail immediately with a clear error message instead of hanging.
Debug Exception: The debug viewer (kitchn --debug) is exempt and can run in parallel.

 Ingredients (`.ing`)

An Ingredient is a single TOML file that teaches Kitchn how to theme a specific application. Ingredients are ingested into the PastryDB upon installation, meaning you don't need to keep the original files.

Structure

[package]
name = "waybar-theme"
version = "0.1.0"
authors = ["Your Name <you@example.com>"]
description = "Waybar styling integration"
license = "MIT"

[[templates]]
target = "~/.config/waybar/style.css"
content = """
* {
    font-family: "{{ fonts.ui }}";
    font-size: {{ fonts.size_ui }}px;
}
window#waybar {
    background-color: {{ colors.bg }};
    border-bottom: 2px solid {{ colors.primary }};
}
"""

[hooks]
reload = "pkill -SIGUSR2 waybar"

Package Fields

Field	Required	Description
`name`	Yes	Unique identifier for the ingredient
`version`	Yes	Semantic version (e.g., `0.1.0`)
`authors`	No	List of author names and emails
`description`	No	Short description of what this ingredient themes
`license`	No	License identifier (e.g., `MIT`, `GPL-3.0`)
`ignored`	No	Set to `true` to disable without deleting (Default: `false`)

Bags (`.bag`)

A Bag is a portable zip archive containing multiple .ing files. Use bags to distribute complete theme collections.

Creating a Bag

# Package all .ing files from a directory
kitchn wrap ./my-theme-ingredients/

# Creates: my-theme-ingredients.bag

Installing a Bag

# Extract and stock all ingredients from a bag
kitchn stock ./my-theme.bag

Note

Bags are simply ZIP files with a .bag extension. You can inspect their contents with any archive tool.

Template Variables

Ingredients use the Tera templating engine. The following variables are available:

Colors (`colors.*`)

All colors defined in theme.toml:

{{ colors.bg }}         → #161925
{{ colors.fg }}         → #F8F8F2
{{ colors.primary }}    → #BD93F9
{{ colors.secondary }}  → #FF79C6
{{ colors.success }}    → #50FA7B
{{ colors.error }}      → #FF5555
{{ colors.warn }}       → #FFB86C
{{ colors.info }}       → #8BE9FD

Fonts (`fonts.*`)

{{ fonts.mono }}        → JetBrainsMono Nerd Font
{{ fonts.ui }}          → Roboto
{{ fonts.size_mono }}   → 10
{{ fonts.size_ui }}     → 11

Icons (`icons.*`)

Icons from the active icon set (configured via theme.toml):

{{ icons.success }}     →  (or * in ASCII mode)
{{ icons.error }}       →  (or ! in ASCII mode)
{{ icons.warn }}        →
{{ icons.info }}        →
{{ icons.net }}         → 󰖩

Tera Filters

Kitchn provides custom filters for common transformations:

Filter	Input	Output	Use Case
`hex_to_rgb`	`#BD93F9`	`[189, 147, 249]`	JSON/Chrome themes

Example:

content = """
{
  "colors": {
    "toolbar": {{ colors.bg | hex_to_rgb }}
  }
}
"""

 Configuration

Located in ~/.config/kitchn/.

File	Purpose
`theme.toml`	Colors, fonts, and visual settings
`icons.toml`	Icon sets (Nerd Font, ASCII fallback)
`layout.toml`	Log message structure and formatting
`dictionary.toml`	Pre-defined log message presets

You may split your configuration using include = ["path/to/extra.toml"].

theme.toml

[meta]
name = "Sweet Dracula"

[settings]
active_icons = "nerdfont"  # or "ascii"

[colors]
bg = "#161925"
fg = "#F8F8F2"
primary = "#BD93F9"
# ... see full palette above

[fonts]
mono = "JetBrainsMono Nerd Font"
ui = "Roboto"
size_mono = "10"
size_ui = "11"

icons.toml

[nerdfont]
success = ""
error = ""
warn = ""
info = ""

[ascii]
success = "*"
error = "!"
warn = "!!"
info = "i"

layout.toml

[tag]
prefix = "["
suffix = "]"
transform = "lowercase"

[labels]
error = "error"
success = "success"

[structure]
terminal = "{tag} {scope} {icon} {msg}"
file = "{timestamp} {tag} {msg}"

[logging]
base_dir = "~/.local/state/hyprcore/logs"
path_structure = "{year}/{month}/{scope}"

dictionary.toml

Define reusable log presets:

[presets.boot_ok]
level = "success"
scope = "SYSTEM"
msg = "startup complete"

[presets.deploy_fail]
level = "error"
scope = "DEPLOY"
msg = "deployment failed"

Use presets via CLI:

kitchn-log boot_ok
kitchn-log deploy_fail

Rich Text in Messages

Log messages support inline formatting tags:

msg = "Welcome to <primary>Kitchn</primary>! Status: <success>OK</success>"

Tag	Effect
`<bold>`	Bold text
`<primary>`	Primary color (purple)
`<secondary>`	Secondary color (pink)
`<success>`	Success color (green)
`<error>`	Error color (red)
`<warn>`	Warning color (orange)
`<info>`	Info color (cyan)

 Uninstall

just uninstall

Name		Name	Last commit message	Last commit date
Latest commit History 103 Commits
.github/workflows		.github/workflows
assets		assets
crates		crates
include		include
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
README.md		README.md
install.sh		install.sh
justfile		justfile
uninstall.sh		uninstall.sh

ryugen-io/kitchN

Folders and files

Latest commit

History

Repository files navigation