# Hermes — git-репозиторий конфига и агента

**Дата:** 2026-09-15
**Статус:** актуально

## Структура (важно!)

Git-репозиторий лежит **в `~/.hermes/`**, а НЕ в `~/.hermes/hermes-whale/`.
Это главный подвох: `git status` из `hermes-whale/` показывает пути вида `../config.yaml`,
`../skills/` — потому что корень на уровень выше.

```
~/.hermes/                      ← git repo root (branch: main, origin/main)
├── .gitignore
├── .gitmodules
├── config.yaml                 ← глобальный конфиг
├── SOUL.md
├── channel_directory.json      ← в .gitignore, но УЖЕ ЗАКОММИЧЕН (см. долги)
├── thread_ownership.json       ← состояние whale-thread-guard плагина
├── webhook_subscriptions.json  ← секреты! в .gitignore (не коммитить)
├── hermes-agent/               ← SUBMODULE: исходники Hermes Agent (Python)
├── hermes-whale/               ← профиль Whale (конфиг + память + промпты)
│   ├── config.yaml             ← конфиг профиля Whale
│   ├── SOUL.md                 ← идентичность Кита
│   ├── review/                 ← prompt_overrides: 7 .md блоков + memory/skill prompt
│   ├── memories/
│   │   ├── MEMORY.md, USER.md  ← глобальные
│   │   └── threads/<key>/MEMORY.md  ← thread-scoped память
│   ├── cron/jobs.json
│   └── lsp/                    ← ⚠️ 39M бинарников закоммичено (долг)
├── memories/                   ← глобальные (не профиля)
├── plugins/whale-thread-guard/ ← роутинг ботов в Zulip
├── scripts/refresh-claude-token.sh
└── skills/                     ← курируемые скиллы
```

## Два репозитория

| Репо | Что | Ветка |
|------|-----|-------|
| `~/.hermes/` | Конфиг Whale, скиллы, память, плагины, пин сабмодуля | main |
| `~/.hermes/hermes-agent/` | Исходники Hermes Agent (Python) — сабмодуль | main |

Правки Python-кода Hermes (`agent/*.py`) коммитятся **в сабмодуле**,
затем в родительском репо обновляется пин: `git add hermes-agent`.
Если пин не обновить — в родительском `git status` видно
`hermes-agent (new commits, modified content)`, а сам сабмодуль чист.

**Как проверить, всё ли закоммичено:**
```bash
cd ~/.hermes && git status --porcelain | head
cd ~/.hermes/hermes-agent && git status --porcelain   # должно быть пусто
```

## Правила .gitignore (обновлено 2026-09-15)

До 2026-09-15 игнорировался только `.env` — вариант `**`.env.bak`/`.env.new` НЕ покрывался,
хотя в них лежали живые токены. Один `git add .` затащил бы их в историю.

Добавлены секции:

```gitignore
# Secrets
.env / .env.bak / .env.new / .env.local / .env.*.bak
**/.env / **/.env.bak / **/.env.new

# Webhook subscriptions (содержат per-endpoint secret, 16 символов)
webhook_subscriptions.json
**/webhook_subscriptions.json

# Config/state бэкапы (могут содержать секреты)
config.yaml.bak* / config.yaml.*.bak / config.yaml.whale-bak*
config.yaml.work / config.yaml.transitional / config.yaml.corrupt*
**/config.yaml.bak* / **/config.yaml.*.bak / **/config.yaml.whale-bak*
*.tmp

# Node
node_modules/ / **/node_modules/
```

### Проверка игнора (обязательно после правки .gitignore)

```bash
cd ~/.hermes && git check-ignore -v .env.bak .env.new \
  hermes-whale/.env.bak hermes-whale/.env.new \
  webhook_subscriptions.json config.yaml.bak
```

Каждый файл должен вывести строку `.gitignore:<N>:<pattern>\t<file>`.

**Pitfall:** `.gitignore` НЕ влияет на уже отслеживаемые файлы.
`hermes-whale/lsp/node_modules/` остаётся в репо несмотря на правило `node_modules/`.
Вывод — применять `git add` по именам файлов, а не `git add .`, иначе новое правило
может дать ложное чувство защиты.

## Что коммитить / что не коммитить

**Коммитим:**
- `config.yaml`, `hermes-whale/config.yaml` — конфиги
- `hermes-whale/review/*.md` — prompt_overrides (без них подмены промпта теряются!)
- `hermes-whale/memories/`, `memories/` — память
- `plugins/`, `skills/`, `scripts/`
- `hermes-agent` (пин сабмодуля)

**Не коммитим (в .gitignore):**
- `.env*` любые варианты
- `webhook_subscriptions.json` — секреты
- `config.yaml*.bak*` — 10+ бэкапов могут содержать секреты
- `node_modules/`, `.restart_last_processed.json`, `config.yaml.zulip-router`
- `lsp/`, `review/` в корне — дубликаты `hermes-whale/lsp/` и `hermes-whale/review/`

## Долги (не исправлено, требуют решения Alex)

1. **`hermes-whale/lsp/node_modules/` в git** — 39M бинарников + `gopls` 41MB.
   `.gitignore` не помогает (файлы уже отслеживаются). Чистка = `git rm -r --cached` + rewrite истории.
2. **`channel_directory.json` в .gitignore, но отслеживается** — правило добавлено после коммита.
   В коммите `7fd200c` из него удалено 869 строк (файл в основном генерируемый).

## Команды

```bash
# Статус обоих репо
cd ~/.hermes && git status -sb
cd ~/.hermes/hermes-agent && git status -sb

# Закоммитить Python-правки Hermes
cd ~/.hermes/hermes-agent && git add agent/*.py && git commit -m "..."
cd ~/.hermes && git add hermes-agent && git commit -m "chore: bump submodule"

# Проверить, что секреты не в истории
cd ~/.hermes && git log --all --diff-filter=A --name-only --pretty=format: | grep '\.env'
```

## Связанное

- [[hermes-whale-system-prompt]] — состав system prompt, prompt_overrides
- [[hermes-agent-improvements]] — вынос хардкода промптов в файлы
- [[hermes-memory-architecture]] — thread-scoped память