Хук Claude File Guard (для Claude Desktop/CLI) [1.0]

Claude File Guard

Надёжная правка исходников в Claude Code на Windows: кодировки cp1251/ANSI и UTF-16, CRLF и BOM без порчи файлов.

Авторы: Dragokas & Claude · Лицензия: MIT
Скачать: claude-file-guard-*.zip — во вложении к сообщению.

Предисловие
Ну вот и настала эпоха, когда ИИ научился улучшать сам себя, я всего лишь задал вопрос в чат.

Что это?
Улучшалка (баг-фикс) для Claude Desktop или Claude Code CLI, только для ОС Windows.

Назначение
Набор хуков для Claude Code (вкладка Code в Claude Desktop, CLI, расширения VS Code/JetBrains). Хуки исправляют слабые места встроенных инструментов правки файлов на Windows и заставляют Claude всегда пользоваться одним надёжным способом вместо «зоопарка» из sed, PowerShell и Python-скриптов.
Косвенно: в виду предотвращения откатов записи, это немного экономит токены.

Проблема

Если вы работаете с Claude на Windows, наверняка видели такое:

«Команда sed снова убрала CRLF в двух файлах. Возвращаю исходные окончания строк.»
«Файлы в CRLF, поэтому правки делаю байтовым Python-скриптом.»
«Из-за проблем с кавычками откатываю изменения и использую Write.»

Причина не в модели, а в инструментах. Вот что делает стандартный Claude Code (проверено на версии 2.1.270, Windows 11):

Ситуация	Без File Guard
Read файла в cp1251	кириллица превращается в `��`
Edit файла в cp1251	файл молча портится: кириллица заменяется на U+FFFD, файл пересохраняется в UTF-8
Read файла в UTF-16 (с BOM и без)	вместо текста мусор (`c l a s s A`)
Edit UTF-16LE без BOM / UTF-16BE	файл портится: байты UTF-8 вставляются посреди UTF-16, BOM заменяется на `EF BF BD`
Write поверх файла с CRLF	все переводы строк молча становятся LF
Write поверх файла с UTF-8 BOM	BOM теряется
Правка через `sed -i`, `Set-Content`, `python -c`	ломаются CRLF и кодировка, а кавычки и экранирование в командной строке приводят к ошибкам и откатам

Что делает File Guard

Прозрачная работа с любой кодировкой. Файлы не в UTF-8 (ANSI — на русской Windows это cp1251, UTF-16LE/BE с BOM и без, UTF-32) Claude читает и правит через UTF-8 копию. После каждой правки хук сразу записывает изменения в исходный файл в его кодировке, с тем же BOM и теми же переводами строк. Байты, которых правка не касалась, остаются нетронутыми.
Сохранение CRLF/LF и BOM при перезаписи файла через Write.
Новые файлы наследуют стиль соседних: новый .bas рядом с модулями в cp1251/CRLF будет создан в cp1251/CRLF, новый .rc рядом с файлами в UTF-16 — в UTF-16.
Защита от потери чужих правок: если файл изменили вне Claude после того, как он его прочитал (в IDE, через git checkout), правка блокируется, и Claude перечитывает файл.
Защита от непредставимых символов: если в файл cp1251 пытаются записать →, ✓ или эмодзи, правка отклоняется с понятным объяснением, файл остаётся целым, Claude заменяет символы и повторяет.
Один способ правки. Запись в исходники через shell (sed -i, perl -i, Set-Content/Out-File/Add-Content, [IO.File]::WriteAll*, python -c ... write, writeFileSync, tee, > file.cs) блокируется с подсказкой использовать Edit. Чтение (sed -n, grep, Get-Content) и запись временных файлов в Temp не затрагиваются.
Защита бинарных файлов и файлов с битыми байтами: Edit/Write на них блокируются, а не портят их.

Чем это лучше стандартного способа

Ни одного испорченного файла. Стандартный Edit портит cp1251 и часть вариантов UTF-16 без каких-либо предупреждений. File Guard либо корректно применяет правку, либо отказывает до того, как файл будет затронут.
Без лишних диффов. CRLF, LF и BOM сохраняются, поэтому в git diff видна только сама правка, а не перевод всего файла на другие окончания строк.
Меньше откатов и повторов. Claude больше не пытается писать сложный код через командную строку, где кавычки и \ нужно экранировать в несколько слоёв. Правка идёт через встроенный Edit, параметры которого передаются как есть.
Работает автоматически. Это хуки: их выполняет сам Claude Code, а не модель. Их нельзя забыть, «передумать» или обойти.
Поддержка legacy-проектов: VB6 (.bas, .frm, .cls в cp1251 с обязательным CRLF), ресурсы .rc в UTF-16, старые .ini/.reg/.bat в ANSI.

