Флаг Codex CLI —add-dir: как предоставить доступ к дополнительным каталогам

Флаг Codex CLI --add-dir применяется для добавления дополнительного каталога, к которому агент получает доступ во время работы. Это особенно полезно, когда проект состоит не из одной папки: исходный код находится в одном месте, общие библиотеки — в другом, документация — в третьем, а тестовые данные и конфигурация лежат за пределами текущего рабочего каталога.

--add-dir расширяет рабочую область Codex CLI, но не превращает весь компьютер в свободно доступное хранилище. Добавляйте только те каталоги, которые действительно нужны конкретной задаче.

На практике этот флаг помогает решить типичную проблему: Codex запущен из директории проекта, однако для анализа или изменения файлов ему требуется обратиться к соседнему репозиторию, общей папке с пакетами или заранее подготовленным данным. Ниже разберём, как работает --add-dir, чем он отличается от смены рабочей директории, в каких сценариях его применять и почему чрезмерное расширение доступа может привести к путанице или нежелательным изменениям.

Как использовать --add-dir

Флаг указывается в командной строке при запуске Codex CLI и принимает путь к дополнительной директории. В простейшем случае команда выглядит так: codex --add-dir ../shared. После запуска Codex рассматривает указанную папку как доступную дополнительную область, сохраняя при этом исходный рабочий каталог проекта.

Главное различие между рабочим каталогом и добавленной директорией состоит в роли: рабочий каталог задаёт основной контекст сессии, а --add-dir расширяет этот контекст дополнительным путём.

Путь можно указывать как относительный, так и абсолютный. Относительный путь вычисляется относительно текущей директории, из которой запускается команда, поэтому перед использованием полезно проверить положение в файловой системе с помощью pwd в Unix-подобных системах или Get-Location в PowerShell.

Вариант пути	Пример	Когда удобен	На что обратить внимание
Относительный	../shared	Для связанных папок внутри одного рабочего пространства	Зависит от текущей директории запуска
Абсолютный Unix-путь	/home/user/libs	Для стабильных локальных сценариев	Путь привязан к конкретной машине
Абсолютный путь macOS	/Users/alex/projects/docs	Для локальных проектов пользователя	На другом компьютере обычно потребуется изменить путь
Путь Windows	C:workshared	Для запуска из PowerShell или Windows Terminal	Нужно учитывать правила оболочки и обратные слеши

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

codex --add-dir ../shared --add-dir ../docs "Сравни API проекта с документацией и предложи обновления"

Такой подход делает намерение понятным: Codex получает доступ именно к общей библиотеке и документации, а не ко всему домашнему каталогу пользователя. В командных скриптах это также облегчает аудит: по строке запуска видно, какие внешние области нужны задаче.

Задача	Подход	Преимущество	Риск менее удачного варианта
Читать одну общую библиотеку	Добавить конкретную папку библиотеки	Минимальный и понятный доступ	Добавление всего родительского каталога откроет лишние проекты
Сопоставить код и документацию	Указать две директории через два флага	Контекст разделён явно	Сложнее понять структуру, если все данные смешаны в одной большой папке
Работать с монорепозиторием	Добавить нужный внешний пакет или соседний модуль	Не требуется переносить файлы	Можно случайно изменить зависимый модуль

Когда применять --add-dir

Флаг особенно полезен в проектах, где физическая структура файлов не совпадает с логической. Например, приложение находится в ~/projects/shop, общий пакет — в ~/projects/common, а документация команды — в ~/team-docs. Запуск из каталога приложения даёт Codex основной контекст, а дополнительные пути позволяют не копировать материалы и не менять структуру репозиториев.

Лучший повод использовать --add-dir — реальная зависимость задачи от внешней папки, а не желание «на всякий случай» открыть агенту побольше файлов.

Есть несколько распространённых сценариев, в которых этот флаг заметно экономит время:

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

Ситуация	Основной каталог	Дополнительный каталог	Зачем нужен доступ
Приложение использует локальную библиотеку	app	shared-lib	Изучить интерфейсы и совместимость
Нужно обновить документацию по коду	backend	docs	Сверить описание с фактическим поведением
Идёт перенос старой системы	new-service	legacy-service	Сравнить реализацию и сохранить важную логику
Тесты используют внешние фикстуры	api	test-fixtures	Проверить формат данных и сценарии тестирования

Работа с соседним репозиторием

