42 lines
3.7 KiB
Markdown
42 lines
3.7 KiB
Markdown
# Архитектура
|
||
|
||
Три части, связанные файлами в `~/.cache/claude-agents/` и адресом `127.0.0.1:8766`: хук внутри
|
||
каждой сессии Claude Code пишет события, служба launchd их читает и отдаёт страницу, скрипт iTerm2
|
||
показывает эту страницу в Toolbelt. iTerm2 для работы панели не нужен.
|
||
|
||
```
|
||
claude (каждая сессия) ──hook──▶ agents_panel_hook.sh ──append──▶ ~/.cache/claude-agents/<sid>.jsonl
|
||
│
|
||
launchd: claude_agents.py --headless ◀──── read (poll 1.5 s) ────────────┘
|
||
├─ + ps, tmux, транскрипты ~/.claude/projects, git
|
||
├─ + api.anthropic.com oauth/usage, prepaid/credits (OAuth из Keychain)
|
||
└─ HTTP 127.0.0.1:8766 ──▶ web view «Claude» в Toolbelt (регистрирует claude_agents.py в iTerm2)
|
||
└─▶ браузер; с iPad — SSH local forward в Termius
|
||
```
|
||
|
||
## Модули
|
||
|
||
| Модуль | Ответственность | Зависит от |
|
||
|---|---|---|
|
||
| `files/agents_panel_hook.sh` | Событие хука → строка jsonl с PID, вкладкой iTerm2 или панелью tmux | `jq`, `ps` |
|
||
| `files/claude_agents.py` — сессии | `load_sessions`/`replay`: jsonl → состояние сессий и субагентов; `build_tree` сводит с процессами и tmux | файлы хука, `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` (tmux) | `state` |
|
||
| `files/claude_agents.py` — запуск | `run`: `serve` (служба, `--headless`) или `register_toolbelt` (iTerm2) | launchd, `iterm2` |
|
||
| `files/launchagent.py` | plist службы `com.andrey.claude-agents` | — |
|
||
| `files/settings_hooks.py` | Идемпотентно добавить/убрать хуки в `~/.claude/settings.json` | — |
|
||
| `install.sh` / `uninstall.sh` | Разложить/убрать файлы, поставить/снять службу, включить Python API iTerm2 | `settings_hooks.py`, `launchagent.py`, `launchctl` |
|
||
|
||
## Границы
|
||
- Хук не зависит от панели и не должен влиять на Claude Code: без вывода, всегда `exit 0`.
|
||
- Панель только читает данные Claude Code (jsonl, транскрипты, `~/.claude.json`) и ничего туда не пишет;
|
||
её единственная запись — удаление собственных логов старше `keep_logs_days`.
|
||
- Порт занимает только служба; скрипт iTerm2 сервер не поднимает и данные iTerm2 не передаёт.
|
||
- `claude_agents.py` — только стандартная библиотека + опционально `iterm2`; импорт без iTerm2 должен работать.
|
||
- HTTP слушает только `127.0.0.1`.
|
||
- Фон панели выбирается на клиенте и хранится в браузере/web view; сервер о нём не знает.
|
||
|
||
## Открытые вопросы
|
||
- После перезагрузки Mac без входа на нём (только SSH) служба не стартует, Keychain заблокирован.
|
||
- `claude_agents.py` — один файл на ~1400 строк.
|