wctx

Контекст рабочего пространства для агентов кодирования.

Ваша система охватывает несколько репозиториев. Контекст вашего агента тоже должен.

wctx capture --summary "what this session figured out"   # at the end of a session
wctx search  "has anyone looked at this?"                # from any other repo, later

Session in Repo A
        ↓
discovers behavior in Repo B
        ↓
wctx
        ↓
fresh session in Repo B retrieves it

Сессия агента кодирования ограничена репозиторием, потому что именно там редактируются файлы. Исследуемая система — нет. Поэтому сессия в вашем UI-репозитории выясняет, что ошибка на самом деле в вашем SDK — а когда вы открываете новую сессию в SDK неделю спустя, эти знания исчезают.

wctx превращает завершённые сессии агентов в структурированный, подтверждённый доказательствами инженерный контекст и предоставляет его будущим сессиям через MCP. Локально-ориентированный: никакого облачного аккаунта, никаких эмбеддингов, никакой загрузки транскриптов.

Двухминутная демонстрация

pnpm install
pnpm demo

Никакого API-ключа, никакой сети. Он создаёт три синтетических репозитория, импортирует завершённую сессию из одного, а затем задаёт вопрос на естественном языке из другого:

$ wctx search "Has the selfie session expiration issue already been investigated?" --repo websdk-demo

  3 result(s) · 4 candidates · 14ms · searched websdk-demo plus 2 related repositories

  1. WebSDK uploadSessionImage does not retry after session expiration  [finding]
     from websdk-demo · session ses_8d3fb1a5 · commit 45a4cab · confidence 0.87
     · matches the query text
     · same repository
     · matches symbol uploadSessionImage

  3. Verify UI delegates selfie upload to the WebSDK  [finding]
     from verify-ui-demo · session ses_8d3fb1a5 · commit b041200 · confidence 0.95
     · matches the query text
     · verify-ui-demo uses websdk-demo (direct consumer)
     · high stated confidence (0.95)

Затем файл SDK изменяется, и доказательства перестают быть достоверными:

$ wctx evidence verify ev_9ae81278
  before: current — The repository is still at the source commit b60a991; nothing has changed.
  after:  stale   — All 1 referenced file(s) changed in b60a991..1ceeaa4. Re-read the code
                    before relying on this.

Полное прохождение: docs/demo.md.

Related MCP server: obsmcp

Установка

Требуется Node 22+ и git.

pnpm install
pnpm build
npm link        # optional: puts `wctx` on your PATH

wctx init       # creates ~/.wctx
wctx doctor     # checks database, git, adapters, and prints MCP setup hints

Настройка MCP

claude mcp add wctx -- wctx mcp

Или для Codex и других MCP-клиентов:

{ "mcpServers": { "wctx": { "command": "wctx", "args": ["mcp"] } } }

Семь инструментов, упорядоченных для постепенного раскрытия, чтобы они оставались доступными в окне контекста:

wctx mcp-info выводит поверхность и фрагменты конфигурации клиента.

Запись того, что узнала сессия

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

wctx capture --summary "Traced the upload failure into the SDK" \
  --finding "SDK swallows the 419 :: uploadSessionImage returns it as terminal, no retry" \
  --repo my-sdk \
  --file "src/session/upload.ts#uploadSessionImage"

Или просто попросите вашего агента сделать это — "запиши, что мы узнали" — и он вызовет finalize_session со своим собственным идентификатором сессии. Ему никогда не нужно знать внутренний идентификатор, а повторный вызов в одной сессии накапливает доказательства, а не дублирует сессию.

Как сделать это проактивным

Агент делает это только в том случае, если что-то ему говорит об этом, и самое надёжное место для этого — собственный файл агента проекта; они читаются при каждом запросе:

wctx instructions          # print the guidance
wctx instructions --write   # install it into CLAUDE.md / AGENTS.md (idempotent)

Инструкции охватывают, когда искать (перед исследованием чего-либо нетривиального), когда записывать (коренные причины, решения с обоснованием, с трудом добытые ограничения, нерешённые вопросы, неожиданности) и что не записывать. Это разница между инструментом, который вы помните использовать, и тем, который накапливается сам.

Если сводка не предоставлена вовсе, wctx capture выводит фактическую на основе записанной активности инструментов сессии — количество файлов, команд, ошибок, изменённых файлов. Намеренно скучно: придумывание повествования из вызовов инструментов было бы той самой уверенной бессмыслицей, которую этот проект отказывается производить.

Основные концепции

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

Репозиторий — зарегистрированная git-рабочая копия, идентифицируемая по её реальному пути, чтобы один и тот же репозиторий не мог быть зарегистрирован дважды через символическую ссылку или подкаталог. Он может принадлежать нескольким рабочим пространствам.

Связь — объявленное, направленное, типизированное ребро (uses, depends_on, calls, imports, consumes_api, provides_api, shares_schema_with, related). Обход следует по рёбрам в обоих направлениях, потому что если verify-ui использует websdk, то сессия в websdk всё равно хочет знать, что узнал verify-ui.

Сессия — нормализованная сессия агента кодирования из Xirp, Claude Code или универсального JSONL, с её рабочей директорией, веткой, коммитом, сообщениями и активностью инструментов.

