longrun

Быстрый старт: поставить и просто работать

Скилл рассчитан на то, что человек работает в сессиях как обычно, а заметки, дайджесты и доставку сообщений ведут хуки и модель по инструкции. Ниже все, что нужно сделать руками.

1. Установить один раз. Одной строкой, клон не нужен - установщик сам забирает исходники:

   curl -fsSL https://krllx.github.io/longrun/install.sh | bash

   Он ставит скилл, 12 хуков в ~/.claude/settings.json, CLI ~/.local/bin/longrun, MCP-сервер longrun, и таймер, который раз в пять минут гоняет проверки и смотрителя. Спрашивает он только про одно - про уведомления на рабочем столе, это следующий шаг. Из клона - тот же install.sh; --uninstall все это снимает.
2. Уведомления, если они нужны. install.sh спрашивает, настраивать ли их, и этот шаг - про то, что решает ответ. longrun от них не зависит - halt и сработавший watch и так доезжают до сессии через ее сокет или инбокс, - поэтому отказ ничего больше не меняет (--no-notify отвечает заранее, brew install terminal-notifier включает потом). На macOS установщик выполняет brew install terminal-notifier, если его нет (Homebrew - то самое требование; без него он просто скажет об этом и пойдет дальше), и шлет одно тестовое уведомление; macOS может один раз спросить, разрешить ли уведомления от terminal-notifier - разрешите. Встроенными средствами macOS этот шаг не заменить: osascript -e 'display notification' отправляет уведомление от имени Script Editor, у которого нет разрешения, поэтому система кладет его в базу, не рисует ничего и выходит с нулем (25 из 25 так на macOS 15; разрешения Script Editor не получает даже после запуска). В баннере будут имя и иконка самого terminal-notifier: macOS берет и то и другое из бандла, который отправил уведомление, и переопределить их для отдельного уведомления нельзя. На Linux это notify-send (пакет libnotify), он есть в большинстве десктопов. Проверка в обоих случаях - longrun notify --test: шлет пробу, вычитывает, нарисовала ли ее система, и печатает, какая сессия откроется по клику. Сессию, которую нельзя пропустить, помечают отдельно: longrun important on (или next, или число) - после этого конец каждого ее хода приходит уведомлением независимо от notify_turn_end и от того, какое окно в фокусе, а проверка фокуса как раз этого и не умеет, пока вы печатаете в другой сессии Claude.
3. Сделать папку проектом. Проект для longrun - это папка, которую вы открываете в Claude Code. Не обязательно корень репозитория: это может быть папка с несколькими репозиториями, подкаталог монорепозитория или пустая папка-штаб. В ней один раз выполнить longrun init: в терминале или прямо в сессии Claude Code, агент выполнит его сам, если попросить. Появится каталог .longrun/; если папка внутри репозитория, добавьте его в ignore (или longrun init --external, тогда каталог ляжет под ~/.claude/longrun/). Из каждого worktree того же проекта: longrun link <путь к проекту>. Проверка: longrun where.
4. Настроить под себя. В сессии сказать агенту: "настрой longrun" (или /longrun onboard). Он выполнит longrun onboard, коротко расскажет, что делает скилл, и спросит про главные настройки: окно автокомпакции, пороги зависания, размеры заметок, уведомления. Ответы применит сам через longrun config set. Одно исключение: окно автокомпакции хук выставить не может, поэтому агент попросит вас ввести /autocompact 300k (или выбранное значение) в Claude Code. За 50 тысяч токенов до этого порога хук попросит сессию записать заметки перед компакцией. Подробно про ключи (см. дальше часть 9).
5. Работать. Ничего вызывать не нужно. На старте сессия получает дайджест (общие заметки, свои, кто еще работает), после компакции все возвращается само, чужие изменения приходят на следующем ходу. Агент сам пишет заметки о тупиках и решениях. Словами можно попросить: "запиши", "что мы уже пробовали", "статус сессий", "передай другой сессии", "что осталось", "скажи, когда PR вольется".
6. Когда сессий несколько и есть общая цель. В одной из них: "возьми роль оркестратора, цель: ...". Она заведет доску задач и будет раздавать работу; остальным сессиям задачи приходят ходом, ничего учить не надо. "Стоп всем" и "продолжаем" тоже словами, в сессии оркестратора (см. дальше часть 8).

Зачем

Контекст модели конечен. На длинной дистанции компакция случается всегда: автоматически, когда окно заполнено, или вручную через /compact. Claude Code сообщает об этом хукам до и после (PreCompact, PostCompact), и longrun ловит оба момента. Но саму потерю компакция не отменяет: история сжимается в резюме, следующая компакция сжимает резюме.

Картинка ниже про проблему 1. Верхняя строка: что модель держит в контексте, слева направо во времени: сначала полная история, после компакции только резюме, и агент, который читает это резюме. Нижняя строка: файл на диске, куда агент в самом начале записал одну заметку. Пунктирные стрелки: заметка попадает в контекст при старте и снова после компакции.

Из чего состоит скилл

Три сущности, больше ничего

Слово "проект" значит только каталог .longrun/: не проект в монорепозитории и не папка транскриптов Claude Code. Worktree привязывается к проекту командой longrun link, своих заметок у него нет. Сессия принадлежит одному проекту. При resume приложение выдает сессии новый CLI id; longrun идет по цепочке priorCliSessionIds, и свои заметки продолжаются.

Файлы на диске

Каждый файл появился из конкретной задачи:

