Cómo instalar y usar Open GSD (gsd-pi) con un modelo local

Esta guía instala gsd-pi 1.20.1, el agente de terminal de Open GSD, y lo conecta a un modelo local servido por llama.cpp. Después le encarga una tarea real en un repositorio Git desechable. También explica qué es gsd-core, qué comandos buscas cuando lo usas por primera vez y los siete trucos que aprendí por el camino. Todo se probó el 30 de septiembre de 2026 en Linux arm64 con Docker. El 2 de octubre salió la 1.21.0; revisé su código y el temporizador de 15 s del modo headless sigue igual, también en la 1.21.1 del 7 de octubre.

Puntos clave

• gsd-pi es el agente de terminal (comando gsd) y gsd-core es un paquete de comandos y skills que se instala dentro de Claude Code, OpenCode, Codex o Cursor.
• Se instala con npx @opengsd/gsd-pi@latest; el paquete sin ámbito gsd-pi (versión 3.0.0) está retirado de npm y no es el bueno.
• Funciona sin clave de API: con un models.json apuntando a llama.cpp, un Qwen3.5 de 4B cerró una tarea con 12 tests en verde y un commit.
• Cada petición arranca con unos 29.400 tokens de instrucciones, así que el modelo necesita una ventana de contexto de 64k.
• gsd quick en modo headless da por terminada la sesión tras 15 s sin eventos; con un modelo lento en CPU, usa la interfaz interactiva.

Qué son gsd-pi y gsd-core, y cuál instalar

Open GSD publica dos paquetes que se confunden porque comparten el lema «Git. Ship. Done.»: uno es un agente completo y el otro un conjunto de instrucciones para el agente que ya usas.

Nuestro artículo qué es Open GSD repasa el catálogo completo a 9 de octubre de 2026, con gsd-graph, gsd-loop y gsd-path incluidos.

La regla práctica es esta: si ya trabajas con Claude Code u OpenCode y quieres su método, instala gsd-core. Si quieres un agente propio que puedas apuntar a cualquier proveedor, incluido un modelo local, instala gsd-pi. El «Pi» del nombre tiene origen concreto: el package.json de sus paquetes internos dice que el núcleo del agente y la TUI están «vendored from earendil-works/pi», el arnés de agentes Pi^[1].

El README del proyecto lo define así:

«GSD Pi is a local-first coding agent for planning, implementing, verifying, and tracking project work from the command line.» (README de open-gsd/gsd-pi)

Qué necesitas antes de instalar gsd-pi

gsd-pi exige Node.js 22.18.0 o superior, Git 2.20 o superior y un proveedor de modelos. Yo usé un contenedor node:24-bookworm-slim (Node 24.21.0, npm 11.19.0, Git 2.39.5) para no ensuciar el equipo, porque el instalador escribe en el directorio global de npm y en ~/.gsd.

Si no tienes clave de API, el proveedor puede ser un servidor local con API compatible con OpenAI. La documentación de proveedores cubre Ollama, LM Studio, vLLM y SGLang; llama.cpp entra por la misma puerta. Si todavía no lo tienes, sigue antes la guía para instalar llama.cpp en Linux, macOS y Docker.

Cómo instalar gsd pi paso a paso

El instalador guiado se lanza con npx y, con --yes, no pregunta nada. Como mi usuario no era root, primero apunté el prefijo global de npm a mi carpeta personal:

export NPM_CONFIG_PREFIX="$HOME/.npm-global"
npx -y @opengsd/gsd-pi@1.20.1 --yes
export PATH="$HOME/.npm-global/bin:$PATH"
gsd --version

El instalador puso el paquete en el directorio global y enlazó 14 paquetes del espacio de trabajo. Después descargó un Chromium de Playwright para automatizar el navegador e intentó instalar RTK, una utilidad externa que resume la salida de la shell. En arm64 terminó con RTK: binary validation failed, un aviso sin consecuencias: el resto siguió y cerró con Verified gsd v1.20.1.

El espacio en disco sorprende la primera vez: 771 MB en el directorio global de npm y 662 MB de Chromium en ~/.cache/ms-playwright. El paquete deja cuatro ejecutables: gsd, gsd-cli, gsd-pi y gsd-mcp-server. Al primer arranque descarga además ripgrep a ~/.gsd/agent/bin/rg si no lo encuentra en el sistema.

Cómo conectar gsd-pi a un modelo local con llama.cpp

gsd-pi lee los proveedores locales de ~/.gsd/agent/models.json y recarga el fichero cada vez que abres /model. Levanté llama-server (build b11206) en Docker con la plantilla de chat del modelo (--jinja), 64k de contexto y el razonamiento desactivado:

services:
  llama:
    image: ghcr.io/ggml-org/llama.cpp:server-b11206
    volumes:
      - ./models:/models:ro
    command: >
      -m /models/Qwen_Qwen3.5-4B-Q4_K_M.gguf
      --alias qwen3.5-4b --host 0.0.0.0 --port 8080
      -c 65536 --jinja -t 6 --parallel 1 --reasoning off

El models.json declara el servidor como un proveedor más. El campo apiKey es obligatorio aunque llama.cpp no lo compruebe, y los dos ajustes de compat evitan que gsd-pi envíe el rol developer y el parámetro reasoning_effort, que los servidores locales no entienden:

{
  "providers": {
    "llamacpp": {
      "baseUrl": "http://llama:8080/v1",
      "api": "openai-completions",
      "apiKey": "not-needed",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        { "id": "qwen3.5-4b", "name": "Qwen3.5 4B (llama.cpp)",
          "contextWindow": 65536, "maxTokens": 8192 }
      ]
    }
  }
}

Comprueba que gsd-pi lo ve antes de abrir una sesión. El id tiene que coincidir con el alias que publica el servidor en /v1/models:

$ gsd --list-models llamacpp
provider  model       name                    context  max-out  thinking  images
llamacpp  qwen3.5-4b  Qwen3.5 4B (llama.cpp)  65.5K    8.2K     no        no

El tamaño de la ventana no es un detalle. La primera petición de la tarea rápida ocupó 29.425 tokens entre instrucciones, definiciones de herramientas y mi orden, y la sesión terminó ocupando 37k de los 66k disponibles. Con un modelo de 32k de contexto no cabe ni el arranque.

Una tarea real de principio a fin con gsd quick

Para probarlo creé un repositorio con una función slugify() que solo cambiaba espacios por guiones y un test. La tarea: quitar tildes y agrupar espacios y signos en un único guion. Primero abre gsd en el repositorio, porque ese primer arranque crea .gsd/, y después lanza la tarea desde la propia sesión:

cd demo
gsd --model llamacpp/qwen3.5-4b
# dentro de la sesión, en una sola línea:
/gsd quick Make slugify() in slug.py strip accents (Mundo Ñandú
  becomes mundo-nandu) and collapse runs of spaces and punctuation
  into one hyphen. Add tests to test_slug.py and run python3 -m unittest.

gsd-pi convirtió la orden en la tarea rápida número 1, creó .gsd/quick/1-make-slugify-in-slug-py-strip-accents-mu/ y le pasó al modelo instrucciones fijas: leer el código, escribir tests, verificar, hacer commits atómicos con mensajes convencionales y dejar un 1-SUMMARY.md. En 20 peticiones al modelo, el agente leyó los ficheros y falló una edición, así que reescribió el fichero entero. Luego probó una expresión regular con \p{}, que el módulo re de Python no admite, la sustituyó y dejó 12 tests pasando.

Estas son las comprobaciones que hice por mi cuenta después, fuera de gsd-pi:

$ git log --oneline
ba7a16a feat: enhance slugify() to strip accents and collapse
        punctuation into hyphens
50e1729 initial
$ python3 -m unittest 2>&1 | tail -1
OK
$ python3 -c 'import slug; print(slug.slugify("Canción del año, 2026"))'
cancion-del-ano-2026

El commit tocó dos ficheros con 116 líneas añadidas y 2 borradas, directamente sobre main: las tareas rápidas no abren worktree ni rama. Revisar el diff sigue siendo trabajo tuyo. El docstring que escribió el modelo documenta "mundonandu" y "helloworld" como salidas, justo lo contrario de lo que hace el código, y "straße" sale sin transliterar. Los tests pasan porque prueban el código, no el comentario.

Antes de dar con el modelo de 4B probé Nex-N2.5-mini, un MoE de 34.660 millones de parámetros que ocupa 22 GB en Q4_K_M. Con otros procesos en la misma máquina de 47 GB, el servidor empezó a tirar de swap y la generación se volvió inservible. Para gsd-pi en CPU compensa un modelo que quepa con holgura en la RAM libre.

Comandos y opciones de gsd que más vas a usar

gsd-pi tiene dos superficies: los flags del ejecutable en la shell y los comandos /gsd dentro de la sesión. Estos son los que usé o los que la documentación recomienda para empezar:

Los códigos de salida del modo headless son 0 (completado), 1 (error o tiempo agotado), 10 (bloqueado) y 11 (cancelado). Con --output-format json el resultado final incluye la rama, los commits y los artefactos creados.

Cómo instalar gsd-core en tu agente de programación

gsd-core no es un agente: copia comandos, subagentes, skills y hooks en la carpeta de configuración de la herramienta que ya usas. Lo instalé para OpenCode en modo local, dentro de un repositorio vacío:

npx -y @opengsd/gsd-core@1.15.0 --opencode --local

El resultado fueron 899 ficheros bajo .opencode/: 72 comandos, 64 agentes, 72 skills y 30 hooks, además del motor gsd-core/bin. El instalador avisó de que las 72 skills «tapan» a los 72 comandos del mismo nombre, que es el comportamiento esperado. Para Claude Code el equivalente es --claude --global, y después se arranca con /gsd-new-project o /gsd-onboard. Si usas OpenCode con un modelo local, la guía de OpenCode con llama.cpp y Ollama cubre la otra mitad.

Trucos que aprendí al instalar y usar gsd-pi

Ninguno de estos trucos es imprescindible para instalarlo, pero todos te ahorran tiempo si los conoces de antemano:

1. El paquete equivocado. npm install -g gsd-pi trae la versión 3.0.0, marcada como no soportada. La buena es @opengsd/gsd-pi y su numeración empezó de nuevo en 1.0.0. Si tienes la antigua, desinstálala y borra ~/.gsd/.update-check y ~/.gsd/agent/managed-resources.json.
2. gsd no aparece. El directorio bin global de npm no está en el PATH. En oh-my-zsh, el plugin gitfast define un alias gsd para git svn dcommit; compruébalo con alias gsd.
3. El modo headless necesita .gsd/. En un repositorio recién creado, gsd headless quick falla con No .gsd/ directory found in current directory. Abre gsd una vez antes.
4. El temporizador de 15 s del modo headless. Tras la primera llamada a una herramienta, gsd headless quick da la sesión por acabada si pasan 15 s sin eventos, aunque pases --timeout 0. Con Nex-N2.5-mini en CPU terminó con status: timeout, 3 llamadas a herramientas y 0 commits. La constante IDLE_TIMEOUT_MS = 15_000 está en dist/headless-events.js; el modo auto no la aplica.
5. Los ficheros de estado no se ignoran solos en una tarea rápida. Tras la tarea, git status seguía mostrando .gsd/ y .bg-shell/ sin seguimiento. Añádelos a .gitignore o revisa el git add antes de cada commit tuyo.
6. gsd-core toca la configuración global. Incluso con --local, el instalador escribió ~/.gsd/defaults.json, el mismo directorio que usa gsd-pi. Un rm -rf ~/.gsd para desinstalar uno se lleva la configuración del otro.
7. El razonamiento multiplica la salida. Qwen3.5 piensa por defecto: a un simple «Say pong» devolvió un bloque entero de reasoning_content antes de «Pong». Con --reasoning off en llama-server contesta directamente.

Preguntas frecuentes

¿gsd-pi funciona sin clave de API?

Sí. Los proveedores locales (Ollama, LM Studio, vLLM, SGLang o cualquier servidor compatible con la API de OpenAI, como llama.cpp) solo necesitan una entrada en ~/.gsd/agent/models.json con un apiKey de relleno. Lo que no puedes esperar es la calidad de Claude o GPT de un modelo de 4B: cerró la tarea, pero con errores que hay que revisar.

¿Qué diferencia hay entre gsd pi y gsd core?

gsd-pi es un agente completo con su propia interfaz, base de datos de proyecto y selección de modelo. gsd-core es un paquete de instrucciones que se instala dentro de otro agente (Claude Code, OpenCode, Codex, Cursor y otros) y añade comandos /gsd-*. Puedes usar los dos, pero comparten ~/.gsd.

¿Qué significa Git Ship Done?

Es el lema de Open GSD y el nombre que muestra la ayuda de gsd («GSD v1.20.1, Git Ship Done»). El GSD original lo creó Lex Christopherson, conocido como TÂCHES, y su paquete npm get-shit-done-cc sigue publicado; la web de Open GSD le reconoce ese origen en su página de créditos.

Conclusión

gsd-pi se instala con un comando y funciona con un modelo local si le das 64k de contexto y un models.json bien escrito. Para una primera prueba, abre gsd, lanza /gsd quick sobre un repositorio limpio y revisa el diff como revisarías el de un compañero nuevo. Si lo vas a automatizar en CI con un modelo lento, ten en cuenta el temporizador de 15 s del modo headless. El contexto de qué problema resuelve Open GSD está en qué es Open GSD, y esta guía también está en inglés.

Fuentes: [1] README de gsd-pi en GitHub^[2], [2] @opengsd/gsd-pi en npm^[3], [3] README de gsd-core^[4], [4] Open GSD, página de origen^[5], [5] Pi agent harness^[1], [6] llama.cpp^[6].

Fuentes

1. arnés de agentes Pi
2. README de gsd-pi en GitHub
3. @opengsd/gsd-pi en npm
4. README de gsd-core
5. Open GSD, página de origen
6. llama.cpp