Доказательство — находка, решение, изменение, нерешённый вопрос, известная проблема, архитектурная заметка или ограничение, прикреплённое к репозиторию, о котором оно (часто не тому, в котором проходила сессия), с указанием файлов и символов, которых оно касается, и коммита, на котором оно было истинно.

Свежесть — основанный на git вердикт о том, изменились ли указанные файлы с момента этого коммита: current (актуально), possibly_stale (возможно устарело), stale (устарело) или unknown (неизвестно).

Архитектура

Xirp · Claude Code · Codex · generic JSONL
                  ↓
          session adapters              ← the only code that knows a vendor format
                  ↓
        NormalizedSession
           ↓            ↓
  transcript copy   deterministic extraction (files, commands, errors — no LLM)
                        ↓
              structured evidence (findings, decisions, questions)
                        ↓
              workspace catalog · SQLite + FTS5 + git
                        ↓
              CLI  ·  MCP  ·  web UI          ← one service layer, no duplicated logic

Подробности и обоснование каждой границы: docs/architecture.md.

Статус интеграции с Xirp

Xirp оказался с открытым, документированным путём чтения, поэтому адаптер реален, а не заглушка.

Адаптер фиксирует обе строки схемы и громко сообщает об ошибке при неизвестной версии, а не угадывает. Полные доказательства, включая то, что остаётся непроверенным и как это воспроизвести: docs/research/xirp.md.

Безопасность

Ничто не покидает вашу машину. Никакого облака, никакой телеметрии, никакого API эмбеддингов, никакой загрузки транскриптов; весь список зависимостей — это @modelcontextprotocol/server, better-sqlite3, commander и zod.

• Транскрипты копируются в ваш каталог данных (Claude Code удаляет свои через 30 дней) вместе с отредактированной копией — и предоставляется только отредактированная копия.

• Редактирование охватывает закрытые ключи, JWT, заголовки авторизации, токены AWS/GitHub/Slack/OpenAI/Google, URL с учётными данными и присвоения секретов. Это сопоставление с образцом, выполняемое по мере возможности, и не является гарантией того, что транскрипт безопасен для распространения.

• Доказательства, возвращаемые агентам, помечаются как исторические, ненадёжные данные, а строки, похожие на инструкции ("игнорируй все предыдущие инструкции"), нейтрализуются. Смягчение, а не иммунитет.

• Каждый вызов git использует массив аргументов, никогда не строку оболочки. Запросы FTS5 конструируются, никогда не интерполируются.

• Удаление транскриптов и удаление доказательств — независимые операции.

Подробности: docs/security.md.

Сравнение с существующими инструментами

Заявления о возможностях взяты из собственных README каждого проекта, проверены 2026-08-13. Ничто здесь не утверждает, что другой проект не может чего-то делать.

Полный обзор с границей памяти каждого проекта, механизмом захвата и тем, что было использовано в качестве идеи: docs/research/competitive-landscape.md.

Оценка

На синтетическом корпусе из 15 запросов, 28 элементов (pnpm eval) соответствующая предыдущая сессия появилась в первой пятёрке для 15 из 15 запросов и заняла первое место для 11 из 15, с медианной задержкой локального поиска 1,6 мс. Добавление топологии рабочего пространства к обычному FTS5 оставило частоту попаданий на этом корпусе неизменной, но улучшило MRR с 0,839 до 0,867, сделало атрибуцию репозитория точной (0,93 → 1,00) и исключило результаты из несвязанных репозиториев (0,20 → 0,00 на запрос).

Корпус мал, синтетичен и написан тем же человеком, который писал запросы. Что это означает для чтения цифр, подробно описано в docs/evaluation.md.

Ограничения

Честный список, полностью: KNOWN_LIMITATIONS.md. Три наиболее важных:

• Поиск ориентирован на ключевые слова. FTS5 сопоставляет токены. Полностью перефразированный запрос без лексического пересечения может пропустить результат; структурные повышения лишь частично компенсируют.

• Свежесть — это не верификация. Он отвечает на вопрос «изменились ли упомянутые файлы?», но никогда — «верно ли это утверждение до сих пор». Изменение поведения в нетронутом файле невидимо.

• Связи объявляются, а не выводятся. Необъявленная связь невидима для ранжирования.

Дорожная карта

Отсортировано по степени улучшения основного цикла:

1. Автоматическое завершение сессии через хук stop обвязки (сейчас вручную).

2. Укрепление адаптера Xirp в разных версиях и обвязок codex / gemini.

3. Обнаружение конфликтов и предложения по замене — схема поддерживает и то, и другое; никто их не заполняет.

4. Импорт Backstage / Portal catalog-info.yaml за существующим швом CatalogProvider.

5. Более сложный корпус для оценки с почти дублирующимися находками, чтобы проверить, помогает ли топология находить, а не только упорядочивать.

Участие в разработке

См. CONTRIBUTING.md. Должны проходить pnpm typecheck && pnpm lint && pnpm test, а pnpm demo должно работать из чистой копии без учетных данных.

Атрибуция и отсутствие принадлежности

wctx — это независимый эксперимент с открытым исходным кодом, вдохновленный публичными идеями Xirp, Spotify Portal, Backstage и MCP.

Он не связан с Spotify и не одобрен им.

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

Лицензия

MIT. См. LICENSE.