Config

Properties

• gen: Refer to #/$defs/GenOptions. Default:

file: ~/.config/chordgen/chords.csv
keyboard:
  directional:
    custom_layout:
    - _X__X__X__X__X__X__X__X_
    - X_XX_XX_XX_XX_XX_XX_XX_X
    - _X__X__X__X__X__X__X__X_
    - _X__X_
    - X_XX_X
    - _X__X_
    - _X__X_
    - X_XX_X
    - _X__X_
    custom_layout_name: custom
    directional_change_penalty: 2
    effort_map:
    - '040030020020'
    - '695594493493'
    - '030020010010'
    - '030'
    - '192'
    - '040'
    - '030'
    - '192'
    - '040'
    layout: charachorder
  standard:
    custom_layout:
    - _qwertyuiop_
    - _asdfghjkl;_
    - _zxcvbnm,./_
    - ____
    custom_layout_name: custom
    effort_map:
    - '965446'
    - '732116'
    - '865536'
    - '43'
    layout: qwerty
    same_column_chord_penalty: 2
    same_row_chord_penalty: 2
    scissor_penalty: 3
  type: standard
alts:
  adjective:
    enabled: true
    forms:
    - comparative
    - superlative
  adverb:
    enabled: true
    forms: []
  demonstrative:
    enabled: true
    forms:
    - plural
    - distal
  modal:
    enabled: true
    forms:
    - past
  noun:
    enabled: true
    forms:
    - plural
  number:
    enabled: true
    forms:
    - ordinal
  overwrite: false
  pronoun:
    enabled: true
    forms:
    - objective
    - possessive_det
    - reflexive
  verb:
    enabled: true
    forms:
    - 3sg
    - past
    - gerund
assignment:
  frequency_exponent: 3.0
  min_frequency_weight: 1.0
  priority_tiers: []
  unmatched_penalty: 10000.0
min_word_length: 3
min_chord_length: 0
key_replacement: {}

• output: Refer to #/$defs/OutputOptions. Default:

formats:
- qmk
- zmk
- charachorder
- kanata
- training
qmk:
  alt1_keys:
  - KC_CHORD_ALT1
  alt2_keys:
  - KC_CHORD_ALT2
  alt3_keys:
  - KC_CHORD_ALT1
  - KC_CHORD_ALT2
  chord_keys:
  - KC_CHORD
  file: ~/.config/chordgen/qmk_chords.def
  key_codes:
    ;: KC_SFT_SEMI
    A: KC_SFT_A
    D: KC_GUI_D
    F: KC_CTL_F
    J: KC_CTL_J
    K: KC_GUI_K
    L: KC_ALT_L
    S: KC_ALT_S
  shifted_chord_keys:
  - KC_CHORD
  - KC_CHORD_SFT
zmk:
  alt1_keys:
  - '!'
  alt2_keys:
  - '@'
  alt3_keys:
  - '!'
  - '@'
  chord_keys:
  - $
  chord_timeout: 100
  chords_file: ~/.config/chordgen/zmk_chords.dtsi
  key_positions:
  - _qwertyuiop_
  - _asdfghjkl;_
  - _zxcvbnm,./_
  - _!@#$_
  limit: 200
  macros_file: ~/.config/chordgen/zmk_macros.dtsi
  shifted_chord_keys:
  - $
  - '#'
charachorder:
  file: ~/.config/chordgen/charachorder_chords.json
kanata:
  alt1_keys:
  - lalt
  alt2_keys:
  - spc
  alt3_keys:
  - lalt
  - spc
  chord_keys:
  - prtsc
  chord_timeout: 100
  file: ~/.config/chordgen/kanata_chords.kbd
  key_mapping: {}
  limit: 0
  shifted_chord_keys:
  - prtsc
  - ralt
training:
  file: ~/.config/chordgen/training.txt

• learn: Refer to #/$defs/LearnOptions. Default:

show_words: 10
new_words_per_day: 20
reviews_per_day: 200
leech_threshold: 8
mastery_threshold: 3
learning_steps: 5
show_chord_steps: 3
relearn_steps: 2
target_retention: 0.9
slow_wpm_fraction: 0.7
slow_min_samples: 20

