# cc-agents-iterm-plugin

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

## Стек и ограничения
- Python 3.8+, только стандартная библиотека; модуль `iterm2` нужен только регистратору Toolbelt
  (его даёт iTerm2). Без зависимостей из pip — пользователь ставит панель `./install.sh`.
- Хук — POSIX `sh` + `jq`. Хук никогда не мешает Claude Code: ничего не выводит, всегда `exit 0`.
- macOS, launchd. Токен OAuth берётся из Keychain (`Claude Code-credentials`) или
  `~/.claude/.credentials.json`, поэтому служба работает в GUI-сессии пользователя.
- Сервер слушает только `127.0.0.1` — в панели видны тексты сообщений сессий.
- Установщик не трогает чужие хуки и настройки: правит `~/.claude/settings.json` только через
  `settings_hooks.py` (маркер `agents_panel_hook`), перед заменой кладёт копии в
  `~/.claude-panel-backup/<дата>/`. Повторный запуск `install.sh` идемпотентен. Запуск по SSH
  `install.sh`/`uninstall.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` — один файл, два режима (`run`):
  - `--headless` (`serve`) — служба launchd `com.andrey.claude-agents`, единственный владелец порта:
    - `refresher` раз в `poll_sec` перечитывает jsonl (`load_sessions` → `replay`), сверяет с
      процессами (`ps`) и панелями tmux, дочитывает из транскриптов модель и токены, из git —
      worktree; собирает `state["tree"]` (`build_tree`, без данных iTerm2).
    - `usage_poller` / `balance_poller` ходят в `api.anthropic.com/api/oauth/usage` и
      `.../prepaid/credits` (запасной путь — claude.ai с `sessionKey` из Keychain).
    - HTTP-сервер (`handle`): `/`, `/fragment` (дерево), `/limits`, `/message` (последние
      сообщения), `/activate` и `/open-wt` (через tmux), `/raw` (отладка).
  - без флага (`register_toolbelt`) — скрипт AutoLaunch iTerm2: регистрирует web view «Claude» на
    адрес службы; если порт молчит — `launchctl kickstart`. Свой сервер не поднимает.
- `files/launchagent.py` — пишет plist службы (`write <plist> <python> <script> <log> <PATH>`; PATH берётся из оболочки `install.sh`, его наследуют панели tmux, которые открывает служба).
- `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` — установить или обновить у себя (за самим Mac); затем Toolbelt → Claude и перезапуск сессий `claude`.
- `./uninstall.sh` — удалить (`--purge` — вместе с настройками и логами).
- `python3 -m unittest discover -s tests -v` — весь набор тестов (stdlib, без pytest; `node` нужен
  для теста клиентского JS). Зелёным считается только весь набор.
- `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` — что видит запущенная панель: логи хука, причины скрытия
  сессий, ошибки лимитов и баланса. Лог службы — `~/Library/Logs/claude-agents/panel.log`,
  состояние — `launchctl print gui/$(id -u)/com.andrey.claude-agents`.

## Тесты
- `tests/` — `unittest`. `claude_agents.py` импортируется без iTerm2 (`iterm2 = None`). Сеть,
  Keychain, launchd, `ps` и tmux в тестах подменяются; реальные `~/.claude` и `~/Library` не трогаются.
- `install.sh` и `uninstall.sh` в тестах запускаются только с `SSH_CONNECTION`/`SSH_TTY` (проверка
  отказа): без охраны они остановили бы настоящую панель на порту 8766.

## Где лежит код
- Код — в `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`.