Этот сценарий встречается в командах, где сервис и общая библиотека хранятся в разных репозиториях. Codex запускается внутри сервиса, а --add-dir даёт возможность изучить код библиотеки без объединения репозиториев.

cd ~/projects/orders
codex --add-dir ../common-lib "Проверь, совместим ли клиент orders с последним интерфейсом common-lib"

Полезно заранее уточнить, что требуется от агента: только анализ, предложение изменений или конкретное редактирование. Если внешняя папка содержит несколько независимых компонентов, лучше добавить более узкий путь, например ../common-lib/src/client, а не весь репозиторий.

Сопоставление кода с документацией

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

codex --add-dir ../team-docs "Найди расхождения между API проекта и документацией, не изменяя файлы"

Фраза «не изменяя файлы» полезна, когда задача носит исследовательский характер. Она не заменяет настройки подтверждений и политики безопасности, но явно сообщает намерение на уровне запроса.

Работа с локальным пакетом

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

cd ~/projects/dashboard
codex --add-dir ../ui-kit "Проверь, почему компонент Button не принимает новый параметр size"

Здесь важно различать чтение и изменение. Если библиотека используется несколькими проектами, перед разрешением правок стоит проверить состояние Git и создать отдельную ветку. Иначе исправление, полезное для одного приложения, может неожиданно повлиять на другие.

Сравнение старой и новой реализации

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

cd ~/projects/new-billing
codex --add-dir ../legacy-billing "Сравни расчёт комиссий в старой и новой реализации и перечисли отличия"

Для такого анализа полезно заранее определить границы: какие файлы сравнивать, какие версии считать эталонными и должен ли Codex предлагать перенос логики. Иначе запрос может превратиться в слишком широкий обзор двух больших систем.

Анализ внешних тестовых данных

Фикстуры, эталонные ответы и обезличенные наборы данных нередко находятся вне исходного репозитория по причинам безопасности или большого размера. Добавление отдельного каталога помогает проверить, как приложение обрабатывает реальные сценарии.

codex --add-dir ../fixtures "Проверь, какие тестовые сценарии покрывают ответы из каталога fixtures"

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

Тип внешних данных	Допустимость	Рекомендация
Обезличенные JSON-фикстуры	Обычно допустимо	Проверить отсутствие токенов и персональных данных
Логи с идентификаторами пользователей	Требует осторожности	Предварительно удалить или замаскировать чувствительные поля
Файл с секретами окружения	Не следует добавлять	Использовать безопасные заглушки и шаблоны конфигурации
Публичная документация	Обычно безопасно	Ограничить путь конкретным набором документов

Примеры использования

Одно дело — знать синтаксис, и совсем другое — понимать, как флаг ведёт себя в повседневной работе. В этом разделе собраны практические команды для анализа, разработки, рефакторинга и проверки связанных файлов.

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

Пример 1. Добавление одной соседней папки

Если рядом с текущим проектом находится каталог с общими типами, его можно подключить относительным путём.

cd ~/projects/web-app
codex --add-dir ../shared-types "Проверь соответствие импортов типам из shared-types"

Элемент команды	Назначение
cd ~/projects/web-app	Устанавливает основной рабочий каталог
--add-dir ../shared-types	Добавляет соседнюю папку с типами
Текст запроса	Определяет, какую проверку нужно выполнить

Пример 2. Несколько дополнительных директорий

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

codex --add-dir ../shared-lib --add-dir ../architecture-docs "Сопоставь публичные методы библиотеки с архитектурными ограничениями"

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

Пример 3. Абсолютный путь

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

codex --add-dir /Users/alex/work/company-docs "Найди в документации описание процесса авторизации"

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

Пример 4. Только анализ без изменения файлов

Если требуется получить отчёт о различиях, задачу лучше сформулировать явно и не просить редактирование.

codex --add-dir ../old-api "Составь список несовместимых изменений между old-api и текущим сервисом; файлы не изменяй"

Такой запрос полезен перед миграцией, обновлением зависимости или подготовкой технического задания.

Пример 5. Поиск источника ошибки

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

codex --add-dir ../payment-client "Разбери путь запроса оплаты и найди возможную причину ошибки timeout"

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

Пример 6. Подготовка изменений в общей библиотеке

Если задача действительно предполагает правки во внешнем модуле, это стоит сказать напрямую и ограничить область изменений.

