ChessShock

NNCL v1.4 License TL;DR

This is a simplified summary and does not replace the full license terms.

What You Can Do

• Use, study, modify, and share the work for free
• Create and distribute modified versions
• Deploy it for personal and non-commercial purposes
• Accept Non-Rewarded Donations as defined in section 1

What You Must Do

• Provide proper attribution to the licensor (me)
• Provide source code if you distribute compiled versions
• Include the full license with all distributions
• Maintain the ethical policy in your adaptations

What You Cannot Do

• Use it for racism, xenophobia, queerphobia, transphobia, homophobia, enbyphobia, misogyny, misandry, and/or sexism.
• Use it for commercial purposes (sales, subscriptions, SaaS, ads, etc.)
• Train commercial AI or ML models with it
• Use it to enable discrimination or violence
• Alter or remove the license terms
• Use it as/for law enforcement, military, or immigration enforcement

Key Points

• All modified versions must use the same license
• The licensor can revoke your rights with 7 days notice
• No warranties or guarantees are provided
• Large-scale deployments (100+ users) require public compliance documentation
• Filing patent lawsuits related to the work or its content automatically terminates your license

Bottom Line

Free for ethical, non-commercial use, with the requirement to share your code and keep the license intact.

---

ChessShock monitors your Lichess account and can trigger OpenShock actions when:

• it becomes your turn in an ongoing game
• a newly finished game is detected as a loss

Python 3.10 or newer is required, along with Nanashi-OpenShockPY 0.1.0.0 or newer.

Install

Recommended with pipx:

pipx install --force 'git+https://github.com/NanashiTheNameless/ChessShock@main'

If you do not already have pipx, install it first and make sure its bin directory is on your PATH.

Local checkout fallback:

python -m pip install -r requirements.txt

OpenShockPY is pulled from PyPI as Nanashi-OpenShockPY>=0.1.0.0, so only the pipx path needs git.

If you installed an older ChessShock that pulled OpenShockPY from GitHub, upgrade it.

pipx installs (rebuilds the isolated environment from scratch):

pipx install --force 'git+https://github.com/NanashiTheNameless/ChessShock@main'

Local checkout installs:

python -m pip install --upgrade 'Nanashi-OpenShockPY>=0.1.0.0'

After installation, the console command is:

ChessShock

Config Location

By default, ChessShock reads and writes:

• Linux: ~/.config/ChessShock/config.json
• macOS: ~/Library/Application Support/ChessShock/config.json
• Windows: %APPDATA%\ChessShock\config.json

You can override that with --config /path/to/config.json.

Quick Start

Fastest path:

ChessShock --configure

The setup wizard will:

• ask for your contact email and build the User-Agent for you
• log you into Lichess with OAuth
• detect your Lichess username automatically
• ask for your OpenShock API token every time you run the wizard
• prompt for turn and loss alert settings
• write the config file to your default config directory

If you prefer editing by hand:

mkdir -p ~/.config/ChessShock
cp config.example.json ~/.config/ChessShock/config.json

Then update the placeholders in config.example.json.

Authentication

Lichess

ChessShock supports:

• OAuth login through the wizard
• a manually pasted personal access token in lichess.api_token

If lichess.api_token is empty and lichess.oauth.enabled is true, ChessShock can refresh the token interactively later with:

ChessShock --oauth-login

OpenShock

ChessShock uses an OpenShock API token stored in:

"openshock": {
  "api_token": "..."
}

During setup, ChessShock opens:

• https://openshock.app/settings/api-tokens

if you do not already have a saved token, so you can create one and paste it into the wizard.

Config Overview

The main config sections are:

• username: your Lichess username
• user_agent: must include a real contact email address
• poll_interval_seconds: how often ChessShock polls Lichess
• lichess: API base URL, token, and OAuth settings
• openshock: whether OpenShock is enabled, your API token, and default shocker_id
• alerts.turn: settings for turn alerts
• alerts.loss: settings for loss alerts

Current default alert behavior from config.example.json:

• turn: enabled, vibrate, 600 ms, intensity 100, only on new turn, 5 second cooldown
• loss: enabled, shock, 800 ms, intensity 45, 5 second cooldown

Important config notes:

• openshock.enabled can stay false while you test
• openshock.shocker_id defaults to "all"
• each alert can optionally override shocker_id
• placeholder emails like [email protected] are rejected
• legacy openshock.api_key is still accepted on load, but api_token is the canonical field now

Commands

Run continuously with the default config path:

ChessShock

Run one poll and exit:

ChessShock --once

List available OpenShock shockers:

ChessShock --list-shockers

Use a custom config path:

ChessShock --config /path/to/config.json

python -m chessshock also works if you prefer module execution.

How It Works

ChessShock uses the official Lichess API:

• GET /api/account for token verification and username discovery
• GET /api/account/playing for ongoing games
• GET /oauth and POST /api/token for Lichess OAuth login with PKCE
• GET /api/games/user/{username} for recently finished games

Behavior details:

• Turn alerts are based on the authenticated ongoing-games feed.
• Loss alerts are based on recently finished games from the user export feed.
• On startup, ChessShock can still catch a very recent loss if it happened shortly before the app launched.
• If Lichess returns 429, ChessShock backs off instead of continuing at the normal poll interval.

Limitations

• Turn alerts are best-effort, not frame-perfect.
• Finished-game exports can appear slightly after the game actually ends.
• ChessShock polls sequentially and should be kept conservative to respect Lichess rate limits.
• The app currently supports turn and loss alerts only.

Safety

• Keep openshock.enabled off until your config is correct.
• Double-check intensity and duration values before enabling real actions.
• Read OpenShock’s safety guidance before using hardware: https://wiki.openshock.org/home/safety-rules