ctx-manager

Провайдер-агностический CLI и MCP-сервер для контекстной инженерии, предназначенный для мультиязычной агентной разработки.

ctx-manager располагается между вашей папкой Docs/ (PRD, архитектурные документы, планы фаз, спецификации API) и AI-агентами кодирования (Claude Code, Cursor, Windsurf), сокращая расход токенов двумя способами:

• Детерминированная нарезка документов на основе заголовков — извлекайте именно тот раздел, который нужен из файла-чертежа, а не весь файл целиком. Структурный подход (регулярные выражения по Markdown-заголовкам), а не RAG/эмбеддинги.

• Дополняемый, проверяемый через git файл Memory_Ledger.md — точное состояние сессии, чтобы агенты не выводили заново и не галлюцинировали то, что уже было создано. Каждая запись проверяется по реальному выводу git status перед тем, как быть помеченной как проверенная.

Работает одинаково в Rust, Go, TypeScript, Python или любом другом стеке — ctx-manager никогда не касается исходного кода вашего приложения, только Docs/.

Установка

uvx --from ctx-manager ctx --help

Никакой настройки virtualenv, глобальная установка не требуется.

Related MCP server: Claude Session MCP

Использование

Нарезка файла-чертежа по заголовку:

ctx build --slice "PRD.md > 5. Feature List"

Выводит содержимое выбранного раздела в stdout — передайте его в CLAUDE.md или туда, откуда ваш агент читает контекст.

Автоматическая нарезка следующей фазы на основе истории журнала:

ctx build --auto-phase

Читает Memory_Ledger.md для последней завершённой фазы и автоматически вырезает раздел следующей фазы из Phase_file.md — без ручного указания --slice. Если в журнале ещё нет записей о завершённых фазах, возвращается к Фазе 0 с предупреждением.

Добавление проверенной записи в журнал сессии:

ctx append-ledger --summary "Implemented the login endpoint" --category completed

Проверяет git status вашего проекта перед записью и добавляет префикс [Verified: N files changed], [Reasoning/State Only] или [Unverified: not a git repo] в зависимости от того, что найдено — так заявленное агентом «готово» сверяется с тем, что реально произошло на диске.

Запуск как MCP stdio-сервер (для Cursor, Windsurf, Claude Desktop):

ctx mcp

Предоставляет query_slice, append_ledger_entry и get_current_phase как MCP-инструменты, вызывая тот же самый код, что и CLI-команды выше.

Конфигурация

ctx-manager ищет вверх от текущей директории файл .context/config.toml. Если он не найден, используются разумные значения по умолчанию (папка Docs/, Memory_Ledger.md и т.д.) с однократным предупреждением.

[project]
docs_dir = "Docs/"
ledger_file = "Memory_Ledger.md"
phase_file = "Phase_file.md"

[blueprint_files]
files = ["PRD.md", "Architecture.md", "API_Spec.md"]

[git]
scope = "docs_dir"  # or "repo_root"

Полностью переопределите поиск с помощью --project-root.

Интеграция с Claude Code

Примеры хуков SessionStart/SessionEnd (автообновление CLAUDE.md перед сессией через --auto-phase, автоматическое логирование в журнал после) находятся в examples/claude_code_hooks/.

Принципы проектирования

1. Docs/ на входе, Docs/ на выходе — никогда не касается исходного кода приложения, на любом языке.

2. Дешёвое перед тяжёлым — stdlib re перед эмбеддингами, subprocess git перед библиотекой git, локальный stdio перед любым сетевым сервисом.

3. Журнал только на добавление — ни один путь кода не перезаписывает Memory_Ledger.md целиком. Никогда.

4. Громкий сбой, а не тихий — отсутствующий заголовок или файл возвращает явную ошибку, а не пустое содержимое, на котором агент мог бы галлюцинировать.

Полное описание архитектуры см. в Docs/Architecture.md и Docs/PRD.md (этот проект использует сам себя — его собственная папка Docs/ нарезается и отслеживается ctx-manager во время его собственной разработки).

Ограничения

ctx-manager не может помешать агенту обойти его. Ничто здесь не мешает агенту с прямым доступом к файловой системе читать Docs/PRD.md напрямую, вместо того чтобы идти через ctx build. Это структурное ограничение, а не отсутствующая функция — CLI на основе подпроцессов не имеет доступа к вызовам чтения файлов другого процесса.

Если вам нужно реальное принуждение (а не просто соглашение), оно должно исходить от самого агентного рантайма:

• Claude Code: используйте правила permissions.deny в .claude/settings.json, чтобы заблокировать инструменту Read прямой доступ к Docs/*.md, вынуждая полагаться на CLAUDE.md, который генерирует ctx build --auto-phase. См. документацию Claude Code по правам доступа — это не то, что ctx-manager настраивает за вас.

• MCP-клиенты (Cursor, Windsurf и т.д.): любые средства контроля доступа к файловой системе, которые предоставляет этот клиент, если они есть — вне контроля ctx-manager.

Без одного из этих механизмов ctx-manager — это соглашение, которому агент должен следовать, подкреплённое проверенной историей сессий (журналом), а не песочница.

Разработка

git clone <this-repo>
cd ctx-manager
uv sync
uv run pytest

Лицензия

MIT — см. LICENSE.