cc-agents-iterm-plugin/ARCHITECTURE.md

Архитектура

Два процесса, связанные только файлами в ~/.cache/claude-agents/: хук внутри каждой сессии 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 строк.