MartinLoop

MartinLoop

Tu agente de codificación dice que está listo. MartinLoop hace que lo demuestre.

Un solo sistema para controlar, verificar y comprender el trabajo de los agentes de codificación.

Comienza aquí

Instalación — ejecuta npx -y martin-loop@0.5.0 start, o instálalo globalmente con npm install -g martin-loop@0.5.0.

Ejecución gobernada — define un objetivo, verificador, presupuesto y límite de iteraciones con martin run.

Verificador — la finalización requiere evidencia fresca del verificador vinculada a la ejecución activa y al espacio de trabajo. Un verificador configurado solo demuestra las comprobaciones que ejecuta; VERIFIED no es una afirmación de que el código esté libre de errores o sea automáticamente seguro para fusionar.

Presupuesto — establece un límite de gasto máximo con --budget-usd y un límite de intentos con --max-iterations.

Recibos — inspecciona el último resultado con martin dossier --latest y valida la integridad almacenada con martin runs verify --latest.

MCP — instala @martinloop/mcp@0.5.0 en un host compatible o genera la configuración del host con martin mcp print-config.

Documentación — continúa con la guía de inicio rápido, la referencia de CLI o la configuración de MCP.

Cuando se proporciona --model, MartinLoop lo pasa sin cambios. Sin --model, el runtime del host autenticado elige su propio valor predeterminado. MartinLoop no inyecta un modelo de respaldo oculto.

Por qué MartinLoop

Los agentes de codificación de IA son útiles, pero los bucles de reintento sin límites son costosos.

Una tarea que parecía un pequeño ajuste puede convertirse en docenas de intentos, un presupuesto de tokens agotado y un diff en el que nadie confía. MartinLoop otorga a cada ejecución un contrato explícito: objetivo, verificador, presupuesto, alcance, recibos y una condición de detención clara.

Úsalo cuando el trabajo de codificación de IA deba mantenerse acotado, inspeccionable y seguro de revisar antes de que se vuelva costoso o destructivo.

Por qué los equipos adoptan MartinLoop

• Convierte el comportamiento del agente en recibos de ejecución inspeccionables que realmente puedes revisar.
• Aplica condiciones de detención estrictas antes de que los reintentos descontrolados gasten más dinero.
• Añade reglas conscientes de reversión para que los intentos fallidos no dejen cambios inseguros en silencio.
• Ayuda a los equipos a comparar resultados entre agentes bajo un flujo gobernado único.

Los equipos usan MartinLoop cuando necesitan ejecución de agentes gobernada que pueda revisarse y en la que se pueda confiar.

Ruta de instalación en 2 minutos

npx -y martin-loop@latest start
npx -y martin-loop@latest demo
cd martin-loop-demo
npm install
npx -y martin-loop@latest run "Summarize the demo workspace and prove tests still pass" --verify "npm test" --budget-usd 2 --max-iterations 1

Inicio rápido

Prueba MartinLoop en un espacio de trabajo demo desechable:

npx -y martin-loop@latest start
npx -y martin-loop@latest demo
npx -y martin-loop@latest --version
cd martin-loop-demo
npm install
npx -y martin-loop@latest run "Summarize the demo workspace and prove tests still pass" --verify "npm test" --budget-usd 2 --max-iterations 1
npx -y martin-loop@latest dossier --latest
npx -y martin-loop@latest share --latest

Instalación global opcional:

npm install -g martin-loop
martin-loop --version

Si este flujo es útil, abre un issue con comentarios para que podamos seguir mejorando la experiencia pública.

start imprime la ruta guiada del primer uso. run verifica automáticamente doctor, session-start y preflight, y luego ejecuta cuando el entorno está listo. Usa --proof solo cuando quieras intencionalmente un carril explícito sin gasto.

Flujo de inspección primero:

