Sayknow-CLI
Programar debería sentirse como pensar.
Un ejecutor de agentes de codificación enfocado en entrevistas, planes revisados, ejecución nativa en tmux y verificación duradera.
English ·
한국어 ·
中文 ·
日本語 ·
Español ·
Français ·
Deutsch
> Sayknow-CLI es un proyecto experimental en fase beta. Espera asperezas y verifica los resultados antes de confiar en él para trabajos importantes.
## Languages
La interfaz está localizada en **7 idiomas** — English, 한국어 (coreano),
中文 (简体 / chino simplificado), 日本語 (japonés), Español,
Français (francés) y Deutsch (alemán). Detecta automáticamente la configuración regional de tu sistema en
el primer arranque; cámbiala en cualquier momento en **Settings → Appearance → Language**, o inícialo
con, por ejemplo, `LANG=ja_JP.UTF-8 skc`. Las cadenas no traducidas recurren al inglés, y
los nombres de marca/técnicos (Claude, OpenAI, MCP, …) se mantienen literales en todas las configuraciones regionales.
## ¿Qué es Sayknow-CLI?
Sayknow-CLI (`skc`) es un arnés externo de agentes de codificación. Se ejecuta desde el repositorio o worktree que elijas y luego le da al agente una superficie de flujo de trabajo pequeña y explícita:
```text
deep-interview -> ralplan -> ultragoal
└─ optional team execution when parallel tmux workers help
```
Intencionadamente no es un plugin oculto para Codex CLI, Claude Code, OpenCode o Claw Code. Inicia `skc` junto a esas herramientas cuando quieras planificación estructurada, evidencia persistente, workers respaldados por tmux o un worktree aislado.
## Install
```sh
npm install -g sayknow-cli # o: bun install -g sayknow-cli
skc --version
```
El paquete incluye binarios nativos precompilados para macOS, Linux y Windows, así que no necesitas Rust ni paso de compilación. Para actualizar: `npm install -g sayknow-cli@latest` o ejecuta `skc update` en la terminal.
> ¿Vienes de una instalación desde el código fuente (git clone)? Cambia una sola vez: `rm -f ~/.local/bin/skc && npm install -g sayknow-cli`. Para la instalación desde el código (desarrollo), consulta el [README en inglés](../../README.md#install-from-source-development).
## Quick start
```sh
# Run directly in the current checkout
skc
# Use a tmux-backed leader session
skc --tmux
# Use an isolated worktree for risky or reviewable work
# --worktree takes an optional branch-like name, not a filesystem path.
skc --tmux --worktree my-task-branch
# If you already created a worktree directory, launch from that directory instead.
cd ../my-task-worktree && skc --tmux
```
Dentro de una sesión de SKC, usa la superficie pública del flujo de trabajo:
```text
/skill:deep-interview clarify ambiguous requirements
/skill:ralplan build and critique the implementation plan
skc ultragoal create-goals --brief-file
skc ultragoal complete-goals
```
Añade `skc team ...` solo cuando los workers coordinados de tmux ayuden de forma significativa.
## Capacidades principales
- **Entrevistar antes de suponer**: `deep-interview` convierte solicitudes vagas en requisitos concretos.
- **Planificar antes de mutar**: `ralplan` revisa el enfoque antes de los cambios de código.
- **Ejecutar con evidencia**: `ultragoal` rastrea objetivos, revisiones, comprobaciones y evidencia de finalización.
- **Paralelizar cuando sea útil**: `team` coordina workers respaldados por tmux para tareas más grandes.
- **Mantenerse externo y revisable**: ejecútalo desde un repositorio o worktree elegido sin parchear otro runtime de agente.
- **Seguir adelante cuando falla un proveedor**: cuando el modelo predeterminado está bloqueado (sin credenciales, sin cuota, errores de autenticación o del servidor), la sesión continúa con un modelo de otro proveedor; `/fallback` muestra y edita esa cadena. Un paso interrumpido por un reinicio o un fallo transitorio se reanuda solo una vez, con el mismo modelo. Las respuestas de cuota como Z.AI `1113` pasan al siguiente modelo tras una sola solicitud en lugar de agotar el presupuesto de reintentos.
- **Las sesiones largas no se salen de la ventana de contexto**: tras la compactación, Codex parte de una base nueva visible para el proveedor en lugar de crecer hasta `context_length_exceeded`, y los resúmenes de compactación se redactan para que los proveedores no los rechacen.
- **Encontrar código por su significado**: la herramienta `locate` encuentra dónde vive un comportamiento a partir de una descripción en lenguaje natural cuando no tienes un nombre que buscar con grep.
- **Llevar cada trabajo al modelo adecuado**: `/model` asigna modelos por rol y por uso detallado; las tareas de subagentes declaran una `specialty` para caer en el modelo que elegiste para ese tipo de trabajo.
- **Entregar desde la sesión**: las herramientas `github` y `gitlab` abren e inspeccionan pull/merge requests y CI sin salir de SKC.
- **Demostrar que las pruebas se ejecutaron sobre este código**: el plugin `verification-receipts` guarda un recibo de cada ejecución de pruebas y te avisa cuando el código ha cambiado desde entonces.
- **Volver a cualquier sesión**: selector de reanudación con `alt+r`, `ctrl+q` para continuar la más reciente, `/star`, `/fork`, `/rename` y `/import-session` para transcripciones de Codex y Claude Code.
## Superficie del flujo de trabajo
Sayknow-CLI incluye cuatro skills de flujo de trabajo predeterminadas:
| Skill | Qué hace |
| ---------------- | --------------------------------------------------------------------- |
| `deep-interview` | Aclara requisitos ambiguos antes de planificar o cambiar código. |
| `ralplan` | Construye y critica un plan de implementación antes de mutar. |
| `ultragoal` | Rastrea objetivos a través de ejecución, revisión, verificación y evidencia. |
| `team` | Coordina workers respaldados por tmux cuando vale la pena la ejecución paralela. |
Y cuatro agentes de rol incluidos:
| Agent | Qué hace |
| ----------- | -------------------------------------------------- |
| `executor` | Implementación acotada, correcciones y refactorizaciones. |
| `architect` | Evaluación de arquitectura y revisión de código de solo lectura. |
| `planner` | Secuenciación y criterios de aceptación de solo lectura. |
| `critic` | Crítica de planes y revisión de accionabilidad de solo lectura. |
Sin un zoológico de skills predeterminadas desbordante: SKC mejora haciendo mejor este pequeño método.
## Herramientas integradas
El agente trabaja con estas herramientas. Las marcadas como *opt-in* permanecen desactivadas hasta que las actives en **Settings → Tools** (o con la clave indicada en `~/.skc/config.yml`).
| Área | Herramientas |
| ---- | ----- |
| Archivos y código | `read`, `write`, `edit`, `find`, `search`, `locate` (encuentra código por descripción), `ast_grep` / `ast_edit` (búsqueda y reescritura sensibles a la sintaxis), `lsp` |
| Shell y runtime | `bash`, `eval` (celdas JS/Python), `ssh`, `debug`, `bisect`, `calc` |
| Delegación y seguimiento | `task` (subagentes), `subagent`, `job`, `monitor`, `cron`, `irc` (para hablar con agentes en ejecución), `todo_write`, `goal`, `checkpoint` / `rewind` |
| Alojamiento Git | `github` (*opt-in*, `github.enabled`): pull requests, pushes y ejecuciones de CI mediante `gh` · `gitlab` (*opt-in*, `gitlab.enabled`, requiere [`glab`](https://gitlab.com/gitlab-org/cli)): `mr_create` (devuelve la MR abierta en lugar de crear un duplicado), `mr_view`, `mr_list`, `ci_status` para gitlab.com e instancias autoalojadas |
| Web y dispositivos | `web_search`, `browser`, `computer`, `render_mermaid` |
| Descubrimiento | `search_tool_bm25` (activa bajo demanda herramientas ocultas y de MCP), `skill`, `skill_discovery`, `ask` |
Elige el conjunto de herramientas de una sola ejecución con `--tools read,bash,...`; ahí también se aceptan nombres de herramientas de plugins, personalizadas y de MCP.
## Plugins
SKC carga paquetes de plugins (herramientas, hooks, skills, servidores MCP) que se verifican por hash al instalarse y se ponen en cuarentena si algún archivo cambia después. Gestiónalos con `skc plugin install|list|...`.
**`verification-receipts`** (incluido en este repositorio) responde a la pregunta «¿pasaron de verdad las pruebas sobre el código que hay ahora?»:
- `verification_run` ejecuta archivos de prueba explícitos con `bun test` o `node --test` y guarda un recibo inmutable: recuentos de aprobados/fallidos por archivo más una huella del árbol de trabajo.
- `verification_status` recalcula esa huella sin volver a ejecutar las pruebas e informa `fresh`, o `stale` en cuanto el código ha cambiado.
- `verification_loop` y sus hooks te avisan cuando una `task` en segundo plano termina sin un recibo fresh.
Es solo orientativo, funciona únicamente en POSIX y necesita Node 24.11.1+ para `node --test`. No forma parte del paquete npm; instálalo desde una copia local del repositorio:
```sh
git clone https://github.com/jaybeyond/Sayknow_CLI.git
skc plugin install ./Sayknow_CLI/packages/coding-agent/bundles/verification-receipts --user
```
## Funciona junto a tu agente o bot existente
| Herramienta o bot | Comando SKC recomendado | Límite |
| ----------- | ----------------------- | -------- |
| Codex CLI | `skc --tmux --worktree ` o `skc` | `--worktree` nombra un worktree hermano gestionado por SKC; para una ruta existente, haz `cd` allí primero. |
| Claude Code | `skc --tmux` o `skc --tmux --worktree ` | SKC no se convierte en una extensión de Claude Code. |
| OpenCode | `skc` o `skc --tmux` | Solo flujo de trabajo de ejecutor externo por ahora. |
| Claw Code | `skc --tmux --worktree ` | SKC no se instala dentro de Claw Code ni lo reemplaza. |
| Controlador / bot externo | `skc mcp-serve coordinator` más `skc setup hermes` para una configuración compatible, o `skc --mode rpc` para un worker en subproceso | Cualquier bot con capacidad MCP/RPC controla SKC mediante el contrato genérico coordinator/RPC, no mediante scraping del scrollback. |
Para la configuración genérica de bots de terceros y pruebas de humo independientes del proveedor, consulta [`docs/bot-integration.md`](docs/bot-integration.md). Para la clasificación de preparación a través de las superficies MCP, RPC, ACP y Bridge/HTTPS, consulta [`docs/external-control-readiness.md`](docs/external-control-readiness.md). Para los detalles de protocolo de más bajo nivel, consulta [`docs/hermes-mcp-bridge.md`](docs/hermes-mcp-bridge.md), [`docs/rpc.md`](docs/rpc.md) y [`docs/bridge.md`](docs/bridge.md). Para la hoja de ruta de las superficies de operador remoto, consulta [`docs/sayknow-remote.md`](docs/sayknow-remote.md) (volante web) y [`docs/telegram-remote.md`](docs/telegram-remote.md) (botón de ciclo de vida de Telegram).
## Configuration
El comportamiento de reintento, reanudación y fallback del proveedor vive en `~/.skc/config.yml` (los valores de abajo son los predeterminados):
```yaml
retry:
requestMaxRetries: 4
streamMaxRetries: 100
maxRetries: 3
maxDelayMs: 300000
autoResume: true # reanuda una sola vez un paso interrumpido, con el mismo modelo
maxSilentTimeouts: 3 # se detiene tras este número de timeouts sin salida
fallback:
auto: true # continúa con otro proveedor autenticado si el modelo predeterminado está bloqueado
maxAttempts: 3 # intentos por modelo de la cadena antes de pasar al siguiente
```
`requestMaxRetries` se aplica antes de que se establezca un stream. `streamMaxRetries` se aplica solo a fallos transitorios de stream que son seguros de reproducir. La autenticación inválida, los modelos/proveedores no compatibles, las solicitudes malformadas, el desbordamiento de contexto, las cancelaciones del usuario y los fallos permanentes de cuota fallan rápido en el modelo actual; con `fallback.auto`, un modelo predeterminado bloqueado cede entonces el relevo al siguiente modelo de la cadena (`/fallback` la muestra y la edita).
## Identidad de la TUI
La identidad predeterminada de la TUI es el tema **ink-octopus** de SKC — tinta de pulpo: grafito cálido, texto color papel y un único acento ámbar — para terminales oscuras, con **blue-octopus** para terminales claras. También se incluye una variante cálida **red-octopus** para quienes prefieren una paleta más oscura y de alto contraste. Tres temas de migración adicionales — `claude-code`, `codex` y `opencode` — reflejan el aspecto de esas herramientas para facilitar la migración visual y se pueden seleccionar desde Settings o `/theme`. Los ajustes de tema explícitos del usuario siguen prevaleciendo.
### Cuadrícula de temas incluidos
Elige desde Settings (`Appearance -> Dark theme` / `Light theme`) o `/theme`.
| Tema | Sensación visual | Mejor uso |
| --- | --- | --- |
| `blue-octopus` | Paleta de pulpo azul con acentos azul-tentáculo. | Predeterminado para terminales claras. |
| `red-octopus` | Variante cálida de pulpo rojo con fuerte contraste de estado. | Alternativa oscura de alto contraste. |
| `ink-octopus` | Tinta de pulpo — fondo grafito cálido, texto color papel y un único acento ámbar. | Predeterminado para terminales oscuras. |
| `glow-octopus` | Bioluminiscencia abisal — negro verdiazulado con verde brillante y violeta como secundario. | Terminales oscuras que quieren un acento vivo. |
| `violet-octopus` | Oscuro ciruela con acentos lavanda y albaricoque como secundario. | Alternativa oscura suave y colorida. |
| `claude-code` | Paleta oscura inspirada en Claude Code con resaltados terracota y rosa. | Memoria muscular de Claude Code sin salir de SKC. |
| `codex` | Paleta nítida azul-gris oscuro con un contraste de sesión de codificación más marcado. | Un espacio de trabajo oscuro al estilo Codex. |
| `opencode` | Paleta oscura inspirada en OpenCode con acentos de terminal más vibrantes. | Memoria muscular de OpenCode en el selector incluido. |
## Development
Instala las dependencias, compila los bindings nativos y configura los valores predeterminados locales:
```sh
bun install
bun run build:native
bun run install:defaults
```
El binario `.node` para `@sayknow-cli/natives` está en gitignore y es necesario antes de cualquier invocación del CLI (`install:defaults`, `dev:link`, tests).
### Canónico: compilar y enlazar el `skc` de desarrollo
Para hacer que el comando global `skc` ejecute **el código fuente TypeScript de esta copia** (sensible a cada edición, con skills/natives funcionando), enlázalo a tu `PATH`:
```sh
bun install
bun run dev:link
```
`dev:link` crea un symlink de `skc` → `packages/coding-agent/src/cli.ts` en `~/.local/bin` (sobrescríbelo con `SKC_DEV_LINK_DIR`), reemplaza ese objetivo gestionado, advierte y falla si otro `skc` aún lo oculta antes en `PATH`, y ejecuta `--smoke-test` para confirmar que `@sayknow-cli/natives` carga. Usa `bun run install:dev` para el bootstrap completo (install + link + `setup defaults`).
Comprueba en cualquier momento si tu `skc` se ha desviado (fuente incorrecta, o un binario compilado que no puede cargar skills):
```sh
bun run dev:doctor
```
> **No** uses el binario compilado para el desarrollo diario. `bun --cwd=packages/coding-agent run build` produce un `dist/skc` independiente, pero un binario `bun build --compile` no puede cargar dinámicamente `@sayknow-cli/natives`, por lo que las skills fallan con `Cannot find module '@sayknow-cli/natives' from '/$bunfs/root/skc'`. Ejecutar desde el código fuente mediante `dev:link` evita esto. Compila el binario solo al validar una release.
Ejecuta el CLI directamente desde el código fuente sin enlazarlo:
```sh
bun packages/coding-agent/src/cli.ts --help
```
Las definiciones de flujo de trabajo predeterminadas viven en el código fuente, no en copias `.skc` comprometidas:
```text
packages/coding-agent/src/defaults/skc/skills//SKILL.md
packages/coding-agent/src/prompts/agents/.md
```
Para cambios en las definiciones de flujo de trabajo o en la superficie de rebranding, ejecuta las puertas del proyecto:
```sh
bun scripts/check-visible-definitions.ts
bun scripts/verify-g002-gates.ts
bun scripts/rebrand-inventory.ts --strict
bun test packages/coding-agent/test/default-skc-definitions.test.ts
```
Para un mapa paquete por paquete, consulta [`docs/codebase-overview.md`](docs/codebase-overview.md).
## Contributors
Las contribuciones, los informes de errores y la validación de releases son bienvenidos a través de GitHub Issues y Pull Requests.
## Inspiraciones y linaje
La identidad predeterminada de la TUI de Sayknow-CLI es la familia de pulpos: ink-octopus como predeterminado oscuro, blue-octopus como predeterminado claro y red-octopus, glow-octopus y violet-octopus como alternativas. También incluye los temas de migración `claude-code`, `codex` y `opencode`, cuyas paletas están inspiradas en esas herramientas para que los usuarios que migran de ellas obtengan un aspecto familiar. Se basa en las lecciones de una pequeña familia de arneses de agentes mientras mantiene la superficie pública de SKC intencionadamente enfocada. La atribución histórica se conserva en [`NOTICE.md`](NOTICE.md).
## License
MIT. Consulta [`LICENSE`](LICENSE).