Docs

Pi

Pi es un agente de terminal deliberadamente pequeño: un shell mínimo que se adapta a cómo trabajas en vez de imponer cómo trabaja él. Habla el formato de OpenAI, así que Helmcode entra como un proveedor más.

Se instala con curl -fsSL https://pi.dev/install.sh | sh, o en Windows con powershell -c "irm https://pi.dev/install.ps1 | iex".

Configuración

1. Declara el proveedor

En ~/.pi/agent/models.json:

{
  "providers": {
    "helmcode": {
      "baseUrl": "https://api.helmcode.com/v1",
      "api": "openai-completions",
      "apiKey": "sk-your-key-here",
      "compat": { "supportsDeveloperRole": true },
      "models": [
        {
          "id": "deepseek-v4-flash",
          "name": "DeepSeek V4 Flash",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 1048576,
          "maxTokens": 32768
        },
        {
          "id": "glm5.3",
          "name": "GLM 5.3",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 1048576,
          "maxTokens": 32768
        },
        {
          "id": "glm5.3-flash",
          "name": "GLM 5.3 Flash",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 1048576,
          "maxTokens": 32768
        },
        {
          "id": "qwen3.6",
          "name": "Qwen 3.6",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 262144,
          "maxTokens": 32768
        },
        {
          "id": "gemma4",
          "name": "Gemma 4",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 262144,
          "maxTokens": 32768
        }
      ]
    }
  }
}

api: "openai-completions" es lo que le dice a Pi qué formato hablar. maxTokens es el techo de una respuesta, no el contexto — la misma cifra que el bloque de OpenCode publica como limit.output, porque responde a la misma pregunta.

2. Déjalo por defecto

En ~/.pi/agent/settings.json:

{
  "defaultProvider": "helmcode",
  "defaultModel": "glm5.3-flash"
}

Una sesión interactiva necesita un modelo por defecto, y lo dice. Sin defaultModel, lo primero que te suelta Pi nada más conectarte es:

Error: Saved API key for helmcode, but no default model is configured for
provider "helmcode". Use /model to select a model.

Puedes hacerle caso y elegir con /model en cada sesión, o escribirlo aquí una vez. Pi no persiste tu elección: el settings.json que escribe él solo lleva el tema y nada más.

El headless es la excepción — pi -p resuelve un modelo sin este fichero. Y si declaras un segundo proveedor sin fijar defaultProvider, Pi elige por ti; en nuestra prueba se fue al otro y falló contra él.

3. Deja la key fuera del fichero, si lo prefieres

Este paso va después del 1, no en lugar del 1: /login ofrece los proveedores declarados en models.json, así que si helmcode no sale en la lista es que ese fichero no está puesto. Nada te lo dice — la entrada simplemente no aparece.

En vez del campo apiKey de arriba, abre una sesión y ejecuta:

/login

Pega la key cuando la pida. Pi escribe ~/.pi/agent/auth.json con permisos 600, así que tu models.json no lleva ningún secreto y puedes sincronizarlo entre máquinas sin cuidado. No escribas ese fichero a mano: la credencial va tipada ("type": "api_key") y una forma plausible pero equivocada se acepta en silencio y luego no autentica.

En cualquiera de los dos casos, esto confirma que el proveedor está listo antes de preguntarle nada:

pi auth check --provider helmcode

Responde ready.

4. Pruébalo

pi

Pídele algo corto. Si responde, está saliendo por Helmcode. Puedes cambiar de modelo a media sesión sin salir del agente.

Modelo recomendado

glm5.3-flash para trabajo de código: ventana de 1M, y cuenta contra la misma cuota mensual que deepseek-v4-flash, que es el otro modelo de 1M incluido en todos los planes. qwen3.6 para todo lo que esté acotado y quiera respuesta ya.

Problemas conocidos

  • Un error sobre un ByteString es una key rota, no un modelo roto. Si una petición falla con Cannot convert argument to a ByteString because the character at index 7 has a value of …, la key lleva un carácter no ASCII. El índice 7 es el primer carácter después de Bearer , así que está señalando el primer carácter de tu credencial. Pasa al copiar la key desde una interfaz de terminal con marco y arrastrar un carácter de dibujo de cajas: el mensaje no menciona ni la key ni la cabecera, así que no hay por dónde atarlo. Las keys empiezan por sk-hke_ y son ASCII enteras, y eso se comprueba en un segundo.
  • La key queda escrita en el fichero, salvo que uses /login. models.json vive en tu directorio home, así que no suele acabar en un repositorio, pero tenlo en cuenta si sincronizas tu configuración entre máquinas.
  • maxTokens no es el contexto. Es el techo de cada respuesta. El razonamiento sale de ese mismo presupuesto, así que si pides respuestas razonadas largas, súbelo.
  • Los modelos que declaras son los que tienes. Pi no le pregunta a la API qué hay disponible: muestra lo que haya en la lista.