desk-core
v0.2.0 · 166 тестов · только Python stdlib

Контекстный фреймворк на хуках для агентов

desk-core решает, что агент видит в контексте и когда.

  • Правило — к вызову, последним перед решением
  • Запрещённый вызов не проходит
  • Правила — твои markdown-файлы
desk-core — семь частей фреймворка. Выбери любую. 3 / 7
DESK_HOME/process/git.md

Правило — файл, шапка — механика

Текст пишется для модели, шапка — для фреймворка: к какому сроку подать, на что сработать, что остановить.

Отдельного конфига правил нет: удалил файл — правила не стало. Выключить, не удаляя, — enabled: false.

tier — крайний срок правила. Чем он позже, тем меньше висит в сессии без дела.

process/git.mdиз шаблона, сокращён
---
tier: action                    ← срок: не позже действия
when:
  - git: write                  ← подать: git-команда что-то меняет
guard:
  - deny: 'Co-Authored-By|Generated with'
    in: commit-message           ← остановить: до вызова
    id: commit-no-attribution    ← имя: для замера соблюдения
---
importвсегда, в каждой сессии
sessionдо первого действия
actionкогда сработал when:
linkсправочник, по ссылке
when: [варианты]

Правило приезжает к действию

Правило приходит, когда агент слушает его лучше всего: перед самим действием, а не за сто шагов до него. Что не сработало — контекст не занимает.

  • tool · command · input · skill — вызов
  • paths · git · desk — запись, и из Bash тоже
  • prompt — реплика, до первого инструмента
  • gate: true — без правила вызов не пройдёт
одна сессия: что попадает в контекст
правил в контексте8 из 9
desk.mdcontext.mdloop.mdlocal.md tracker.md sensitive.md tests.md git.md
итогthreads.md (как вести нити — намерения дольше сессии) не понадобился — и не занимал контекст

Правила и их when: — из шаблона desk init; сценарий сессии условный.

guard: deny | ask | deny-unless | ask-unless

Решение до вызова, а не после

Запрет исполняет скрипт, а не память модели. Причину из why видят и модель, и человек; текст правила едет вместе с решением.

  • deny — отклонить, каждый раз
  • ask — спросить человека, раз за сессию
  • ищет в команде, коммите, записи в файл и вводе MCP-инструмента
  • команду хук не переписывает
один вызов: что делает хук
вызов
git commit -m "fix(cart): handle an empty cart"
подано в контекст
process/git.md
проходитзаголовок по формату; правило второй раз не подаётся

Сценарий из шаблона desk init. Там же стартовый набор запретов: deny на rm -rf по / и ~, ask перед записью .env и ключей.

desk measure --days 28

Правило без замера — пожелание

Скрипт проходит по записям сессий и считает результат, а не открытие файла. Без модели.

  • досягаемость: сработал when: — дошло ли правило; меньше 100 % — правила в контексте не было: хуки ещё не стояли, правило ждало своей порции, контекст сжали
  • соблюдение: доля вызовов, прошедших запрет, по id
  • не держится — переписать или сделать guard
досягаемость · сработал when: → правило в контексте
process/worktrees.md59/10656 %
process/tests.md61/12648 %
process/git-flow.md75/18640 %
соблюдение · вызов прошёл запрет
commit-no-attribution1746/1746100 %
commit-format584/65589 %
paid-code-<репо>3/1619 %

Настоящий вывод на desk автора: 387 сессий за 28 дней, строки выбраны. Низкие — не стыд, а список дел: видно, какое правило не работает.

DESK_HOME/contexts/<место>/

Место работы — отдельно от правил

Хостинг, трекер, репозитории лежат в папке места. Хаб объявляет, когда место активно; его правила молчат в остальных сессиях.

Сменил работу — новая папка, переносимые правила не тронуты.

contexts/example/context.mdшапка хаба
---
tier: session
match:
  remote: ['git.example.com']   ← подстрока в git remote -v
  path: ['~/work/*']            ← или каталог сессии
