SmallCode: Potenciando LLMs locales en tu terminal

Qué hace SmallCode

SmallCode es un agente de codificación nativo de terminal que hace que los modelos de lenguaje locales pequeños (8B–35B parámetros) sean efectivos en tareas de programación. Compensa las limitaciones de los modelos de hardware de consumo mediante la gestión del presupuesto de contexto, análisis flexible de llamadas a herramientas (JSON, YAML, XML, texto plano, autorreparación), edición basada en parches con buscar y reemplazar, planificación guiada por TODO, sesiones de shell persistentes, escalado opcional a la nube y herramientas de observabilidad. El agente funciona completamente en local de forma predeterminada.

Primeros pasos

Instalación mediante npm: npm install -g smallcode (requiere Node.js 18+). Hay binarios precompilados para Linux, macOS y Windows disponibles a través de un script de shell. Verifica con smallcode --help. Necesitas un servidor LLM local con un endpoint compatible con OpenAI (LM Studio, Ollama). El paquete opcional better-sqlite3 habilita el grafo de código y la memoria FTS5; si la compilación falla, se usa un almacén JSON.

Crea un archivo .env con:

• SMALLCODE_MODEL=<nombre-del-modelo> (obligatorio)
• SMALLCODE_BASE_URL=http://localhost:1234/v1 (obligatorio)

Opcionalmente, añade claves de API en la nube (ANTHROPIC_API_KEY, etc.) para el escalado. Ejecuta smallcode para comenzar.

TUI interactiva y comandos slash

Ejecuta smallcode dentro de un directorio de proyecto. El agente detecta automáticamente el entorno de ejecución y los comandos de prueba, y luego presenta una interfaz conversacional. Las tareas complejas se descomponen en planes TODO; utiliza herramientas automáticamente y valida cada paso. Los comandos slash ofrecen control:

/quit, /clear, /stats, /tokens, /budget (visualización del contexto), /trace, /eval, /memory, /plan, /model, /profile, /cognition, /mcp, /skill, /plugin, /sessions, /help.

Estos permiten la monitorización, la gestión de sesiones y el cambio de modelo.

Uso programático y pruebas

Incrusta SmallCode como una biblioteca. Requiere Smallcode, instáncialo con el modelo y la URL base, y llama a agent.run(). Suscríbete a eventos como tool_start y error. El RunResult devuelto incluye los archivos creados/editados, las llamadas a herramientas, el estado de éxito y el uso de tokens.

const { SmallCode } = require('smallcode');

const agent = new SmallCode({
  model: 'gemma-4-e4b',
  baseUrl: 'http://localhost:1234/v1',
});

const result = await agent.run("create hello.py that prints hello world");
console.log(result.filesCreated);  // ['hello.py']
console.log(result.toolCalls.length);  // 1
console.log(result.success);  // true

agent.on('tool_start', ({ name, args }) => console.log(`Using: ${name}`));
agent.on('tool_end', ({ name, ms }) => console.log(`Done: ${name} (${ms}ms)`));
agent.on('error', (err) => console.error(err));

Ejecuta benchmarks con npm run bench:smoke, bench:polyglot o bench:tools. Los resultados se guardan en .smallcode/benchmarks/. Genera pruebas de regresión a partir de trazas usando /trace test <id>.

Opciones de configuración

Configura mediante .env o el archivo heredado smallcode.toml. Variables clave:

• SMALLCODE_MODEL (obligatorio) – nombre del modelo.
• SMALLCODE_BASE_URL (obligatorio) – endpoint.
• ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY – claves de escalado a la nube opcionales.
• SMALLCODE_THINKING_BUDGET – tokens máximos de razonamiento (por defecto 2000); deshabilita con THINKING_DISABLE=true.
• SMALLCODE_SHELL_PERSIST – mantiene el estado de la shell entre turnos (por defecto true).
• SMALLCODE_WRITE_GUARD – rechaza la primera escritura en un archivo no leído (por defecto true).
• SMALLCODE_SNAPSHOT/AUTO_ROLLBACK – instantáneas previas a la edición y reversión automática en caso de fallo grave.
• SMALLCODE_PLAN – fuerza el modo planificar‑luego‑ejecutar.
• SMALLCODE_TEST_RUNNER/TEST_DISABLE – anula o deshabilita la inyección del ejecutor de pruebas.
• SMALLCODE_WEB_BROWSE – habilita herramientas web (requiere modelo de 20B+).
• SMALLCODE_MODEL_MEDIUM/STRONG – modelos para enrutamiento adaptativo.
• TEMP_ADAPT, TRUST_DECAY – indicadores de reintento adaptativo y puntuación de confianza.

