|
|
||
|---|---|---|
| .claude-plugin | ||
| docs | ||
| hooks | ||
| scripts | ||
| tests | ||
| types | ||
| .gitignore | ||
| LICENSE | ||
| README.md | ||
| THIRD-PARTY-NOTICES.md | ||
| tsconfig.json | ||
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.
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
- 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. Keys2to8open the other games (see More games), and9switches every game to French (see Français). - Press
1with an empty prompt, or run/claudleat 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. - 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
EEofGEESE, 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. - 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.
- 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 listin 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 showsNot enough letterson 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
1on the rowpress 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 |
|---|---|---|
![]() |
![]() |
![]() |
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
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
éore, both giveE, andPECHEstands for pêche and péché alike. - clatter keeps the accents:
trèsmust be typed with itsè, andeforé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.





