kgen

A sophisticated keyboard layout generator and management system.

---

kgen (Key Gen) bridges the gap between human-readable layout design and firmware-specific configurations. It allows you to define your keyboard layers in intuitive text formats and compiles them into ready to use firmware code.

Core Capabilities

• Declarative Configuration: Manage your entire keyboard through a central config.toml and clean text-based layer files.
• Visual Consistency: Automatic formatting ensures your layer files remain readable and aligned with your physical layout.
• Cross-Firmware Support: Generate configurations for QMK (fully supported) and ZMK (in development).

Installation

Building from source requires the Rust toolchain:

git clone https://github.com/vincbro/kgen.git
cd kgen
cargo install --path .

Technical Workflow

kgen operates on a structured project directory:

1. config.toml The source of truth for your physical layout and layer definitions.
2. Layer Files (.txt) Human-readable representations of individual keyboard layers.

The tool parses these inputs to generate the final keymap logic for your target firmware.

Configuration (config.toml)

The config.toml file defines the physical architecture of your keyboard and identifies the layers to be compiled.

Layout Definition

The layout field uses a visual grid to define key positions. Each # represents a physical key, while spaces represent gaps. This grid is used by kgen format to generate and align your layer files.

[config]
layout = [
	"######     ######",
	"######     ######",
	"######     ######",
	"######## ########",
	"   ##### #####   ",
	"####         ####",
]

Layer Management

The layers field lists the names of your layer files (without the .txt extension). kgen expects to find a corresponding file for each entry (e.g., base.txt, nav.txt).

layers = ["base", "nav", "sym"]

QMK keyboard layout macro

For a Ferris Sweep, use the built-in preset. It supplies both the 34-key physical grid and QMK's required 10/10/10/4 argument ordering:

[config]
layers = ["base", "nav", "sym"]

[config.qmk]
preset = "ferris_sweep"

When a preset is selected, it replaces config.layout; remove the old Elora layout to avoid confusion. With Chordal Hold enabled, the Ferris thumb keys use QMK's '*' handedness so layer-taps and mod-taps can chord with either hand.

For other keyboards, define the visual grid under [config] and set the layout macro exported by that keyboard:

[config.qmk]
layout_macro = "LAYOUT_your_keyboard"

Configurations without a preset or layout_macro continue to use LAYOUT_elora_hlc for backward compatibility.

Features

kgen can generate boilerplate for QMK features that benefit from knowledge of your physical layout.

Chordal Hold

Chordal Hold is a native QMK feature that improves home row mods by settling same-hand chords as taps and opposite-hand chords as holds. Because kgen already knows your layout, it automatically derives the chordal_hold_layout handedness matrix — no manual L/R mapping needed.

Enable it under [config.features.chordal_hold]:

[config.features.chordal_hold]
enabled = true
mode = "hold_on_other_key_press"   # "hold_on_other_key_press" | "permissive" | "none"
tapping_term = 200                 # optional

Field	Description	Default
enabled	Toggles Chordal Hold code generation.	false
mode	Companion mode for opposite-hand chords. hold_on_other_key_press settles immediately on press; permissive settles on a nested press; none defers to QMK defaults.	hold_on_other_key_press
retro_tapping	Emits #define RETRO_TAPPING. When a hold is released without interruption, the tap fires. Stacks with any mode.	false
tapping_term	Emits #define TAPPING_TERM (ms). Omit to keep QMK's default.	(unset)

When enabled, kgen build emits two files:

• keymap.c — your layers plus an auto-generated chordal_hold_layout matrix with 'L'/'R' handedness derived from your layout grid (split at the midpoint).
• config.h — #define CHORDAL_HOLD, the companion mode define, and optional TAPPING_TERM.

Note: In stdout mode (--output omitted), only keymap.c is printed; use --output to write config.h alongside it.

Command Reference

init

Initializes a new project structure with a default configuration.

kgen init --path ./my-keyboard

format

Standardizes the visual layout of your layer files. If a file is missing, kgen generates a template based on your configuration.

kgen format --path ./my-keyboard

build

Compiles your project into firmware-specific source code.

kgen build --path ./my-keyboard --manufacturer qmk --output ./keymap.c

Parameters

Option	Shorthand	Description	Default
--path	-p	Path to the keyboard project directory.	Required
--manufacturer	-m	Target firmware (e.g., qmk, zmk).	qmk
--output	-o	Path to save the generated output.	stdout

Ecosystem Support

QMK Firmware

kgen provides first-class support for QMK, translating text layers into robust C code compatible with standard QMK builds. This includes auto-generated Chordal Hold support when enabled in your configuration.

ZMK Firmware

Support for ZMK is currently under active development.

Contribution

To add support for a new manufacturer, please refer to the implementation patterns in src/parser/qmk.rs and extend the Manufacturers enum. Pull requests are welcome.