ARCHITECTURE.md

@@ -1,35 +1,15 @@
 # Архитектура
 
-Два процесса, связанные только файлами в `~/.cache/claude-agents/`: хук внутри каждой сессии
+{{Карта модулей на одну страницу: что где лежит, границы, потоки данных. Читается агентом перед architectural brainstorming. Обновляется вместе со спеками.}}
-Claude Code пишет события, скрипт iTerm2 их читает и рисует панель.
-
-```
-claude (каждая сессия) ──hook──▶ agents_panel_hook.sh ──append──▶ ~/.cache/claude-agents/<sid>.jsonl
-                                                                         │
-iTerm2 AutoLaunch: claude_agents.py ◀───── read (poll 1.5 s) ────────────┘
-   ├─ + iTerm2 API (вкладки, профиль), ps, tmux, транскрипты ~/.claude/projects, git
-   ├─ + api.anthropic.com oauth/usage, prepaid/credits (OAuth из Keychain)
-   └─ HTTP 127.0.0.1:8766 ──▶ web view tool «Claude» в Toolbelt
-```
 
 ## Модули
 
 | Модуль | Ответственность | Зависит от |
 |---|---|---|
-| `files/agents_panel_hook.sh` | Событие хука → строка jsonl с PID, вкладкой iTerm2 или панелью tmux | `jq`, `ps` |
+| | | |
-| `files/claude_agents.py` — сессии | `load_sessions`/`replay`: jsonl → состояние сессий и субагентов; `build_tree` сводит с живыми вкладками, процессами, tmux | файлы хука, iTerm2 API, `ps`, `tmux`, транскрипты, `git` |
-| `files/claude_agents.py` — лимиты | `fetch_usage`/`fetch_balance` + `parse_limits`/`parse_balance` | Keychain/`~/.claude/.credentials.json`, `~/.claude.json`, api.anthropic.com, claude.ai |
-| `files/claude_agents.py` — UI | `render_*`, `handle` (HTTP), `activate`/`open_worktree`, `theme_poller` | `state`, iTerm2 API |
-| `files/settings_hooks.py` | Идемпотентно добавить/убрать хуки в `~/.claude/settings.json` | — |
-| `install.sh` / `uninstall.sh` | Разложить/убрать файлы, включить Python API iTerm2, перезапустить панель | `settings_hooks.py` |
 
 ## Границы
-- Хук не зависит от панели и не должен влиять на Claude Code: без вывода, всегда `exit 0`.
+- Что не должно импортировать что.
-- Панель только читает данные Claude Code (jsonl, транскрипты, `~/.claude.json`) и ничего туда не пишет;
-  её единственная запись — удаление собственных логов старше `keep_logs_days`.
-- `claude_agents.py` — только стандартная библиотека + `iterm2`; импорт без iTerm2 должен работать.
-- HTTP слушает только `127.0.0.1`.
 
 ## Открытые вопросы
-- Docstring `claude_agents.py` ссылается на несуществующий `settings-hooks.json` (теперь это `settings_hooks.py` + `install.sh`).
+- 
-- Автотестов нет; `claude_agents.py` — один файл на 1500 строк.

CLAUDE.md

@@ -1,59 +1,28 @@
 # cc-agents-iterm-plugin
 
 ## Что это
-Панель «Claude» для iTerm2 Toolbelt. Сверху — дерево активных сессий Claude Code и их субагентов
+{{ОДНИМ АБЗАЦЕМ: что делает система, для кого, главный сценарий.}}
-(название, модель, размер контекста, worktree, статус), снизу — лимиты подписки (5 ч, неделя,
-разбивка по продуктам) и баланс extra usage. Для одного пользователя на его Mac: видеть, что
-делают все запущенные `claude` и сколько осталось лимитов, и в один клик переходить в нужную
-вкладку или панель tmux.
 
 ## Стек и ограничения
-- Python 3.8+, только стандартная библиотека; модуль `iterm2` предоставляет сам iTerm2
+- {{Язык, сборка, тесты — например: Python 3.12, uv, pytest.}}
-  (скрипт AutoLaunch). Без зависимостей из pip — пользователь ставит панель `./install.sh`.
+- {{Жёсткие ограничения среды исполнения — без чего код не должен собираться.}}
-- Хук — POSIX `sh` + `jq`. Хук никогда не мешает Claude Code: ничего не выводит, всегда `exit 0`.
-- Только macOS + iTerm2 с включённым Python API. Токен OAuth берётся из Keychain
-  (`Claude Code-credentials`) или `~/.claude/.credentials.json`.
-- Установщик не трогает чужие хуки и настройки: правит `~/.claude/settings.json` только через
-  `settings_hooks.py` (маркер `agents_panel_hook`), перед заменой кладёт копии в
-  `~/.claude-panel-backup/<дата>/`. Повторный запуск `install.sh` идемпотентен.
 
 ## Архитектура
