spaceshell/README.md

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

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

Сборка и ручное тестирование описаны отдельно в RUNNING.md. Техническая спецификация — в MAIN.md.

---

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

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

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

---

Установка

• Готовый билд: скачать .dmg, перетащить spacesh.app в /Applications. Сборка пока без подписи — при первом запуске снять карантин:

  xattr -dr com.apple.quarantine /Applications/spacesh.app
  

• Из исходников (нужны Rust + Node ≥ 20):

  make reinstall   # собирает .app, ставит в /Applications, перезапускает демон
  

  Полный список целей — make help.

---

Главное окно

Три зоны:

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 — следующее/предыдущее. Поиск привязан к панели, на которой открыт, и не «уезжает» при переключении фокуса.

---

Настройки

Шестерёнка в шапке. Всё хранится демоном в ~/.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, поверх той же шины:

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/ (персист демона)