GitHuman

Локальный CLI + веб-интерфейс для просмотра изменений в git-репозитории — staged/unstaged diff, сравнение веток и коммитов, браузер файлов с подсветкой синтаксиса — до коммита. Данные никуда не уходят: всё работает локально, поверх обычного git.

Идея и часть архитектуры унаследованы от оригинального mcollina/githuman (MIT) — эта версия переосмысливает стек (Fastify + node:sqlite на бэкенде, Vue 3 + Quasar на фронтенде вместо React) и интерфейс.

Что уже работает

• Просмотр diff: staged, unstaged, между ветками, между произвольными коммитами.
• Браузер файлов репозитория (не только изменённых) с подсветкой синтаксиса (shiki).
• Live-обновления через SSE: интерфейс сам обновляется при изменении файлов в репозитории — удобно смотреть, как редактирует код AI-агент. После перезапуска serve уже открытые вкладки перезагружаются сами.
• Чаты с ACP-агентами (Claude Code, Cursor, Codex, pi): до 5 чатов во вкладках, контекст — diff, файл целиком, ревью, вложения и @-файлы и папки из репозитория. Подробнее — в разделе «Агенты» ниже.
• Ручной/авто выбор тёмной-светлой темы.
• CLI: serve (поднять сервер), list/export (быстрый доступ к сохранённым ревью без веб-интерфейса).

Установка и запуск

Требуется Node.js ≥ 24 (используется нативный node:sqlite).

Быстрый старт (npx)

Без клонирования и локальной установки — пакет опубликован на npm как @tequila99/githuman:

npx @tequila99/githuman serve

Запускать из корня того git-репозитория, изменения в котором нужно просматривать (определяется как git rev-parse --show-toplevel от текущей директории).

Из исходников

Требуется pnpm.

git clone <url-этого-репозитория>
cd githuman
pnpm install
pnpm run build
node dist/cli/index.js serve

По умолчанию сервер слушает http://localhost:3847 и открывает браузер автоматически (отключить: --no-open). Репозиторий, который анализируется — это git-репозиторий, из корня которого запущена команда (определяется как git rev-parse --show-toplevel от текущей директории).

node dist/cli/index.js serve --port 4000 --host 0.0.0.0   # LAN-доступ, см. ниже
node dist/cli/index.js list --status in_progress            # список ревью без веб-интерфейса
node dist/cli/index.js export last --format markdown -o review.md

Доступ из локальной сети

--host принимает localhost (по умолчанию), 127.0.0.1, ::1, а для доступа из сети — 0.0.0.0 (IPv4) или :: (IPv4 и IPv6). Конкретный LAN-адрес не принимается: без loopback-слушателя некому подтвердить устройство. При запуске на всех интерфейсах консоль печатает http://localhost:<порт> и LAN-адреса машины.

Устройство из сети получает доступ только после сопряжения:

1. Откройте LAN-адрес на телефоне или другой машине (адрес и QR-код — в пункте меню Devices вкладки на localhost).
2. Нажмите Request access: устройство покажет шестизначный код.
3. Во вкладке на localhost появится запрос. Введите в нём код с экрана устройства и нажмите Approve. Без открытой localhost-вкладки запрос истекает через 2 минуты; консоль сервера печатает только факт запроса, без кода.

Доверенное устройство работает со всем приложением, включая терминал и агентов. Доступ хранится в cookie браузера и в .githuman/ght-reviews.db (по базе на репозиторий) и истекает через 30 дней без активности. Отзыв — в Devices: открытые терминал и чаты устройства закрываются сразу (если тот же репозиторий открыт вторым сервером на другом порту — в течение 2 секунд). Управлять устройствами можно только с localhost.

Сервер принимает из сети только адреса своих интерфейсов в заголовке Host — это защищает от DNS rebinding. Другое имя (например, имя машины в Tailscale) разрешается флагом --allowed-host <имя>, его можно повторять. Прокси на той же машине должен передавать X-Forwarded-For, иначе его запросы выглядят локальными; ssh -L — локальный доступ самого пользователя.

