Forge

От идеи до проверенного кода, не покидая терминал — Forge объединяет ИИ-агента, редактор кода и оболочку в одном сфокусированном рабочем процессе.

Forge — это опенсорсный ИИ-агент для написания кода, работающий в вашем терминале. Он запускает полноэкранный TUI в репозитории, над которым вы работаете, помогает просматривать и изменять файлы, выполняет команды с вашего одобрения и ведёт постоянный журнал сеансов, чтобы вы могли продолжить работу после перерыва.

Forge — это альфа-программное обеспечение. Внимательно проверяйте каждый запрос на одобрение и используйте его в первую очередь в одноразовом или резервируемом репозитории.

Зачем это существует

Claude Code — действующий лидер в области терминального ИИ-кодинга, но его опыт сосредоточен на агенте, которым вы управляете через подсказки, и внешнем редакторе, который вы используете параллельно. Forge предназначен для тех, кто хочет иметь агента, редактор кода, файловый менеджер, оболочку, одобрения, диффы и постоянные сеансы в одном рабочем пространстве, управляемом с клавиатуры, чтобы проверка кода, его изменение и проверка результата оставались в едином сфокусированном цикле.

Что умеет Forge

• Общается с настроенной моделью, оставаясь в терминале.
• Читает и редактирует файлы рабочего пространства, применяет точечные патчи, ищет код и работает с Git.
• Выполняет каждую команду оболочки внутри песочницы ОС, ограниченной вашим рабочим пространством, с исходящим сетевым трафиком, ограниченным списком разрешённых адресов.
• Сохраняет историю сеансов и незавершённую работу в локальном журнале SQLite.
• Поддерживает вход через провайдера и выбор модели из TUI.
• Подключает настроенные MCP-серверы и предоставляет их инструменты агенту.
• Показывает файлы, диффы, вывод команд, активность, диагностику и состояние задач в одном рабочем пространстве, управляемом с клавиатуры.

Установка

Установка готового релиза

На macOS или Linux:

curl --proto '=https' --tlsv1.2 -LsSf \
  https://raw.githubusercontent.com/NorviaLabs/forge/main/install/forge-installer.sh | sh

В Windows PowerShell:

irm https://raw.githubusercontent.com/NorviaLabs/forge/main/install/forge-installer.ps1 | iex

Установщики выбирают текущий релиз для вашей платформы и проверяют его контрольную сумму SHA-256 перед установкой. Чтобы установить конкретный релиз, задайте переменную FORGE_VERSION, например v0.1.0-beta.6.

На Linux установщик также устанавливает зависимости песочницы — bubblewrap и socat — если они ещё не установлены, запрашивая один раз sudo. Он поддерживает apt, dnf, yum, pacman, zypper и apk. Если это не удаётся, он сообщает об этом и продолжает: forge всё равно работает, но без песочницы он должен спрашивать разрешение перед каждой командой. Установите FORGE_SKIP_DEPS=1, чтобы управлять ими самостоятельно.

Для macOS ничего дополнительного не требуется; его песочница встроена в ОС.

Windows запускает forge под WSL2, где используется песочница Linux. Нативной сборки для Windows нет — установщик PowerShell обнаруживает WSL2 и указывает вам на установщик Linux внутри неё. Набор тестов песочницы выполняется против WSL2 в CI.

Сборка из исходников

Вам понадобятся Git и Rust 1.97.1 или новее.

git clone https://github.com/NorviaLabs/forge.git
cd forge
cargo build --release --locked --package forge-cli
./target/release/forge --version

Для запуска сборочной версии для разработки:

cargo run --locked --package forge-cli

Запуск Forge

Запустите Forge из репозитория, в котором вы хотите, чтобы агент работал:

forge

Рабочее пространство по умолчанию — текущий каталог. Forge также учитывает переменную окружения FORGE_WORKSPACE.

При первом запуске Forge проводит вас через настройку темы, доверия к каталогу и подключения провайдера. Сохранённая тема хранится в вашей пользовательской конфигурации; доверие хранится для каждого каталога (дочерние каталоги наследуют его). Нажатие Esc на этих шагах завершает работу, не утверждая, что настройка завершена. Последующие папки запрашивают только доверие. Возврат в доверенную папку открывает обычный TUI.

Провайдеры и модели

Forge включает встроенные маршруты для:

• OpenAI API (openai/*)
• Anthropic API (anthropic/*)
• xAI Grok через OAuth (xai/*)
• Подписки OpenAI Codex через вход с устройства (openai-codex/*)
• OpenCode Go (opencode-go/*)
• OpenCode Zen (opencode-zen/*)
• Локально запущенный Ollama (ollama/*) Самый простой способ настройки — экспортировать клюок провайдера и модель, затем запустить Forge:

export OPENAI_API_KEY="..."
export FORGE_MODEL_ID="openai/gpt-4.1-mini"
forge

Другие переменные окружения с API-ключами включают ANTHROPIC_API_KEY, OPENCODE_API_KEY, OPENCODE_GO_API_KEY и OPENCODE_ZEN_API_KEY.

Для OAuth-провайдеров используйте /connect внутри Forge. Для Ollama сначала запустите локальный сервис Ollama, затем выберите маршрут Ollama и доступную локальную модель.

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

/connect       Connect or change a provider
/model         Browse or change models
/resume        Browse previous sessions in the current journal
/clear         Clear the visible transcript
/compact       Compact the active context
/disconnect    Remove a saved provider connection
/refresh       Refresh the file explorer's Git state
/edit          Open the active file in your editor
/context-file  Attach the active file to the next message
/terminal      Open the terminal panel
/theme         Change the presentation theme
/status        Session status and diagnostics
/help          Open help
/quit          Exit Forge

/resume <session-id> возобновляет конкретную сессию. Форма командной строки forge --resume <session-id> делает то же самое; просто forge --resume возобновляет последнюю изменённую сессию, если она существует.

Управление с клавиатуры

Forge отображает контекстные подсказки для текущего фокуса. Наиболее полезные глобальные управляющие клавиши:

В нижнем колонтитуле есть ряд чипов: модель и усилие. Это обычная точка остановки Tab — перейдите к нему с помощью Tab, используйте ←/→ для выбора чипа, Enter для открытия выбора. Enter по-прежнему отправляет сообщение из композера; ⏎ — это только подсказка. Ctrl+Shift+V прикрепляет PNG/JPEG/GIF/WebP из локального буфера обмена (только для рабоской области; в SSH нет буфера обмена изображениями). Модель также может вызвать view_image для файла рабоской области, если активная модель принимает изображения на вход.

Обозреватель файлов требует терминал шириной не менее 116 столбцов. При меньшей ширине Ctrl+E сообщает об этом, а не переключает панель, которую невозможно отобразить.

Когда панель терминала находится в фокусе, она представляет собой интерактивную оболочку входа, и в её заголовке отображается ● с более толстой линией, чтобы вы могли понять, что она удерживает клавиатуру. Вводите или вставляйте команды прямо в неё; стандартные управляющие клавиши, стрелки, Tab и изменение размера терминала передаются оболочке. Ctrl+Backtick, Esc или введённая команда exit закрывают панель, не убивая оболочку, поэтому повторное открытие возобновляет ту же сессию.

Когда открыт текстовый файл, рабоская область использует редактирование в стиле Vim. Файлы начинаются в обычном режиме; нажмите i для вставки, Esc для возврата в обычный режим и Alt+E, чтобы передать файл в $VISUAL/$EDITOR. В обычном режиме : открывает командную строку редактора. Бета-набор команд включает :w, :q, :q!, :wq, :x, :e [path], :s/pattern/replacement/[g] и :%s/pattern/replacement/[g]. Сохранение происходит немедленно. Forge спрашивает, сохранить, отбросить или отменить изменения перед выходом или переключением с изменённых буферов, а также спрашивает, перезагрузить или принудительно сохранить, если файл изменился на диске. Двоичные файлы и файлы с недопустимой кодировкой UTF-8 остаются явно только для чтения.

Конфигурация

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

Минимальный проект forge.toml может выглядеть так:

[model]
model = "openai/gpt-4.1-mini"

[tui]
theme = "forge-dark"
file_icons = "unicode"

[journal]
path = ".forge/sessions"

Темы

Forge поставляется со встроенными темами, которые можно выбрать с помощью /theme или задать в forge.toml. Просто /theme открывает нижнюю панель: ↑↓ предпросмотр в реальном времени на реальном интерфейсе, Enter подтверждает, Esc возвращает предыдущую тему. /theme <id> применяется немедленно.

Поместите пользовательские файлы тем .toml в .forge/themes/ в вашей рабоской области или ~/.config/forge/themes/, чтобы добавить или переопределить темы. Смотрите crates/forge-tui/themes/ для схемы и примеров.

Часто используемые переменные окружения:

FORGE_MODEL_ID
FORGE_MODEL_PROVIDER
FORGE_API_KEY
FORGE_WORKSPACE
FORGE_JOURNAL_PATH
FORGE_MODEL_REQUEST_TIMEOUT_SECS

Forge хранит журналы сессий в локальном хранилище времени выполнения репозитория, когда это возможно, или в каталоге данных приложения платформы вне Git репозиторий. Данные времени выполнения не являются исходным кодом и не должны сохраняться в системе контроля версий.

MCP-серверы

MCP-серверы могут быть настроены в доверенном пользовательском конфиге или в явно управляемой конфигурации:

[[mcp.servers]]
id = "my-tools"
transport = "stdio"
command = "my-mcp-server"
args = ["--stdio"]

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

Песочница

Каждая команда оболочки, которую запускает агент, ограничивается операционной системой. Ограничение применяется при запуске, поэтому оно не зависит от того, правильно ли агент классифицировал команду заранее — forge не пытается решать, опасна ли rm -rf, он убирает доступ, который мог бы сделать это значимым.

Внутри песочницы команда может:

• читать широко, чтобы работали инструментальные цепочки и системные библиотеки;
• записывать только в ваше рабочее пространство и временный каталог сеанса;
• достигать сети только через прокси для исходящего трафика, описанный ниже;
• передавать файл хост-приложению с помощью open macOS (Launch Services). Это приложение не ограничено. То же право Apple Event также позволяет команде управлять другими GUI-приложениями через osascript.

.git и .forge доступны только для чтения: агент может просматривать историю, но не может переписать ее, и не может редактировать правила разрешений, которые управляют ей.

Широкое чтение имеет одну известную цену, и ее стоит прямо заявить. В Linux песочница предоставляет файловую систему хоста только для чтения, и монтирование только для чтения не останавливает процесс от подключения к Unix-сокету — эта проверка смотрит на inode, а не на флаг монтирования. Forge маскирует /run и /tmp, что покрывает сокеты с наибольшим радиусом поражения: docker.sock (root на хосте), systemd, D-Bus и $XDG_RUNTIME_DIR, где находятся ssh-agent и gpg-agent. Сокет с именем пути где-то еще — ~/.docker является реалистичным примером — все еще доступен из песочницы. Ограниченная команда уже работает от вашего имени, поэтому это расширяет то, к чему она может получить доступ, а не пересекает границу привилегий. Для закрытия этой возможности требуется LANDLOCK_ACCESS_FS_RESOLVE_UNIX из Landlock, который новее, чем ядра, на которых сегодня работает forge; seccomp не может это выразить. Отслеживается в issue #392.

Если ОС не может обеспечить ограничение — отсутствует bubblewrap, неподдерживаемая платформа — forge не запускается. Он выводит причину в stderr и завершает работу. Не существует комбинации настроек, которая отключает надзор без установленного минимального уровня принуждения.

Исходящий сетевой трафик

Песочница полностью запрещает сетевой доступ, затем восстанавливает его через фильтрующий прокси, доступный через Unix-сокет. Прокси читает хост CONNECT, который называет каждый запрос, и отказывает всему, что не входит в список разрешений. Он не завершает TLS, не устанавливает сертификат и не видит ваш трафик — он только решает, куда может идти соединение.

Список разрешений пуст, пока вы не добавите хосты. Ничто — ни crates.io, npm, PyPI, ни GitHub — не доступно, если личное разрешение host(...) не разрешает это, или вы не предоставите неограниченный доступ к сети с помощью host(*). Файл, переданный в репозиторий, не может открыть это; только ваш личный файл разрешений может.

Правила разрешений

permissions.toml может повторно запросить вызов (deny) или пропустить запрос, который в противном случае появился бы (allow). Правила шаблонов соответствуют фактическому вызову — префикс команды для инструментов оболочки, глоб пути для файловых инструментов, хост для инструментов типа fetch. Правила host(...) отличаются: они питают прокси для исходящего трафика, а не запрос на одобрение. Оболочка не запрашивает по умолчанию, поэтому правила allow для оболочки ничего не делают для запросов. MCP все еще запрашивает, если не разрешено:

allow = [
  "bash(cargo test *)",
  "bash(cargo build*)",
  "host(**.crates.io)",
  "host(**.github.com)",
]
deny = ["bash(cargo publish*)"]

host(*) — это неограниченный доступ к сети через прокси (песочница файловой системы остается включенной). Запрет host(...) по-прежнему имеет приоритет над более широким разрешением.

Запись deny создает исключение из более широкой записи allow (cargo * разрешено, но cargo publish все еще спрашивает); она никогда не блокирует вызов напрямую — это все еще работа ACL. Читаются и объединяются два файла:

• <user config dir>/forge/permissions.toml — личный, доверенный.
• .forge/permissions.toml в рабочем пространстве — переданный в репозиторий, и по той же причине, по которой ограничена обнаруживаемая в проекте конфигурация MCP выше, его записи allow игнорируются. Проверенный репозиторий не может предоставить себе более широкий радиус поражения, чем человек одобрил локально. Его записи deny всегда учитываются, поскольку дальнейшее сужение разрешений безопасно независимо от источника.

Строки меню (когда появляется запрос): - Выполнить один раз — выполнить этот вызов; спросить снова в следующий раз. - Запомнить похожие команды на эту сессию — запомнить обобщённое семейство на остаток сессии. Выбранная строка объясняет, что будет соответствовать (например, git push …). Соответствующие команды в дальнейшем выполняются без запроса; другое семейство всё ещё спрашивает. Не записывается в permissions.toml. - Не выполнять — заблокировать вызов.

Когда песочница заблокировала хост (например, CLI, обращающийся к api.github.com), меню вместо этого предоставляет доступ к хосту, и команда повторяется, оставаясь ограниченной. Предоставление доступа к хосту также проецирует HTTPS-идентичность для этого хоста в ограниченный запуск: учётные данные заполняются на хосте (git credential), SSH-удалённые репозитории (git@host:) переписываются на HTTPS (SSH не может использовать CONNECT-прокси), запись в git-dir разрешена только для запусков, которые выполняют сам git — и никогда для .git/hooks, которые в противном случае выполнялись бы на хосте, — а HTTPS-CLI, читающие переменную окружения {label}_TOKEN, получают её, производную от предоставленного хоста. Обычные команды по-прежнему не могут записывать в .git. Песочница не может открыть хранилище секретов ОС, поэтому без проекции HTTPS-клиент получает HTTP 401 / "недопустимый токен" и выглядит как сломанная аутентификация.

• Всегда разрешать **.github.com — записывает host(**.github.com) в личный файл разрешений, чтобы следующая сессия больше не спрашивала.
• Разрешить **.github.com на эту сессию — только живой прокси.
• Не выполнять — заблокировать вызов.

Одобрения

Нет настройки режима разрешений. Команды оболочки и запись файлов выполняются без запроса: песочница является границей. Инструменты MCP всё ещё запрашивают, потому что это отдельные серверные процессы, которые песочница не ограничивает. Шаблон deny повторно запрашивает даже для оболочки. Запрет ACL — это жёсткая блокировка, а не запрос.

Хост, который не может быть ограничен, никогда не достигает этой политики — Forge отказывается запускаться.

Одобрение команд оболочки

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

• ↑ / ↓ — перемещение выбора (по умолчанию: Выполнить один раз)
• Enter — подтвердить
• Esc — не выполнять (или выйти из «Запретить с примечанием»)

Дополнительные текстовые псевдонимы по-прежнему работают: yes, no, remember, always, no <note>.

Встроенные инструменты

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

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

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

Сессии и возобновление

Каждая сессия Forge имеет постоянный идентификатор и журнал. Если процесс остановится неожиданно, запустите Forge с:

forge --resume

или возобновите известную сессию напрямую:

forge --resume <session-id>

Внутри TUI /resume перечисляет предыдущие сессии и показывает подсказку заголовка из первого сообщения пользователя, когда это доступно. Журналы сессий остаются отдельными от ваших исходных файлов и никогда не должны содержать ключи API или токены OAuth.

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

Forge может выполнять команды и изменять файлы на вашем компьютере. Относитесь к нему как к оболочке с ИИ-интерфейсом:

1. Запускайте его только в репозиториях, которым вы доверяете. Песочница ограничивает, к чему команда может получить доступ; она не делает непроверенный репозиторий безопасным для сборки.
2. Читайте каждый запрос на одобрение, включая точную команду и последствия. В автоматическом режиме большинство команд оболочки не запрашивают — песочница заменяет эту проверку, поэтому убедитесь, что она активна (индикатор режима в нижней части показывает, когда режим ограничен).
3. Храните учётные данные в вашем окружении или доверенной пользовательской конфигурации. Песочница ограничивает, куда команда может подключаться, но команда, которая легитимно достигает разрешённого хоста, может переносить всё, что она может прочитать.
4. Не коммитьте .forge/, журналы выполнения, ключи API, токены OAuth или файлы учётных данных.
5. Используйте одноразовый клон при оценке незнакомого репозитория.

См. SECURITY.md для модели угроз и процесса сообщения о частных уязвимостях.

Разработка

Forge — это рабочее пространство Rust. Основные крейты:

• forge-cli — точка входа командной строки;
• forge-tui — терминальный интерфейс;
• forge-core — цикл агента и жизненный цикл сессии;
• forge-model — транспорты провайдеров и нормализация сообщений;
• forge-connect — профили провайдеров, учётные данные и каталог моделей;
• forge-tools — встроенные инструменты и проверка;
• forge-durable — журналы сессий SQLite.

Запустите стандартные проверки перед отправкой изменения:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --all-targets --locked

Рекомендации по внесению вклада см. в CONTRIBUTING.md.

Лицензия

Forge распространяется по лицензии MIT.