codex --add-dir ../common-parser "Исправь обработку пустого заголовка только в common-parser/src/headers и покажи diff"

После такой работы изменения необходимо проверить отдельно в каждом потребителе библиотеки. Общий код — это место, где маленькая правка иногда отправляется в путешествие по нескольким проектам.

Пример 7. Сравнение конфигураций

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

codex --add-dir ../deployment-config "Сравни переменные окружения приложения с шаблонами deployment-config и укажи отсутствующие ключи"

Не добавляйте каталог с настоящими секретами. Для анализа достаточно шаблонов, примеров и файлов с именами переменных без значений.

Пример 8. Анализ документации перед релизом

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

codex --add-dir ../docs "Проверь, описаны ли в документации все новые параметры CLI и подготовь список недостающих разделов"

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

Пример 9. Работа из скрипта

Флаг можно включать в локальный скрипт, который запускается из корня рабочего пространства.

#!/usr/bin/env bash
set -e
cd "$(dirname "$0")/app"
codex --add-dir ../shared --add-dir ../docs "Проверь изменения API перед ревью"

В автоматизации особенно важны проверка существования каталогов и понятные сообщения об ошибках. Если папка была перемещена, скрипт не должен молча работать с неправильным контекстом.

Пример 10. Windows PowerShell

В PowerShell путь можно передать в кавычках, особенно если в нём есть пробелы.

Set-Location "C:WorkCustomer Portal"
codex --add-dir "C:WorkShared Contracts" "Проверь совместимость моделей клиента с общими контрактами"

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

Операционная система	Что проверить перед запуском	Частая проблема
Linux	Результат pwd и права доступа	Относительный путь рассчитан не от той папки
macOS	Точное расположение каталогов в домашней директории	Путь скопирован с другой машины
Windows PowerShell	Кавычки вокруг путей с пробелами	Путь разбился на несколько аргументов
CI-окружение	Существование каталога внутри runner	Локальный путь недоступен в автоматической среде

Чем --add-dir отличается от других команд

В командной строке рядом с --add-dir часто используют параметры, связанные с рабочей директорией, режимом подтверждений и запуском команд. Они могут выглядеть похожими, но решают разные задачи. Ошибка в выборе флага приводит либо к отсутствию нужного контекста, либо к запуску агента не там, где ожидалось.

Не путайте «где работает Codex» с «какие дополнительные каталоги ему доступны». Это разные настройки, даже если в обоих случаях речь идёт о путях.

--add-dir и --cd или -C

Параметр --cd, также встречающийся в короткой форме -C, обычно используется для выбора основного рабочего каталога. --add-dir не переносит сессию в другой проект, а добавляет дополнительную область.

Параметр	Что меняет	Типичный сценарий
--cd	Основную директорию работы	Запустить Codex из корня нужного проекта
-C	То же, в сокращённой форме	Использовать в коротких командах или скриптах
--add-dir	Дополнительную доступную директорию	Подключить общую библиотеку или внешнюю документацию

codex --cd ~/projects/app --add-dir ~/projects/shared "Изучи приложение с учётом общей библиотеки"

--add-dir и обычный cd

Команда оболочки cd меняет текущую директорию самого терминала. Она не добавляет второй каталог к рабочему пространству. После обычного cd Codex стартует в новой папке, но не получает автоматически доступ к соседним каталогам как к дополнительному контексту.

cd ~/projects/app
codex --add-dir ../shared "Проверь интеграцию с общей библиотекой"

Здесь cd выбирает проект, а --add-dir подключает соседний ресурс. Удаление любого из элементов изменит смысл команды.

--add-dir и --full-auto

Флаг --full-auto связан с режимом автоматизации и подтверждений, а не с перечнем доступных каталогов. Он не добавляет файлы и не расширяет рабочую область. Использование этих параметров одновременно означает: «работать в автоматизированном режиме с основным проектом и указанными дополнительными директориями».

codex --add-dir ../shared --full-auto "Запусти проверку и исправь очевидные ошибки в интеграции"

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

--add-dir и --sandbox

Параметр --sandbox относится к ограничениям среды выполнения и не является альтернативой указанию каталога. Если задача зависит от внешней папки, её всё равно может потребоваться явно добавить через --add-dir, а затем выбрать подходящий режим изоляции.

codex --sandbox workspace-write --add-dir ../shared "Проанализируй общий модуль и подготовь безопасные изменения"

