# cc-agents-iterm-plugin

## Что это
Панель «Claude» для iTerm2 Toolbelt. Сверху — дерево активных сессий Claude Code и их субагентов
(название, модель, размер контекста, worktree, статус), снизу — лимиты подписки (5 ч, неделя,
разбивка по продуктам) и баланс extra usage. Для одного пользователя на его Mac: видеть, что
делают все запущенные `claude` и сколько осталось лимитов, и в один клик переходить в нужную
вкладку или панель tmux.

## Стек и ограничения
- Python 3.8+, только стандартная библиотека; модуль `iterm2` предоставляет сам iTerm2
  (скрипт 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,
  Notification, SubagentStart/Stop, PostModelSwitch, PreToolUse(Agent|Task). Дописывает событие
  в `~/.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`.
- `./uninstall.sh` — удалить (`--purge` — вместе с настройками и логами).
- `python3 -m py_compile files/*.py && sh -n files/agents_panel_hook.sh && bash -n install.sh && bash -n uninstall.sh` —
  синтаксическая проверка; сборки нет.
- `curl -s http://127.0.0.1:8766/raw` — что видит запущенная панель: логи хука, причины скрытия
  сессий, ошибки лимитов и баланса.

## Тесты
- Автотестов пока нет. `claude_agents.py` импортируется без iTerm2 (`iterm2 = None`), так что чистые
  функции (`replay`, `build_tree`, `parse_limits`, `parse_balance`, `session_name`, `settings_hooks.add/remove`)
  можно покрывать pytest без iTerm2. Сеть, Keychain, `ps` и tmux в тестах мокаются.
- Фикстуры — образцы jsonl хука и ответов API в `tests/fixtures/`.

## Где лежит код
- Код — в `files/`; хук require-plan защищает его через `.claude/code-paths`. `install.sh` и
  `uninstall.sh` в корне хуком не покрыты (он умеет только каталоги).

## OpenSpec и superpowers
- Вход в любую задачу — superpowers:brainstorming. Skills openspec-propose и openspec-explore сами по себе не запускать.
- Когда brainstorming классифицировал задачу как architectural, структуру change создать через `openspec new change <id>` (или `/opsx:propose <id>`), а содержимое proposal.md, specs/ и design.md написать по итогам brainstorming. tasks.md из OpenSpec не заполнять — задачи живут в плане superpowers.
- `/opsx:apply` не использовать: исполнение идёт через writing-plans и SDD/executing-plans.
- `openspec archive <id>` — после merge PR, как часть чеклиста закрытия.
- Хук require-plan защищает любой каталог `src/` на любой глубине. Если код лежит иначе — перечислить каталоги (префиксы от корня, по одному в строке) в `.claude/code-paths`.