p-backlog
v0.14.1
Published
Keep pull requests clean and audit findings safe: a local, autonomous backlog for Claude Code. The agent files out-of-scope issues as Markdown tasks with context and re-checks them as code changes. Optional web UI with metrics.
Maintainers
Readme
p-backlog
Чистые пулреквесты. Находки аудитов не теряются.
Личный беклог для Claude Code, который живёт рядом с кодом markdown-файлами. Когда агент замечает проблему вне текущей задачи, он не протаскивает правку в ваш пулреквест, а заводит задачу: файл, строка и чем это грозит. Находки аудитов и ревью тоже становятся задачами, а не теряются в истории чата.
- Чистые пулреквесты. Посторонние правки уходят в беклог, а не в дифф, который вы ревьюите. Вкладка «Эффект» в статистике показывает, сколько строк не попало в пулреквесты.
- Ничего не теряется. Каждая находка аудита или ревью — задача с источником (
файл:строка), описанием риска и чеклистом. - Контекст сохранён, токены сэкономлены. Задача хранит контекст, который нужен агенту, чтобы потом взять её в работу. При перепроверке агент получает суть задачи, текущий код вокруг её строки и изменения с прошлой проверки — обычно этого хватает, чтобы решить, не перечитывая кодовую базу.
- Сам следит за актуальностью. Stop-хук просит агента перепроверить задачи, чьи строки изменились с прошлой проверки, — не правку в другом месте файла и не файл, которого просто нет в текущей ветке. Агент закрывает исправленные со ссылкой на коммит, номера строк и переименованные файлы следуют за кодом. Закрытые задачи удаляются через 7 дней, задачи открытого эпика — после его закрытия.
- Локальный и автономный. Обычные файлы в
~/backlog, без аккаунта и облака. Агент работает с ним через скилл, так что трогать CLI не обязательно — но можно. - Графики — когда нужны. Поднимите локальное веб-приложение, чтобы просматривать и разбирать задачи и следить за метриками: долг по неделям, где болит в коде, насколько точны проверки, во что обходится хук в токенах.
Состоит из CLI backlog, скилла backlog и Stop-хука для Claude Code и веб-приложения по желанию.
Скриншоты





