No description
Find a file
2026-11-16 15:32:29 +01:00
.claude-plugin Second look at the French tests: LG-TS-22 rejected the ï of haïr, a French clatter word drawn by Math.random, so it failed at random; share one FRENCH_LETTERS set across the French tests and add a fixed haïr run; the narrow stats read "1 parties", pinned by LG-TS-27, so add playedCount (partie for 0 and 1) to the common table and use it in the narrow claudle, clordle and cladder lines; strings.test fed claubee.taken a string and listed its "+undefined" as same in both languages, so give it a real sample and fail on undefined or NaN in any leaf; drop two unrelated constant checks from lang-flow; type lang-store's records with the real record types; note the singular in the French PRD; and bump the version to 0.21.1 2026-11-16 15:32:29 +01:00
docs Second look at the French tests: LG-TS-22 rejected the ï of haïr, a French clatter word drawn by Math.random, so it failed at random; share one FRENCH_LETTERS set across the French tests and add a fixed haïr run; the narrow stats read "1 parties", pinned by LG-TS-27, so add playedCount (partie for 0 and 1) to the common table and use it in the narrow claudle, clordle and cladder lines; strings.test fed claubee.taken a string and listed its "+undefined" as same in both languages, so give it a real sample and fail on undefined or NaN in any leaf; drop two unrelated constant checks from lang-flow; type lang-store's records with the real record types; note the singular in the French PRD; and bump the version to 0.21.1 2026-11-16 15:32:29 +01:00
hooks Second look at the French tests: LG-TS-22 rejected the ï of haïr, a French clatter word drawn by Math.random, so it failed at random; share one FRENCH_LETTERS set across the French tests and add a fixed haïr run; the narrow stats read "1 parties", pinned by LG-TS-27, so add playedCount (partie for 0 and 1) to the common table and use it in the narrow claudle, clordle and cladder lines; strings.test fed claubee.taken a string and listed its "+undefined" as same in both languages, so give it a real sample and fail on undefined or NaN in any leaf; drop two unrelated constant checks from lang-flow; type lang-store's records with the real record types; note the singular in the French PRD; and bump the version to 0.21.1 2026-11-16 15:32:29 +01:00
scripts French version M5, docs and release: describe the code after M1 to M4 in the main design docs (lld, hld, word-lists and every game doc: the lexicon, keyFor, the strings tables, refusal codes, accent folding and the band's 9 key); amend NFR-1 and NFR-12 for French letters and the 1,150 KB data budget; add the French review commands to the test plan; add a Français section, the French store keys and the Lexique credit to the README with a claubee-fr screenshot and a retaken band shot; mark the French specs and the plan done; and bump the version to 0.21.0 2026-11-16 10:59:24 +01:00
tests Second look at the French tests: LG-TS-22 rejected the ï of haïr, a French clatter word drawn by Math.random, so it failed at random; share one FRENCH_LETTERS set across the French tests and add a fixed haïr run; the narrow stats read "1 parties", pinned by LG-TS-27, so add playedCount (partie for 0 and 1) to the common table and use it in the narrow claudle, clordle and cladder lines; strings.test fed claubee.taken a string and listed its "+undefined" as same in both languages, so give it a real sample and fail on undefined or NaN in any leaf; drop two unrelated constant checks from lang-flow; type lang-store's records with the real record types; note the singular in the French PRD; and bump the version to 0.21.1 2026-11-16 15:32:29 +01:00
types French version M2, every drawn string from a table with no change for English: engines return codes instead of text (Refusal for every refusal, ClaubeeTaken for claubee's points), the shells turn them into text with refusalText, and the views take S from stringsFor(lang); hooks/lang/text holds one section per game plus common for the words several games share, so French translates each once; claubee's rank becomes an index named by S.claubee.ranks, with its stats shape at claubee-stats-2; notices are compared through the table or by code, never by English text; add LG-TS-21 and LG-TS-25 (English halves), point the file-reload snapshot at the common strings, record the design in the LLD, and bump the version to 0.18.0 2026-11-13 16:53:31 +01:00
.gitignore Keep colours in the terminal snapshots as SGR codes, like a Jest snapshot of terminal output 2026-10-21 14:57:21 +02:00
LICENSE Scaffold the claudle mod and ship the word lists 2026-10-21 09:56:56 +02:00
README.md French version M5, docs and release: describe the code after M1 to M4 in the main design docs (lld, hld, word-lists and every game doc: the lexicon, keyFor, the strings tables, refusal codes, accent folding and the band's 9 key); amend NFR-1 and NFR-12 for French letters and the 1,150 KB data budget; add the French review commands to the test plan; add a Français section, the French store keys and the Lexique credit to the README with a claubee-fr screenshot and a retaken band shot; mark the French specs and the plan done; and bump the version to 0.21.0 2026-11-16 10:59:24 +01:00
THIRD-PARTY-NOTICES.md French version M3, the French word data: add scripts/build_word_lists_fr.py, which reads the pinned Lexique 3.83, folds accents to a-z except for clatter's words, builds the known, common and base sets and from them the ten lists in the English formats, asserts every range and the 600 KB budget, and checks its fold against the same 40 samples as foldLetters; generate hooks/data/fr under CC BY-SA 4.0 (573,773 bytes) and give lexiconFor('fr') those lists with French Scrabble's tiles; draw gram and bee seeds from words both base and common so every seed is playable (1,559 and 1,043); add the Lexique notice; add LG-TS-5, LG-TS-6, LG-TS-9, LG-TS-11 to LG-TS-14; and bump the version to 0.19.0 2026-11-13 16:54:33 +01:00
tsconfig.json Add clordle, cladder, claugram and clatter to the plugin, with one band row for all five games, one game pane at a time, and a shell module per game, and bump the version to 0.5.0 2026-10-27 13:52:19 +01:00

clarcade

clarcade is a set of eight word games you play inside Claude Code while Claude works on a turn. It is a Claude Code mod, so a game opens in a pane next to the chat, and Claude keeps working while you play.

The first game, claudle, is a five-letter word game: you get six guesses to find a hidden word, and each guess shows which letters are in the right place, which are in the word elsewhere, and which are not in it. The seven others play the same way: clordle (two words at once), cladder (a word ladder), claugram (words from six letters), clatter (typing speed), claubox (words chained around a box of letters), cloggle (words traced in a letter grid) and claubee (words from seven letters around a center). See More games.

Games are unlimited: each one draws a new puzzle, and your score history and stats carry over between sessions.

claudle docked beside the chat while Claude works on a turn

Needs Claude Code 2.1.304 or later, in the terminal. The desktop app, VS Code and mobile show a pane that says the game needs the terminal (ADR-0044).

Install

Install it from the repository, then start a new session:

claude plugin marketplace add https://forgejo.deziat.ch/deziat/clarcade.git
claude plugin install clarcade@clarcade

Get a newer version with claude plugin update clarcade@clarcade, then /reload-plugins in a running session.

Try a checkout for one session instead, without installing:

git clone https://forgejo.deziat.ch/deziat/clarcade.git
claude --plugin-dir ./clarcade

Use one or the other: a session started with --plugin-dir while the plugin is installed loads it twice.

Play

The row of games above the prompt during a turn

  1. Start a turn. After it has run for 3 seconds, one row shows above the prompt: play: 1: claudle 2: clordle 3: cladder 4: claugram 5: clatter 6: claubox 7: cloggle 8: claubee 9: français, or two or three shorter rows on a narrower terminal. Keys 2 to 8 open the other games (see More games), and 9 switches every game to French (see Français).
  2. Press 1 with an empty prompt, or run /claudle at any time, mid-turn included. The pane opens and takes the keys. In fullscreen from 110 columns it docks beside the chat, with the game at its bottom next to the prompt; otherwise it opens above the prompt.
  3. Type a word and press Enter. There is no text field: letters fill the current row in uppercase, and the cursor sits on the tile where the next letter goes. Digits, spaces and a 6th letter are dropped, and Backspace removes the last letter. Letters always go at the end: Left and Right cannot be blocked and move the cursor, but the next letter or Backspace acts on the end of the row and puts the cursor back on the next tile. The game cannot see an arrow press, so inside a run of one letter, such as the EE of GEESE, or after a paste of 2 or more letters mid-word, the cursor can land off the next tile until your next letter or Backspace.
  4. Each guess turns into tiles one letter at a time, left to right, in your theme's colors; you can type the next word meanwhile. Green (success): right letter, right place. Yellow (warning): the letter is in the word, somewhere else. Gray (inactive): not in the word. The keyboard under the board takes the row's colors once its last tile has turned, keeps the best color seen for each letter, and fades a letter ruled out to a darker gray.
  5. When the 5th letter lands, the Enter mark shows right after it, with the cursor on it. Enter refuses a word not in the list with Not in word list in the row between the board and the keyboard; in a hard game it refuses a word that drops a hint the same way. With the live check on (see Live check), a refused word turns red (your theme's error color), gets no mark, and that row says why before you press Enter. A guess under 5 letters shows Not enough letters on Enter. None of these uses up a guess, and the word stays on its row to fix.

Press Esc to hide the pane mid-game. The keys go back to the prompt, and the game, typed letters included, stays as it was. On a later turn the claudle button above the prompt reads 1: claudle 2/6; 1 or /claudle brings back the same game.

Tab moves the keys from the open pane to the prompt, and so does a click on the prompt. Your typed letters stay. To go back in:

  • press Tab again while the prompt is empty;
  • press ctrl+x then Tab, which switches between the pane and the prompt, also with text in the prompt; right after a Tab out it takes two presses;
  • click the pane;
  • run /claudle;
  • during a turn, press 1 on the row press 1: back to claudle.

The mod never opens the pane by itself. The row above the prompt shows only while a turn runs, so a prompt that starts with 1 stays a prompt between turns.

When a game ends, the board stays and the row under it shows a line: from Unreal! 1/6 to Close one! 6/6 for a win, or the answer, such as Answer: CRANE, for a loss, with the cursor right after it. A win lifts the winning row's tiles one by one and runs a light across the line; a loss shakes the line. It stays until you press Enter, which shows the result: the answer, your stats, how many guesses your wins took, with each of this game's guesses as a row of colored tiles when the pane is 40 columns or wider, and your 10 most recent games. Esc there hides the pane, and the next open starts a new game. Then, in the result, the bottom row reads next game exit esc hide with each key in bold and underlined, and the row above it shows each setting with its key and an on or off block:

key does
n start the next game
x close the pane
Esc hide the pane; the next open starts a new game
Enter nothing, so a second Enter cannot skip the stats

An unfinished game is never replaced: it survives a hot reload, /clear, /resume, a fork and a new session. Letters you typed but did not submit are kept for the session only.

In VS Code and the mobile app the pane shows claudle needs the terminal, and under claude -p the command answers with the same words plus the host's reason.

Hard mode

In hard mode each guess must use what the last guess showed: a green letter stays in its place, and a letter shown green or yellow is used again, as many times as it was shown. Gray letters are still allowed. A guess that breaks this shows 2nd letter must be R or Guess must contain C and uses no row.

Hard mode is off by default. To turn it on, run /config, find the claudle hard mode row and pick on, or type /config clarcade.hardMode=on. You can also set it in settings.json:

{ "pluginConfigs": { "clarcade": { "options": { "hardMode": "on" } } } }

That key is right for a --plugin-dir run; an installed copy may sit under another key, so /config is the sure way. The change applies to your next new game: a game in progress keeps its mode. The pane shows hard next to the keyboard while a hard game runs. Hard games count in the same stats as normal ones.

Live check

The live check is off by default: a full row always shows the Enter mark, and a word the game refuses is reported only when you press Enter. With it on, a full row the game would refuse turns red and row 7 says why before Enter, and only a word the game takes gets the mark. Turn it on in /config (the claudle live check row), with /config clarcade.liveCheck=on, or in settings.json:

{ "pluginConfigs": { "clarcade": { "options": { "liveCheck": "on" } } } }

It changes only what the pane shows, so it applies to the game in progress at once. Hard mode still checks every guess at Enter either way.

More games

The plugin hosts seven more games. Each has its own command and band key, opens in the same pane spot, and keeps its own stats. Only one game pane is open at a time: opening one hides the other, which keeps its game.

game command band key rule
clordle /clordle 2 two 5-letter answers, 7 guesses, both boards scored per guess
cladder /cladder 3 start word to target word, one letter changed per step
claugram /claugram 4 find words of 3-6 letters in six shuffled letters, finish when you like
clatter /clatter 5 type a run of common words, speed and accuracy
claubox /claubox 6 chain words around 12 letters on 4 sides until every letter is used
cloggle /cloggle 7 find words traced through neighbor cells of a 4x4 letter grid
claubee /claubee 8 find words of 4+ letters from 7 letters, each with the center letter, for points and ranks
clordle cloggle claubee
clordle: two boards, one guess on both cloggle: a word traced in the letter grid claubee: seven letters around a center, with the found words

The press 1: back to <game> row, Esc, Tab and the result keys (n next, x close, Esc hide) work as they do for claudle, and each game ends on a line that waits for Enter before its result view; a win runs a light across that line and a loss or a give-up shakes it. Arrow keys work as in claudle: Left and Right cannot be blocked and move the cursor, but the next letter or Backspace acts on the end of the word and puts the cursor back. An unfinished game of any of them but clatter survives a reload and a new session; a clatter run lasts for the session.

clordle

Two hidden words, one board each, 7 guesses. Each guess goes on both boards and is colored against each board's own word; a solved board stops taking rows. Each key on the keyboard has two halves: the letter takes the left board's color, the cell after it the right board's. Below 40 columns the tiles shrink to one cell. A win reads Both in 5/7, a loss Answers: CRANE LOUSE.

cladder

Go from the top word to the bottom word, changing one letter per step; every step must be a real word. The target row turns a letter green where your last word already has it. par is the shortest ladder. Refusals: Not in word list, Change one letter. Type a word already on your ladder to go back to it. Press 0 twice to give up. A win reads At par! 4 steps or Solved in 6 (par 4), and the result view shows your ladder and one shortest ladder.

claugram

Find words of 3 to 6 letters in six shuffled letters, as many as you can. Only the letters shown can be typed, each as often as it appears. Space shuffles the letters. Words beyond the common list count as bonus. There is no timer unless you set one: press 0 twice to finish, or find every word. The end line reads Found 12 of 40, and the result view lists the words you found, then the words you missed.

clatter

Type the words shown; space moves to the next word, and Backspace fixes the current one. Right words turn green, wrong ones red. Only the time between your keys counts, each gap capped at 2 seconds, so a permission dialog or a pause does not slow your score. The end line reads 62 wpm 96%; the result view adds the words, the time, your best and your average of the last 10 runs.

claubox

Twelve letters sit on the four sides of a box, three per side. Make words from them: each word starts with the last letter of the word before, and two letters in a row never come from the same side, so the game drops a letter that would break that rule. Use all twelve letters to win, in as few words as you can. Backspace past the first letter takes the last word back to fix it. Press 0 twice to give up. The end line reads Solved in 3 words or Gave up, with a two-word solution above it, such as two words: BLANKET-TOUCHY.

cloggle

Sixteen letters in a 4x4 grid. Type words of 3 or more letters whose letters touch each other in the grid, across, down or diagonally, each cell used once. The game keeps a letter only when the word so far can still be traced, and marks its path on the grid. Words beyond the common list count as bonus. Press 0 twice to finish, or find every word. The end line reads Found 12 of 44 +2 bonus, and the result view lists the words you found, then the words you missed. In cloggle, claubee and claugram a list longer than its rows scrolls with ] and [ or the mouse wheel: -3 at its start counts the words above, +5 at its end the words below. While a list holds more than its rows, the message row shows a mark, its triangles bright on the ways the list can move, by turns with any message. Click the pane and Right and Left scroll too; the pane then draws its own blinking caret, as the terminal cursor moves to the prompt. Esc hands the keys back to the prompt; the caret goes at your next key there.

claubee

Seven letters, one in the center. Type words of 4 or more letters that use the center letter and only these seven, as often as you like. A 4-letter word scores 1 point, a longer word one per letter, and a word with all seven letters is a pangram, worth 7 more. Your rank climbs with your share of the top score, from Egg to Queen. Space shuffles the outer letters. Press 0 twice to finish, or find every word. The end line reads Forager 30 of 91 points, and the result view lists the words you found, then the words you missed.

Settings

A language setting (en or fr, default en) applies to all eight games. Two more settings in /config change the new games: claugramTimer (off, 1, 2 or 3 minutes per claugram game, default off) and clatterWords (10, 25 or 50 words per clatter run, default 25). Each game's result view also shows its settings above the keys row: press t in claugram or w in clatter for the next value, and h or l in claudle to flip hard mode or the live check. A change applies from the next game. The design is in docs/games/README.md.

Français

claubee in French: the rank Butineuse, French words found, and the espace mélanger and 0 finir keys

Every game also plays in French. Press 9 in the row above the prompt during a turn, run /config clarcade.language=fr, or pick fr in the Language / Langue row of /config. The band then reads jouer : ... 9: english, and 9 switches back. The rules, keys and keyboard stay the same; the words and every text become French: Pas dans la liste, Réponse : MONDE, claubee's ranks from Larve to Reine.

  • The word games play on A to Z. Accents are folded: type é or e, both give E, and PECHE stands for pêche and péché alike.
  • clatter keeps the accents: très must be typed with its è, and e for é counts as a wrong letter.
  • Each language keeps its own games and stats. An unfinished French game waits in French while you play in English, and the other way round.

The French words come from Lexique 3.83, every plural and verb form included, so parlerions counts in cloggle. Offensive words are not filtered out. The design is in docs/french/.

Stats

The result view shows games played, win percentage, current and longest win streak, and the guess distribution. A win streak counts finished games in a row, not days.

Everything is kept in clarcade's own JSON file under ~/.claude/plugins/store/, on your machine only. It holds three keys: history, one record per finished game (answer, score 1 to 6 or X, finish time, and a hard flag for a hard game); current, the unfinished game; and last, your latest finished game with every guess and its tile colors, so you can check a board after the pane has moved on. Each finish replaces last, unless a newer claudle wrote it. History keeps the newest 10,000 games. The other games keep their own keys in the same file (clordle.current, clordle.history, and so on; clatter keeps only its history), each with its newest 1,000 games. French games keep the same keys led by fr. (fr.history, fr.cloggle.current...), and French claudle keeps its newest 1,000 games. There is no export; deleting the file resets your stats. If the file is unreadable or full, the game still plays and is just not saved.

Word lists

claudle accepts 8,901 words, and 1,768 of them can be answers. The other games add words of 3 to 6 letters and common words of 7 letters or more from the same sources. Both lists are built from ENABLE2K (public domain) and SCOWL 2020.12.07 (Kevin Atkinson, permissive license). The frequency bands of 12dicts 6.0.2 (Alan Beale, under AGID's permissive notice) and the inflection lists of AGID 2016.01.19 (Kevin Atkinson, permissive license) decide which words can be answers. See THIRD-PARTY-NOTICES.md for the credits and license texts, and docs/word-lists.md for how the lists are made.

The French lists come from Lexique 3.83 by Boris New and Christophe Pallier (CC BY-SA 4.0): 1,862 answers, 5,037 five-letter words and about 115,000 forms in all. docs/french/word-lists.md says how they are made.

License

MIT, see LICENSE. The French word lists in hooks/data/fr/ are adapted from Lexique 3.83 and stay under CC BY-SA 4.0 (see THIRD-PARTY-NOTICES.md).

Develop

The spec set is in docs/: the requirements in prd.md, the build sheet in lld.md, and the test scenarios in test-plan.md. The game logic in hooks/engine/ and hooks/<game>/engine.ts is pure TypeScript with no host calls; only hooks/register.tsx, hooks/shell/* and hooks/<game>/shell.tsx talk to Claude Code (ADR-0028).

Run the mod from your checkout. An interactive session watches the folder and hot-reloads the hooks module on save:

claude --plugin-dir .

Run the tests, which every change starts with (test first, see it fail, then make it pass):

claude plugin test .

The CI gate runs on every commit, and a red gate blocks the merge:

claude plugin validate --strict . && claude plugin test . && tsc -p .

The terminal snapshots check the real paint in tmux before a release (see docs/test-plan.md): python3 -I scripts/e2e/snapshot.py. The screenshots in docs/images/ come from the same tmux run, painted by headless Chrome: python3 -I scripts/e2e/screenshots.py.

tsconfig.json reads the host's types from .claude-plugin/types/claude-code/index.d.ts, which Claude Code writes (and keeps current) each time it loads the mod from this folder, so run claude --plugin-dir . once before tsc -p .. The folder is gitignored.

The review commands check what a test cannot read. Each prints nothing or ok:

grep -rniE '#[0-9a-f]{6}\b' hooks/view/
test "$(cat hooks/data/*.ts | wc -c)" -lt 520000 && echo ok
test -f LICENSE && test -f THIRD-PARTY-NOTICES.md && grep -q '"license": "MIT"' .claude-plugin/plugin.json && echo ok
jq -e '.userConfig.hardMode | .type == "string" and .options == ["on", "off"] and .default == "off"' .claude-plugin/plugin.json >/dev/null && echo ok
jq -e '.userConfig.liveCheck | .type == "string" and .options == ["on", "off"] and .default == "off"' .claude-plugin/plugin.json >/dev/null && echo ok
jq -e '.userConfig.claugramTimer | .type == "string" and .options == ["off", "1", "2", "3"] and .default == "off"' .claude-plugin/plugin.json >/dev/null && echo ok
jq -e '.userConfig.clatterWords | .type == "string" and .options == ["10", "25", "50"] and .default == "25"' .claude-plugin/plugin.json >/dev/null && echo ok

The word-list modules in hooks/data/ are generated; rebuild them with scripts/build_word_lists.py as docs/word-lists.md describes, never by hand. Before a release, run the manual live checks in docs/test-plan.md.