# 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 Lua scripts for mpv (0.36+, bundled Lua 5.2).

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

### Shared Library

`scripts/lib/utils.lua` contains common utilities (trim, clamp, ASS color helpers). Scripts load it via:

```lua
package.path = mp.command_native({ "expand-path", "~~/scripts/lib/?.lua;" }) .. package.path
local lib = require("utils")
```

When adding new shared functions, prefer adding to this module over duplicating 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.)