Как начать
Установка CLI (нужен Node.js 22.13 или новее):
npm i -g p-backlogПодключите агента.
Claude Code — плагин (рекомендуется). В Claude Code выполните:
/plugin marketplace add expatriate/p-backlog /plugin install p-backlog-ru@p-backlogp-backlog@p-backlogставит английский скилл. Плагин приносит скилл и хук Stop и обновляется командой/plugin marketplace update p-backlog; сам CLI по-прежнему ставится из npm, и для плагина нужен CLI p-backlog 0.5.0 или новее.Без плагина, а также для Codex и Cursor:
backlog setupставит ссылку на скилл и хук Stop каждому найденному агенту — см. Другие агенты.
Язык — по умолчанию русский, если беклог уже есть, иначе язык берётся из локали системы. Сменить можно в любой момент:
backlog config language en # или ruПервый проект и первая задача — откройте Claude Code в своём репозитории и попросите «запиши в беклог …», либо создайте задачу сами:
backlog new --title "Таймаут загрузки не учитывает размер файла" --category bug <<<'Описание проблемы'Проект для текущего репозитория
backlog newсоздаст сам, если его ещё нет.Веб-приложение —
backlog service installзапускает его наhttp://localhost:4317и при входе в систему; проверить можно так:backlog service statusХук Stop и тревоги — после каждого ответа агента в репозитории хук Stop проверяет, не изменился ли код у открытых задач этого проекта, и просит агента перепроверить их, если да. Он же показывает тревоги — сигналы о состоянии беклога (растущий долг, зависшие задачи, старые задачи с низким приоритетом и т. п.); их сводку показывает и
backlog stats.
Другие агенты
backlog setup находит установленных агентов и подключает каждого; --agent claude|codex|cursor сужает до одного:
| Агент | Как находится | Скилл | Хук Stop |
|---|---|---|---|
| Claude Code | всегда | ~/.claude/skills/backlog | ~/.claude/settings.json |
| Codex CLI | $CODEX_HOME или ~/.codex | ~/.agents/skills/backlog | <каталог codex>/hooks.json |
| Cursor | ~/.cursor | ~/.agents/skills/backlog | ~/.cursor/hooks.json |
Скилл — ссылка на скилл пакета на выбранном языке; backlog config language переставляет её у всех
агентов, которым её поставил setup. Чужие хуки в этих файлах остаются на месте, повторный setup ничего
не дублирует. Codex один раз просит одобрить новый хук: откройте /hooks в Codex. В Cursor просьба перепроверить
задачи приходит следующим сообщением. Статистика токенов и расходов считает только Claude Code.
У Codex и Cursor одна ссылка на скилл в ~/.agents/skills — общем каталоге скиллов, который читают оба; прежние
ссылки в ~/.codex/skills и ~/.cursor/skills setup снимает. Cursor читает ещё и ~/.claude/skills, поэтому при
ручной установке для Claude Code он может показать скилл дважды.
Если включён плагин для Claude Code, setup Claude Code не трогает; backlog setup --remove-manual снимает ссылки на
скилл и хуки Stop, которые setup ставил раньше (у всех агентов или у --agent).
Где лежат задачи
Каталог беклога — ~/backlog или путь из переменной BACKLOG_DIR. Внутри — по каталогу на проект:
~/backlog/spa/project.md # name, prefix, repos
~/backlog/spa/SPA-12.md # задача: frontmatter + markdownПроект для текущей директории определяется по git-корню и полю repos в project.md. Если проекта нет,
backlog new создаёт его сам.
Хранение данных
| Файл | Что хранит | Сколько хранится |
| --- | --- | --- |
| Файлы задач | По файлу на задачу, включая закрытые | Закрытые — 7 дней после закрытия (задачи открытого эпика — после закрытия эпика), затем удаляются (служба — раз в час; без службы — раз в сутки, после команды CLI, кроме хука агента) |
| journal.jsonl | История событий задач и проверок по проекту | История существующих задач — целиком; остальные события — 13 недель (уплотняется раз в сутки, службой и после команд CLI, кроме хука агента) |
| .runs.jsonl | Журнал запусков CLI | 13 недель |
| .usage-cache.json | Расход Claude Code, разобранный из транскриптов; для транскриптов, которые Claude Code уже удалил, — единственная копия | 13 недель |
| .code-cache.json | Кэш истории git для вкладки «Код» | 90 дней |
| Лог службы | stdout/stderr launchd на macOS, p-backlog.log в %LOCALAPPDATA% на Windows | macOS: обрезается до последних 256 КиБ, когда превышает 1 МиБ. Windows: больше 1 МиБ — при старте службы переносится в p-backlog.log.old. Linux: размер ограничивает journald |
| .swept-at, .journal-compacted-at | Отметка времени последней уборки/уплотнения | До следующей |
Окно хранения не настраивается.
Команды CLI
| Команда | Что делает |
|---|---|
| backlog new --title <t> --category <категория> [--type task\|epic] [--priority low\|medium\|high\|critical] [--tags a,b] [--found incidental\|review\|manual] [--source файл:строка] [--epic ID] [--blocked-by ID,…] [--related ID,…] [--project id] [--force] [--json] | Создаёт задачу, описание читается из stdin; похожая открытая задача — отказ (код 3), --force создаёт всё равно; --found: incidental — агент заметил попутно (в «Эффекте» считаются только такие), review — находка ревью, manual — заведена по просьбе пользователя (по умолчанию) |
| backlog list [--query q] [--status s,…] [--tag t,…] [--project id \| --all-projects] [--json] | Список задач, по умолчанию открытые задачи текущего проекта |
| backlog show <ID> [--json] | Задача целиком: связи, блокеры, предупреждения |
| backlog take <ID> [--force] [--json] | --next [--project id] [--json] | Берёт задачу в работу, проверяя блокеры |
| backlog take --path <файл\|каталог> [--project id] [--json] | Берёт в работу все открытые задачи внутри пути |
| backlog status <ID> <backlog\|in-progress\|blocked\|done\|cancelled> | Меняет статус |
| backlog priority <ID> <low\|medium\|high\|critical> | Меняет приоритет |
| backlog category <ID> <категория\|none> | Меняет категорию или убирает её |
| backlog epic <ID> [<ID> …] --to <ID эпика\|none> | Переносит задачи в эпик или вынимает из него |
| backlog check [--changed] [--project id \| --all-projects] [--json] | Чинит висячие ссылки и завершённые эпики, находит задачи, которые пора перепроверить |
| backlog close <ID> --as fixed\|obsolete\|duplicate --reason <улика> [--duplicate-of ID] | Закрывает задачу с причиной; fixed — только с хешем коммита из репозитория проекта; задаче, закрытой через status <ID> done, fixed привязывает коммит, не открывая её снова |
| backlog verify <ID> [<ID> …] [--source файл:строка] | Отмечает, что задачи ещё актуальны, и запоминает фрагмент кода |
| backlog prune [--project id \| --all-projects] [--apply] | Задачи с низким приоритетом старше 30 дней; --apply отменяет их; --all-projects — только активные проекты |
| backlog stats [--project id \| --all-projects] [--json] | Сводка статистики и тревоги |
| backlog project list \| status <id> active\|inactive \| delete <id> --confirm <id> | Активность проектов и удаление проекта вместе с задачами |
| backlog hook stop [--agent claude\|codex\|cursor] | Хук Stop для Claude Code, Codex или Cursor: просит агента перепроверить задачи, чей код изменился |
| backlog config language [ru\|en] | Без значения — печатает текущий язык беклога; со значением — меняет его |
| backlog setup [--agent claude\|codex\|cursor] [--service] | Скилл и Stop-хук найденным агентам — Claude Code, Codex, Cursor (см. Другие агенты); с --service — ещё и служба автозапуска |
| backlog setup --remove-manual [--agent claude\|codex\|cursor] | Снимает ссылки на скилл и хуки Stop, которые поставил setup |
| backlog serve [--port N] | Запускает веб-сервер в текущем процессе, порт — из PORT, иначе 4317 |
| backlog service install \| uninstall \| status | Автозапуск веб-сервера при входе: launchd на macOS, systemd --user на Linux, скрипт в папке «Автозагрузка» на Windows; status — установлена ли служба и отвечает ли сервер |
Коды выхода: 0 — успех, 1 — ошибка аргументов или правил, 2 — не найдено, 3 — отказ (задача
закрыта, заблокирована или все подходящие заблокированы), 4 — команда не выполнилась (в том числе файл задачи
занят другим процессом), 5 — у check есть кандидаты или проблемы задач, которые надо разобрать.
С --json команды new, show и take печатают один и тот же объект задачи (с прогрессом, блокерами и
связями), а list и take --path — массив таких объектов.
Проект, который больше не ведётся, помечается неактивным: его задачи не попадают в список и статистику
режима «Проекты», но страница проекта работает как обычно. Проверки (backlog check), Stop-хук и
удаление старых закрытых задач идут по всем проектам, включая неактивные. Удаление проекта сносит каталог
~/backlog/<id> со всеми задачами и журналом — и в интерфейсе, и в CLI оно требует ввести id проекта.
Порядок в беклоге
- Агент заканчивает ответ в репозитории, где открытые задачи ссылаются на изменившийся код, — хук Stop просит его перепроверить эти задачи. По просьбе «проверь беклог» он проходит весь проект.
- Две открытые задачи — возможный дубль (проверка предлагает пару,
backlog newотказывает с кодом 3), когдаsourceу них в одном файле и в заголовках не меньше трёх общих слов (все слова короткого заголовка) или когда заголовки почти одинаковы, включая короткие слова. Одних общих слов мало: их всё время делят группы «Мелочи ревью» и задачи одной части кода. - Ненужную задачу агент закрывает через
backlog closeс уликой; в интерфейсе такие задачи видны по ссылке «Закрыты агентом», их можно вернуть в беклог. - Эпик, все задачи которого закрыты, сервер при старте и раз в час закрывает сам; такие эпики тоже видны по ссылке «Закрыты агентом».
- Любая закрытая задача удаляется через 7 дней вместе с файлом: это делает сервер при старте и раз в час. Задачу открытого эпика сервер держит, пока эпик не закроется, чтобы прогресс эпика и его сделанное не пропадали, — тогда вместо отсчёта видно «удаление задержано». Номера удалённых задач повторно не выдаются.
В паре с code-review-graph
code-review-graph строит локальный граф кода (функции, классы, их
строки) в .code-review-graph/graph.db в корне репозитория. p-backlog без него работает, но если граф есть —
использует его, только на чтение:
- Перепроверка по символу.
sourceзадачи (файл:строка) сопоставляется с функцией или классом, в которых стоит. Stop-хук иbacklog checkпредлагают перепроверить задачу, только когда изменился этот символ, а не любая строка файла, — лишних перепроверок меньше. Без графа проверка опирается на строкиsource, затем на весь файл. - Дубли по символу. Пара-дубль, задачи которой указывают в одну функцию, помечается как найденная по символу — вкладка «Качество» показывает, как часто этот признак прав.
- Состояние графа в вебе. Боковая панель предупреждает, если у проекта нет графа, он устарел или не читается (собран другой версией или для другого пути), и подсказывает команду, которая это исправит.
- Точность проверки. Вкладка «Качество» в статистике показывает, как часто был прав каждый способ проверки: по
символу, по строкам
source, по файлу.
Настройка, один раз на репозиторий (инструмент на Python; подойдёт и pipx install code-review-graph):
uv tool install code-review-graph
code-review-graph build # в корне репозитория
code-review-graph install --platform claude-code # по желанию: его MCP-сервер и инструкции для Claude CodeЧтобы граф не устаревал, держите запущенным code-review-graph watch или выполняйте code-review-graph update
после изменений. Проверено с code-review-graph 2.3.
Веб-приложение
backlog serve # запускает веб-сервер в текущем процессе, порт — из PORT, иначе 4317
backlog serve --port 5000Сервер слушает только 127.0.0.1 и показывает изменения каталога сразу: задача, созданная агентом,
появляется в открытой вкладке без перезагрузки.
Задачи видны списком или доской (переключатель «Список / Доска» рядом с поиском). На доске по колонке на каждый статус из фильтра и «сделана» как место для переноса; перетащите карточку в другую колонку — мышью, пальцем или с клавиатуры (пробел — взять, стрелки влево и вправо — выбрать колонку, пробел — положить), — и статус сменится, «Отменить» вернёт его. Эпики остаются в списке.
Чтобы сервер поднимался сам при входе в систему, установите его как службу (поддерживаются macOS, Linux и Windows):
backlog service install # macOS: launchd, Linux: systemd --user, Windows: скрипт в папке «Автозагрузка»
backlog service status # установлена ли служба, отвечает ли сервер; код 4, если нет
backlog service uninstallЛоги:
- macOS —
~/Library/Logs/p-backlog.log - Linux —
journalctl --user -u p-backlog - Windows —
%LOCALAPPDATA%\p-backlog\p-backlog.log
Переход с установки из клона
Если p-backlog был установлен из клона репозитория, переходите на пакет:
npm i -g p-backlog # или, из клона: npm link
backlog setup --servicesetup переставит ссылку скилла с клона на установленный пакет и не задублирует хук Stop; с
--service install перезаписывает службу автозапуска на месте, поэтому заодно заменяет и
LaunchAgent local.p-backlog, настроенный вручную по старому шаблону plist.
Обновление
npm update -g p-backlog
backlog service installЗапущенная служба продолжает работать со старым cli.js, пока её не переустановят, — веб-ресурсы на
диске уже новые, но именно backlog service install переключает службу на новый код. Переустановка
сохраняет порт, на котором служба была установлена; PORT задавайте, только чтобы его сменить.
После обновления самого Node (например, через Homebrew) тоже запустите backlog service install —
служба хранит путь к бинарнику Node, с которым была установлена.
Удаление
backlog setup --remove-manual
backlog service uninstall
npm uninstall -g p-backlogbacklog setup --remove-manual снимает ссылки на скилл и хуки Stop у всех агентов (плагин удаляется через
/plugin uninstall). Перед удалением пакета выполните backlog service uninstall — иначе KeepAlive у launchd
(или Restart=on-failure у systemd) продолжит перезапускать несуществующий cli.js.
На Windows скрипт в папке «Автозагрузка» не перезапускает сервер после падения — в отличие от KeepAlive
у launchd или Restart=on-failure у systemd; после сбоя запустите backlog service install заново или
backlog serve.
Разработка
Как предложить изменения — в CONTRIBUTING.md (на английском), как сообщить об уязвимости — в SECURITY.md; правила общения — Code of Conduct.
npm install
npm run build
npm link # глобальная команда backlog
npm run install-skill # ~/.claude/skills/backlog → skill/backlog и хук Stop в ~/.claude/settings.json
npm run plugins # после правки скилла или версии: пересобрать plugins/npm start # сборка и сервер на http://localhost:4317
npm run dev # сервер и Vite с горячей перезагрузкойnpm test # модульные, серверные и интерфейсные тесты
npm run typecheck
npm run lint
npx playwright install chromium # один раз, перед первым запуском e2e
npm run test:e2e # Playwright в Chromium: массовые действия, перенос на доске, живое обновление, CSP, графики, ширина панели задачи
npx playwright install webkit # по желанию: тот же набор ещё и в WebKit
npx playwright test # Chromium, затем WebKit
npm run test:package # весь путь установки из tarball на этой ОС (медленный)
npm run screenshots # скриншоты для README на демо-данных, в docs/screenshotsЧтобы попробовать сборку так, будто это опубликованный пакет, без публикации:
npm pack && npm i -g ./p-backlog-0.2.0.tgzВерсии публикует в npm workflow GitHub Actions Release через Trusted Publishing: поднимите версию и CHANGELOG,
выполните npm run plugins, закоммитьте, запушьте и запушьте тег v<версия> — workflow проверит, что тег совпадает
с package.json, прогонит проверки и опубликует пакет с подтверждением происхождения (provenance). Токен npm нигде не
хранится.
