GigaLoom

GigaLoom — локальная панель управления для кодинг-агентов, не привязанная к одному провайдеру. Она объединяет нативные команды вида giga <агент> и браузерный интерфейс для сессий, подтверждений, worktree, расписаний, оценок и мультиагентных сценариев.

В GigaLoom 0.9 основной рабочий путь выглядит так: Проект → Тред → Запуск → Результаты → Действие. Также появились ограниченный Thread Relay, схемы для редакторов, безопасные для разных кодировок вложения, read-only просмотр Effective Instructions, локальные продуктовые отчёты и точные маршруты запуска агентов через gpt2giga. Состояние пользователя хранится локально, чувствительные значения скрываются при сохранении и выводе в UI, а при неполных правах или данных о совместимости запуск блокируется.

GigaLoom позволяет:

• запускать Codex, Claude, Gemini, Pi и совместимые агенты из одной локальной точки, не заменяя их нативные CLI;
• изолировать работу в привязанных к проекту worktree и сохранять подтверждения, результаты проверок, оценки и данные для повторного анализа;
• подключать проверенные MCP-приложения и ACP-агенты по планам установки, привязанным к digest;
• просматривать и обрабатывать поддерживаемые треды без копирования приватного состояния провайдера;
• запускать один явно выбранный маршрут через gateway, не меняя домашние конфиги Codex, Claude или Gemini;
• автоматизировать headless-запуски через детерминированный JSONL-контракт и опциональные адаптеры без неявной передачи учётных данных или прав на проект.

Быстрый старт

Нужны Python 3.11–3.14 и установленный CLI хотя бы одного провайдера, например Codex CLI. Управляемые терминальные сессии на Linux и macOS также используют tmux; без него останется обычный нативный запуск провайдерского CLI.

Установите GigaLoom и проверьте окружение:

uv tool install 'gigaloom==0.9.0'
giga doctor
giga --version

Запустите браузерный интерфейс:

giga ui

Откройте http://127.0.0.1:8091/. Для обычного запуска нативного CLI достаточно добавить префикс giga; остальные аргументы передаются без изменений:

giga codex exec --json "проверь этот репозиторий"
giga claude -p "проверь этот репозиторий"
giga gemini -p "проверь этот репозиторий"
giga pi

Предпросмотр доставки сообщения через Thread Relay без изменения целевого треда и без запроса к провайдеру:

giga session send THREAD_ID --text "проверь падающие тесты" --dry-run --json

Codex через gpt2giga в терминале

Этот вариант подходит для интерактивного Codex и для codex exec. Для проверенного маршрута GigaChat-2-Max GigaLoom сам запустит локальный gpt2giga 0.3.0, передаст ему учётные данные GigaChat и остановит принадлежащий этому запуску процесс после выхода из Codex.

1. Установите интеграцию

uv tool install --force \
  --with 'gpt2giga==0.3.0' \
  'gigaloom[gpt2giga]==0.9.0'

Codex CLI устанавливается отдельно. Для маршрута GigaLoom 0.9 проверялся Codex CLI 0.146.0; другая версия может быть заблокирована до запуска процесса.

2. Передайте учётные данные GigaChat

Выберите один способ авторизации и экспортируйте переменные в том же терминале, из которого будет запущена команда giga:

# Вариант 1: OAuth credentials
export GIGACHAT_CREDENTIALS='<ваши-credentials>'
export GIGACHAT_SCOPE='GIGACHAT_API_PERS'

# Вариант 2: уже полученный access token
# export GIGACHAT_ACCESS_TOKEN='<ваш-access-token>'

# Вариант 3: логин и пароль для соответствующего GigaChat endpoint
# export GIGACHAT_USER='<логин>'
# export GIGACHAT_PASSWORD='<пароль>'
# export GIGACHAT_BASE_URL='<адрес-api>'

Не сохраняйте секреты в README, репозитории или отслеживаемом .env-файле. Значение GIGACHAT_SCOPE должно соответствовать вашим учётным данным.

3. Запустите Codex

Интерактивный режим:

giga --with gpt2giga --model GigaChat-2-Max codex

Одноразовая задача без интерактивного интерфейса:

giga --with gpt2giga --model GigaChat-2-Max \
  codex exec --json "проверь падающие тесты"

Однокомандный managed-маршрут релиза 0.9 проверен с GigaChat-2-Max. Для GigaChat-3-Ultra сначала запустите постоянный внешний gateway по инструкции ниже, а затем подключите к нему Codex из второго терминала. Модель в любом случае должна присутствовать в /models вашего GigaChat endpoint.

Что означает gateway_upstream_credentials_unavailable

Сообщение

{"reason_ids":["gateway_upstream_credentials_unavailable"],"status":"blocked"}

означает, что GigaLoom не увидел ни GIGACHAT_CREDENTIALS, ни GIGACHAT_ACCESS_TOKEN, ни GIGACHAT_USER. Gateway и Codex при этом не запускаются, запрос к провайдеру не отправляется. Экспортируйте переменные в том же процессе shell и повторите команду. Быстрая проверка без вывода самого секрета:

test -n "$GIGACHAT_CREDENTIALS" || \
test -n "$GIGACHAT_ACCESS_TOKEN" || \
test -n "$GIGACHAT_USER"

gpt2giga и Codex в одном терминале