Поддерживаемые кодировки

Кодировка	Определение	Read	Edit / Write
UTF-8, UTF-8 с BOM	автоматически	встроенный	встроенный; хук сохраняет BOM и CRLF/LF при Write
ANSI (cp1251 на русской Windows; cp1252, cp1250 и др. — по системе)	файл не UTF-8, но корректен в ANSI	через UTF-8 копию	через копию, запись обратно в ANSI
UTF-16LE с BOM	по BOM `FF FE`	через копию	через копию
UTF-16LE без BOM	эвристика по нулевым байтам	через копию	через копию
UTF-16BE с BOM / без BOM	по BOM `FE FF` / эвристика	через копию	через копию
UTF-32LE/BE с BOM	по BOM	через копию	через копию
Бинарные файлы, «битый» ANSI	—	встроенный	блокируется

Переводы строк: CRLF, LF и смешанные сохраняются. Символы вне BMP (эмодзи) в UTF-16/32 записываются корректно (суррогатными парами).

Совместимость

Claude Desktop, вкладка Code, Claude Code CLI, расширения Claude Code для VS Code и JetBrains — используют общий файл настроек %USERPROFILE%\.claude\settings.json, хуки работают везде.
Desktop Commander MCP (установленный как плагин или как MCP-сервер) — совместим. Его чтение, поиск, процессы, SSH и прочее работают как обычно. Правка файлов (edit_block, write_file) перенаправляется на встроенные Edit/Write, а команды его терминала (start_process, interact_with_process) проходят через ту же защиту от shell-правок, что и Bash/PowerShell.
Режимы разрешений (обычный, acceptEdits, auto, bypass) — сохраняются: правка через копию разрешается или запрашивается так же, как правка самого исходного файла.
Не действует в обычном чате Claude Desktop (вкладка Chat) — хуки есть только в Claude Code.
Проверено: Windows 11, Claude Code 2.1.270, Python 3.13/3.14.

Требования

Windows 10 или 11.
Python 3.9+ с python.org. При установке оставьте включённой опцию py launcher (по умолчанию включена) и отметьте Add python.exe to PATH. Python из Microsoft Store тоже подойдёт, но py launcher надёжнее: хук не сломается при обновлении Python.
Claude Desktop со вкладкой Code или Claude Code CLI.

Установка

Автоматическая:

Попросите у Claude Desktop установить этот хук

Полу-автоматическая:

Установите Python 3.9+ (см. «Требования»), если его ещё нет. Проверка — в PowerShell или cmd:
Код:
```
py -3 --version
```
Распакуйте архив в любую папку, например Загрузки\claude-file-guard.
Запустите install.cmd двойным щелчком. Установщик:
- найдёт папку конфигурации Claude Code: %USERPROFILE%\.claude (или CLAUDE_CONFIG_DIR, если задана) и создаст её, если её ещё нет — на свежей установке Claude Desktop её может не быть;
- скопирует хуки в %USERPROFILE%\.claude\hooks\;
- зарегистрирует их в settings.json: создаст файл, если его нет; если есть — аккуратно добавит свои записи, не трогая остальные настройки и другие хуки, и сохранит резервную копию settings.json.bak-ДАТА;
- добавит правила правки файлов в CLAUDE.md между метками  и : создаст файл, если его нет, иначе допишет в конец;
- запустит самопроверку (около минуты) и выведет RESULT: ALL PASSED.
Полностью перезапустите Claude Desktop: значок в трее → Quit, затем запустите снова. В CLI достаточно начать новую сессию.
Проверка: попросите Claude выполнить sed -i "s/a/b/" test.cs — команда должна быть заблокирована с сообщением File Guard. При чтении файла в cp1251 Claude получит подсказку о UTF-8 копии.

Повторный запуск install.cmd безопасен: он обновляет файлы и записи, не создавая дубликатов.

Ручная:

Если вы предпочитаете не запускать установщик:

Скопируйте hooks\file_guard.py и hooks\test_file_guard.py в %USERPROFILE%\.claude\hooks\.
Добавьте в %USERPROFILE%\.claude\settings.json раздел hooks (если файла нет — создайте его с этим содержимым; если раздел hooks уже есть — добавьте элементы в существующие массивы PreToolUse и PostToolUse). Замените ИМЯ на имя вашего пользователя Windows; путь пишется через /:
JSON:
```
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Edit|MultiEdit|Write|Bash|PowerShell|mcp__.*desktop-commander__(edit_block|write_file|start_process|interact_with_process)",
        "hooks": [{ "type": "command", "command": "py", "args": ["-3", "C:/Users/ИМЯ/.claude/hooks/file_guard.py"], "timeout": 30 }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [{ "type": "command", "command": "py", "args": ["-3", "C:/Users/ИМЯ/.claude/hooks/file_guard.py"], "timeout": 30 }]
      }
    ]
  }
}
```
Если py launcher не установлен, вместо "command": "py", "args": ["-3", ...] укажите полный путь к python.exe в command и только путь к скрипту в args.
Допишите содержимое CLAUDE.snippet.md в конец %USERPROFILE%\.claude\CLAUDE.md (создайте файл, если его нет).
Перезапустите Claude Desktop и выполните самопроверку:
Код:
```
py -3 %USERPROFILE%\.claude\hooks\test_file_guard.py
```

Обновление и удаление

Обновление: распакуйте новую версию и снова запустите install.cmd.
Удаление: запустите uninstall.cmd. Будут удалены хуки, их записи в settings.json (с резервной копией), блок в CLAUDE.md и временные копии файлов. Остальные ваши настройки не затрагиваются.
Временное отключение: добавьте "disableAllHooks": true в settings.json (отключит все хуки).

Настройка
ANSI-кодировка берётся из системы (GetACP): на русской Windows это cp1251. Чтобы задать другую, добавьте в settings.json:

JSON:

{ "env": { "CLAUDE_FILE_GUARD_ANSI": "cp1252" } }

PreToolUse перехватывает Read/Edit/Write: определяет кодировку и, если это не UTF-8, создаёт UTF-8 копию в %LOCALAPPDATA%\Temp\claude-enc-shadow\ и перенаправляет на неё инструмент. Для Write также восстанавливает CRLF/LF и BOM исходного файла. Для Bash/PowerShell и терминала Desktop Commander проверяет, не пишет ли команда в исходники.
PostToolUse после правки копии кодирует текст обратно в исходную кодировку и записывает в оригинал. Если символ непредставим в кодировке файла, оригинал не трогается, а копия откатывается.
Копии старше 14 дней удаляются автоматически. Накладные расходы — около 50–100 мс на вызов (запуск Python); файл 4 МБ обрабатывается за 0,2 с.

Ограничения

Для файлов не в UTF-8 Claude должен передавать в Edit путь копии (хук сообщает его после каждого Read; правило записано в CLAUDE.md). По исходному пути встроенный Edit сверяет old_string с искажённым текстом ещё до хука и отвечает «String not found» — файл при этом не портится.
Встроенный Grep не находит кириллицу внутри файлов в ANSI/UTF-16. Используйте Select-String -Encoding 1251 (или unicode / bigendianunicode).
Защита от shell-правок распознаёт типичные команды, но не может проверить содержимое скрипта, запущенного из файла (python fix.py). От этого защищает правило в CLAUDE.md.
Особенность самого Claude Code, не связанная с File Guard: встроенные Edit и Write удаляют пробелы и табуляции в конце строк нового текста (нетронутые строки сохраняются как есть).

Состав пакета

Файл	Назначение
`README.md`	описание
`LICENSE`	лицензия MIT
`install.cmd`	установка двойным щелчком (запускает `install.py`)
`uninstall.cmd`	удаление
`install.py`	установщик: копирование, регистрация хуков, правка `CLAUDE.md`, самопроверка
`CLAUDE.snippet.md`	правила для Claude, добавляемые в `CLAUDE.md`
`hooks\file_guard.py`	сам хук
`hooks\test_file_guard.py`	самопроверка: 118 сценариев кодировок/EOL/кавычек + проверка shell-фильтра и Desktop Commander

Ответственность

Dragokas не берёт на себя ответственность за любой ущерб, нанесенный вашим данным вследствие использования данного хука или его установщика. Весь код целиком и полностью подготовлен и протестирован искусственным интеллектом Claude (Opus 5.5)

Реакции: akok

Хук Claude File Guard (для Claude Desktop/CLI) 1.0

Оценки

Другие ресурсы пользователя Dragokas

Поделиться ресурсом