Осторожно: соединение идёт по обычному HTTP. Тот, кто слушает ту же сеть Wi-Fi, может перехватить cookie доверенного устройства и получить доступ к терминалу. Используйте LAN-доступ только в сети, которой доверяете. Cookie не разделяются по портам: другой веб-сервер на этой же машине тоже получит cookie устройства.

Агенты

Иконка робота в шапке открывает панель чатов. Агенты запускаются как подпроцессы по протоколу ACP в корне репозитория; нужные адаптеры подтягиваются через npx при первом запуске.

• Контекст. «Add to chat» в меню файла и diff, кнопка у активного ревью; в поле ввода @ + часть имени + Tab вставляет файл или папку из репозитория. Кнопка микрофона в поле ввода — голосовой ввод: держите её и говорите, после отпускания текст попадает в поле (отправка — как обычно). Работает через Web Speech API браузера: в Chrome и Edge звук обрабатывает облачный сервис браузера. В Firefox кнопки нет, как и на странице по обычному http с другой машины (--host 0.0.0.0): микрофону нужен защищённый контекст (localhost или https). Язык — в строке настроек чата. Shift+Tab переключает режим агента, модель и режим выбираются под полем.
• Подтверждения. Запросы разрешений приходят карточкой в чат. Для отдельного чата можно включить автоподтверждение (кнопка-щит) — агент тогда меняет файлы и выполняет команды без вашего ответа; включайте его только для работы, которую готовы проверить и откатить. pi вообще не спрашивает.
• Свои команды запуска — <репозиторий>/.githuman/ght-agents.json: { "cursor": { "args": ["--model", "<модель>", "acp"] } }. Допустимы поля command, args, env; любое другое (в том числе опечатка) — ошибка при запуске сервера.
• Кто может запускать. Агентские маршруты принимают запросы с этой машины и с доверенных устройств (см. «Доступ из локальной сети») и отклоняют чужие Origin/Host.

Данные и совместимость с оригинальным mcollina/githuman

Ревью хранятся в .githuman/ght-reviews.db (SQLite) в корне анализируемого репозитория. Префикс ght- — сознательный выбор: оригинальный mcollina/githuman хранит свои данные в том же .githuman/reviews.db с несовместимой схемой — без префикса оба инструмента затирали бы файлы друг друга при использовании в одном репозитории.

Префикс настраивается флагом --db-prefix (доступен у serve, list, export — указывайте один и тот же для всех трёх) или переменной окружения GITHUMAN_DB_PREFIX; флаг имеет приоритет над переменной. Пустое значение (--db-prefix "") — осознанный режим совместимости: работать с .githuman/reviews.db оригинального инструмента напрямую (миграция схем на вашей ответственности).

node dist/cli/index.js serve --db-prefix myteam-   # .githuman/myteam-reviews.db
node dist/cli/index.js list --db-prefix ""         # .githuman/reviews.db (оригинальный githuman)

HTTP API

Сервер отдаёт OpenAPI-спецификацию своего API по адресу /api/openapi.json (OpenAPI 3.1, всегда). Swagger UI — на /api/docs, только с флагом --api-docs (pnpm run dev:server включает его сам). Агентские маршруты попадают в спецификацию, только когда сервер их отдаёт (loopback-хост).

Разработка

Два процесса нужны одновременно — backend (Fastify, автоперезапуск при правках) и frontend (Quasar dev-сервер с HMR):

# терминал 1 — backend
pnpm run dev:server

# терминал 2 — frontend, из этого же репозитория
pnpm run dev

Если backend должен анализировать другой репозиторий, а не сам githuman — запустите dev:server из cwd того репозитория, указав абсолютный путь к скрипту:

cd /path/to/other/repo
node --watch-path=/path/to/githuman/src \
  /path/to/githuman/src/cli/index.ts serve --no-open --api-docs

Прочие команды:

pnpm test           # server (node:test) + CLI
pnpm run typecheck   # tsc (server) + vue-tsc (web)
pnpm run lint:check  # oxfmt --check + oxlint (read-only)
pnpm run lint        # то же самое, но с автофиксом
pnpm run build       # server (tsc) + web (quasar build) → dist/