npx -y martin-loop@latest doctor
npx -y martin-loop@latest session-start
npx -y martin-loop@latest preflight "Summarize the demo workspace and prove tests still pass" --verify "npm test"

share --latest escribe tres archivos en el directorio de ejecución seleccionado bajo share/: run-receipt.json, run-receipt.md y proof-card.svg.

Notas de la versión para el paquete raíz actual: MartinLoop 0.5.0.

Prueba visual

MartinLoop convierte una ejecución de codificación de IA en un registro de ejecución inspeccionable: presupuesto utilizado, resultado del verificador, archivos modificados, evidencia de reversión y recibo final.

Los agentes no gobernados pueden reintentar hasta que el costo y el alcance se desvíen. MartinLoop añade límites de presupuesto, compuertas de verificador y evidencia de auditoría para que la ejecución tenga una condición de detención clara.

Recibos de prueba

Los recibos de prueba son paquetes de intercambio locales para ejecuciones de codificación de IA gobernadas. Muestran la tarea, el gasto, el presupuesto, el resultado del verificador, la integridad del recibo y cualquier límite de evidencia que no deba redondearse en confianza.

Esta ejecución gobernada real gastó $0.51 contra un presupuesto de $3.00. El verificador pasó y la integridad del recibo fue firmada, pero la prueba se mantuvo en EVIDENCE_BOUNDARY porque no se registró evidencia de reversión.

Genera tu propio recibo después de una ejecución gobernada:

npx -y martin-loop@latest run "Summarize the demo workspace and prove tests still pass" --proof --verify "npm test"
npx -y martin-loop@latest runs verify --latest
npx -y martin-loop@latest share --latest

Archivos de recibo de ejemplo: Markdown y JSON.

Ejecuta esta auditoría tú mismo

Usa este carril desde un directorio temporal limpio para verificar el flujo público de CLI exactamente como se distribuye:

npx -y martin-loop@0.5.0 --version
npx -y martin-loop@0.5.0 start
npx -y martin-loop@0.5.0 demo
cd martin-loop-demo
npm install
npx -y martin-loop@0.5.0 run "Summarize the demo workspace and prove tests still pass" --verify "npm test" --budget-usd 2 --max-iterations 1 --json
npx -y martin-loop@0.5.0 dossier --latest --json
npx -y martin-loop@0.5.0 share --latest --json

Para instalaciones deterministas, fija la línea del paquete (martin-loop@0.5.0) o usa martin-loop@latest. Un npx martin-loop simple puede resolver una caché local obsoleta en algunas máquinas.

Salidas esperadas del paquete de intercambio:

• share/run-receipt.json
• share/run-receipt.md
• share/proof-card.svg

Míralo en acción

El punto no es que cada ejecución gobernada sea siempre más barata. El punto es que cada ejecución se vuelve inspeccionable y aplicable: política de presupuesto, resultado del verificador, motivo de detención y evidencia son explícitos.

Para un carril de reproducción pública determinista, usa el espacio de trabajo de referencia y compara la ejecución gobernada con el comportamiento de reintento sin límites:

• npx martin-loop bench --suite under-3-challenge
• npx martin-loop bench --suite ralphy-engineering-50

Bucles estilo Ralph

Un bucle estilo Ralph es el modo de fallo donde un agente de codificación de IA sigue intentando sin saber cuándo continuar es inseguro, antieconómico o improbable de tener éxito.

MartinLoop conserva la parte útil del bucle y luego añade frenos:

• detenerse antes del sobregasto del presupuesto
• clasificar acciones inseguras o inválidas antes de la ejecución
• escribir un registro de auditoría para cada intento
• preservar la evidencia de reversión y del verificador para revisión
• reducir el crecimiento descontrolado del contexto con resúmenes de ejecución compactos

Taxonomía de fallos (13 clases de runtime)

Las ejecuciones públicas gobernadas usan una taxonomía canónica: los 13 valores de FailureClass del runtime de @martin/contracts.