• notes.md сессии: проблема 1. Тупики и решения этой сессии, которые должны пережить компакцию.
• NOTES.md проекта: проблема 2. Факты, которые нужны любой сессии: номер PR, решение, особенность окружения.
• journal.md: хронология без токенов. Вехи от агента, а механика дописывает старт, конец, упавшие команды, компакции. По нему видно, что сессия делала, не читая транскрипт.
• archive/compact/ и archive/precompact/: резюме каждой компакции дословно и снимок перед ней (HANDOFF). Первое находит recall, второе возвращается в дайджест после компакции.
• inbox/: сообщение сессии, которая сейчас не работает, ждет ее следующего хода.
• meta.json: счетчики, последний ответ, идущий инструмент. Из него строки SESSIONS и флаги для оркестратора.
• board.json, stale.json, watch/, halt.json: доска оркестратора, пометки "перестало быть правдой", отложенные проверки, стоп всем. Про них в частях 7 и 8.

Все общее лежит в проекте. Все свое лежит вне дерева репозитория и вне синхронизируемых папок, потому что переписывается на каждом вызове инструмента. Нажмите на файл.

Хуки: где живет механика

Claude Code зовет внешнюю команду на каждое событие сессии. longrun ставит двенадцать таких команд, все это один python-скрипт. Хук это отдельный процесс на событие, поэтому после установки новый код работает во всех сессиях сразу. Нажмите на хук в цикле.

Заметки: что писать и куда

Одна строка, по-английски, до 400 символов (тот же факт по-русски стоит в полтора раза больше токенов, а бюджеты жесткие). Тест один: вернет ли это одна команда, Read или grep? Если да, не писать.

Заметка по умолчанию идет в общие заметки проекта; --own оставляет ее внутри этого разговора. Не влезает в строку - значит это файл: longrun doc add research/plan.md "план раскатки и что открыто" кладет в общие заметки одну строку-указатель, а сам файл каждая сессия открывает, только когда он ей нужен. Прогресс ("запушил", "тесты зеленые") не пишется никуда: хроника и так лежит в журнале, ее ведут хуки. То, что переживет задачу (кто пользователь, как он работает), в автопамять Claude Code, не сюда.

Проверьте себя: куда это?

Одна сессия переживает компакцию

Проект shop, сессия A. Кнопки "Дальше" и "Назад" или стрелки на клавиатуре. Слева, кто с кем говорит на этом шаге; справа, команда и что она печатает; внизу, что изменилось на диске.

Две сессии: общая память

В той же папке открывается сессия B.

Передать работу и ждать событие

Сообщение другой сессии приходит к ней как ход пользователя. Ожидание события стоит ноль токенов: проверку гонит таймер.

Оркестратор: одна сессия координирует остальные

Слой поверх заметок и сообщений. Одна сессия держит цель и доску, остальные учат три команды: board take, board done, board block. Все, что нужно оркестратору, лежит в файлах состояния, транскрипты он не читает. Это координация нескольких окон плюс линия к человеку, а не автономная езда: одну сессию к условию, которое умеет проверить оценщик, ведет встроенный /goal.

Настройки

Два уровня: глобальный файл ~/.claude/longrun/config.json и файл проекта .longrun/config.json; значение проекта перекрывает глобальное. Смотреть и менять руками JSON не нужно:

longrun config                                  # действующие значения и откуда каждое: default / global / project
longrun config set stuck_tool_min 60 --global   # для всех проектов
longrun config set notes_max_bytes 8000         # для этого проекта
longrun config unset notes_max_bytes            # обратно к умолчанию

Ключей около сорока (полный список в docs/REFERENCE.md, раздел 6). Сразу после установки имеет смысл посмотреть на эти:

Шпаргалка и границы

# установка
curl -fsSL https://krllx.github.io/longrun/install.sh | bash
                        # скилл, 12 хуков, CLI, MCP-сервер, таймер на 5 минут, уведомления
longrun watch install   # только таймер (установщик уже это сделал)
longrun notify --test   # по желанию: доходит ли уведомление до экрана
longrun init [--external]  # в папке проекта
longrun link <проект>   # из каждого worktree
longrun where           # какой проект, какая сессия

# заметки
longrun add [--own] -t TAG "..."
longrun doc add путь "что внутри" | doc ls
longrun rm s3 n12 | replace n12 "..."
longrun stale n12 "почему" | mute n12
longrun notes | prune [--auto] [--shared]
longrun recall слово

# сессии
longrun status
longrun send [--list] [--resume] КТО "текст"
longrun important on|next|N|off [--to КТО]
longrun watch add --to КТО --then "..." -- pr-merged ID
longrun watch ls | test -- CHECK | sessions

# оркестратор
longrun orchestrate start --goal "..."
longrun board | board add|assign|take|done|block T7
longrun board add --fact "..." --task T7 | board ls --facts | board ack F1
longrun halt "почему" | resume
longrun ask "вопрос" --options "Да,Нет"

# настройки
longrun onboard [done]
longrun config
longrun config set KEY VALUE [--global]
longrun config unset KEY [--global]

Что гарантирует механика, а что зависит от модели

Границы

• Дайджест не больше 9000 байт. Вытесняются по порядку: watch, хвост журнала, обязанности оркестратора, список сессий, доска, HANDOFF. Заметки уступают последними и не хвостом, а по одной самой старой записи без pin: обрезать конец значило бы выкинуть как раз последние.
• Resume в приложении связывается по priorCliSessionIds; /clear в CLI по эвристике "та же папка, конец с причиной clear не позднее трех минут назад".
• Формат сокета и транскриптов не задокументирован: при смене версии Claude Code первым сломается send в работающую сессию, очередь через inbox продолжит работать.
• Под таймером macOS у python может не быть доступа к ~/Documents (TCC). Проверки от этого не зависят; сообщение тогда ложится в каталог сессии под ~/.claude.
• Сабагенты дайджест не получают. /rewind заметки не откатывает.

Подробности: README.md, docs/REFERENCE.md, docs/ORCHESTRATOR.md в репозитории, и longrun help.