CodeAlmanac: живая вики кодовой базы на ИИ-агентах

Параметры настройки описаны в разделе Setup.

После того как CodeAlmanac настроен:

Установите глобальные инструкции для агентов и выбранных локальных инструментов:

Setup устанавливает инструкции для агентов под выбранные инструменты и три локальных задания launchd для macOS. Все задания и вся работа с вики выполняются локально.

Эти расписания выполняются локально в фоновом режиме. Команда codealmanac automation status покажет, что установлено.

На последнем шаге настройки вас спросят об анонимной телеметрии — рекомендуется ответить «Да», чтобы мы могли видеть, какие команды работают и где CLI даёт сбои. Телеметрия отправляет контролируемые сведения о командах и событиях жизненного цикла, а также очищенные данные об необработанных сбоях, привязанные к случайному UUID установки. Код, пути, аргументы, запросы, промпты, транскрипты, идентификаторы репозитория или запуска, локальные переменные и учётные данные никогда не передаются; GeoIP отключён. Чтобы отказаться, выберите «Нет» в процессе настройки, передайте setup --no-telemetry, установите telemetry.enabled в false или используйте DO_NOT_TRACK=1 в любой момент. Без будущего входа в систему UUID-профиль не связан ни с именем, ни с адресом электронной почты.

Если у вас нет Codex или вы предпочитаете Claude, используйте --runner claude.

Флаг --target определяет только то, какие файлы глобальных инструкций для агентов будут установлены; он не влияет на выбор ИИ-runner:

Настройте автоматическую работу во время установки:

Чтобы удалить локальные артефакты, созданные CodeAlmanac:

Агенты и люди используют одни и те же локальные команды чтения:

Используйте --wiki <name>, чтобы читать другую зарегистрированную локальную вики. По умолчанию команды нацелены на текущий каталог, если он является корнем зарегистрированного репозитория.

Команды жизненного цикла (lifecycle commands) запускают один из трёх явных агентов — build, ingest или garden — через публичный Yoke SDK. Имеющиеся файлы промптов остаются полными инструкциями к задаче и направляют агентов на редактирование вики в каталоге almanac/.

Агенты жизненного цикла — это доверенные локальные агенты программирования. Они работают с теми же широкими неинтерактивными правами доступа к файловой системе, которые CodeAlmanac исторически предоставлял, поэтому граница almanac/ — это инструкция и политика коммитов, а не песочница на уровне ОС. Запускайте команды жизненного цикла только в тех репозиториях, где вы принимаете эту модель доверия, и проверяйте результирующий Git diff, когда автоматические коммиты отключены.

ingest включает выбранные локальные материалы в вики. В качестве входных данных могут выступать файлы, каталоги, Git diff-ы, диапазоны коммитов, GitHub PR или issues, URL-адреса и локальные транскрипты агентов.

garden улучшает существующий граф вики: устаревшие страницы, ссылки, темы, слабые связи, дублирующиеся страницы и неподтверждённые утверждения.

Холостой ход допустим. Если материал не добавляет долговременных знаний в вики, агент должен оставить её без изменений.

init, ingest и garden создают задания в очереди и запускают локальный worker. Чтобы следить за ними визуально, выполните codealmanac serve и выберите Jobs на боковой панели. Чтобы оставаться в терминале, используйте codealmanac jobs attach <run-id>.

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

Sync сканирует локальные хранилища транскриптов Codex и Claude на предмет разговоров, активных с момента предыдущей завершённой синхронизации. Разговоры, связанные с зарегистрированными репозиториями, ставятся в очередь как обычные задания ingest. Sync может решить, что разговор не содержит долговременных знаний, и оставить вики без изменений.

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

Update поддерживает локально установленный CodeAlmanac CLI в актуальном состоянии. Запланированные обновления пропускаются, когда обновление было бы небезопасным — например, пока активна работа жизненного цикла.

Автоматизация реализована через локальные задания macOS launchd, а не через размещённый сервис или облачную синхронизацию. Логи хранятся в ~/.codealmanac/logs/.