• drill: Refer to #/$defs/DrillOptions. Default:

show_words: 10
mode: time
count: 25
time_seconds: 30
include_alts: true
always_show_chords: false

• book: Refer to #/$defs/BookOptions. Default:

wpm_window_seconds: 30
max_width: 80
always_show_chords: false

• theme (string): Textual theme used by the learn and drill TUIs. Updated automatically when you change the theme via the in-app command palette (Ctrl+P). Default: "textual-dark".

Definitions

• AdjectiveAltOptions (object)
• enabled (boolean): Default: true.
• forms (array): Adjective forms to fill alt1..alt3 with, in order. Length must be at most 3. Default: ["comparative", "superlative"].
  • Items (string): Must be one of: "comparative" or "superlative".
• AdverbAltOptions (object)
• enabled (boolean): Default: true.
• forms (array): Adverb forms to fill alt1..alt3 with, in order. Length must be at most 3. Default: [].
  • Items (string): Must be one of: "comparative" or "superlative".
• AltOptions (object)
• overwrite (boolean): Overwrite existing alt1/alt2/alt3 values in chords.csv. By default, non-empty alt slots are preserved. Default: false.

• verb: Refer to #/$defs/VerbAltOptions. Default:

  enabled: true
  forms:
  - 3sg
  - past
  - gerund
  

• noun: Refer to #/$defs/NounAltOptions. Default:

  enabled: true
  forms:
  - plural
  

• adjective: Refer to #/$defs/AdjectiveAltOptions. Default:

  enabled: true
  forms:
  - comparative
  - superlative
  

• adverb: Refer to #/$defs/AdverbAltOptions. Default:

  enabled: true
  forms: []
  

• pronoun: Refer to #/$defs/PronounAltOptions. Default:

  enabled: true
  forms:
  - objective
  - possessive_det
  - reflexive
  

• demonstrative: Refer to #/$defs/DemonstrativeAltOptions. Default:

  enabled: true
  forms:
  - plural
  - distal
  

• modal: Refer to #/$defs/ModalAltOptions. Default:

  enabled: true
  forms:
  - past
  

• number: Refer to #/$defs/NumberAltOptions. Default:

  enabled: true
  forms:
  - ordinal
  

• AssignmentOptions (object)

• min_frequency_weight (number): Floor for the weight applied to words missing a frequency value. Treats them as low-priority but still eligible. Default: 1.0.
• unmatched_penalty (number): Cost charged per word that ends up without a chord. Acts as a soft constraint in the optimal matcher: if recovering a word would cost more than this, leaving it unmatched is allowed. Default: 10000.0.
• frequency_exponent (number): Exponent applied to each word's frequency weight before it multiplies the chord score. 1.0 gives a linear cost model. Values > 1 (like the default 3.0) make frequent words dominate the cost so the matcher won't trade a common word's short chord to a rare word that happens to improve the global sum slightly. Must be > 0. Default: 3.0.
• priority_tiers (array): Cumulative frequency-rank cutoffs for tiered assignment. The pool (already in descending-frequency order) is split at each cutoff, then each tier is solved by the optimal matcher in order, with previous tiers' chord keys reserved out. Default [] runs a single global pass. Example [500, 1000] runs three passes: top 500 -> next 500 -> rest. Cutoffs must be strictly increasing; values >= len(pool) are clamped. Default: [].
  • Items (integer)
• BookOptions (object)
• wpm_window_seconds (integer): Sliding window (in seconds) over which the running WPM is computed in book mode. Default: 30.
• max_width (integer): Maximum width (in characters) of the rendered text block in book mode. Long paragraphs are wrapped to this width. Default: 80.
• always_show_chords (boolean): When true, the chord for the current word is rendered beneath it the moment the cursor lands on it, instead of only after a stumble. Mirrors the drill option of the same name. Default: false.
• CharaChorderOutput (object)
• file (string, format: path): Default: "~/.config/chordgen/charachorder_chords.json".
• DemonstrativeAltOptions (object)
• enabled (boolean): Default: true.
• forms (array): Demonstrative forms to fill alt1..alt3 with, in order. Demonstratives are this, that, these, and those arranged on number (singular/plural) and distance (proximal/distal) axes. Length must be at most 3. Default: ["plural", "distal"].
  • Items (string): Must be one of: "singular", "plural", "proximal", or "distal".