-- `files/agents_panel_hook.sh` — хук Claude Code на SessionStart/End, UserPromptSubmit, Stop,
+- `src/core/` (или {{ваш путь}}) — чистая логика без зависимостей от фреймворка/платформы. Покрывается тестами полностью.
-  Notification, SubagentStart/Stop, PostModelSwitch, PreToolUse(Agent|Task). Дописывает событие
+- `src/{{adapter}}/` — тонкая обёртка над платформой. Тестируется руками или интеграционно.
-  в `~/.cache/claude-agents/<session_id>.jsonl` вместе с PID процесса `claude`,
+- {{Ключевые интерфейсы/порты между ними, если есть.}}
-  `ITERM_SESSION_ID` или сокетом/панелью tmux.
-- `files/claude_agents.py` — скрипт iTerm2 AutoLaunch, один файл:
-  - `refresher` раз в `poll_sec` перечитывает jsonl (`load_sessions` → `replay`), сверяет с живыми
-    сессиями iTerm2, процессами (`ps`) и панелями tmux, дочитывает из транскриптов модель и токены,
-    из git — worktree; собирает `state["tree"]` (`build_tree`).
-  - `usage_poller` / `balance_poller` ходят в `api.anthropic.com/api/oauth/usage` и
-    `.../prepaid/credits` (запасной путь — claude.ai с `sessionKey` из Keychain).
-  - HTTP-сервер на `127.0.0.1:8766` (`handle`) отдаёт страницу, которую iTerm2 показывает как web view
-    tool: `/`, `/fragment` (дерево), `/limits`, `/message` (последние сообщения), `/activate`,
-    `/open-wt`, `/raw` (отладка).
-  - `theme_poller` подстраивает цвета под профиль iTerm2.
-- `files/settings_hooks.py` — добавляет/убирает хуки панели в `settings.json` (`add` / `remove`).
-- `files/config.example.json` — все ключи настроек; рабочий файл `~/.config/claude-agents/config.json`
-  перечитывается на лету, кроме `port`.
-- `install.sh` / `uninstall.sh [--purge]` — раскладывают файлы по местам (таблица в README.md).
 
 ## Команды
-- `./install.sh` — установить или обновить у себя; затем Toolbelt → Claude и перезапуск сессий `claude`.
+- `{{npm test / pytest}}` — весь набор тестов. Зелёным считается только весь набор.
-- `./uninstall.sh` — удалить (`--purge` — вместе с настройками и логами).
+- `{{npm run build / ...}}` — сборка.
-- `python3 -m py_compile files/*.py && sh -n files/agents_panel_hook.sh && bash -n install.sh && bash -n uninstall.sh` —
+- `{{npm run dev / ...}}` — локальный запуск.
-  синтаксическая проверка; сборки нет.
-- `curl -s http://127.0.0.1:8766/raw` — что видит запущенная панель: логи хука, причины скрытия
-  сессий, ошибки лимитов и баланса.
 
 ## Тесты
-- Автотестов пока нет. `claude_agents.py` импортируется без iTerm2 (`iterm2 = None`), так что чистые
+- Golden-тесты: `tests/fixtures/<name>.*` + эталон `<name>.expected.*`. Внешние сервисы в тестах мокаются.
-  функции (`replay`, `build_tree`, `parse_limits`, `parse_balance`, `session_name`, `settings_hooks.add/remove`)
+- {{Где лежит тестовое окружение (vault, БД, песочница).}}
-  можно покрывать pytest без iTerm2. Сеть, Keychain, `ps` и tmux в тестах мокаются.
-- Фикстуры — образцы jsonl хука и ответов API в `tests/fixtures/`.
 
-## Где лежит код
+## Первая подсистема
-- Код — в `files/`; хук require-plan защищает его через `.claude/code-paths`. `install.sh` и
+{{Что делается первым и почему. Тестовая инфраструктура — Task 1 первого плана.}}
-  `uninstall.sh` в корне хуком не покрыты (он умеет только каталоги).
 
 ## OpenSpec и superpowers
 - Вход в любую задачу — superpowers:brainstorming. Skills openspec-propose и openspec-explore сами по себе не запускать.