Consulta la tabla canónica: Taxonomía de fallos (13 clases de runtime).

Qué hace

• Los límites de presupuesto detienen el siguiente intento antes de que se exceda un límite configurado de USD, tokens o iteraciones.
• Las compuertas de verificador requieren una comprobación real, como npm test, antes de que una ejecución pueda contarse como completa.
• Las comprobaciones de política bloquean comandos de verificador inseguros, cambios de ruta riesgosos y entradas de tarea similares a secretos antes de la ejecución.
• La clasificación de fallos usa clases de runtime canónicas para triaje e informes. Consulta Taxonomía de fallos (13 clases de runtime).
• Los recibos de ejecución capturan el motivo de detención, la evidencia del verificador, la postura del presupuesto, el estado de integridad y la siguiente acción segura.
• martin share --latest convierte la última ejecución gobernada en un paquete de intercambio local con un recibo JSON redactado, un resumen en Markdown y una tarjeta SVG de prueba.
• La integración MCP otorga a los hosts un punto de entrada de ejecución con capacidad de escritura, además de ayudas más ricas de planificación, inspección y revisión.

Cómo funciona

Capa	Propósito
Contrato de tarea	Objetivo, plan de verificador, raíz del repositorio, rutas permitidas, rutas denegadas, criterios de aceptación, espacio de trabajo, proyecto y presupuesto.
Política y presupuesto	Los valores predeterminados provienen de martin.config.yaml; las banderas de CLI pueden anularlos. El preflight de presupuesto bloquea intentos que excederían la política.
Adaptadores de agente	Los adaptadores de Claude CLI, Codex CLI, Gemini CLI y proveedor directo normalizan los resultados de ejecución.
Seguridad y verificación	Las comprobaciones de alcance, las comprobaciones de comandos del verificador, la integridad del prompt y la fundamentación deciden si el trabajo puede continuar.
Persistencia	Registros de ejecución JSONL, resúmenes de evidencia y artefactos respaldados por el repositorio hacen que cada ejecución sea inspeccionable más tarde. Cada registro de bucle está firmado localmente (HMAC, clave por raíz de ejecuciones) y dossier/runs get/runs verify/challenge/badge informan un veredicto integrity (verified / tamper_detected / unsigned) para que las ediciones posteriores a un registro sean detectables, no solo inspeccionables.

Límites de confianza

• Las salidas de costo y tokens siempre incluyen procedencia (actual, estimated o unavailable).
• Para Codex específicamente, MartinLoop informa el uso autoritativo solo cuando el host lo expone; de lo contrario, MartinLoop etiqueta el uso como estimado y evita presentarlo como contabilidad definitiva.
• La integridad del recibo debe ser verified antes de que una ejecución se trate como evidencia confiable para revisión externa.

CLI

martin-loop doctor
martin-loop demo
martin-loop session-start [--host <claude|codex|gemini|generic>]
martin-loop phase status|contract|session-start|preflight|run [--execute]
martin-loop preflight <objective> [options]
martin-loop run <objective> [options]
martin-loop bench --suite <suiteId>
martin-loop triage
martin-loop dossier (--latest | --loop-id <id> | --file <path>)
martin-loop runs list|get|attempt|verify ...
martin-loop mcp print-config --host <codex|claude|gemini|generic>
martin-loop mcp install --host <codex|claude|gemini|generic>
martin-loop challenge [--loop-id <id> | --file <path> | --latest]
martin-loop share (--loop-id <id> | --file <path> | --latest) [--out-dir <path>]
martin-loop badge [--format svg|json] [--runs-dir <path>]

Opciones comunes:

--budget <n>            Hard cost cap in USD
--budget-usd <n>        Alias for --budget
--soft-limit-usd <n>    Soft budget threshold in USD
--verify <cmd>          Verifier command after each attempt
--proof                 Explicitly opt into a no-spend proof adapter lane
--max-iterations <n>    Maximum number of attempts
--max-tokens <n>        Maximum token budget
--engine <name>         Adapter to use: claude, codex, gemini, or openai
--cwd <path>            Repo root for the run
--allow-path <glob>     Restrict writes to this path pattern; repeatable
--deny-path <glob>      Block this path pattern; repeatable
--runs-dir <path>       Override the local Martin runs root

Los ejemplos a continuación usan npx martin-loop para que funcionen sin una instalación global. Si instalas martin-loop globalmente, el alias martin también funciona.

Usa martin-loop share --latest después de dossier cuando quieras un paquete redactado que puedas entregar a otra persona sin enviar archivos crudos del almacén de ejecuciones.

Más detalles: referencia de CLI y referencia de configuración.

Benchmarks

MartinLoop incluye un espacio de trabajo de benchmark público determinista en benchmarks/ más el comando bench del paquete instalado.

Desde un paquete instalado:

npx martin-loop bench --suite under-3-challenge
npx martin-loop bench --suite ralphy-engineering-50

Desde un clon público limpio:

pnpm install --frozen-lockfile
pnpm bench:build
pnpm bench:eval
pnpm bench:report:ralphy

Comandos equivalentes de filtro de espacio de trabajo:

pnpm --filter @martin/benchmarks build
pnpm --filter @martin/benchmarks test
pnpm --filter @martin/benchmarks eval
pnpm --filter @martin/benchmarks report:ralphy

El comando del paquete instalado lee los fixtures públicos incluidos. El flujo de trabajo de clon del repositorio ejecuta el espacio de trabajo de benchmark público directamente.

MCP

Ejecuta el paquete MCP independiente directamente:

npx -y @martinloop/mcp

Añádelo a hosts comunes:

codex mcp add martin-loop -- npx -y @martinloop/mcp
claude mcp add --transport stdio --scope user martin-loop -- npx -y @martinloop/mcp
claude mcp add --transport stdio --scope user martin-loop -- cmd /c npx -y @martinloop/mcp

Genera la configuración del host desde la CLI raíz:

npx martin-loop mcp print-config --host codex --transport stdio --profile minimal
npx martin-loop mcp print-config --host claude --transport stdio --profile diagnostic
npx martin-loop mcp print-config --host gemini --transport stdio --profile full-local
npx martin-loop mcp print-config --host generic --transport stdio --profile github-review

El paquete raíz martin-loop y el paquete independiente @martinloop/mcp están avanzando ambos a 0.5.0 en esta versión. Sus líneas de versión pueden moverse de forma independiente en versiones futuras.

Las etiquetas públicas del tren de lanzamiento MCP son:

• 0.1.4 base del operador
• 0.2.0 expansión de cockpit
• 0.2.5 línea de paquete MCP público
• 0.2.7 versión de usabilidad y revisión
• 0.3.0 versión de adopción e incorporación de hosts
• 0.3.1 versión de revisión y entrega

El identificador de registro/servidor MCP independiente es io.github.Keesan12/martin-loop.

Más detalles: configuración de MCP, referencia de herramientas MCP y compatibilidad de MCP.

SDK

npm install martin-loop

import { MartinLoop, createClaudeCliAdapter } from "martin-loop";

const loop = new MartinLoop({
  adapter: createClaudeCliAdapter({ workingDirectory: process.cwd() }),
  defaults: {
    workspaceId: "my-workspace",
    projectId: "my-project",
    budget: {
      maxUsd: 3,
      softLimitUsd: 2.25,
      maxIterations: 3,
      maxTokens: 20_000,
    },
  },
});

const result = await loop.run({
  task: {
    title: "Fix auth regression",
    objective: "Fix the failing auth regression tests",
    verificationPlan: ["pnpm test"],
    repoRoot: process.cwd(),
  },
});

console.log(result.decision.status);