• DirectionalKeyboardOptions (object)
• layout (string): Must be one of: "charachorder", "stained", "svalboard_qwerty", or "custom". Default: "charachorder".
• directional_change_penalty (integer): A penalty to add when chords have different directions per finger on the same hand. Can be set to -1 to disable this type of chord. Default: 2.
• custom_layout (array): Default: ["_X__X__X__X__X__X__X__X_", "X_XX_XX_XX_XX_XX_XX_XX_X", "_X__X__X__X__X__X__X__X_", "_X__X_", "X_XX_X", "_X__X_", "_X__X_", "X_XX_X", "_X__X_"].
  • Items (string)
• custom_layout_name (string): Display name used for a custom layout in places like the drill score leaderboard. Only meaningful when layout='custom'. Default: "custom".
• effort_map (array): Default: ["040030020020", "695594493493", "030020010010", "030", "192", "040", "030", "192", "040"].
  • Items (string)
• DrillOptions (object)
• show_words (integer): Number of words shown on screen at once during a drill. Default: 10.
• mode (string): How a drill session ends: 'count' stops after a fixed number of words, 'time' stops when the timer runs out. Must be one of: "count" or "time". Default: "time".
• count (integer): Number of words drilled when mode = count. Ignored when mode = time. Default: 25.
• time_seconds (integer): Duration of the drill in seconds when mode = time. Ignored when mode = count. Default: 30.
• include_alts (boolean): When true, alt-slot inflections (alt1/alt2/alt3 columns of chords.csv) ride along into the drill pool whenever their base word is graduated. The chord shown after a stumble is suffixed with the slot digit (e.g. au1) and the alt-slot indicator below the keyboard highlights the matching modifier. Set to false to drill only the base word from each chord row. Default: true.
• always_show_chords (boolean): When true, chords are revealed below every word in the drill row, not just on a stumble. Useful while you're still building muscle memory; turn off (default) once you want drill mode to test recall. Default: false.
• GenOptions (object)
• file (string, format: path): Default: "~/.config/chordgen/chords.csv".

• keyboard: Refer to #/$defs/KeyboardOptions. Default:

  type: standard
  standard:
    custom_layout:
    - _qwertyuiop_
    - _asdfghjkl;_
    - _zxcvbnm,./_
    - ____
    custom_layout_name: custom
    effort_map:
    - '965446'
    - '732116'
    - '865536'
    - '43'
    layout: qwerty
    same_column_chord_penalty: 2
    same_row_chord_penalty: 2
    scissor_penalty: 3
  directional:
    custom_layout:
    - _X__X__X__X__X__X__X__X_
    - X_XX_XX_XX_XX_XX_XX_XX_X
    - _X__X__X__X__X__X__X__X_
    - _X__X_
    - X_XX_X
    - _X__X_
    - _X__X_
    - X_XX_X
    - _X__X_
    custom_layout_name: custom
    directional_change_penalty: 2
    effort_map:
    - '040030020020'
    - '695594493493'
    - '030020010010'
    - '030'
    - '192'
    - '040'
    - '030'
    - '192'
    - '040'
    layout: charachorder
  

• alts: Refer to #/$defs/AltOptions. Default:

  overwrite: false
  verb:
    enabled: true
    forms:
    - 3sg
    - past
    - gerund
  noun:
    enabled: true
    forms:
    - plural
  adjective:
    enabled: true
    forms:
    - comparative
    - superlative
  adverb:
    enabled: true
    forms: []
  pronoun:
    enabled: true
    forms:
    - objective
    - possessive_det
    - reflexive
  demonstrative:
    enabled: true
    forms:
    - plural
    - distal
  modal:
    enabled: true
    forms:
    - past
  number:
    enabled: true
    forms:
    - ordinal
  

