wled-screen-controller-mixed/CLAUDE.md

Claude Instructions for WLED Screen Controller

Code Search

If ast-index is available, use it as the PRIMARY code search tool. It is significantly faster than grep and returns structured, accurate results. Fall back to grep/Glob only when ast-index is not installed, returns empty results, or when searching regex patterns/string literals/comments.

IMPORTANT for subagents: When spawning Agent subagents (Plan, Explore, general-purpose, etc.), always instruct them to use ast-index via Bash for code search instead of grep/Glob. Example: include "Use ast-index search, ast-index class, ast-index usages etc. via Bash for code search" in the agent prompt.

# Check if available:
ast-index version

# Rebuild index (first time or after major changes):
ast-index rebuild

# Common commands:
ast-index search "Query"                  # Universal search across files, symbols, modules
ast-index class "ClassName"               # Find class/struct/interface definitions
ast-index usages "SymbolName"             # Find all places a symbol is used
ast-index implementations "BaseClass"     # Find all subclasses/implementations
ast-index symbol "FunctionName"           # Find any symbol (class, function, property)
ast-index outline "path/to/File.cpp"      # Show all symbols in a file
ast-index hierarchy "ClassName"           # Show inheritance tree
ast-index callers "FunctionName"          # Find all call sites
ast-index changed --base master           # Show symbols changed in current branch
ast-index update                          # Incremental update after file changes

CRITICAL: Git Commit and Push Policy

🚨 NEVER CREATE COMMITS WITHOUT EXPLICIT USER APPROVAL 🚨

🚨 NEVER PUSH TO REMOTE WITHOUT EXPLICIT USER APPROVAL 🚨

Strict Rules

1. DO NOT create commits automatically after making changes
2. DO NOT commit without being explicitly instructed by the user
3. DO NOT push to remote repository without explicit instruction
4. ALWAYS WAIT for the user to review changes and ask you to commit
5. ALWAYS ASK if you're unsure whether to commit

Workflow

1. Make code changes as requested
2. STOP - Inform user that changes are complete
3. WAIT - User reviews the changes
4. ONLY IF user explicitly says "commit" or "create a commit":
   • Stage the files with git add
   • Create the commit with a descriptive message
   • STOP - Do NOT push
5. ONLY IF user explicitly says "push" or "commit and push":
   • Push to remote repository

What Counts as Explicit Approval

✅ YES - These mean you can commit:

• "commit"
• "create a commit"
• "commit these changes"
• "git commit"

✅ YES - These mean you can push:

• "push"
• "commit and push"
• "push to remote"
• "git push"

❌ NO - These do NOT mean you should commit:

• "that looks good"
• "thanks"
• "perfect"
• User silence after you make changes
• Completing a feature/fix

Example Bad Behavior (DON'T DO THIS)

❌ User: "Fix the MSS engine test issue"
❌ Claude: [fixes the issue]
❌ Claude: [automatically commits without asking]  <-- WRONG!

Example Good Behavior (DO THIS)

✅ User: "Fix the MSS engine test issue"
✅ Claude: [fixes the issue]
✅ Claude: "I've fixed the MSS engine test issue by adding auto-initialization..."
✅ [WAITS FOR USER]
✅ User: "Looks good, commit it"
✅ Claude: [now creates the commit]

IMPORTANT: Auto-Restart Server on Code Changes

Whenever server-side Python code is modified (any file under /server/src/ excluding /server/src/wled_controller/static/), automatically restart the server so the changes take effect immediately. Do NOT wait for the user to ask for a restart.

No restart needed for frontend-only changes — but you MUST rebuild the bundle. The browser loads the esbuild bundle (static/dist/app.bundle.js, static/dist/app.bundle.css), NOT the source files. After ANY change to frontend files (JS, CSS under /server/src/wled_controller/static/), run:

cd server && npm run build

Without this step, changes will NOT take effect. No server restart is needed — just rebuild and refresh the browser.

Restart procedure

Use the PowerShell restart script — it reliably stops only the server process and starts a new detached instance:

powershell -ExecutionPolicy Bypass -File "c:\Users\Alexei\Documents\wled-screen-controller\server\restart.ps1"

Do NOT use Stop-Process -Name python (kills unrelated Python processes like VS Code extensions) or bash background & jobs (get killed when the shell session ends).

Default Config & API Key

The server configuration is in /server/config/default_config.yaml. The default API key for development is development-key-change-in-production (label: dev). The server runs on port 8080 by default.

Project Structure

This is a monorepo containing:

• /server - Python FastAPI backend (see server/CLAUDE.md for detailed instructions)
• /client - Future frontend client (if applicable)

Working with Server

For detailed server-specific instructions (restart policy, testing, etc.), see:

• server/CLAUDE.md

Frontend (HTML, CSS, JS, i18n)

For all frontend conventions (CSS variables, UI patterns, modals, localization, tutorials), see contexts/frontend.md.

Task Tracking via TODO.md

Use TODO.md in the project root as the primary task tracker. Do NOT use the TodoWrite tool — all progress tracking goes through TODO.md.

• When starting a multi-step task: add sub-steps as - [ ] items under the relevant section
• When completing a step: mark it - [x] immediately — don't batch updates
• When a task is fully done: mark it - [x] and leave it for the user to clean up
• When the user requests a new feature/fix: add it to the appropriate section with a priority tag

Documentation Lookup

Use context7 MCP tools for library/framework documentation lookups. When you need to check API signatures, usage patterns, or current behavior of external libraries (e.g., FastAPI, OpenCV, Pydantic, yt-dlp), use mcp__plugin_context7_context7__resolve-library-id to find the library, then mcp__plugin_context7_context7__query-docs to fetch up-to-date docs. This avoids relying on potentially outdated training data.

General Guidelines

• Always test changes before marking as complete
• Follow existing code style and patterns
• Update documentation when changing behavior
• Write clear, descriptive commit messages when explicitly instructed
• Never make commits or pushes without explicit user approval