El SDK raíz también exporta createCodexCliAdapter, createGeminiCliAdapter, createDirectProviderAdapter y createOpenAiCompatibleAdapter.

Más detalles: referencia del SDK y mapa de paquetes.

Ejemplos

• Inicio rápido
• Ejemplos
• Atlas de fallos de agentes
• Taxonomía de fallos (13 clases de runtime)
• PRE-028-PUBLIC-SURFACE-DIFF.md
• Recorrido por Claude Code
• Configuración de Codex
• Configuración de MCP
• Referencia de herramientas MCP
• Recibos de ejecución de agentes
• Página de benchmark + recibos
• Compuerta de presupuesto de GitHub Actions
• Adaptador estilo OpenCode

Desarrollo

Requisitos:

• Node.js 20+
• pnpm 10.x

git clone https://github.com/Keesan12/martin-loop.git
cd martin-loop
pnpm install --frozen-lockfile
pnpm lint
pnpm test
pnpm build
pnpm public:copy-scan
pnpm public:git-surface
pnpm oss:validate
pnpm public:smoke
pnpm release:matrix:local

Validación MCP independiente:

pnpm --filter @martinloop/mcp lint
pnpm --filter @martinloop/mcp test
pnpm --filter @martinloop/mcp build
pnpm --filter @martinloop/mcp smoke:pack
pnpm --filter @martinloop/mcp smoke:published:pack
pnpm --filter @martinloop/mcp verify:release

Contribuciones

Los issues, informes de errores, comentarios sobre flujos de trabajo y pull requests enfocados son bienvenidos. Los documentos públicos deben mantenerse concisos, centrados en el usuario y precisos.

git checkout -b feat/your-feature
pnpm lint
pnpm test
git commit -m "feat: describe what you built"
git push -u origin feat/your-feature

Dale una estrella a este repositorio si crees que la codificación con IA necesita presupuestos, frenos y recibos.

martinloop.com · support@martinloop.com

MartinLoop forma parte del programa NVIDIA Inception.

Telemetría y Privacidad

MartinLoop envía datos de uso anónimos mínimos para ayudar a mejorar la fiabilidad y priorizar el desarrollo. Aparece un aviso en el primer uso antes de que se transmita cualquier dato. No se envía ningún dato en esa primera ejecución.

Qué se envía:

• ID de instalación aleatorio (generado localmente, nunca vinculado a tu identidad)
• ID de sesión por proceso
• Versión de CLI, versión de Node, sistema operativo y arquitectura
• Nombre del evento y marca de tiempo
• Categoría de comando, duración de la ejecución, categoría de éxito/fallo
• Si se generó un recibo; si se produjo una recuperación
• ID/tipo de experiencia remota opaco después de un clic

Qué nunca se envía:

• Código fuente, indicaciones, texto de tareas, contenido del repositorio, nombres de archivos, rutas de archivos
• Variables de entorno, secretos, salida del proveedor/modelo
• Contenido de recibos, contenido del libro mayor, detalles de aprobación, evidencia del verificador
• Direcciones de correo electrónico, espacio de trabajo, proyecto o identificadores de organización
• Mensajes de excepción sin procesar o seguimientos de pila

Punto final: https://tupopqvqnyyjuxseyxkr.supabase.co/functions/v1/product-events

Cabeceras enviadas: Content-Type: application/json, User-Agent: MartinLoop-CLI/<version>

Sin cabecera de autorización, clave de API ni acceso directo a tablas.

Exclúyete en cualquier momento:

martin telemetry off

Inspecciona lo que se envía:

martin telemetry explain

Variables de entorno que desactivan la telemetría: MARTIN_TELEMETRY_DISABLED=1, DO_NOT_TRACK=1, CI=1

MartinLoop sigue funcionando con normalidad con la telemetría desactivada. Ninguna función depende del consentimiento de telemetría.

Licencia

Apache-2.0. Consulta LICENSE.