• assignment: Refer to #/$defs/AssignmentOptions. Default:

  min_frequency_weight: 1.0
  unmatched_penalty: 10000.0
  frequency_exponent: 3.0
  priority_tiers: []
  

• min_word_length (integer): Default: 3.

• min_chord_length (integer): The minimum length a chord, setting this to 2 and disabling the chord key is a way to avoid needing a chord key. This works well on CharaChorder, but you will need to lower the chord timeout to avoid missfires on other keyboards. Default: 0.
• key_replacement (object): Map characters to replacements when generating chord candidates. For example, if your keyboard lacks 'q' and 'z', set {'q': 'k', 'z': 's'} so chords use 'k' instead of 'q' and 's' instead of 'z' -- the typed word is unaffected, only the chord string changes. Useful for remapping non-letter characters too: "'": x lets a word like "o'clock" earn a chord that contains 'x' wherever the apostrophe sits. Each key must be a single lowercase character; its replacement must be a single lowercase letter that exists on your keyboard. Can contain additional properties. Default: {}.
  • Additional properties (string)
• KanataOutput (object)
• file (string, format: path): Default: "~/.config/chordgen/kanata_chords.kbd".
• chord_keys (array): Default: ["prtsc"].
  • Items (string)
• shifted_chord_keys (array): Default: ["prtsc", "ralt"].
  • Items (string)
• alt1_keys (array): Default: ["lalt"].
  • Items (string)
• alt2_keys (array): Default: ["spc"].
  • Items (string)
• alt3_keys (array): Default: ["lalt", "spc"].
  • Items (string)
• limit (integer): Default: 0.
• chord_timeout (integer): Default: 100.
• key_mapping (object): Since Kanata combos are based in the layout in defsrc (probably qwerty) you will need to remap the letters if you are using a custom layout eg. 'a': 'b'. Can contain additional properties. Default: {}.
  • Additional properties (string)
• KeyboardOptions (object)
• type (string): Must be one of: "standard" or "directional". Default: "standard".

• standard: Refer to #/$defs/StandardKeyboardOptions. Default:

  layout: qwerty
  scissor_penalty: 3
  same_column_chord_penalty: 2
  same_row_chord_penalty: 2
  custom_layout:
  - _qwertyuiop_
  - _asdfghjkl;_
  - _zxcvbnm,./_
  - ____
  custom_layout_name: custom
  effort_map:
  - '965446'
  - '732116'
  - '865536'
  - '43'
  

• directional: Refer to #/$defs/DirectionalKeyboardOptions. Default:

  layout: charachorder
  directional_change_penalty: 2
  custom_layout:
  - _X__X__X__X__X__X__X__X_
  - X_XX_XX_XX_XX_XX_XX_XX_X
  - _X__X__X__X__X__X__X__X_
  - _X__X_
  - X_XX_X
  - _X__X_
  - _X__X_
  - X_XX_X
  - _X__X_
  custom_layout_name: custom
  effort_map:
  - '040030020020'
  - '695594493493'
  - '030020010010'
  - '030'
  - '192'
  - '040'
  - '030'
  - '192'
  - '040'
  

• LearnOptions (object)

