# spacesh — руководство пользователя

spacesh — терминал-воркспейс для параллельного запуска AI-агентов (Claude Code,
Codex, Gemini, opencode, shell) на macOS. Сессиями владеет фоновый демон, а не
окно: закрыл GUI, обновил приложение или словил краш — агенты продолжают
работать, а при следующем открытии экран восстанавливается из снапшота.

> Сборка и ручное тестирование описаны отдельно в [`RUNNING.md`](DOCS/RUNNING.md).
> Техническая спецификация — в [`MAIN.md`](DOCS/MAIN.md).

---

## Как это устроено

- **`spaceshd` (демон)** — единственный источник истины. Владеет живыми
  PTY-сессиями, держит грид-модель экрана, слушает один Unix-socket
  (`~/.spacesh/sock`), хранит конфиг и лог событий.
- **GUI (Tauri)** и **CLI `spacesh`** — тонкие клиенты. Состояния не хранят,
  только шлют команды и подписываются на события. Клик в GUI и `spacesh focus`
  из скрипта — одна и та же операция.
- GUI/CLI **поднимают демон лениво**, если он не запущен.

Следствие: GUI можно перезапускать и обновлять, не теряя сессии агентов.

---

## Установка

- **Готовый билд:** скачать `.dmg`, перетащить `spacesh.app` в `/Applications`.
  Сборка пока без подписи — при первом запуске снять карантин:
  ```bash
  xattr -dr com.apple.quarantine /Applications/spacesh.app
  ```
- **Из исходников** (нужны Rust + Node ≥ 20):
  ```bash
  make reinstall   # собирает .app, ставит в /Applications, перезапускает демон
  ```
  Полный список целей — `make help`.

---

## Главное окно

![Главное окно spacesh](DOCS/images/app-overview.png)

Три зоны:

1. **Сайдбар (слева)** — список воркспейсов и групп. Кнопка **New workspace**
   (⌘N). У каждого воркспейса слева — кольцо агрегированного статуса (см. ниже),
   справа на наведении — звезда (избранное) и корзина (удаление).
   - Сворачивается кнопкой-гамбургером в шапке: вместо полного списка остаётся
     узкий **rail** со статус-кольцами — активность видна даже в свёрнутом виде.
2. **Сетка панелей (центр)** — терминалы агентов в выбранной раскладке.
3. **Центр событий (справа)** — лента уведомлений о сменах статуса и выходах.

---

## Воркспейсы

- **Создание:** New workspace (⌘N) → выбрать папку проекта, раскладку (пресет)
  и агентов по слотам.
- **Переименование:** двойной клик по названию в сайдбаре → ввести новое →
  Enter (Esc — отмена).
- **Избранное:** звезда на строке. Запиненные собираются в секцию **FAVORITES**
  сверху.
- **Порядок:** перетаскивание строк внутри секции мышью.
- **Удаление:** корзина на строке → модалка с подтверждением. Если в воркспейсе
  есть живые терминалы — предупреждение, что они будут завершены.

## Панели

- **Раскладки/пресеты:** `1`, `2↔`, `2↕`, `2+1`, `1+2`, `3`, `2×2`, `4`, `2×3`,
  `2×4` — кнопки в тулбаре над сеткой.
- **Ресайз:** тянуть разделитель между панелями.
- **Перетаскивание:** взять панель за шапку (иконка‐грип) и бросить к краю
  другой — переставляется местами/делится.
- **Зум:** иконка разворота в шапке панели — панель на весь грид; повторный клик
  возвращает.
- **Перезапуск:** если процесс вышел, в панели кнопка **Restart**.

---

## Статусы агентов

Статус приходит **пушем** — от хуков агентов (`spacesh notify`), маркеров
OSC 133 для shell и паттернов как запасной вариант:

| Статус  | Значение                          | Цвет     |
|---------|-----------------------------------|----------|
| `work`  | агент работает                    | синий    |
| `wait`  | ждёт ввода/лимита                 | жёлтый   |
| `done`  | задача завершена                  | зелёный  |
| `error` | ошибка                            | красный  |
| `idle`  | простаивает                       | серый    |

Статус виден кольцом в шапке панели и в сайдбаре (агрегат по воркспейсу).

### Центр событий

Лента справа. Вкладки **All / Unread / Errors**. Клик по записи — фокус на
нужной панели. Действия в шапке:

- **Mark all read** — пометить всё прочитанным.
- 🗑 (красная корзина) — очистить весь лог событий (на пустом списке неактивна).

---

## Поиск по скроллбэку

`⌘F` на сфокусированной панели открывает строку поиска **в её заголовке** —
видно, где именно ищем. Поиск инкрементальный (по мере ввода), с подсветкой и
счётчиком совпадений; Enter / Shift+Enter — следующее/предыдущее. Поиск
привязан к панели, на которой открыт, и не «уезжает» при переключении фокуса.

---

## Настройки

![Модалка настроек](DOCS/images/settings.png)

Шестерёнка в шапке. Всё хранится демоном в `~/.spacesh/config.toml` и
применяется на лету ко всем окнам. Закрыть — крестик справа сверху или Esc.

- **Terminal** — шрифт (курированный список) и размер (10–20).
- **Appearance** — тема **Dark / Light** и акцентный цвет.
- **Default shell** — shell для plain-панелей; пусто = автоопределение
  (env `SPACESH_SHELL` → config → login-shell из passwd → `$SHELL` → `/bin/sh`).
- **Daemon** — версия, build-id, pid, uptime и кнопка **Restart**
  (перезапускает демон; панели переподцепляются автоматически).

---

## CLI

`spacesh` — те же операции, что и в GUI, поверх той же шины:

```bash
spacesh status --json          # состояние воркспейсов/панелей
spacesh focus s_8f3            # сфокусировать панель
spacesh open <path>            # открыть/создать воркспейс
spacesh new-surface ...        # добавить панель
spacesh notify ...             # сообщить статус (для хуков агентов)
```

`$SPACESH_SURFACE_ID` инъектируется в окружение каждой панели — хуки знают, о
какой панели рапортуют.

---

## В планах

- Внешние уведомления в **Telegram** и **MAX** (подписчик на шине событий).
- Diff-просмотр изменений агента.
- Удалённая работа через SSH-туннель к демону.

---

## Где что лежит

- Конфиг: `~/.spacesh/config.toml`
- Socket: `~/.spacesh/sock`
- Lock: `~/.spacesh/daemon.lock`
- Состояние воркспейсов и лог событий: `~/.spacesh/` (персист демона)