Ducklab

Un harness de desarrollo de software de ciclo completo que es multi-LLM por defecto y honesto por construcción.

En un bloque: harness de desarrollo autoalojado (motor Go + CLI + escritorio, Linux primero) · brief → requisitos → especificación → plan → build → revisión → release · los veredictos son códigos de salida, nunca opiniones de modelos · modelos locales primero (llama.cpp, vLLM) junto a cualquier endpoint compatible con OpenAI o Anthropic · operable por humanos o por otros agentes a través de MCP con decisiones registradas y atribuidas · Apache-2.0 · se desarrolla a sí mismo (los registros en .ducklab/ son los recibos). Agentes: comiencen en AGENTS.md y llms.txt.

Le das un brief. Escribe requisitos, una especificación y un plan; construye tareas con un modelo o varios discutiendo; ejecuta la puerta de pruebas real de tu proyecto; y se detiene para ti antes de que se confirme nada. Cada llamada de modelo queda registrada. Ningún modelo decide jamás un veredicto.

Fue construido para modelos locales primero — los dos que construyeron la mayor parte son una caja vLLM en la LAN y un servidor llama.cpp en localhost, ambos a precio cero — y los modelos alojados se sientan junto a ellos en el mismo roster, medidos por la misma evidencia.

Por qué existe

La mayoría de las herramientas de codificación agénticas asumen un modelo fuerte y confían en él. Ducklab asume varios modelos baratos y no confía en ninguno de ellos:

• La puerta decide, nunca un modelo. Un veredicto es el código de salida de un comando. Una ejecución primero mide una línea base verde antes de que se escriba ninguna prueba, el rojo sobre la nueva prueba después, y cada aceptación reproduce la puerta desde un checkout limpio del sha confirmado — nada llega que no se haya reproducido, y una aceptación cuya reproducción falla se lleva su propio commit de vuelta.

• Descorrelación en todas partes. Un modelo diferente revisa; un revisor nunca aprende quién escribió el código (ausente del payload, no oculto en la interfaz); los jueces del torneo eligen a ciegas; los críticos del consejo leen el borrador, no entre sí.

• El trabajo es un contrato. Los entregables de una tarea son la lista de verificación numerada del implementador; informa sobre cada uno por número, el revisor verifica cada uno contra el diff, y un elemento no entregado convoca al pato de goma — un asiento de asesor que se despierta solo ante angustia medida (negativas de freno, rachas de fallos, puertas rojas) y responde none, una nota que envía al implementador directamente de vuelta al trabajo, o stop.

• Los asientos se eligen con evidencia. Cada patito lleva una tarjeta de puntuación — tasa de aprobación en el asiento de tus propias ejecuciones, coste por ejecución, índice de codificación — y el tablero de roster sugiere asientos a partir de ella, con los criterios de clasificación tuyos para reordenar. Las sugerencias son raras y justificadas: las tasas de aprobación se clasifican por su límite inferior de Wilson, mínimo tres ejecuciones, los locales nunca ganan por un precio de $0.

• Nada es ilimitado. Turnos, tokens, coste, tiempo de pared, salida de herramientas, comandos de shell — cada techo visible y elevable a mitad de ejecución, en el registro.

• Tu documentación no está limitada por la ventana del modelo. Adjunta una wiki a una etapa y un asiento grande la lee entera; un asiento pequeño recibe cada documento digerido para que quepa, el texto completo a una llamada ref_read de distancia, y la puerta nombra cualquier documento que nadie abrió. Un modelo local de 32k puede recibir el brief de un cuarto de millón de caracteres de material de referencia — el harness lleva la memoria de trabajo.

Y la prueba de existencia: ducklab se desarrolla dentro de ducklab. El plan, los errores, los releases y las últimas noventa y tantas tareas aceptadas pasaron por su propio bucle, impulsado por los mismos modelos locales y alojados que mide — las características más recientes (el chat multimodal, el asiento de consultor, el historial de ejecuciones de la guía) fueron construidas por el pato, con la puerta de una persona.

Related MCP server: Loki Mode

Estado

v0.6.1+, avanzando rápido. Siete etapas, cinco modos, el tablero de roster con evidencia y sugerencias, documentos de referencia con digestión automática, habilidades gestionadas desde el escritorio, un consultor sentado con el que puedes chatear (imágenes incluidas, visión verificada antes de enviarlas), errores con evidencia de captura de pantalla, releases, autopiloto, un CLI, una aplicación de escritorio y un servidor MCP que permite a otro modelo operar todo el bucle con decisiones registradas y atribuidas.