• show_words (integer): Number of words shown on screen at once during learning. Default: 10.
• new_words_per_day (integer): Maximum number of brand-new words introduced per calendar day, inspired by Anki's 'new cards per day' setting. Once the day's quota is exhausted no more new words are added until tomorrow. Default: 20.
• reviews_per_day (integer): Maximum number of overdue / re-drilled review words surfaced per calendar day. Prevents a long absence from dumping the entire backlog at once. Default: 200.
• leech_threshold (integer): Number of lapses (Again ratings on a graduated word) after which a word is considered a 'leech' and called out in the session summary. Set to 0 to disable leech detection. Default: 8.
• mastery_threshold (integer): Number of total FSRS reviews before a word is considered mastered and its chord is hidden during practice. If you make a mistake on a mastered word, its chord is revealed again for that attempt. Default: 3.
• learning_steps (integer): Number of consecutive correct repetitions a brand-new word must earn in one session before it graduates to Review state. Each error resets the step counter to zero so the word starts over. Default: 5.
• show_chord_steps (integer): How many of the initial learning steps show the chord during the learning phase. After this many consecutive correct reps the chord is hidden for the remaining learning steps. An error resets the counter and the chord reappears. Default: 3.
• relearn_steps (integer): Number of consecutive correct repetitions a lapsed word must earn before re-graduating to Review state. Each error resets the step counter to zero so the word starts over. Default: 2.
• target_retention (number): FSRS desired retention probability. The next review for each word is scheduled when its predicted recall falls to this value. Default: 0.9.
• slow_wpm_fraction (number): A correct word counts as 'slow' (FSRS hard) when its per-word WPM is below this fraction of the user's rolling median per-word WPM. Set to 0 to disable slow grading. Default: 0.7.
• slow_min_samples (integer): Minimum number of recorded per-word WPM samples before slow grading activates. Until this is reached all correct words are graded 'good'. Default: 20.
• ModalAltOptions (object)
• enabled (boolean): Default: true.
• forms (array): Modal-verb forms to fill alt1..alt3 with, in order. Modals are paired present <-> past: can/could, will/would, shall/should, may/might. must has no past form. Length must be at most 3. Default: ["past"].
  • Items (string): Must be one of: "present" or "past".
• NounAltOptions (object)
• enabled (boolean): Default: true.
• forms (array): Noun forms to fill alt1..alt3 with, in order. Length must be at most 3. Default: ["plural"].
  • Items (string): Must be one of: "plural" or "singular".
• NumberAltOptions (object)
• enabled (boolean): Default: true.
• forms (array): Number forms to fill alt1..alt3 with, in order. Numbers are cardinal/ordinal pairs (one/first, two/second, ...). Length must be at most 3. Default: ["ordinal"].
  • Items (string): Must be one of: "cardinal" or "ordinal".
• OutputOptions (object)
• formats (array): Default: ["qmk", "zmk", "charachorder", "kanata", "training"].
  • Items (string): Must be one of: "qmk", "zmk", "charachorder", "kanata", or "training".

• qmk: Refer to #/$defs/QmkOutput. Default:

  file: ~/.config/chordgen/qmk_chords.def
  chord_keys:
  - KC_CHORD
  shifted_chord_keys:
  - KC_CHORD
  - KC_CHORD_SFT
  alt1_keys:
  - KC_CHORD_ALT1
  alt2_keys:
  - KC_CHORD_ALT2
  alt3_keys:
  - KC_CHORD_ALT1
  - KC_CHORD_ALT2
  key_codes:
    ;: KC_SFT_SEMI
    A: KC_SFT_A
    D: KC_GUI_D
    F: KC_CTL_F
    J: KC_CTL_J
    K: KC_GUI_K
    L: KC_ALT_L
    S: KC_ALT_S
  

• zmk: Refer to #/$defs/ZmkOutput. Default:

  chords_file: ~/.config/chordgen/zmk_chords.dtsi
  macros_file: ~/.config/chordgen/zmk_macros.dtsi
  chord_keys:
  - $
  shifted_chord_keys:
  - $
  - '#'
  alt1_keys:
  - '!'
  alt2_keys:
  - '@'
  alt3_keys:
  - '!'
  - '@'
  limit: 200
  chord_timeout: 100
  key_positions:
  - _qwertyuiop_
  - _asdfghjkl;_
  - _zxcvbnm,./_
  - _!@#$_
  

• charachorder: Refer to #/$defs/CharaChorderOutput. Default:

  file: ~/.config/chordgen/charachorder_chords.json
  

• kanata: Refer to #/$defs/KanataOutput. Default:

  file: ~/.config/chordgen/kanata_chords.kbd
  chord_keys:
  - prtsc
  shifted_chord_keys:
  - prtsc
  - ralt
  alt1_keys:
  - lalt
  alt2_keys:
  - spc
  alt3_keys:
  - lalt
  - spc
  limit: 0
  chord_timeout: 100
  key_mapping: {}
  

• training: Refer to #/$defs/TrainingOutput. Default:

  file: ~/.config/chordgen/training.txt
  