Точные доступные значения и поведение режимов могут зависеть от версии Codex CLI. Перед использованием в важной автоматизации проверяйте справку установленной версии командой codex --help.

Инструмент или параметр	Отвечает за	Не отвечает за
cd	Текущую директорию оболочки	Дополнительный доступ к соседним папкам
--cd / -C	Основной каталог сессии	Автоматическое подключение всех связанных репозиториев
--add-dir	Дополнительные каталоги	Смену основного проекта
--sandbox	Ограничения выполнения	Описание содержимого рабочего пространства
--full-auto	Степень автоматизации	Добавление файловых путей

Типичные ошибки

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

Перед тем как искать сложную причину, проверьте три простые вещи: текущую директорию, существование добавляемого пути и точное написание аргумента.

Ошибка 1. Неправильный относительный путь

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

pwd
ls ../shared
codex --add-dir ../shared "Проверь общие типы"

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

Ошибка 2. Путь содержит пробелы

Без кавычек оболочка может воспринять части пути как отдельные аргументы. Особенно часто это случается в Windows, но аналогичная проблема возможна и в Unix-подобных системах.

codex --add-dir "C:WorkShared Contracts" "Проверь общие модели"

В Bash похожая команда также должна использовать кавычки или экранирование пробелов. Если путь формируется автоматически, безопаснее передавать его как отдельный аргумент средствами используемого языка или скрипта.

Ошибка 3. Добавлен слишком широкий каталог

Иногда пользователь указывает --add-dir ~ или весь каталог с рабочими проектами, хотя ему нужна одна небольшая папка. Это затрудняет понимание контекста и увеличивает вероятность случайного обращения к нерелевантным или чувствительным файлам.

codex --add-dir ~/projects "Изучи только проект reports"

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

codex --add-dir ~/projects/reports "Изучи проект reports"

Чем уже область, тем легче объяснить результат, проверить изменения и повторить запуск на другой машине.

Ошибка 4. Ожидание, что флаг меняет основной проект

Добавление каталога не означает переход в него. Если нужно запускать работу именно из другого проекта, используйте --cd или предварительный cd, а внешний ресурс подключайте отдельно.

codex --cd ~/projects/service --add-dir ~/projects/contracts "Проверь сервис с учётом контрактов"

В этом примере сервис остаётся главным проектом, а контракты выступают дополнительным источником файлов.

Ошибка 5. Добавление каталога с секретами

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

codex --add-dir ../config "Проверь настройки приложения"

Если в ../config лежат реальные секреты, безопаснее подготовить отдельную папку с шаблонами:

codex --add-dir ../config-example "Проверь имена и обязательность переменных окружения"

Симптом	Вероятная причина	Что сделать
Каталог не найден	Неверный относительный путь	Проверить pwd и содержимое родительской папки
Путь разбивается на части	В имени есть пробелы	Заключить путь в кавычки
Codex работает не с тем проектом	Перепутаны cd и --add-dir	Явно задать основной каталог через --cd
В контексте слишком много файлов	Добавлен широкий родительский каталог	Указать более узкую директорию
Внешние изменения затронули общий код	Задача не ограничивала область правок	Указать конкретные файлы и проверить diff

Краткая памятка

--add-dir — это инструмент для расширения рабочей области Codex CLI дополнительными каталогами. Он особенно полезен в многочастных проектах, при работе с общими библиотеками, отдельной документацией, внешними фикстурами и связанными репозиториями.

Добавляйте не «всё, что может пригодиться», а минимальный набор каталогов, необходимый для конкретной задачи.

Вопрос	Короткий ответ
Что делает --add-dir?	Добавляет указанную директорию в доступную рабочую область
Можно ли указать несколько каталогов?	Да, флаг можно использовать несколько раз
Можно ли использовать относительный путь?	Да, он считается от текущей директории запуска
Меняет ли флаг основной рабочий каталог?	Нет, для этого используют cd, --cd или -C
Стоит ли добавлять домашний каталог?	Нет, если задача не требует такого широкого доступа
Что проверить перед запуском?	Путь, права доступа, отсутствие секретов и границы задачи
Как проверить доступные параметры версии?	Запустить codex --help

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

codex --cd ПУТЬ_К_ПРОЕКТУ --add-dir ПУТЬ_К_ДОПОЛНИТЕЛЬНОЙ_ПАПКЕ "Чётко сформулированная задача"

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