LocalForge ⚒️

Мост на базе Model Context Protocol (MCP) для гибридного агентного кодирования — передача токеноёмкой реализации локальным моделям с открытым исходным кодом.
Архитектор — в облаке. Реализация — локально. Экономьте 80–90% токенов премиальных API.

💡 Проблема и решение

В традиционных схемах агентного кодирования передовые модели (OpenAI Codex, Claude 3.7 Sonnet / Opus) выполняют каждый шаг рабочего процесса: от высокоуровневых рассуждений до чтения тысяч строк репозитория, запуска тестов и исправления ошибок компилятора.

Это крайне дорого и неэффективно:

• Более 80% всех токенов уходит на повторяющиеся механические циклы (поиск файлов, исправление синтаксиса, итерации модульных тестов).

• Контекст собственной кодовой базы многократно передаётся во внешние облачные API.

LocalForge решает это с помощью гибридного агентного кодирования:

1. Передовая облачная модель: выступает в роли архитектора и ревьюера (высокий интеллект, малый объём токенов).

2. LocalForge (граница MCP): диспетчеризирует структурированные ограниченные спецификации задач и управляет локальными песочницами.

3. Локальная open-source модель (Local LLM): выполняет токеноёмкие циклы реализации, редактирования и отладки тестов локально с нулевой дополнительной стоимостью API.

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

   ┌──────────────────────────────────────────────────────────┐
   │                  1. ARCHITECT / REVIEWER                 │
   │                      (Codex / Claude)                    │
   │       • Understands requirement  • Reviews diff & logs   │
   └────────────────────────────┬─────────────────────────────┘
                                │
                    [MCP Task Specification]
                                │
                                ▼
   ┌──────────────────────────────────────────────────────────┐
   │                   2. LOCALFORGE (MCP)                    │
   │      • Session continuity      • Privacy boundary        │
   │      • Cross-process locks     • Telemetry ledger        │
   └────────────────────────────┬─────────────────────────────┘
                                │
                    [Local Inference Stream]
                                │
                                ▼
   ┌──────────────────────────────────────────────────────────┐
   │                3. IMPLEMENTATION WORKER                  │
   │           (DeepSeek V4 Flash / Qwen 2.5 / 3.5)           │
   │  ┌────────────────────────────────────────────────────┐  │
   │  │ 🔄 LOCAL ITERATION LOOP                            │  │
   │  │ Read Repo ➔ Edit Code ➔ Run Tests ➔ Fix Errors    │  │
   │  └────────────────────────────────────────────────────┘  │
   └──────────────────────────────────────────────────────────┘

Related MCP server: local-llm-delegation-mcp

✨ Ключевые особенности

• 📉 Сокращение премиальных токенов на 80–90%: Токеноёмкие изменения кода, индексация файлов и отладка тестов полностью выполняются на локальном оборудовании.

• 🛡️ Строгие границы конфиденциальности и безопасности: Чувствительные внутренние файлы и многократные диагностические дампы остаются внутри вашей локальной сети.

• 🔄 Непрерывность сессии: Многошаговые уточнения (opencode_followup) возобновляют ту же самую сессию выполнения без повторной отправки всего контекста репозитория.

• 🔒 Межпроцессная блокировка репозитория: Предотвращает конфликтующие параллельные записи из нескольких вкладок или клиентов агента.

• 📊 Телеметрия и журнал аудита: Автоматическая запись длительности выполнения, затронутых файлов, добавленных/удалённых строк и расчётной экономии токенов в state/ledger.jsonl.

• ⚡ Регистрация клиента без настройки: Подключение в одну команду для Codex, Claude Code, Claude Desktop и Antigravity.

🛠️ Справочник MCP-инструментов

LocalForge регистрирует 8 собственных инструментов поверх стандартного Model Context Protocol (stdio/JSON-RPC):

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

1. Предварительные требования

• Node.js: >= 20.0.0

• OpenCode CLI: установлен и доступен в PATH (npm i -g opencode-ai или из бинарной сборки)

• Локальная инференс-модель: работающая OpenAI-совместимая конечная точка (например, DeepSeek V4 Flash, Qwen 2.5/3.5 на vLLM, Ollama, SGLang или двойные кластеры DGX Spark).

2. Установка и сборка

git clone https://github.com/aditya1503/LocalForge.git
cd LocalForge
npm install
npm run build

3. Получение и проверка состояние

npm run dev
# or run health check
tsx tests/v2.test.ts

4. Подключение к вашему AI-клиенту

LocalForge включает автоматический скрипт регистрации клиентов:

# Register with OpenAI Codex / Antigravity
node scripts/register-client.mjs antigravity

# Register with Claude Code
node scripts/register-client.mjs claude-code

# Register with Claude Desktop
node scripts/register-client.mjs claude-desktop

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

Задайте следующие переменные окружения в вашем окружении или клиентской конфигурации:

📊 Телеметрия и отчёты

Каждая завершённая задача автоматически записывает телеметрию в state/ledger.jsonl. Запустите встроенную утилиту анализа для подсчёта экономии:

npm run rollup

Пример вывода:

=== LocalForge Telemetry Rollup ===
Total Tasks: 42
Success Rate: 95.2%
Avg Task Duration: 28.4s
Estimated Cloud Tokens Saved: ~1.85M tokens
Top Task Classes: unit-test-generation, bugfix, refactoring

🎨 Интерактивная инфографика архитектуры

Этот репозиторий включает автономную интерактивную HTML-инфографику, визуализирующую полный процесс делегирования через MCP:

open index.html

📄 Лицензия

Лицензия MIT. Спроектировано и поддерживается ADIS (Artificially Developed Intelligence Services).