У меня MacBook Air M4, ПК под Ubuntu 24.04, консальные Claude Code и Codex (каждый хорош немного под свои задачи, как по мне). Я люблю Ubuntu, но вот в поездках Mac прям незаменим — с ним удобно работать, батарея живет достаточно долго, даже в самолете можно комфортно что-то тыкать тачпадом. При этом яблочную экосистему я не люблю, Ubuntu мне ближе и приятнее в использовании. Важный момент: я не программист, так что большая часть моих проектов — это всякая маркетинговая, менеджерская и редакторская штукенция. Поэтому у меня нет под это всё каких-то IDE и т.п. Конечно, разработчики и другие инженеры обычно работают с кодом, а потому просто коммият всё напрямую в гитхаб.
Но к делу. У меня постоянно запущено по 6-10 окон Claude и Codex в терминале и я заколебался проекты синхронизировать через Избранное телеграма — зипами. Плюс хочется, чтобы проекты нормально работали и в той, и в другой нейронке. То есть мне понадобилась какая-то система синхнонизации проектов между разными устройствами и разными нейронками.
Сегодня наконец собрался с силами и доделал такую — выложил ее под Apache 2.0 на гитхабе, можно пользоваться, форкать, дорабатывать и выражать своё «фи» в ишшьюсах и комментариях. Наверянка уже кто-то что-то такое себе делал и я просто изобретаю велосипед. Но что ж теперь поделать, я его уже переизобрел.
В статье расскажу, как делал, что делал, где и что пришлось дотюнивать. Скажу честно, мне эту часть с инструкцией писать было лень и она написана уже GPT, так что простите. Немного пробегусь по стилистике, конечно, но в целом текст править почти не буду.
AI Workspace System: единое рабочее место для Codex и Claude Code
У меня постепенно накопилась типичная проблема человека, который много работает с AI-агентами локально. Есть проекты Codex, проекты Claude Code, обычные репозитории, черновики, пайплайны, инструкции, скиллы, локальные артефакты и несколько машин. В какой-то момент становится непонятно, где актуальная версия проекта, какие файлы можно пушить, где живут инструкции для агента, а где уже опасная смесь из исходников, логов и промежуточных результатов.
Так появился AI Workspace System: набор shell-скриптов, соглашений и Markdown-документации, который приводит локальную работу с AI-агентами к одному предсказуемому формату. Это не IDE и не оркестратор агентов, а тонкий слой инфраструктуры вокруг Git, GitHub, Codex и Claude Code.
Главная идея простая: все проекты должны быть видны из одного интерактивного списка, инструкции должны быть устроены одинаково, синхронизация должна быть безопасной по умолчанию, а все машинно-специфичные детали не должны попадать в репозиторий.
Что умеет проект
Проект решает несколько практических задач. Во-первых, он дает общий launcher для Codex и Claude Code. Команда ai-launch codex или ai-launch claude показывает интерактивный список проектов. Вверху всегда есть New project и No project: первый пункт создает новый репозиторий по шаблону, второй запускает агента без привязки к конкретному проекту.
Во-вторых, проект вводит единый формат инструкций. AGENTS.md считается каноническим файлом с общими правилами проекта. CLAUDE.md импортирует его через @AGENTS.md и содержит только то, что специфично для Claude Code.
В-третьих, есть консервативный workspace-sync. Он проходит по настроенным корням, делает fetch, подтягивает только чистые worktree, пушит только уже закоммиченные изменения и пропускает грязные репозитории. В scheduled-режиме он никогда сам не коммитит. Это важно: агент может оставить проект в промежуточном состоянии, а автоматическая синхронизация не должна превращать это в опубликованный мусор.
В-четвертых, проект различает свои репозитории и внешние upstream-репозитории. Если origin принадлежит вашей GitHub-организации или аккаунту, синк может пушить туда. Если origin внешний, например это сайт, vendor repo или upstream проекта, scheduled sync пушит только в отдельный remote backup. Пуш в настоящий upstream должен быть явным действием. Для чего это нужно? Например, я работаю с сайтом cozystack.io, который хранится в репозитории cozystack/website, но у меня написан ряд нейроинструкций для работы с контентом этого сайта: по каким правилам структурировать анонс новой версии платформы, по каким правилам делать какие-то врезки и фактоиды, как располагать картинки, какие блоки ссылок давать в конце и т.п. Для другого сайта я собрал пайплайн, который из видеоподкаста делает статью: скачивает, прогоняет через whisper, проводит 3 этапа редактуры, выдирает из видео скриншоты, обращается в сервис ahrefs для сбора SEO и GEO-семантики и анализа статей-конкурентов, добавляет изображения в нужные места материала, дробит его на разделы с заголовками, собирает фактоиды, врезки и цитаты, добавляет всю дополнительную метаинформацию, а также составляет внутритекстовые инструкции для агента, который уже непосредственно верстает статью. Всему этому в репозиториях сайтов пока не место (хотя со временем наверняка всё это туда попадет).
В-пятых, есть заготовка для разделения target repo и delivery workbench. Target repo содержит проверенный код, сайт, публичные документы и PR-ветки. Workbench содержит промпты, исследования, черновики, исходные материалы, пайплайны и локальное состояние. Связь между ними описывается в workspace.yaml.
Как использовать
Минимальная установка выглядит так:
mkdir -p ~/projectsgit clone <ai-workspace-system-repo-url> ~/projects/ai-workspace-system~/projects/ai-workspace-system/bin/install-localworkspace-configure
install-local кладет symlink-и в ~/.local/bin, а workspace-configure интерактивно создает локальный конфиг:
~/.config/ai-workspace/config
В этот конфиг попадает все, что зависит от конкретной машины:
PROJECTS_HOME="$HOME/projects"PROJECT_ROOTS="$HOME/projects"SYNC_ROOTS="$HOME/projects"GITHUB_ORG=""BACKUP_REMOTE="backup"CODEX_BIN="$HOME/.local/bin/codex"CLAUDE_BIN="$HOME/.local/bin/claude"SECRET_SCAN_CMD=""
PROJECT_ROOTS отвечает за picker, SYNC_ROOTS — за автоматическую синхронизацию. Проект может быть виден агентам, но не участвовать в scheduled sync.
После настройки можно запускать:
ai-launch codexai-launch claude
При запуске в терминале агент не стартует сразу в случайной директории. Сначала появляется список: New project, No project, затем проекты из PROJECT_ROOTS. New project вызывает workspace-new-project: создается каталог в PROJECTS_HOME, базовые README.md, AGENTS.md, CLAUDE.md, workspace.yaml, .gitignore, .env.example, затем выполняются git init -b main и initial commit. No project нужен для разовых вопросов без проектного контекста.
Для плановой синхронизации используется user-level systemd timer. В проекте он настроен на 13:00, 19:00 и 23:50:
systemctl --user daemon-reloadsystemctl --user enable --now ai-workspace-sync.timer
Перед включением таймера полезно выполнить:
workspace-sync --dry-run
Так видно, какие репозитории будут обнаружены и какие действия будут выполнены.
Промпт для сбора локальных проектов
Отдельная часть системы — prompt prompts/discover-and-normalize-local-projects.md. Его можно дать Codex или Claude Code на машине, где проекты уже разбросаны по домашней директории. Он просит агента сначала провести инвентаризацию, классифицировать каталоги, создать ~/projects, предложить move plan, а затем после подтверждения перенести безопасные проекты, добавить README.md, AGENTS.md, CLAUDE.md, .gitignore, workspace.yaml и инициализировать Git там, где это настоящий проект, а не архив, cache или runtime state.
Короткая версия:
Find likely local projects, classify them, move approved ones into ~/projects,add baseline AI/project docs, and initialize Git repos where appropriate.Do not move secrets, agent sessions, logs, caches, auth files, or shell history.Preserve existing remotes. Ask before committing dirty repos or changing upstream policy.
Глобальные инструкции агентов
Глобальные агентские файлы не затираются. ~/.codex/AGENTS.md, ~/.claude/CLAUDE.md и ~/.claude/rules/ считаются машинными предпочтениями. Если файла нет, агент может предложить его создать. Если файл уже есть, он должен сохранить содержимое и предложить маленькое дополнение. Runtime state, auth, sessions, logs, sqlite и история shell не попадают в Git.
Какие команды есть
workspace-configure интерактивно пишет локальный конфиг. Это ключевая команда для open-source-версии проекта: GitHub organization, пути до бинарников, project roots и secret scanner больше не хранятся в репозитории.
ai-launch codex запускает Codex через project picker. Для Codex используется --cd, поэтому агент стартует сразу в нужной директории.
ai-launch claude запускает Claude Code через project picker. Для Claude Code скрипт сначала делает cd, затем запускает бинарник.
workspace-new-project <name> создает проект в PROJECTS_HOME, инициализирует Git и делает initial commit. Если GITHUB_ORG задан и gh авторизован, создается приватный GitHub-репозиторий. Важный момент — если вы уже синканулись с моим проектом, то при запуске новой сессии Codex или Claude он предложит вам создать проект, отказаться от создания проекта либо выбрать проект из списка ваших проектов.
workspace-sync выполняет обычную безопасную синхронизацию: fetch, fast-forward pull для чистых репозиториев и push закоммиченных изменений.
workspace-sync --scheduled используется таймером. В этом режиме нет auto-commit, нет force push и нет пуша во внешний origin.
workspace-sync --commit включает интерактивный режим: для грязных репозиториев скрипт спрашивает, нужно ли закоммитить изменения. Если задан SECRET_SCAN_CMD, перед коммитом запускается secret scan.
workspace-ensure-backup --push добавляет backup remote для внешних upstream-репозиториев. Имя mirror-репозитория строится по исходному origin, например mirror-source-owner-source-repo.
Ограничения
Проект сознательно не пытается быть полноценным backup-решением. GitHub sync не заменяет restic, borg или нормальный файловый backup. Незакоммиченные документы, большие артефакты, базы, дампы и сессии агентов должны жить отдельно.
Синхронизация работает только с Git-репозиториями. Если важный проект не инициализирован как Git repo, launcher может его показать, но sync не сохранит его состояние.
Scheduled sync не коммитит грязные worktree. Это ограничение иногда неудобно, но оно принципиальное. Автоматический коммит без понимания контекста слишком легко публикует секреты, временные файлы или полусобранную работу.
Система не угадывает политику для внешних репозиториев. Если origin указывает не на ваш GITHUB_ORG, проект считается внешним. По умолчанию его можно бэкапить в backup, но пушить в upstream нужно только после явной команды.
Еще одно ограничение: это shell-first система. Она прозрачная и легко чинится, но не дает красивого UI, истории операций и централизованной базы проектов.
Как мы (я, Claude и Codex) его тюнили и дорабатывали
Изначально система была личной. В документах и примерах была захардкожена конкретная GitHub-организация, в конфиге лежали конкретные root-и, а в workspace-sync был прямой вызов локального secret-audit-скрипта. Для open-source-проекта это плохо: новый пользователь должен передать свои значения при установке, а не вычищать чужие.
Первым шагом мы вынесли машинно-специфичное в workspace-configure. Теперь репозиторий содержит generic defaults, а реальная конфигурация живет в ~/.config/ai-workspace/config.
Вторым шагом мы изменили место хранения логов. Раньше sync-лог мог оказаться внутри самого репозитория. В логах есть локальные пути, имена репозиториев, ветки и remotes. Теперь дефолтный каталог логов находится в ~/.local/state/ai-workspace/logs, а logs/ добавлен в .gitignore.
Третьим шагом мы сделали workspace-new-project независимым от жесткого ~/projects. Он использует PROJECTS_HOME, а если тот не задан, берет первый root из PROJECT_ROOTS. ai-launch теперь берет фактический путь из вывода workspace-new-project.
Четвертым шагом была чистка документации. README, bootstrap prompts, templates и playbook-и переведены на placeholders: <ai-workspace-system-repo-url>, <github-org-or-user>, <projects-home>. Это делает проект пригодным для публикации: в репозитории остаются правила и механика, но не остается личной инфраструктуры автора.
Что не работало и как это исправляли
Первый сбой был концептуальный: система одновременно хотела быть рабочим инструментом и переносимым шаблоном. Hardcoded GitHub organization и локальные пути делали ее удобной на одной машине, но ломали переиспользование. Исправление: setup через workspace-configure и пустой GITHUB_ORG в config.example.
Второй сбой был с безопасностью публикации. Один из логов синхронизации попал в рабочее дерево проекта. Это не секрет в прямом смысле, но такие логи раскрывают структуру домашней директории. Исправление: логи вынесены в XDG state directory, а logs/ исключен из Git.
Третий сбой был в secret scanning. workspace-sync --commit вызывал локальный скрипт из приватной директории. На другой машине такого файла нет. Исправление: SECRET_SCAN_CMD стал опциональной настройкой.
Четвертый сбой был в Git hook. Глобальный prepare-commit-msg должен был автоматически добавлять Signed-off-by, но использовал echo -e под /bin/sh. На этой системе echo напечатал -e как обычный текст, и commit message получил лишнюю строку. Исправление простое и переносимое:
if [ -n "$SOB" ] && ! grep -qs "^$SOB" "$1"; then printf '\n%s\n' "$SOB" >> "$1"fi
printf в shell-скриптах предсказуемее, чем echo -e.
Пятый сбой был UX-овый: создание проекта через launcher предполагало один фиксированный root. После появления PROJECTS_HOME это стало неверным. Исправление: workspace-new-project печатает фактический путь нового проекта, а launcher использует именно его.
В итоге проект стал менее “моим” и более системным. Он по-прежнему решает ту же бытовую задачу: открыть Codex или Claude Code, выбрать проект, безопасно синхронизировать состояние и не потерять инструкции. Но теперь личные решения вынесены на уровень локального конфига, а сам репозиторий можно публиковать и переносить между машинами.
Репозиторий с проектом
Всё хранится вот тут, под Apache 2.0: https://github.com/tym83-ai/ai-workspace-system. Комментируйте, набрасывайте, предлагайте доработки.
ссылка на оригинал статьи https://habr.com/ru/articles/1041750/