{
  "markdown": "<!--\nKeyword rationale (d4s / DataForSEO, 2026-07-16, google en):\n  word search generator 33,100/mo KD37 · word search maker 33,100 KD40 · sudoku solver 40,500 KD41\n  sudoku generator 1,000 KD9 · sudoku puzzle generator 170 KD10 · crossword generator 12,100 KD51\n  printable word search 18,100 KD5 · printable sudoku puzzles 4,400 KD15 · expert sudoku 2,400 KD0\n  daily sudoku 27,100 KD37 · hangman game 40,500 KD35 · llm evals 480 KD28\n  Dev modifiers (cli/npm/javascript/github variants) are all ≤10/mo — the surfaces that matter are\n  GitHub search, npm search, and Google snippets of the repo page, all of which read the repo\n  description, package.json description/keywords, and README H1/H2s.\nContiguous phrases to keep intact: \"word search generator\", \"crossword generator\",\n  \"sudoku generator\", \"sudoku solver\", \"printable word search\", \"printable sudoku\",\n  \"expert sudoku\", \"daily sudoku\", \"LLM evals\", \"puzzle generator CLI\", \"MCP server\".\nTop-page deep links (GSC 2026-07, by clicks): mystery-and-murder printable word search (237),\n  /hangman (25), /printable (10), dyslexic-friendly blog post (9), /maker (4).\nBanned claims (not shipped): word search solver, crossword solver, anagram solver (word tools\n  search only the 30 starter banks), MCP server, PNG output, AI clue generation,\n  nonograms/cryptograms, speed guarantees for expert sudoku, \"full English dictionary\".\nIP rule: the package ships only the 30 generic starter themes in scripts/wordbanks-source.json —\n  NEVER include or reference-compile the proprietary puzzletide.com word bank dataset here.\n-->\n\n# PuzzleTide CLI — word search, crossword & sudoku generator\n\n[![npm package](https://img.shields.io/npm/v/puzzletide?label=npm)](https://www.npmjs.com/package/puzzletide)\n[![Docs](https://img.shields.io/badge/docs-GitHub-24292F)](https://github.com/Caravaca-Labs/puzzletide-cli/tree/main/docs)\n[![Agent skills](https://img.shields.io/badge/agent_skills-SKILL.md-0F766E)](https://github.com/Caravaca-Labs/puzzletide-cli/blob/main/docs/agent-skills.md)\n[![smithery badge](https://smithery.ai/badge/caravaca-labs/puzzletide)](https://smithery.ai/servers/caravaca-labs/puzzletide)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)\n\nWord search generator, crossword generator, and sudoku generator + solver in\none local-first puzzle generator CLI — with printable PDF worksheets, starter\nword banks, verifiable LLM evals, and bundled agent skills. From the makers\nof [puzzletide.com](https://puzzletide.com).\n\n## Install\n\n```sh\nnpm install -g puzzletide\nptide --version\n```\n\nThe package installs both binaries:\n\n- `ptide`\n- `puzzletide`\n\n## Why generate puzzles with a CLI\n\nAsk a language model to write a word search and you get a grid where half the\nwords are broken; ask it for a sudoku and you usually get one with several\nsolutions, or none. Grids are exactly the kind of output LLMs are bad at and\ndeterministic code is good at.\n\nPuzzleTide CLI is that deterministic code:\n\n- Every word search word is placed and verifiable — placement coordinates are\n  part of the output, and the generators are property-tested.\n- Every generated sudoku is checked to have exactly one solution.\n- Every crossword is validated against its own clues before it's returned.\n- Same `--seed` in, same puzzle out, on any machine.\n\nThe package also ships `SKILL.md` agent skills, so coding agents (Pi, Hermes,\nOpenClaw, and other SKILL.md-based systems) reach for the CLI instead of\nhand-writing grids.\n\n## Command model\n\n```sh\nptide <namespace> <operation> [input] [options]   # for humans\nptide run <tool-id> [input] [options] --json      # canonical, for scripts/agents\nptide tools list | search <q> | info <id> | docs <id>\nptide agent manifest\n```\n\nUse short commands interactively and canonical tool ids in automation:\n\n```sh\nptide sudoku generate --difficulty hard\nptide run puzzle.sudoku.generate --difficulty hard --json\n```\n\n## Word search generator\n\nEight placement directions with easy/medium/hard presets, auto-sized grids\n(6–30), accent/space/hyphen normalization. Words come from flags, files, or\nbundled themes:\n\n```sh\n# Word search from your own words, printed in the terminal\nptide wordsearch generate --words \"coral,shark,kelp,wave,tide\"\n\n# Themed printable word search (puzzle page + solution page)\nptide wordsearch generate --theme animals/ocean-animals --pdf ocean.pdf\n\n# Kids mode: easy = forward-only words\nptide wordsearch generate --theme seasonal/halloween --difficulty easy\n```\n\n## Crossword generator\n\nInterlocking placement with standard crossword numbering, clue-grid\nvalidation, and deterministic fallback clues for theme words. Words that\ncannot interlock are reported instead of silently dropped:\n\n```sh\n# Crossword with your clues\nptide crossword generate --words \"PARIS: Capital of France; TOKYO: Capital of Japan\"\n\n# From a JSON file, as a printable PDF\nptide crossword generate --file words.json --pdf review.pdf --title \"Unit 4 Review\"\n```\n\n## Sudoku generator and solver\n\nEasy, medium, hard, and expert sudoku (17–21 givens) with a uniqueness\nguarantee, an instant solver, and a validator that reports conflicts,\nsolvability, and solution uniqueness:\n\n```sh\nptide sudoku generate --difficulty expert --seed 42\nptide sudoku solve \"53..7....6..195....98....6.8...6...34..8.3..17...2...6.6....28....419..5....8..79\"\nptide sudoku validate --file puzzle.txt\nptide daily        # today's daily sudoku, same for everyone on a given UTC day\n```\n\n## Printable puzzles: PDF worksheets and SVG\n\nEvery generator takes `--pdf <file>` for a print-ready worksheet — puzzle\npage(s) plus a solution page (`--paper letter|a4`, omit the answer key with\n`--no-solution-page`) — and `--svg <file>` for vector images. Printable word\nsearch and printable sudoku sheets for a classroom packet are one loop away:\n\n```sh\nfor i in 1 2 3 4 5; do\n  ptide sudoku generate --difficulty medium --seed \"$i\" --pdf \"sudoku-$i.pdf\" --title \"Sudoku #$i\"\ndone\n```\n\nPrefer ready-made sheets? The\n[mystery and murder printable word search](https://puzzletide.com/word-search/vocabulary/mystery-and-murder/printable)\nis a reader favorite, with hundreds more at\n[printable puzzles](https://puzzletide.com/printable).\n\n## Word banks and word tools\n\n30 starter themes (ocean animals, fruits, space, halloween, ...) — browse,\nsearch, pattern-match, anagrams, random picks. Bring your own lists via\n`--words`/`--file`, or play the full curated collection at\n[puzzletide.com](https://puzzletide.com):\n\n```sh\nptide words themes --search dinosaur\nptide words match \"c_r_l\"        # crossword-style pattern matching\nptide words anagram coral\n```\n\nThere's a hangman game in the terminal too: `ptide play hangman`.\n\n## Agent skills\n\nPi can load the bundled skills directly from this npm package:\n\n```sh\npi install npm:puzzletide\n```\n\nThe package manifest declares:\n\n```json\n{\n  \"pi\": {\n    \"skills\": [\"./skills\"]\n  }\n}\n```\n\nFive skills are included: word search, crossword, sudoku, printable puzzles,\nand agent evals. Each prefers the local CLI and checks `ptide`, `puzzletide`,\nthen `npx puzzletide`. Skills never auto-install anything; agents should ask\nthe user before installing.\n\n## MCP server for Claude Desktop, Cursor, and any MCP client\n\nThe companion package [`puzzletide-mcp`](https://www.npmjs.com/package/puzzletide-mcp)\nexposes every non-interactive tool over the Model Context Protocol — the same\nword search generator, crossword generator, sudoku generator/solver, word\ntools, and evals, callable from Claude Desktop, Cursor, Windsurf, or any MCP\nclient:\n\n```json\n{\n  \"mcpServers\": {\n    \"puzzletide\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"puzzletide-mcp\"]\n    }\n  }\n}\n```\n\nSee [docs/mcp.md](./docs/mcp.md) for tool names, arguments, and per-client\nsetup.\n\n## Tools\n\nThe MCP server (and `ptide run <tool-id>`) exposes 15 tools:\n\n- `puzzle_wordsearch_generate`: Generate a word search grid from custom words, files, or themed word banks — every placement verifiable, printable via PDF/SVG.\n- `puzzle_crossword_generate`: Generate an interlocking crossword with standard numbering and validated clues.\n- `puzzle_sudoku_generate`: Generate easy, medium, hard, or expert sudoku with a guaranteed unique solution.\n- `puzzle_sudoku_solve`: Solve a sudoku from its 81-character string and report whether the solution is unique.\n- `puzzle_sudoku_validate`: Validate a sudoku grid — conflicts, solvability, and solution uniqueness.\n- `words_categories`: List word bank categories.\n- `words_themes`: List or search the bundled themed word lists.\n- `words_list`: List the words in a theme, filtered by length or count.\n- `words_match`: Find words matching a crossword-style pattern (`c_r_l`).\n- `words_anagram`: Find anagrams of the given letters in the word bank.\n- `words_random`: Pick a random word, optionally from one theme.\n- `words_stats`: Word bank statistics.\n- `eval_generate`: Generate reproducible, objectively gradable puzzle tasks for benchmarking LLMs and agents.\n- `eval_check`: Grade answers to generated eval tasks by construction — no answer key trusted.\n- `play_daily`: Print today's daily sudoku (same for everyone on a UTC day).\n\n## Verifiable LLM evals\n\nPuzzle answers are checkable without an answer key: a sudoku answer either\nsatisfies the rules and preserves the givens or it doesn't; a word search\nanswer either spells the word along a straight line in the grid or it\ndoesn't. That makes puzzles clean benchmark tasks for LLM evals — no LLM\njudge needed:\n\n```sh\nptide eval generate --type sudoku --n 20 --difficulty hard --seed 1 --out tasks.json\n# ...run your model on tasks.json, collect [{id, answer}] ...\nptide eval check --tasks tasks.json --answers answers.json --json\n```\n\nThe (type, difficulty, n, seed) tuple fully determines the task set, so it\nnames a reproducible benchmark.\n\n## Library usage\n\nThe engines are importable TypeScript with no CLI involved:\n\n```ts\nimport { generateSudoku, generateWordSearch, wordSearchPdf } from 'puzzletide';\n\nconst sudoku = generateSudoku({ difficulty: 'hard', seed: 42 });\nconst search = generateWordSearch({\n  words: ['coral', 'shark', 'kelp'],\n  directions: ['E', 'S', 'SE'],\n  seed: 7,\n});\nconst pdfBytes = await wordSearchPdf(search, { title: 'Ocean Animals' });\n```\n\nMore docs:\n\n- [CLI commands](./docs/cli.md)\n- [Tool registry](./docs/registry.md)\n- [Agent skills](./docs/agent-skills.md)\n\n## Online versions\n\nPrefer a browser?\n\n- [PuzzleTide word search](https://puzzletide.com/word-search)\n- [PuzzleTide crossword](https://puzzletide.com/crossword)\n- [PuzzleTide sudoku](https://puzzletide.com/sudoku)\n- [PuzzleTide hangman](https://puzzletide.com/hangman)\n- [Printable puzzles](https://puzzletide.com/printable)\n- [Make your own puzzle](https://puzzletide.com/maker)\n- [Dyslexia-friendly word search fonts and settings](https://puzzletide.com/blog/dyslexic-friendly-word-search-font-and-settings)\n\n## Privacy\n\nEverything runs locally. No account, no API key, no telemetry, no network\naccess.\n\n## Development\n\n```sh\nnpm install\nnpm run build     # tsc → dist/\nnpm test          # vitest + fast-check property tests (build first: CLI tests run dist/)\n```\n\nThe starter word banks are generic, original lists written for this package\n(`scripts/wordbanks-source.json`, compiled with `npm run build:wordbanks`).\nTheme contributions are welcome — add an entry to the source file and run the\nbuild. The full curated PuzzleTide word bank collection is proprietary to\npuzzletide.com and is not part of this repository.\n\n## Citing PuzzleTide CLI\n\nIf you use PuzzleTide CLI in your work — for example the verifiable puzzle\nevals in a model benchmark — please cite it (or use GitHub's \"Cite this\nrepository\" button):\n\n```bibtex\n@software{puzzletide_cli,\n  author  = {{Caravaca Labs}},\n  title   = {PuzzleTide CLI: word search, crossword \\& sudoku generator with verifiable LLM evals},\n  year    = {2026},\n  url     = {https://github.com/Caravaca-Labs/puzzletide-cli},\n  note    = {From the makers of \\url{https://puzzletide.com}}\n}\n```\n\nPlain text: \"PuzzleTide CLI (Caravaca Labs, 2026),\nhttps://github.com/Caravaca-Labs/puzzletide-cli — from the makers of\nhttps://puzzletide.com.\"\n\n## License\n\nMIT © Caravaca Labs\n",
  "bytes": 12175,
  "sha": "7d9e3f40ba2140118ae187bb5ac59b78f277fac99896b2b6e99a554b1368756b",
  "repo_slug": "caravaca-labs/puzzletide-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_catorch_puzzletide_5b08e3cd/readme"
}