Этот сценарий нужен для GigaChat-3-Ultra, браузерного UI и долгоживущих запусков через внешний gateway. gpt2giga работает в фоне того же терминала, а после выхода из Codex или UI автоматически останавливается.

1. Подготовьте .env

Если команда gpt2giga не появилась в PATH после установки интеграции, установите публичный gateway CLI отдельно:

uv tool install 'gpt2giga==0.3.0'

Создайте локальный конфиг и замените в нём значения REPLACE_WITH_...:

cp .env.example .env
$EDITOR .env

gpt2giga сам читает .env, но giga этого не делает: GigaLoom читает только переменные текущего процесса. Поэтому перед giga файл нужно экспортировать через source. В .env.example значение GIGALOOM_API_KEY берётся из GPT2GIGA_API_KEY; не заменяйте его на 0.

Если gateway уже запущен, исправление для текущего терминала выглядит так:

set -a
source .env
set +a

test "$GIGALOOM_API_KEY" = "$GPT2GIGA_API_KEY"
giga --with gpt2giga --model GigaChat-3-Ultra codex

2. Запустите gateway и Codex одной вставкой

Следующий блок загружает .env, запускает gpt2giga в фоне, ждёт авторизованный /models, запускает Codex и гарантированно останавливает gateway при выходе. Перед выполнением остановите ранее запущенный процесс на порту 8090, иначе новый gateway не сможет занять порт:

(
  set -a
  source .env
  set +a

  if [[ -z "$GPT2GIGA_API_KEY" || "$GIGALOOM_API_KEY" != "$GPT2GIGA_API_KEY" ]]; then
    echo "GIGALOOM_API_KEY должен совпадать с GPT2GIGA_API_KEY и не быть пустым" >&2
    exit 2
  fi

  gpt2giga --env-path .env >/tmp/gpt2giga-gigaloom.log 2>&1 &
  gpt2giga_pid=$!
  cleanup_gpt2giga() {
    kill "$gpt2giga_pid" 2>/dev/null || true
    wait "$gpt2giga_pid" 2>/dev/null || true
  }
  trap cleanup_gpt2giga EXIT
  trap 'exit 130' INT TERM

  gateway_ready=false
  for gateway_attempt in {1..50}; do
    if curl -fsS \
      -H "x-api-key: $GIGALOOM_API_KEY" \
      "$GIGALOOM_PROXY_URL/models" >/dev/null; then
      gateway_ready=true
      break
    fi
    kill -0 "$gpt2giga_pid" 2>/dev/null || break
    sleep 0.2
  done

  if [[ "$gateway_ready" != true ]]; then
    tail -n 50 /tmp/gpt2giga-gigaloom.log
    exit 1
  fi

  giga --with gpt2giga --model GigaChat-3-Ultra codex
)

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

giga --with gpt2giga --model GigaChat-3-Ultra \
  codex exec --json "проверь падающие тесты"

3. Запустите gateway и UI в одном терминале

Используйте тот же блок, но замените последнюю команду на giga ui --no-start-proxy. Пока UI открыт, gateway работает в фоне; после Ctrl+C оба процесса завершаются.

Откройте http://127.0.0.1:8091/web/work и выполните следующие шаги:

1. Выберите или зарегистрируйте локальный проект.
2. Нажмите «Новая сессия».
3. Для работы с репозиторием выберите «Тип задачи → Агент разработки» и «Harness → Codex CLI». Для обычного разговора без агентного цикла выберите «Прямой чат» и harness direct-chat.
4. В поле «Модель» выберите GigaChat-3-Ultra или другую модель из /models.
5. Если показан блок reviewed gateway route, выберите маршрут gpt2giga и нажмите «Preflight exact route».
6. Введите задачу и нажмите «Запустить задачу».

Если список моделей или маршрутов пуст, сначала проверьте /health, /models, совпадение GPT2GIGA_API_KEY и GIGALOOM_API_KEY, а также то, что UI запущен с --no-start-proxy и правильным --proxy-url/GIGALOOM_PROXY_URL. Значение GIGALOOM_API_KEY=0 отключает auth-заголовок и приводит к 401 Unauthorized, который GigaLoom отображает как models_unavailable.

Документация

Опубликованная документация на английском и русском языках доступна по адресу https://krakenalt.github.io/gigaloom/.

Интеграция с gateway

Базовый пакет gigaloom устанавливается независимо и не требует checkout исходного кода gateway. Direct Chat и старый preset локального gateway являются опциональными:

uv tool install 'gigaloom[gpt2giga]==0.9.0'

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

Разработка

npm --prefix web ci --ignore-scripts
npm --prefix web run build
./scripts/ci-base.sh sync
./scripts/ci-base.sh ruff-check
./scripts/ci-base.sh pytest tests/harness -q

Сборка самостоятельного дистрибутива:

uv build --no-sources

Перед отправкой изменений прочитайте CONTRIBUTING.md, а правила владения кодом и восстановления описаны в GOVERNANCE.md. Об ошибках сообщайте через GitHub Issues, а о возможных уязвимостях — только по приватному каналу из SECURITY.md.

История исходного кода

GigaLoom был выделен из объединённого репозитория ai-forever/gpt2giga. Ссылки на него в старых changelog и инструкциях по миграции являются историческими. Текущая разработка, issues, документация и релизы находятся в krakenalt/gigaloom.

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