LocalForge ⚒️

Puente del Model Context Protocol (MCP) para codificación agéntica híbrida — en el que se delega la implementación con alto consumo de tokens a modelos locales de código abierto.
Arquitectura en la nube. Implementación en local. Ahorra entre un 80 y un 90 % de tokens premium de API.

💡 El problema y la solución

En las configuraciones tradicionales de codificación agéntica, los modelos de frontera (OpenAI Codex, Claude 3.7 Sonnet / Opus) ejecutan cada paso del flujo de trabajo: desde el razonamiento de alto nivel hasta leer miles de líneas del repositorio, ejecutar suites de pruebas y corregir errores del compilador.

Esto es extremadamente caro e ineficiente:

• Se consume más del 80 % del total de tokens en bucles repetitivos y mecánicos (descubrimiento de archivos, correcciones de sintaxis, iteraciones de pruebas unitarias).

• El contexto propietario del código se transmite repetidamente a APIs externas en la nube.

LocalForge resuelve esto con Codificación Agéntica Híbrida:

1. Modelo de frontera (Nube): Actúa como arquitecto y revisor (alta inteligencia, bajo volumen de tokens).

2. LocalForge (límite MCP): envía especificaciones de tareas estructuradas y acotadas y gestiona los entornos locales de prueba.

3. Modelo local de código abierto (LLM local): ejecuta localmente los bucles de implementación, edición y depuración de pruebas con alto consumo de tokens, con un coste marginal de API de cero.

4. Revisión de la frontera: el modelo en la nube inspecciona únicamente el diff conciso, los registros y el resumen para verificar su correcto funcionamiento.

   ┌──────────────────────────────────────────────────────────┐
   │                  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-agent

✨ Características clave

• 📉 Reducción de tokens premium del 80-90%: las ediciones de código, la indexación de archivos y la depuración de pruebas que más tokens consumen permanecen íntegramente en el hardware local.

• 🛡️ Privacidad y límites de seguridad estrictos: los archivos internos sensibles y los volcados de diagnóstico de varias rondas permanecen dentro de tu red local.

• 🔄 Continuidad de sesión: los seguimientos en varias veces (opencode_followup) retoman la misma sesión de ejecución sin reenviar el contexto completo del repositorio.

• 🔒 Bloqueo del repositorio entre procesos: evita escrituras concurrentes conflictivas en varias pestañas o clientes de agente.

• 📊 Telemetría y libro de auditoría: registro automático de la duración de la ejecución, archivos modificados, líneas añadidas/eliminadas y ahorro de tokens estimado en state/ledger.jsonl.

• ⚡ Registro de clientes sin configuración: un único comando de instalación para Codex, Claude Code, Claude Desktop y Antigravity.

🛠️ Referencia de las herramientas MCP

LocalForge registra 8 herramientas nativas sobre el protocolo estándar Model Context Protocol (stdio/JSON-RPC):

🚀 Inicio rápido

1. Prerrequisitos

• Node.js: >= 20.0.0

• CLI de OpenCode: instalada y accesible en PATH (con npm i -g opencode-ai o un binario).

• Modelo de inferencia local: un endpoint compatible con OpenAI en ejecución (por ejemplo, DeepSeek V4 Flash, Qwen 2.5/3.5 en vLLM, Ollama, SGLang o clústeres duales DGX Spark).

2. Instalar y compilar

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

3. Verificar el estado

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

4. Conectar a tu cliente de IA

LocalForge incluye un script automatizado de registro de clientes:

# 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

⚙️ Configuración

Define las variables de entorno en tu entorno o en la configuración del cliente:

📊 Telemetría y registros

Cada tarea finalizada registra automáticamente su telemetría en state/ledger.jsonl. Ejecuta la herramienta de resumen integrada para analizar los ahorros:

npm run rollup

Ejemplo de salida:

=== 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

🎨 Infografía interactiva de la arquitectura

Este repositorio incluye un diagrama infográfico interactivo independiente en HTML que visualiza el flujo completo de delegación de MCP:

open index.html

📄 Licencia

Licencia MIT. Diseñado y mantenido por ADIS (Artificially Developed Intelligence Services).