docs/status.md rastrea todos los criterios de aceptación y no redondea. Donde el código y la especificación difieren, la diferencia se registra en docs/decisions/.

Instalación

Necesita Go 1.25+, Node 22+ para el escritorio, y git.

Linux

El CLI y el motor son Go puro. El escritorio es una aplicación Wails v3 y necesita los paquetes de desarrollo GTK/WebKit:

sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev   # Debian/Ubuntu names
make desktop && make install

En Ubuntu 24.04+ el escritorio también necesita un perfil de AppArmor — ver decisión 0003 y packaging/apparmor/.

macOS

xcode-select --install    # the desktop build links against WebKit
brew install go node
make desktop && make install

Nota de honestidad: ducklab se desarrolla y se ejercita a diario en Linux. El CLI y el motor compilan para darwin/arm64 en cada make cross, pero ninguna compilación de escritorio se ha verificado en un Mac todavía — la primera persona que lo pruebe es la prueba, y make install te da el CLI y el motor de cualquier manera. Por favor, informa de lo que se rompa.

Ambos

make install instala en ~/.local/bin — asegúrate de que esté en tu PATH. Avisa cuando el binario de escritorio sea anterior a frontend/src, porque instalará felizmente uno obsoleto.

Tres binarios

Las claves de los proveedores provienen del entorno del motor en el momento de la llamada — expórtalas antes de que se inicie, o lanza el escritorio a través de un wrapper que las cargue desde tu llavero. La aplicación te dice cuando el motor que adoptó carece de una clave que esta aplicación tiene, con el botón de reinicio junto a las palabras.

Un ciclo, de principio a fin

Desde el escritorio: Proyectos → Nuevo proyecto, luego Ciclo → Redactar. Desde una terminal:

cd ~/dev/myproject
git init                                    # ducklab needs a git repo
ducklab project init --name MyProject       # auto-starts the engine if none is running

ducklab intake --from brief.txt             # brief        → requirements
ducklab spec                                # requirements → spec
ducklab plan                                # spec         → milestones and tasks

ducklab run T-001                           # build it
ducklab run accept r-20260729-...           # commit it

ducklab review T-001                        # read the commit
ducklab release plan --bump minor           # what shipped

Cada etapa escribe un archivo .proposed primero y espera por ti. accept lo promueve; reject restaura exactamente lo que la ejecución escribió y nada más; "solicitar cambios" envía cualquier borrador — especificación, plan, notas de release — de vuelta con tu nota. Nada se confirma sin ti (o sin el nivel de autonomía que otorgaste explícitamente).

Los documentos de referencia acompañan cualquier etapa: --ref ~/wiki/product/ (o la puerta de adjuntar en el escritorio) carga archivos o directorios completos como fondo para el arquitecto — fundamentado por dos reglas que el prompt declara explícitamente: los requisitos aprobados poseen el alcance, y donde una referencia y el código discrepan, el código es la verdad. Cuando el corpus supera el contexto del asiento, cada documento se digiere una vez (cacheado por hash de contenido), el texto completo sigue siendo accesible a través de la herramienta ref_read, y la tarjeta de propuesta lista cualquier documento que ningún asiento haya abierto jamás.

Adoptar un codebase existente funciona de la misma manera: la admisión lee el código y escribe requisitos tal como están construidos, la especificación marca sus secciones as-built, y el plan permanece deliberadamente vacío — el nuevo trabajo entra entonces a través de informes de errores y enmiendas al plan, que es como se desarrolla el propio ducklab.

Tu proyecto declara su propia verdad en .ducklab/project.toml: la puerta ([verify] — con link_deps y setup para lo que un checkout limpio necesita), cómo se lanza la aplicación ([run] con un preflight), y cómo se reconstruyen los binarios propios del proyecto ([install]) para que todo el bucle funcione sin salir de ducklab.

Añadir un modelo

ducklab provider set openrouter --url https://openrouter.ai/api/v1 \
                                --key-env OPENROUTER_API_KEY
ducklab duckling set pato-sonnet --provider openrouter \
                                 --model anthropic/claude-sonnet-4.5 \
                                 --roles reviewer,judge --context 200000 \
                                 --cost-in 3.0 --cost-out 15.0
