No description
Find a file
Yuguo Cao 59c578fef6 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
The four games share hooks/shell (panes, store), hooks/engine/stored.ts and hooks/view/frame.tsx; register.tsx keeps claudle and the hooks with no matcher (ADR-0027, ADR-0028). claugram and clatter get packed word lists from the pinned sources, and the data budget goes to 400 KB (ADR-0029). Specs, designs and test scenarios are in docs/games; decisions in ADR-0027 to ADR-0035.

The terminal snapshots now cover the four games (12 scenarios, random rows masked). They found that clatter lost keys typed while its field was swapped after a space; each word now keeps its own field and the run is read from all of them in typing order (ADR-0035).

claudle changes: the invite row lists the five games, with 1 still opening claudle; the back row or /claudle on a finished game keeps its end line. tsconfig.json reads the types the engine lays in .claude-plugin/types, since the skill's /private/tmp copy is removed when the CLI exits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 13:52:19 +01:00
.claude-plugin 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
docs 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
hooks 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
scripts 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
tests 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
types 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
.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 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
THIRD-PARTY-NOTICES.md 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
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

claudle

claudle is a five-letter word game you play inside Claude Code while Claude works on a turn. You get six guesses to find a hidden word; each guess shows which letters are in the right place, which are in the word elsewhere, and which are not in it. It is a Claude Code mod, so the game opens in a pane next to the chat, and Claude keeps working while you play.

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

The same plugin has four more games to play the same way: clordle (two words at once), cladder (a word ladder), claugram (words from six letters) and clatter (typing speed). See More games.

Needs Claude Code 2.1.304 or later, in the terminal or the desktop app.

Install

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

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

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

Try a checkout for one session instead, without installing:

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

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

Play

  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. Keys 2 to 5 open the other games (see More games).
  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. It stays until you press Enter, which shows the result: the answer, your stats, how many guesses your wins took, and your 10 most recent games. Esc there hides the pane, and the next open starts a new game. Then, in the result:

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 or the desktop app, 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 claudle.hardMode=on. You can also set it in settings.json:

{ "pluginConfigs": { "claudle": { "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 claudle.liveCheck=on, or in settings.json:

{ "pluginConfigs": { "claudle": { "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 four 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

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. An unfinished clordle, cladder or claugram game 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 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 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.

Settings

Two 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). The design is in docs/games/README.md.

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 claudle'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. 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

The game accepts 8,901 words, and 1,768 of them can be answers. 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.

License

MIT, see LICENSE.

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.

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 400000 && 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.