config set обновляет пользовательский TOML и сразу же применяет изменения к launchd. Если вы редактируете TOML напрямую, после этого выполните codealmanac config apply.

Автоматизация создаёт отдельные фоновые запуски. Инспектировать эти запуски можно отдельно с помощью codealmanac jobs.

Запуски жизненного цикла записываются в ~/.codealmanac/. Для их просмотра и управления используйте следующие команды:

show — это сводка по заданию; logs — снимок истории событий; attach продолжает следить и выводит события по мере их поступления. Все эти команды читают одну и ту же долговременную локальную запись задания, поэтому они работают даже после закрытия терминала, из которого задание было запущено. Добавьте --json при использовании вывода этих команд в скриптах.

CodeAlmanac использует almanac-yoke как единственную границу провайдера. Codex работает через app-server; Claude использует стандартную поверхность Claude в Yoke (в настоящее время Python Agent SDK). Существующие OAuth-сессии Codex или Claude Code переиспользуются, а учётные данные API можно передать через Yoke при встраивании SDK.

Build, ingest и garden упакованы как коллекция агентов Yoke в src/codealmanac/agents/. Каждый агент использует нативный folder contract Yoke: agent.yaml описывает инструменты и разрешения, а instructions.md содержит постоянные инструкции агента. Запуск жизненного цикла передаёт только типизированный контекст выполнения в качестве промпта задачи. При необходимости к агенту можно добавить опциональные папки Yoke skills/, subagents/ и workflows/; нативное выполнение Claude или Codex само решает, как и когда их использовать.

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

При использовании корня по умолчанию:

Markdown-страницы хранятся непосредственно в almanac/ в содержательных папках. topics.yaml организует страницы по папкам. Файлы README.md служат лендинг-страницами для своих маршрутов папок.

Для автоопределения репозиторий считается вики CodeAlmanac, когда существуют almanac/topics.yaml и almanac/README.md.

Производное локальное состояние хранится в ~/.codealmanac/:

Локальная база данных хранит репозитории, запуски, события запусков, блокировки worker-ов и состояние синхронизации. Файлы выполнения для каждого репозитория содержат производные индексы. Они не должны попадать в зафиксированное дерево almanac/.

Пользовательский конфиг находится по адресу:

Поддерживаемые значения по умолчанию:

Флаги CLI имеют приоритет над конфигом.

Для обычных изменений используйте codealmanac config set <key> <value>. Это немедленно применяет изменения автоматизации к launchd. Прямое редактирование файла поддерживается, но после него необходимо выполнить:

auto_commit означает, что промпты жизненного цикла могут давать выбранному агенту указание использовать обычные Git-команды для изменений в исходниках вики. CodeAlmanac не стейджит файлы, не разделяет диффы и не коммитит самостоятельно.

Просмотрщик работает только на чтение. Он отображает страницы, поиск, темы, обратные ссылки (backlinks) и навигацию по файловым ссылкам на основе локальных данных вики. serve открывает его в браузере по умолчанию, как только сервер готов; используйте codealmanac serve --no-open для headless-режима или скриптов. По умолчанию просмотрщик позволяет переключаться между доступными зарегистрированными локальными вики. Используйте codealmanac serve --wiki <name>, чтобы ограничить его одной вики.

Устаревший npm-пакет codealmanac выведен из эксплуатации. PyPI — единственный поддерживаемый дистрибутив. Если вы использовали npm CLI, на вашей машине может остаться старая глобальная установка вместе с хуками и инструкциями для агентов, которые она настроила. Удалите их перед установкой из PyPI.

Удалите старый глобальный пакет и все хуки CodeAlmanac или секции инструкций для агентов, которые он установил, затем установите и настройте Python CLI:

Также удалите старые установки через bun, pnpm или yarn и все устаревшие бинарники из PATH. Оставьте локальные деревья almanac/ в репозиториях нетронутыми — это зафиксированное содержимое вики, не часть установки CLI.

Эта версия пока работает только локально.

Это поверхность продукта Python/PyPI. Интеграция с размещённым сервисом может быть добавлена позже поверх того же артефакта вики, принадлежащего репозиторию, но она не входит в текущую поверхность выпуска.