{"id":47748436,"url":"https://github.com/chessraygg/chessray","last_synced_at":"2026-05-25T11:02:48.511Z","repository":{"id":348808971,"uuid":"1199993396","full_name":"chessraygg/chessray","owner":"chessraygg","description":"Real-time chess position recognition and evaluation overlay","archived":false,"fork":false,"pushed_at":"2026-05-24T15:49:38.000Z","size":211520,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T17:29:30.401Z","etag":null,"topics":["chess","computer-vision","electron","onnx","overlay","stockfish","yolo"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chessraygg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-02T23:31:28.000Z","updated_at":"2026-05-24T15:49:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/chessraygg/chessray","commit_stats":null,"previous_names":["chessraygg/chessray"],"tags_count":85,"template":false,"template_full_name":null,"purl":"pkg:github/chessraygg/chessray","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chessraygg%2Fchessray","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chessraygg%2Fchessray/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chessraygg%2Fchessray/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chessraygg%2Fchessray/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chessraygg","download_url":"https://codeload.github.com/chessraygg/chessray/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chessraygg%2Fchessray/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33471530,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T06:32:55.349Z","status":"ssl_error","status_checked_at":"2026-05-25T06:32:35.322Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chess","computer-vision","electron","onnx","overlay","stockfish","yolo"],"created_at":"2026-04-03T02:04:10.752Z","updated_at":"2026-05-25T11:02:48.501Z","avatar_url":"https://github.com/chessraygg.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# chessray\n\nReal-time chess position recognition and evaluation, delivered as a Chrome extension that overlays Stockfish analysis on top of any chess board visible in your browser tab — chess sites, streams, videos, screenshots, PDFs. Everything runs locally; no pixels leave your machine.\n\nA standalone Electron desktop app shares the same recognition + evaluation core for screen-wide capture outside the browser.\n\n## Features\n\n- **One-click capture in any tab** — toolbar button or `Alt+Shift+C` (rebindable at `chrome://extensions/shortcuts`) starts capturing the active tab. Analysis paints as an on-page overlay on the board; the detailed side-panel view is reachable via right-click on the toolbar icon → **Open side panel**.\n- **Vision-based** — captures pixels and runs YOLOv11n to detect the board and recognize every piece. No DOM scraping, no site integrations, no chess-site allowlist.\n- **Highlight + last-move detection** — finds the highlighted squares so it knows whose turn it is and what was just played, then renders the move as an arrow.\n- **Orientation auto-detection** — figures out which side is at the bottom from piece positions, falling back to PaddleOCR on the coordinate labels.\n- **Stockfish 18 Lite (WASM)** in an offscreen document — iterative deepening, configurable multi-PV, LRU eval cache.\n- **On-page overlay** — top-move arrows and an eval bar drawn directly on the captured board.\n- **Fully local** — no network calls during analysis; all models are bundled.\n\n## Install\n\n### Chrome extension\n\nThe published Chrome Web Store listing is the easiest path (link will be added once review completes). To run from source while waiting for the store listing, see [Development](#development) below for loading the unpacked extension.\n\n### macOS desktop app\n\n```bash\nbrew install --cask chessraygg/tap/chessray\n```\n\nAuto-taps [chessraygg/homebrew-tap](https://github.com/chessraygg/homebrew-tap) on first run, then installs the signed Chessray.app into `/Applications`.\n\nFor other platforms (and to build the desktop app from source), see [Building for release → Electron distributable](#electron-distributable).\n\n## How it works\n\n1. **Tab capture** — Chrome's `tabCapture` API delivers a video stream of the active tab to an extension-bundled offscreen document.\n2. **Board detection** — YOLOv11n locates the chess board bounding box; the bbox is cached per-frame using a cheap RGB fingerprint to skip the ~250 ms detection call when the surrounding UI hasn't moved.\n3. **Piece recognition** — YOLOv11n classifies all 64 squares.\n4. **Highlight detection** — Detected highlighted squares determine the last move and whose turn it is.\n5. **Orientation** — Piece positions first; PaddleOCR fallback on the coordinate labels.\n6. **FEN generation** — Detected pieces → Forsyth-Edwards Notation string.\n7. **Evaluation** — Stockfish 18 Lite (WASM, Web Worker in the offscreen doc) with iterative deepening, multi-PV, and an LRU cache.\n8. **Overlay** — Top-move arrows and an eval bar paint directly on top of the captured board; the side panel (opened manually via right-click on the toolbar icon → Open side panel) shows the same data plus full PV / settings / variation playback.\n\n## Supported environments\n\n- **Chrome extension** (primary): Chrome 116+ on macOS / Windows / Linux. Works on any site — chess sites (chess.com, lichess), video streams (Twitch, YouTube), image / PDF viewers, screenshots.\n- **Electron desktop app** (secondary): macOS (ARM64, x64), Windows (x64), Linux (x64). Useful when the board is outside the browser (a native window, a non-Chrome screencast).\n\n## Known limitations\n\nRecognition is purely vision-based, so it infers game state from a single frame. A few situations are inherently ambiguous from pixels alone:\n\n- **Positions with no highlighted last move can't be recognized.** Detection relies on two highlighted squares (the last move's origin and destination) to determine whose turn it is and what was just played. A board with no move highlight — e.g. the starting position, or a site that doesn't highlight moves — has no last-move signal to read.\n- **Pre-moves are not handled.** Detection assumes the board shows the current position. A piece that has been pre-moved (queued for the opponent's turn) is read as if it were already played.\n- **Orientation guessing is unreliable in races.** When the board has no `a–h` / `1–8` coordinate labels, orientation falls back to a piece-position heuristic that assumes each side has more material on its own half. This misfires in king-and-pawn endgames where pawns have advanced deep into enemy territory racing to promote.\n- **A dragged-and-held piece can be misread.** If a piece is picked up and held over a square without completing the move, that frame can look like the piece has already been placed there, producing a wrong position.\n\n## Prerequisites\n\n- [Node.js](https://nodejs.org/) 22+\n- [Git LFS](https://git-lfs.github.com/) (for the YOLO model weights)\n- npm 10+\n\n## Setup\n\n```bash\n# Clone the repo (includes LFS files)\ngit clone https://github.com/chessraygg/chessray.git\ncd chessray\n\n# Install dependencies\nnpm install\n\n# Download vendor assets (Stockfish, ONNX Runtime, YOLO model, PaddleOCR)\nnpm run setup\n\n# Run tests to verify everything works\nnpm test\n```\n\n## Development\n\n### Chrome extension\n\n```bash\n# Vite + CRXJS dev server — any Chrome that has packages/extension/dist/\n# loaded as an unpacked extension auto-reloads on save.\nnpm run dev -w packages/extension\n```\n\nLoad the extension once:\n1. Open `chrome://extensions`\n2. Enable **Developer mode**\n3. **Load unpacked** → select `packages/extension/dist/`\n\nThe side panel and service worker reload automatically; content scripts already injected into an open tab need that tab refreshed (Chrome MV3 limit).\n\n### Electron desktop app\n\n```bash\n# Start in dev mode (cross-platform via electron-forge)\nnpm start -w packages/electron\n\n# Build and install locally\nnpm run install-app -w packages/electron\n```\n\n## Building for release\n\n### Chrome Web Store\n\n```bash\nnpm run build:webstore\n```\n\nRuns a production Vite build, validates the manifest for store compliance (no localhost / HMR artifacts, no wildcard `web_accessible_resources`, CSP without `unsafe-eval`, all required permissions + vendor assets present), and produces `releases/chessray-v\u003cversion\u003e.zip` ready to upload at \u003chttps://chrome.google.com/webstore/devconsole\u003e.\n\nPrivacy policy: [`docs/chrome-webstore/privacy-policy.md`](docs/chrome-webstore/privacy-policy.md) (kept here because the Web Store submission links it at a public URL). Listing copy, single-purpose statement, and per-permission justifications live in the private marketing repo.\n\n### Electron distributable\n\n```bash\nnpm run build\n# Output → packages/electron/out/make/\n```\n\n## Project structure\n\n```\nchessray/\n  packages/\n    core/         Vision pipeline: board detection, piece recognition, FEN, highlights, orientation\n    runtime/      Host-agnostic frame processor + eval cache, shared by extension and Electron\n    overlay-ui/   Shared overlay/side-panel UI (renderer, PV cycling, settings, debug)\n    extension/    Chrome MV3 extension (service worker, content script, side panel, offscreen doc)\n    electron/     Electron desktop app (main + transparent overlay + hidden analysis window)\n  vendor/         Pre-built engines \u0026 ML models (downloaded via npm run setup)\n  docs/           Privacy-policy doc (public URL for the Web Store submission)\n  test/           Board detection tests \u0026 fixtures\n  scripts/        Build \u0026 utility scripts\n```\n\n## License\n\nThis project is licensed under the [GNU General Public License v3.0](LICENSE).\n\nStockfish is licensed under GPLv3. The YOLO chess piece model is based on [NAKSTStudio/Chess](https://universe.roboflow.com/nakststudio/chess-pieces-new) YOLOv11n weights.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchessraygg%2Fchessray","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchessraygg%2Fchessray","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchessraygg%2Fchessray/lists"}