Restricciones y limitaciones

• Los modelos ≤4B tienen dificultades con el uso de herramientas en varios pasos; el mejor rendimiento se obtiene entre 8B y 35B.
• Los resultados de las herramientas se truncan a 4k caracteres; los resultados más antiguos pueden ser expulsados bajo presión de presupuesto.
• better-sqlite3 puede necesitar compilación nativa para el grafo de código; de lo contrario se utiliza memoria JSON.
• La navegación web solo es fiable con modelos de 20B o más.
• Se aplican cargos por escalado a la nube; las llamadas están limitadas por sesión.
• El presupuesto de razonamiento puede truncar el razonamiento en modelos como DeepSeek R1, afectando tareas complejas.
• El guardia de escritura bloquea la primera escritura en un archivo no leído; se permite un segundo intento.
• La reversión automática de instantáneas puede deshacer todas las ediciones del turno; los datos de las instantáneas persisten en .smallcode/snapshots/.

Best Practices

• Permite que SmallCode detecte automáticamente el entorno de ejecución, el framework y las pruebas del proyecto en el primer turno para ahorrar llamadas a herramientas.
• Utiliza la planificación heurística por defecto; habilita SMALLCODE_PLAN=true solo si el modelo se desvía.
• Mantén activo el almacén de evidencias para capturar los resultados de las tareas y facilitar el aprendizaje futuro.
• Activa el guardia de lectura antes de escritura y la reversión automática de instantáneas para ediciones arriesgadas.
• Define SMALLCODE_TEST_RUNNER si la detección automática falla, para evitar llamadas a herramientas innecesarias.
• Usa sesiones de shell persistentes (SHELL_PERSIST=true) para comandos de varios pasos.
• Supervisa el contexto con /budget y /tokens.
• Mantén activada la temperatura adaptativa de reintentos para que los intentos fallidos varíen.
• Se recomienda la navegación web solo para modelos de 20B o más; desactívala para los más pequeños.
• Genera pruebas de regresión a partir de las trazas después de completar tareas complejas con éxito.

Funcionalidades avanzadas

Instantáneas y reversión: Se crean puntos de control de archivos antes de cada turno. AUTO_ROLLBACK=true revierte todas las ediciones de un turno ante un fallo grave de validación. Las instantáneas persisten en .smallcode/snapshots/.

Sesiones y Memoria: Las sesiones se guardan automáticamente; usa /sessions list y resume. Un bloc de notas persistente actúa como memoria de trabajo; el almacén de evidencias registra lo que se intentó y falló, ayudando en ejecuciones futuras.

Habilidades y Plugins: Seis habilidades integradas (brainstorming, debugging, tdd, etc.) se cargan desde skills/. Gestiónalas con /skill list, /skill use. Los plugins se pueden instalar mediante /plugin.

Enrutamiento Adaptativo: Realiza un seguimiento de las tasas de fallo por modelo; cambia automáticamente a SMALLCODE_MODEL_MEDIUM/STRONG cuando se superan los umbrales (0.3/0.6).

Cognición y Andamiaje: MarrowScript se compila a TypeScript para caché, reintentos y validación. BoneScript genera la estructura completa de un backend Node.js a partir de un único archivo .bone.

Configuración y Actualizaciones: Soporte para .env y el formato heredado .smallcode.toml. Los benchmarks se ejecutan con npm run bench:smoke, bench:polyglot, bench:tools.