From df6e0bcbc11ff8404ca82c26a6bb5f2b71847285 Mon Sep 17 00:00:00 2001 From: Andrey Epifancev Date: Sun, 18 Oct 2026 19:16:49 +0400 Subject: [PATCH] docs: describe project in CLAUDE.md and ARCHITECTURE.md Refs #1 Co-Authored-By: Claude Opus 5.5 --- ARCHITECTURE.md | 28 ++++++++++++++++++++---- CLAUDE.md | 57 ++++++++++++++++++++++++++++++++++++++----------- 2 files changed, 68 insertions(+), 17 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 4a85988..d35acb8 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,15 +1,35 @@ # Архитектура -{{Карта модулей на одну страницу: что где лежит, границы, потоки данных. Читается агентом перед architectural brainstorming. Обновляется вместе со спеками.}} +Два процесса, связанные только файлами в `~/.cache/claude-agents/`: хук внутри каждой сессии +Claude Code пишет события, скрипт iTerm2 их читает и рисует панель. + +``` +claude (каждая сессия) ──hook──▶ agents_panel_hook.sh ──append──▶ ~/.cache/claude-agents/.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 строк. diff --git a/CLAUDE.md b/CLAUDE.md index ab56a20..e932e10 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,28 +1,59 @@ # cc-agents-iterm-plugin ## Что это -{{ОДНИМ АБЗАЦЕМ: что делает система, для кого, главный сценарий.}} +Панель «Claude» для iTerm2 Toolbelt. Сверху — дерево активных сессий Claude Code и их субагентов +(название, модель, размер контекста, worktree, статус), снизу — лимиты подписки (5 ч, неделя, +разбивка по продуктам) и баланс extra usage. Для одного пользователя на его Mac: видеть, что +делают все запущенные `claude` и сколько осталось лимитов, и в один клик переходить в нужную +вкладку или панель tmux. ## Стек и ограничения -- {{Язык, сборка, тесты — например: Python 3.12, uv, pytest.}} -- {{Жёсткие ограничения среды исполнения — без чего код не должен собираться.}} +- 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` идемпотентен. ## Архитектура -- `src/core/` (или {{ваш путь}}) — чистая логика без зависимостей от фреймворка/платформы. Покрывается тестами полностью. -- `src/{{adapter}}/` — тонкая обёртка над платформой. Тестируется руками или интеграционно. -- {{Ключевые интерфейсы/порты между ними, если есть.}} +- `files/agents_panel_hook.sh` — хук Claude Code на SessionStart/End, UserPromptSubmit, Stop, + Notification, SubagentStart/Stop, PostModelSwitch, PreToolUse(Agent|Task). Дописывает событие + в `~/.cache/claude-agents/.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). ## Команды -- `{{npm test / pytest}}` — весь набор тестов. Зелёным считается только весь набор. -- `{{npm run build / ...}}` — сборка. -- `{{npm run dev / ...}}` — локальный запуск. +- `./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` — что видит запущенная панель: логи хука, причины скрытия + сессий, ошибки лимитов и баланса. ## Тесты -- Golden-тесты: `tests/fixtures/.*` + эталон `.expected.*`. Внешние сервисы в тестах мокаются. -- {{Где лежит тестовое окружение (vault, БД, песочница).}} +- Автотестов пока нет. `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/`. -## Первая подсистема -{{Что делается первым и почему. Тестовая инфраструктура — Task 1 первого плана.}} +## Где лежит код +- Код — в `files/`; хук require-plan защищает его через `.claude/code-paths`. `install.sh` и + `uninstall.sh` в корне хуком не покрыты (он умеет только каталоги). ## OpenSpec и superpowers - Вход в любую задачу — superpowers:brainstorming. Skills openspec-propose и openspec-explore сами по себе не запускать.