codename-generator

English · Deutsch

---

A terminal codename generator. Pick a theme (Greek gods, racehorses, gemstones, whisky, ...), get a batch of unique suggestions (10 to 40, your pick) combined with adjective or verb modifiers and optional phonetic mutations.

Themes

Greek gods · Egyptian gods · Norse gods · Constellations · Zodiac · Animals · Dangerous animals · Racehorses · Flowers · Gemstones · Wines · Whisky · Mountains · Mushrooms · Historic ships · Landmarks · Swatch watches · Dev · Random (pooled)

German themes (language: de): Tierwelt · Sagenwesen · Wetter und Landschaft · Random (DE)

Themes whose words are proper names (Greek/Egyptian/Norse gods, racehorses, mountains, landmarks, historic ships, whisky, wines, Swatch watches) are marked language: neutral. They show up in every language and take the modifiers of the one you picked - Silent Secretariat in English, Stiller Secretariat in German.

Two themes use their own curated word pools:

• Evocative - a stark adjective + an emotionally charged noun (Cold Ember, Iron Hour, Sacred Tide). Never mutated.
• Power words - single bold standalone words, no modifiers (Mythos, Skyline, Oracle, Aegis).

A theme YAML can override the global modifier pools (adjectives, verbs), restrict the name patterns, disable mutation (mutate: false) or set the mutation level it starts at (default_mutation).

Setup

setup.bat        # Windows
./setup.sh       # macOS/Linux

Requires uv.

Usage

TUI (default)

run.bat          # Windows
./run.sh         # macOS/Linux
uv run codename  # any platform

Keys: r regenerate · c copy slug · n copy name · m bump mutation +25% · t cycle theme · f favorite · v view favorites · l language · a about · q quit

The left settings panel has three sliders - mutation chance (0-100%), word count (1, 2 or 3 visible words per name) and suggestions (10/20/30/40 names per batch) - plus a language dropdown (see Languages). Moving a slider re-renders the current set of names in place so you see the effect immediately — only r draws a fresh batch. Each theme keeps its own set, so switching themes back and forth never loses what you had. Hover a theme in the list for a tooltip describing it. Right-click any suggestion for a context menu (copy slug/name, favorite, regenerate). The theme list starts with a Favorites entry — selecting it lists your saved favorites on the right, where only the mutation slider applies and re-mutates them live. Ships with 35+ colour themes (Textual built-ins plus retro palettes) — switch with t or the Ctrl+P theme picker. Chosen colour theme, mutation chance, word count, suggestion count and favorites are persisted to ~/.codename-generator/settings.json across restarts.

CLI

uv run codename --list-themes
uv run codename -t greek-gods           # 30 suggestions (default)
uv run codename -t flowers -n 5 --mutation-chance 0.6 --seed 42
uv run codename -t random -n 20         # pulls from every theme
uv run codename -t whisky --words 3     # exactly 3 components per name
uv run codename --list-themes --lang de  # German plus the neutral themes
uv run codename -t tierwelt -n 10       # German names, inflected
uv run codename -t swatch --lang de      # proper names, German modifiers

A * next to a suggestion means a phonetic mutation was applied (Pegasus -> Pegasos, Carnation -> Carnatiyn, Frankel -> Frankil).

Adding themes

Drop a YAML file into src/codename_generator/data/themes/:

name: My Theme
description: ...
words:
  - Word1
  - Word2

Languages

A theme declares its language, and that language decides which modifier pools it draws from, how the name is put together and whether the modifier gets inflected. Themes without a language key are English. A theme of proper names uses language: neutral - it stays visible in every language and borrows the modifiers of whichever one is active.

name: Tierwelt
description: Heimische Tiere
language: de
words:
  - Falke|m
  - Eule|f
  - Wiesel|n

The |m / |f / |n / |p marker is the grammatical gender of the noun. German inflects an attributive modifier after it - still becomes Stiller Falke, Stille Eule, Stilles Wiesel. Without a marker the masculine form is used. Languages that do not inflect (English) ignore it.

Modifier pools live per language in src/codename_generator/data/modifiers/<lang>/ - adjectives.yaml, verbs.yaml and agents.yaml. A language without its own folder falls back to the English pools. German verbs are present participles (jagend, lauernd), because that is what German puts in front of a noun.

Word order differs too: German never trails a participle, so theme-verb ("Falke Jagend") is dropped and three-word names use adj-verb-theme ("Stiller Jagender Falke") instead of adj-theme-verb.

Each language gets its own Random theme (random, random-de, ...) so pooled draws never mix a German noun with an English adjective - neutral themes feed into all of them.

Pick the language in the settings panel (bottom dropdown) or cycle it with l. The theme list then shows that language plus the neutral themes, and every name is generated with its modifiers. On the CLI, --lang does the same for --list-themes and for generation. The setting is persisted like the sliders. Slugs stay ASCII: umlauts are written out (Grüner Blitz -> gruener-blitz), accents are stripped (Volupté -> volupte).

Credits

The settings sliders use textual-slider by Tom J Gooding - thank you for the widget.

License

Apache License 2.0 - see LICENSE.