Ostacky

Ostacky es el agente de OpenCode que instalás en tu proyecto. Usa skills para ser más eficiente con tokens y evitar recorrer todo el proyecto cuando no hace falta. En cambios de bajo impacto prioriza ejecución inline; los subagentes quedan para slices realmente independientes. Los cambios se registran normalmente en specs con los skills de OpenSpec; si el cambio es de bajo impacto, podés saltearte esa generación.

¿Qué es?

Ostacky es el agente (.opencode/agents/) que se instala directamente desde GitHub Releases. Cada instalación queda registrada en un lockfile con versión y checksum, lo que permite actualizaciones controladas y reproducibles.

¿Para qué sirve?

• Instalar el agente Ostacky en cualquier proyecto con un solo comando.
• Mantener un registro de qué versión está instalada (ostacky-lock.json)
• Detectar y aplicar actualizaciones mostrando el diff de versiones antes de confirmar
• Evitar descargas repetidas gracias al cache local en ~/.opencode/cache/
• Resolver tareas chicas sin overhead extra de coordinación.

Requisitos

• Node.js >= 18 (para usar con npx)
• o Bun >= 1.x (para usar con bunx o desarrollo)
• OpenCode instalado en tu máquina

Uso rápido (para usuarios)

No requiere instalación global ni clonar el repositorio. Se usa directamente con npx o bunx:

npx ostacky

bunx ostacky

Uso

Menú interactivo

npx ostacky

Detecta automáticamente el directorio .opencode/ del proyecto (o lo crea) y muestra un menú para elegir qué hacer.

Instalar todo

npx ostacky install

Descarga todos los agentes y commands definidos en el manifest y los escribe en .opencode/.

Agregar agentes o commands individualmente

npx ostacky add agent
npx ostacky add command

Muestra un selector múltiple con los recursos disponibles. Indica si ya están instalados y en qué versión.

Actualizar

npx ostacky update

Consulta la última GitHub Release, compara las versiones instaladas contra el manifest remoto y muestra el diff antes de confirmar:

Actualizaciones disponibles
  agente   ostacky             0.0.1 → 0.0.2
  command  install-stack    0.0.1 → 0.0.2

¿Aplicar 2 actualización(es)? › Sí / No

Solo descarga los items que cambiaron de versión.

Desinstalar

npx ostacky uninstall

Borra todos los archivos instalados (los listados en .opencode/ostacky-lock.json). Antes de borrar, muestra un preview con los paths a eliminar y pide confirmación.

Desinstalar un agente puntual

npx ostacky uninstall agent <nombre>

Por ejemplo:

npx ostacky uninstall agent ostacky

Desinstalar un command puntual

npx ostacky uninstall command <nombre>

Por ejemplo:

npx ostacky uninstall command install-stack

Si no especificás el nombre, el CLI te muestra un selector con los items instalados para que elijas cuáles desinstalar (puede ser uno o varios).

Otros

npx ostacky --version   # muestra la versión del CLI
npx ostacky --help      # muestra la ayuda

Estructura generada

Tras instalar, el proyecto queda así:

.opencode/
├── agents/
│   └── ostacky.md
├── commands/
│   └── install-stack.md
└── ostacky-lock.json          ← versiones instaladas

ostacky-lock.json

{
    "version": "0.0.6",
    "lockedAt": "2025-01-01T00:00:00.000Z",
    "repo": "JaimeHoracio/Ostacky",
    "tag": "v0.0.6",
    "agents": {
        "ostacky": {
            "version": "0.0.6",
            "installedAt": "2025-01-01T00:00:00.000Z",
            "sha256": "abc123..."
        }
    },
    "commands": {
        "install-stack": {
            "version": "0.0.6",
            "installedAt": "2025-01-01T00:00:00.000Z",
            "sha256": "def456..."
        }
    }
}

Se recomienda agregar ostacky-lock.json al control de versiones para que el equipo instale exactamente las mismas versiones.

Después de la instalación

Al terminar la instalación, el flujo normal es:

1. Recargar OpenCode para que detecte los nuevos archivos en .opencode/.
2. Ya puedes usar el agente:

   @Ostacky

   o seleccionarlo desde la interfaz de OpenCode según la configuración del proyecto. @Ostacky invoca al agente que el CLI instaló en .opencode/agents/ostacky.md.

Si por alguna razon querés ejecutar el bootstrap manualmente o regenerar el stack local, también está disponible el command:

/install-stack

Ese paso es opcional. Si no aparece en la terminal, recargá OpenCode y volvé a tipearlo.

Seguridad

• opencode.jsonc se versiona en el repo para compartir permisos y MCP de forma reproducible.
• Las URLs de descarga usan tags de GitHub (ej. v0.0.6), nunca main — instalaciones reproducibles
• Cada path de archivo descargado es validado para prevenir path traversal
• Los archivos incluyen checksum SHA-256 opcional; si el manifest lo define, el contenido se verifica antes de escribir
• El cache local (~/.opencode/cache/) también valida integridad al servir archivos cacheados

Restricciones de acceso a credenciales

• La configuración local de OpenCode (opencode.jsonc) bloquea lectura y escritura de *.env y .secret/** con deny.
• La sesión sigue ejecutándose después del bloqueo porque experimental.continue_loop_on_deny está activado.
• Para worktrees, el repo prefiere .worktrees/; ~/.config/superpowers/worktrees solo se usa con confirmación explícita.

Cache

Los archivos descargados se guardan en:

~/.opencode/cache/<repo>/<tag>/<ruta-del-archivo>

Si ya existe un archivo en cache con el hash correcto, no se hace ninguna petición de red.

Desarrollo

Los pasos de esta sección son solo para quienes quieran contribuir o modificar el código. Si eres usuario final, no necesitas ejecutar nada de esto — basta con npx ostacky.

Requisitos adicionales para desarrollo

• Bun >= 1.x

1. Clonar e instalar dependencias

git clone https://github.com/JaimeHoracio/Ostacky.git
cd Ostacky
bun install

bun install descarga todas las dependencias definidas en package.json (incluyendo TypeScript y los tipos de Bun).

2. Ejecutar en modo desarrollo

bun run dev
# equivalente a: bun run src/cli.ts

3. Compilar la CLI

La CLI se distribuye como un ejecutable JavaScript en dist/cli.js. Para generarlo:

bun run build

Este comando ejecuta internamente:

bun build src/cli.ts --target=node --format=esm --outfile dist/cli.js && bun scripts/add-shebang.ts

Tras compilar deberías obtener:

dist/
└── cli.js

4. Probar el binario compilado

node dist/cli.js
# o
bun run start

Publicar en npm

El script prepublishOnly ejecuta bun run build automáticamente antes de publicar, por lo que dist/ siempre estará actualizado al publicar.

npm publish

Licencia

MIT