diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..20b2a61
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,29 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+just lint        # run luacheck on scripts/
+just fmt         # format with stylua
+just fmt-check   # verify formatting without modifying
+just check       # fmt-check + lint (pre-commit gate)
+```
+
+## Architecture
+
+This repository holds standalone Lua scripts for mpv (0.36+, bundled Lua 5.2). Each script in `scripts/` is self-contained with no external Lua dependencies.
+
+Script structure convention:
+1. Header comment block explaining features, requirements, and configuration
+2. `config` table immediately after header with user-tunable options
+3. Note indicating no edits are needed below the config block
+4. Implementation code
+
+## Code Style
+
+- 2-space indentation, 100-column width, double quotes preferred (enforced by stylua)
+- Lua 5.2 std; `mp` and `mpv` are allowed globals (luacheck config)
+- Run `stylua` then `luacheck` before committing
+- Use Conventional Commits (`feat:`, `fix:`, `chore:`, etc.)