ducklab duckling test pato-sonnet --prompt "say OK"

--key-env es el nombre de una variable de entorno, nunca una clave. Ninguna clave se escribe en la configuración, se envía por la API, ni se guarda en el historial del shell.

La vista Roster del escritorio es donde se asignan los asientos: arrastra desde la Bandada a un asiento de modo, global o por proyecto, con la evidencia de cada patito en la tarjeta y las sugerencias del motor junto a los asientos. Los índices de codificación / inteligencia / agéntico provienen del endpoint de benchmarks de OpenRouter cuando un patito vive allí; tus propias ejecuciones suministran el resto.

Los cinco modos

ducklab run T-001 --mode <modo>

Lo que no hará

Estas son estructurales, no preferencias.

• Un modelo nunca decide un veredicto. Una puerta es el código de salida de un comando.

• Un candidato verde se aplica byte por byte. Nada se regenera después de que pasó.

• Un revisor nunca aprende quién escribió el código.

• Nada llega que no se haya reproducido desde un checkout limpio.

• Un rechazo deshace lo que la ejecución escribió, y el trabajo de nadie más.

• Nada es ilimitado.

• Los secretos nunca tocan el estado del proyecto.

• El motor es solo de bucle local. No hay modo remoto.

Habilidades

Una habilidad es un directorio con un SKILL.md — bajo .ducklab/skills/ para un proyecto, o en el directorio de habilidades de toda la máquina para servir a cada proyecto (el proyecto sombrea lo global en una colisión de nombres). La forma solo de documentación no tiene script y es la predeterminada: una receta que un modelo lee y sigue. El arquitecto lee guías de encuesta antes de una adopción (skill_list está en su prompt), el consultor las lee en el chat, y solo el implementador puede skill_run una ejecutable.

Las habilidades se administran desde el escritorio (engranaje → Habilidades): lista con insignias de alcance y problemas de validación, leer, editar todo el SKILL.md, ejecutar con argumentos, eliminar. Una habilidad que un patito escribe durante una ejecución se muestra allí atenuada pendiente de aceptación hasta que su ejecución sea aceptada — proponer una habilidad pasa por la misma puerta que proponer código.

ducklab skill new house-style
ducklab skill run changelog-entry --arg summary="..."

El consultor

Cada proyecto cuenta con un consultor (un asiento Common en el tablero de roster): el modelo que hay detrás de las puertas de «chatear sobre esto» y del chat libre en la barra guía. Lee el código, las ejecuciones, los tableros y las habilidades — nunca escribe — y acepta imágenes: pega una captura de pantalla de una vista rota y pregunta. La visión se verifica, no se asume: un asiento con visión declarada se pone a prueba una vez con una petición de imagen real, y un asiento de solo texto rechaza el pegado con palabras en lugar de alucinar una respuesta.

Usar ducklab desde otro modelo

ducklab mcp serve exponne todo el bucle sobre stdio como un servidor MCP: un modelo externo lee cada resulta and decide cada punto de control (con un motivo obligaciónio y registrado — las decisiones se recan como approved_by: mcp:`, nunca como "human"), respuenda pregunate, abres errores, modifica los planes e inicia fruto. Las listrutas next del motor serán solo unana: un operador no puede hacer nada de lo que una persna no podrá hacer.

MONTRIButing

Ver CONTRIBUTING.md: cómo se compila and how the tests are protect the arquitectura, cómo fluye el trbajo a ⇢ mediante el propio bucle de ducklab and ¿por dónde empeyar. The shortened version:

make            # vet, test, build the frontend
go test ./...   # 38 packages
cd frontend && npx vitest run

Licencia: Apache-2.0. Contribuciones species in the same manner (§5 de licencia — sin CLA). El nombre Ducklab y el polyto son del mantenedor (§6).

Especification

El código implementa una especificación escrita, en ese repo: docs/spec/ (00-VISION a 08-DESKTOP-UI) is la norma — visión, invariant, protocolo contract and acceptance criteria. What every system today live in .ducklab/docs/ — the building requirements, specficación, and plan that the duck loop itself, each version signed at a human gate. If the two differ in flexibility, the difference is stored in docs/decisions/; thediff between the two is the roadmap, and the alignment stage has them arbitrarily calculate.