Нет отдельного набора тестов для Vue-компонентов и e2e-спеков в tests/e2e/ пока не существует (несмотря на playwright.config.ts и test:e2e-скрипт) — покрытие сейчас только на уровне backend/CLI (175 тестов, node:test).

Стек

• Backend: Fastify 5, node:sqlite (нативный, синхронный), TypeBox (валидация + OpenAPI), SSE для live-обновлений.
• Frontend: Vue 3 + Quasar (Composition API, <script setup>), Pinia, vue-i18n, shiki.
• Тесты: node:test (backend/CLI).
• Пакетный менеджер: pnpm.

Лицензия

MIT, см. LICENSE.

Встроенный терминал

При запуске на loopback кнопка Terminal в шапке и меню открывает терминал в корне репозитория. Ctrl+Shift+` открывает или сворачивает окно. Окно можно перетаскивать и сворачивать; «+» добавляет вкладку, до восьми терминалов. Закрытие вкладки требует подтверждения и останавливает shell с его командами. Команда exit закрывает вкладку сразу.

Сессии переживают обновление страницы и доступны из нескольких страниц браузера. История ограничена 5000 строками scrollback; после остановки сервера она теряется. Без подписчиков простаивающая сессия завершается через 15 минут, работающая или с неизвестным состоянием — не позднее часа.

Окна терминала и предпросмотра открываются из своих кнопок в доке и возвращаются к ним при сворачивании или закрытии. Переходы между размерами тоже плавные; системная настройка уменьшения движения отключает анимации.

| Сочетание | Действие | | -------------- | ----------------------------------------------------------------- | | Ctrl+Win+← / → | Левая / правая половина страницы | | Ctrl+Win+↑ | Полный экран или возврат к обычному размеру | | Ctrl+Win+↓ | Свернуть активное окно | | Ctrl+Win+M | Свернуть все окна | | Ctrl+Win+T | Новая вкладка терминала | | Ctrl+Win+W | Закрыть активную вкладку; последняя вкладка закрывает окно | | Win+Alt+Space | Голосовой ввод в выбранном чате агента, пока клавиши удерживаются |

Если активного окна нет, Ctrl+Win+↑ восстанавливает последнее свёрнутое окно в прежнем размере и положении и передаёт ему фокус.

Повтор команды текущей половины возвращает обычный размер и позицию. Перетаскивание заголовка из половины тоже возвращает обычный размер; ручной resize снимает режим половины. Сочетания работают при вводе в терминале и формах, но отключены в модальных диалогах. Win означает Super/Meta (на macOS — Command вместе с Ctrl). Системные сочетания ОС могут перехватываться до браузера.

Если платформенный бинарник PTY недоступен, терминал работает в ограниченном режиме с баннером: команды вводятся в поле под выводом, Ctrl+C прерывает команду, Ctrl+D закрывает shell. vim, less и другие интерактивные программы требуют PTY. Из сети терминал доступен только доверенному устройству. Переключатель исходных цветов отключает минимальный контраст для программ со своей палитрой.

Для разработки на другом порту backend можно передать GITHUMAN_DEV_API=http://localhost:3848 при запуске Quasar dev-сервера.

Проектные заметки

Раздел Notes хранит Markdown-заметки в .githuman/notes/ относительно каталога запуска приложения. Поддерживаются папки, визуальный редактор, полный исходник Markdown, редактируемые свойства YAML frontmatter и обычные относительные ссылки. Внутренние ссылки активируют заметку в текущем окне; внешние открываются в новой вкладке. Add to agent в контекстном меню заметки и панели редактора добавляет её в чат как удаляемый бейдж. При отправке агент получает актуальный Markdown вместе с YAML-свойствами; связанные заметки и изображения не включаются. Несохранённые изменения сохраняются перед отправкой, ошибки сохранения её блокируют. Кнопка Link to note помогает выбрать заметку для ссылки; теги со счётчиками в дереве фильтруют список. Изменения автоматически сохраняются после паузы ввода.

Другой каталог задаётся через serve --notes-dir ./notes или GITHUMAN_NOTES_DIR; относительный путь считается от каталога запуска. Такой каталог можно версионировать. При создании вводится короткое имя без пути: файл создаётся в выбранном каталоге, расширение .md добавляется автоматически. Заметки можно перетаскивать между каталогами в дереве слева и в обзоре каталога справа, в том числе между панелями. Кнопка корня слева и кнопка родительского каталога справа также принимают заметки. Перенос сохраняет UUID и обновляет относительные ссылки; совпадающий файл не перезаписывается. Delete в контекстном меню скрывает заметку в приложении: отметка хранится в БД, сам Markdown остаётся на диске. Сканирование и перезапуск не возвращают её в список; восстановление через интерфейс пока не предусмотрено. Личное хранилище по умолчанию исключается локально через Git info/exclude; уже отслеживаемые файлы автоматически из индекса не удаляются.

При внешнем изменении файла редактор сохраняет черновик и предлагает сравнить его с диском, загрузить дисковую версию или сохранить черновик отдельной заметкой. Резервная предыдущая версия каждого изменённого файла лежит в скрытом каталоге .history внутри хранилища; этот каталог не показывается в дереве. При альтернативном Git-хранилище исключите .history/ из Git, если резервные копии не нужно публиковать.

Полный Markdown с YAML-шапкой можно вставить в пустое тело визуального редактора или вместо всего выделенного тела: свойства импортируются в Properties, UUID заметки сохраняется. Некорректный YAML отклоняется с сообщением об ошибке. При неподдерживаемой разметке сохраняется полный исходник и включается режим Markdown.

Визуальное редактирование может нормализовать оформление списков, таблиц и reference-ссылок. Открытие и переключение режимов без правок файл не перезаписывают. Если при открытии визуальный редактор теряет конструкции, приложение сохраняет исходный текст и переключается в Markdown. Вставленные PNG, JPEG, GIF и WebP (до 10 МБ) сохраняются в assets/ внутри хранилища заметок и доступны в визуальном редакторе после перезапуска. Ссылки на вложения не зависят от хоста или порта сервиса. Внешние HTTP/HTTPS-изображения доступны в визуальном редакторе. Размер заметки ограничен 1 МБ; символические ссылки в пути хранилища не поддерживаются. Черновик после аварии браузера пока не восстанавливается.

Команда Download external attachments в панели заметки или Ctrl+Shift+D, пока заметка открыта на экране, независимо от фокуса, открывает список внешних вложений. Клавиша определяется по физическому коду, независимо от раскладки. Картинки и ссылки на PNG/JPEG/GIF/WebP/PDF можно выбрать перед загрузкой; одинаковые адреса скачиваются один раз. Размер картинок ограничен 10 МБ, PDF до 50 МБ загружаются без дополнительного вопроса, от 50 до 100 МБ требуют подтверждения, свыше 100 МБ отклоняются. При неизвестном размере подтверждение запрашивается после остановки на пороге 50 МБ; согласие запускает загрузку заново. Лимит одной операции — 200 МБ сохранённых файлов. Проверка размера действует и во время скачивания, не только по заголовкам сервера.

Успешные загрузки заменяют адреса в текущем Markdown, ошибки оставляют внешние ссылки. PDF остаются обычными ссылками, свойства и подписи сохраняются. Скачивание работает с публичными HTTP/HTTPS-адресами без браузерных cookies; обычные ссылки определяются по расширению в пути URL. Restore external links возвращает последнюю замену, пока текст не изменён. Обновление визуального редактора после импорта сбрасывает его прежнюю историю Ctrl+Z.

Заметки имеют UUID в SQLite-каталоге; необязательный githuman_id в YAML помогает распознавать внешние перемещения. Back/Forward и история браузера возвращают между заметками. Rename в контекстном меню сохраняет ID и исправляет относительные ссылки; дополнительное поле папки позволяет переместить элемент. Отсутствующие файлы показывают заглушку; неоднозначные внешние изменения и незавершённые исправления доступны в Notes. Markdown-ссылки остаются переносимыми. Правила идентичности, восстановления и API.