From 60a128a5c4026952a545ba04d3802b13228f7718 Mon Sep 17 00:00:00 2001
From: Kovid Goyal <kovid@kovidgoyal.net>
Date: Sun, 5 Jul 2026 12:30:53 +0530
Subject: [PATCH] Add CLAUDE.md

---
 CLAUDE.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..b9074d4a9
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,47 @@
+# Claude System Instructions & Project Context
+
+## Project Architecture & Stack
+This is a multi-language repository. Adhere strictly to the idiomatic styling, patterns, and type safety of each respective language ecosystem present in the codebase. Do not mix patterns across language boundaries.
+
+## Rules for Code Generation
+- **Type Safety**: Enforce strict typing. Never use `any` or loose types.
+- **Error Handling**: Implement explicit error handling. Avoid silent failures or empty catch blocks.
+- **Dependency Minimization**: Use existing project utilities and native standard libraries before suggesting new external packages.
+- **Local Context**: Search the codebase for existing patterns before writing boilerplate structure from scratch.
+
+## Project Execution Workflows
+You must always use the following custom scripts to build, verify, and test changes. Do not use generic toolchains such as `go test` or `pytest` or `./setup.py test`.
+
+### 🛠️ Build Commands
+Execute this command to compile all modules and check for syntax or type errors:
+```bash
+make debug
+```
+
+### 🧪 Test Commands
+Execute this command to run the test suite across all language domains:
+```bash
+./test.py
+```
+
+To isolate testing to a specific test use, use the test name without the leading
+"test" prefix. For example, to run a python test named test_my_function, use
+```bash
+./test.py my_function
+```
+
+To run all tests in a specific file, for example, in kitty_tests/screen.py, use
+```bash
+./test.py --module screen
+```
+
+To run a Go test named TestMyFunction, use:
+```bash
+./test.py MyFunction
+```
+
+## Verification Pipeline
+Before declaring a task complete, you must follow this exact verification lifecycle:
+1. Run the local **Build Command** to guarantee zero compilation or compilation-stage type errors.
+2. Run the local **Test Command** targeted at the modified module to prevent regressions.
+3. If errors occur, analyze the stdout logs completely before writing a fix. Do not guess.