Персональный provisioning машины из одного git-репозитория. start хранит
желаемое состояние окружения и раскладывает его по установленным инструментам.
Проект управляет тремя областями:
- AI — общие инструкции, agents, skills, plugins, MCP, hooks и statusline для Claude Code и OpenAI Codex;
- Files — dotfiles и профили приложений в
$HOME; - Commands — локальные служебные и provisioning-скрипты, запускаемые вручную из TUI.
Версионный config.toml описывает весь каталог. Машино-локальные
переключатели хранятся в gitignored config.local.toml.
AI-компонент регистрируется один раз в [ai]. Claude и Codex получают свои
представления из одного source: нативный формат сохраняется, а совместимая копия
строится только при необходимости. Поэтому agents, skills и plugins не нужно
поддерживать отдельно для каждого клиента.
make up синхронизирует только установленные клиенты, раскладывает dotfiles и не
перезаписывает чужие файлы без --force. Generated-файлы и runtime-состояние не
коммитятся.
git clone <repo-url> ~/start
cd ~/start
make upНужен Python 3.11+. uv используется при наличии; иначе scripts/run.sh
создаёт локальный .venv.
start без аргументов открывает TUI. Для перехода к нужной вкладке используйте
start tab:skills, start tab:agents, start tab:plugins, start tab:mcp, start tab:status,
start tab:ai, start tab:files или start tab:commands. Промежуточные manage / m убраны.
| Команда | Назначение |
|---|---|
make up |
синхронизировать AI и Files |
make ai |
синхронизировать Claude и Codex |
make ai:claude |
синхронизировать только Claude |
make ai:codex |
синхронизировать только Codex |
make files |
разложить только dotfiles |
make manage |
открыть TUI для AI, Files и Commands |
Флаги передаются после --:
make up -- --dry-run
make ai:codex -- --forceПолный интерфейс доступен через uv run start --help.
Общий каталог включает:
- глобальные инструкции и инженерные правила;
- переиспользуемых agents с platform-specific адаптацией;
- глобальные skills из
ai/skillsи project-local skills из.agents/skills; - plugins из pinned git submodules в
contrib/; - MCP-серверы, hooks и statusline.
По умолчанию компонент поддерживает обе платформы. Для platform-specific source
используется platforms = ["claude"] или platforms = ["codex"].
Зависимости скиллов задаются в [[ai.skills.requirements]]: check проверяет
наличие, hint объясняет ручную установку, необязательный install выполняет
установку при неуспешной проверке. После установки check запускается повторно;
ошибка установки учитывается в результате up. Без install остаётся только
предупреждение. --dry-run выполняет проверки, но не установку; команды check
должны быть без побочных эффектов. Проверяются включённые скиллы выбранной платформы.
Для Impeccable up заранее устанавливает движок через штатный загрузчик с
проверкой checksum в ~/.impeccable/bin/<версия> (или IMPECCABLE_HOME). Это
требует сети и записи в кэш при первой установке или смене версии движка;
UI-сессия затем использует готовый бинарник. При недоступном кэше повторите
start up --only ai:codex в обычном терминале с нужными правами.
При make up ссылки skills в frontmatter агентов проверяются по каталогу целевой
платформы. Для навыка плагина можно указать plugin:skill; короткое имя должно быть
однозначным. Недоступные и неоднозначные ссылки выводятся как предупреждения:
установка роли продолжается. Эта проверка не означает автоматическую загрузку
навыка в Codex — обязательное чтение следует задавать в инструкциях агента.
Новый plugin или skills-репозиторий добавляется одной командой:
uv run start add-submodule <git-url>Команда добавляет сабмодуль в contrib/, определяет тип source и регистрирует
его в общем AI-каталоге.
Запустите start up из рабочего проекта: после глобального provisioning start
применит его start.toml. Поиск идёт от исходной папки вызова до корня Git
включительно; используется только ближайший файл, родительские start.toml не
объединяются. Вне Git проверяется только текущая папка. Настройки устанавливаются
в каталог найденного файла. Без start.toml поведение остаётся прежним.
Например, Grafana может быть объявлена с enabled = false и токеном в личном
config.local.toml репозитория start, а включена только в нужном проекте:
# <проект>/start.toml
[[ai.mcp]]
name = "grafana"
enabled = trueMCP сопоставляются по name: существующая запись наследуется, новая требует
определения server. Можно переопределить часть параметров или добавить сервер:
[[ai.mcp]]
name = "grafana"
enabled = true
[ai.mcp.server.env]
GRAFANA_URL = "https://grafana.example.org"
[[ai.mcp]]
name = "project-api"
[ai.mcp.server]
url = "http://127.0.0.1:8080/mcp"Таблицы объединяются рекурсивно, массивы заменяются целиком. Неуказанные поля
наследуются. Секреты храните в личном глобальном каталоге; не добавляйте их в
отслеживаемый start.toml.
В любом значении ai.mcp.server можно сослаться на UTF-8-файл вместо хранения
секрета в TOML:
[ai.mcp.server.env]
GRAFANA_SERVICE_ACCOUNT_TOKEN = { "$file" = "~/.config/start/secrets/grafana-token" }Ссылка работает и в глобальном каталоге. ~ обозначает домашний каталог,
относительные пути считаются от файла, объявившего ссылку. При чтении удаляются
только завершающие переводы строк. Для включённого MCP отсутствие, недоступность
или пустое содержимое файла останавливает provisioning до записи настроек, в том
числе при --dry-run. Выключенные MCP не требуют наличия секрета.
Храните файл вне Git с правами 0600; сгенерированные локальные runtime-конфиги
содержат прочитанное значение. $file не выполняет выражения или shell-команды.
Источники skills, agents, plugins и hooks сопоставляются по path. Путь,
совпадающий с ключом глобального источника, переопределяет этот источник; путь
нового источника разрешается относительно start.toml. Унаследованный источник
сохраняет глобальный путь. Для новой одноимённой локальной папки используйте
явный ./path вместо глобального ключа path.
[[ai.skills]]
path = "./team-skills"
enabled = ["*"]
[[ai.agents]]
path = "./team-agents"
enabled = ["reviewer"]
[[ai.plugins]]
path = "./team-plugin"
enabled = true
[[ai.hooks]]
path = "./hooks/session.sh"
events = ["SessionStart"]
# Переключить уже объявленные источники без повторного объявления.
[local.ai.skills]
"./team-skills" = ["review"]
[local.ai.plugins]
"./team-plugin" = false[local.ai.*] применяется последним и требует существующего источника. Для skills
и agents задаётся список имён, для MCP, plugins и hooks — true/false.
platforms = ["codex"] или ["claude"] ограничивает компонент одной платформой.
Нативные параметры задаются отдельно:
[ai.platforms.codex.config]
model_reasoning_effort = "high"
[ai.platforms.claude.settings]
permissions.defaultMode = "default"Пересечение нативных параметров с полями, создаваемыми общим каталогом, считается
ошибкой. Проектный слой не меняет Files, команды менеджера, глобальный statusline,
AGENTS.md и CLAUDE.md. start up --only ai:codex применяет обе фазы только для
Codex; --only files пропускает проектный AI-слой. --dry-run показывает изменения
без установки.
Codex получает .codex/config.toml, Claude — .claude/settings.local.json и
проектную запись MCP в ~/.claude.json. Skills, agents, hooks и плагины размещаются
в нативных проектных каталогах. Созданные локальные файлы исключаются через Git
exclude; отслеживаемый файл назначения вызывает ошибку. Sidecar хранит владение
ключами и файлами: удаление записи из start.toml снимает соответствующее
управление, сохраняя чужие настройки.
Настройки Codex требуют штатного доверия к проекту; start не выдаёт его сам.
Нативное наследование вручную созданных конфигов агентов продолжает действовать.
Ограничения платформ не обходятся изменением глобальной установки: например,
отключение глобального агента или глобального skill Claude только для проекта
завершается явной ошибкой.
Проект наследует проверки зависимостей requirements глобальных источников.
Новые или изменённые shell-команды requirements в start.toml отклоняются:
зависимости локальных источников установите отдельно.
«Сессии Codex» объединяет дерево процессов и экспорт диалогов. По умолчанию видны
активные сессии; фильтр «Все» добавляет завершённые из локальной истории и архива.
Enter открывает дерево активной сессии или транскрипт завершённой.
e запрашивает полный путь Markdown-файла, r у завершённой
сессии открывает resume в новом окне терминала из сохранённого cwd. Экспорт не
перезаписывает существующие файлы. Сортировка и фильтр по cwd доступны в списке.
Resume использует Terminal на macOS и GNOME Terminal на Linux. Если у активного
процесса ещё нет доступного файла истории, дерево доступно, а экспорт объяснит,
почему диалог пока нельзя сохранить.
Интерактивные таблицы в разделе Commands поддерживают обновление и фильтры внутри
менеджера. Новая задача подключается через async provider и commands.tasks.view;
изменять UI менеджера не требуется. Локальный skill
start-add-interactive-task
содержит контракт SDK и пример добавления задачи для агента и разработчика.
[[files.dotfiles]] связывает файлы и каталоги из dotfiles/ с $HOME либо
вызывает идемпотентный posthook для приложений с собственным механизмом
хранения настроек.
[[commands.tasks]] описывает разовые команды по операционным системам. Они не
выполняются во время make up: запуск происходит только вручную через
make manage. Здесь живут обслуживание машины, локальный Ansible provisioning,
PXE и диагностические scripts.
Machine-only MCP и их секреты объявляются через [[ai.mcp]] в gitignored
config.local.toml.
ai/ инструкции, agents, skills, hooks и statusline
.agents/ project-local skills для этого репозитория
dotfiles/ файлы и профили для пользовательского окружения
scripts/ launcher, provisioning и служебные scripts
contrib/ pinned внешние plugins и skills
cli/ менеджер, platform adapters и TUI
uv run python -m unittest discover -s tests -v
uv run start completion --check
make ai -- --dry-run