---
projects/<репо>/Правила репозитория идут за ним: вызов коснулся его файлов — приезжают в сессии любого контекста.
place-words.txtИмена места не попадают в переносимые правила: правка с ними — ask.
DESK_HOME/ext/*.py

Что не выразить regex-ом — кодом

Python-файл рядом с правилами: проверка перед вызовом, замер соблюдения, своя строка линтера или обработчик события.

Упавшее расширение хук не ломает — ошибка приходит строкой.

ext/no_force_push.pyупрощённо
from desk import ext

@ext.live("no-force-push", "no force push to a shared branch")
def no_force_push(call, session):       # перед вызовом
    if "push --force" in call.command:
        return ("deny", "desk: push a fix on top instead")
@ext.live@ext.compliance@ext.lint@ext.on(событие)@ext.in_work@ext.checkouts

live — решение до вызова, compliance — случаи для замера, lint — проверка правил, on — свои строки на событиях сессии, in_work — идёт ли работа по ветке (чтобы не тронуть живое), checkouts — чекауты машины. Проверки самого ядра зарегистрированы через этот же API.

desk <команда>

Проверить без сессии, переехать без переписывания

desk why показывает решение хука так, как он его примет. Ничего не выполняет.

  • why — сухой прогон; с --exit-code годится для CI
  • lint · measure — структура и соблюдение
  • init · doctor — скелет и диагностика
  • import · export — из CLAUDE.md и в AGENTS.md
терминалнастоящий вывод на шаблоне, сокращён
$ desk why 'git commit -m "fixed bug"'
Сработают правила:
  process/git.md [action] ← git commit
Запреты:
  deny commit-format — commit subject — Conventional
       Commits `<type>(<scope>): <description>` — «fixed bug»
Итог хука (первый вызов в сессии): deny
  подано: process/git.md
CLAUDE.md→desk import→правила, tier: import→+ when: — к действию

Переезд: разделы ## становятся правилами, модель видит то же, что раньше. Дальше каждому даёшь свой when:.

Зачем

Контекст агента — ресурс, а не свалка. Файл инструкций читается один раз на старте, и к двадцатому шагу от него мало что остаётся; правило из прозы может молча не исполниться — и узнаёшь об этом по коммиту с чужой подписью или по правке кода, который стоит денег.

Контекстом можно управлять так же, как веб-фреймворк управляет запросом. Хуки — точки жизненного цикла агента: старт сессии, реплика, вызов инструмента, его результат. desk-core встаёт в каждую и решает, что положить в контекст к этому вызову и что остановить до выполнения — регулярным выражением или десятью строками Python.

Момент важен не меньше содержания. То, что принёс хук, — самое свежее в контексте: короткий текст про то самое действие, которое агент делает прямо сейчас. Это же правило, прочитанное на старте, к этому времени лежит под сотней килобайт кода и вывода команд. Вес у него разный, хотя слова те же.

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

Как работает

Ты пишешь правило — markdown-файл с шапкой. Дальше работает жизненный цикл агента: в каждой его точке стоит хук фреймворка.

  1. SessionStartстартует сессияСобирает стартовый контекстМесто работы — по git remote или каталогу. Файлы яруса session едут содержимым, до первого действия.
  2. UserPromptSubmitпришла репликаПодаёт по темеТема названа словами — её правило приезжает вместе с репликой, раньше первого инструмента.
  3. PreToolUseагент зовёт инструментПодаёт и решаетВызов сверяется с when и guard всех применимых правил: сработавшее — в контекст, запрещённое — отклонить, спорное — спросить тебя.
  4. PostToolUseкоманда выполниласьСверяет с фактомЧто команда изменила на самом деле — и те же правила по изменённым файлам: запись скриптом не проходит мимо.
  5. SessionEndсессия закончиласьЗакрывает сессиюСтрока в журнал сессий, если он включён, и событие расширениям.

Все пять — одна точка входа, desk-hook, без вызова модели. После сессий desk measure считает по их записям, дошло ли сработавшее правило до агента и какая доля вызовов прошла запрет.

Сверх доставки правил — дополнения, выключенные, пока не включишь в desk.yml: нити — намерения и разборы, которые живут дольше сессии (каждая сессия начинается со списка открытых); журнал сессий; сигнал «мета», когда настройка desk съедает работу; шапка сессии; свод рабочих деревьев и стеков; возврат простаивающего чекаута к базе; дерево сессии. Без них ядро состояние git не меняет.

Попробовать

Пять минут, ничего не ставя: скелет правил и сухой прогон

alias desk=~/desk-core/bin/desk
desk init ~/desk-try
export DESK_HOME=~/desk-try
desk why 'git commit -m "fixed bug"'

Живая сессия с хуками — только на этот запуск, конфиг не меняется

claude --plugin-dir ~/desk-core

Насовсем: CLI пакетом, хуки плагином

uv tool install ~/desk-core
claude plugin marketplace add ~/desk-core
claude plugin install desk@desk-core
desk doctor

Уже есть CLAUDE.md — не выбрасывать, а разложить на правила

desk import CLAUDE.md

Разделы ## становятся правилами яруса import — модель видит то же, что раньше. Дальше разделу даёшь свой when:, и он приезжает к действию, а не висит в каждой сессии.

Без плагина: desk init --hooks печатает блок для ~/.claude/settings.json; DESK_HOME — там же, в ключе env. Хуки — только Claude Code; Codex и Cursor получают вход через desk export agents-md, без подачи по действию и запретов. Подробности — README и docs/ в репозитории ядра.

Контекст агента — по правилам, а не по памяти

Markdown-файлы и хуки. Без облака, без зависимостей, без вызова модели.