• PronounAltOptions (object)

• enabled (boolean): Default: true.
• forms (array): Pronoun forms to fill alt1..alt3 with, in order. Length must be at most 3. Default: ["objective", "possessive_det", "reflexive"].
  • Items (string): Must be one of: "nominative", "objective", "possessive_det", "possessive_pron", or "reflexive".
• QmkOutput (object)
• file (string, format: path): Default: "~/.config/chordgen/qmk_chords.def".
• chord_keys (array): Default: ["KC_CHORD"].
  • Items (string)
• shifted_chord_keys (array): Default: ["KC_CHORD", "KC_CHORD_SFT"].
  • Items (string)
• alt1_keys (array): Default: ["KC_CHORD_ALT1"].
  • Items (string)
• alt2_keys (array): Default: ["KC_CHORD_ALT2"].
  • Items (string)
• alt3_keys (array): Default: ["KC_CHORD_ALT1", "KC_CHORD_ALT2"].
  • Items (string)

• key_codes (object): Can contain additional properties. Default:

  A: KC_SFT_A
  S: KC_ALT_S
  D: KC_GUI_D
  F: KC_CTL_F
  J: KC_CTL_J
  K: KC_GUI_K
  L: KC_ALT_L
  ;: KC_SFT_SEMI
  

  • Additional properties (string)
  • StandardKeyboardOptions (object)
  • layout (string): Must be one of: "qwerty", "colemak", "colemak_dh", "canary", "engram_2021", "engram_en", "enthium_v14", or "custom". Default: "qwerty".
  • scissor_penalty (integer): A penalty to add when pressing keys on the top and bottom rows together. Can be set to -1 to disable this type of chord. Default: 3.
  • same_column_chord_penalty (integer): A penalty to add when pressing 2 keys and the same time with the same finger in the same column. Can be set to -1 to disable this type of chord. Default: 2.
  • same_row_chord_penalty (integer): A penalty to add when pressing 2 keys and the same time with the same finger in the same row. Can be set to -1 to disable this type of chord. Default: 2.
  • custom_layout (array): Default: ["_qwertyuiop_", "_asdfghjkl;_", "_zxcvbnm,./_", "____"].
  • Items (string)
  • custom_layout_name (string): Display name used for a custom layout in places like the drill score leaderboard. Only meaningful when layout='custom'. Default: "custom".
  • effort_map (array): Default: ["965446", "732116", "865536", "43"].
  • Items (string)
  • TrainingOutput (object)
  • file (string, format: path): Default: "~/.config/chordgen/training.txt".
  • VerbAltOptions (object)
  • enabled (boolean): Default: true.
  • forms (array): Verb forms to fill alt1..alt3 with, in order. Length must be at most 3. Default: ["3sg", "past", "gerund"].
  • Items (string): Must be one of: "3sg", "past", "gerund", or "ppart".
  • ZmkOutput (object)
  • chords_file (string, format: path): Default: "~/.config/chordgen/zmk_chords.dtsi".
  • macros_file (string, format: path): Default: "~/.config/chordgen/zmk_macros.dtsi".
  • chord_keys (array): Default: ["$"].
  • Items (string)
  • shifted_chord_keys (array): Default: ["$", "#"].
  • Items (string)
  • alt1_keys (array): Default: ["!"].
  • Items (string)
  • alt2_keys (array): Default: ["@"].
  • Items (string)
  • alt3_keys (array): Default: ["!", "@"].
  • Items (string)
  • limit (integer): Limit the number of chords outputted. It will vary depending on MCU, but I have found ZMK to be quite limited compared to QMK with the number or chords it can fit. Default: 200.
  • chord_timeout (integer): Default: 100.
  • key_positions (array): Should contain the same number of characters as keys on your keyboard. Use _ to ignore a key. Chord, shift, alt1, alt2 can be represented by shifted characters such as $#!@. Spaces will be ignored and can be used for formatting. Default: ["_qwertyuiop_", "_asdfghjkl;_", "_zxcvbnm,./_", "_!@#$_"].
  • Items (string)