Communitygithub.com

glyph-ai/glyph

Glyph es un banco de trabajo para componer las formas que la inteligencia adopta hoy — y descubrir el lenguaje que hablará mañana.

¿Qué es glyph?

Glyph es una habilidad para que agentes de IA (como Claude Code, Cursor, Codex) controlen un servidor Glyph a través de su interfaz de línea de comandos (CLI). Proporciona un mapeo completo de la superficie de comandos `glyph`, incluyendo grupos como `workspace`, `session`, `task`, `schedule`, `catalog`, `workflow` y `runtime`, además de comandos de inspección del servidor como `health`, `config`, `status` y `logs`. Esta habilidad es útil porque impone una disciplina de ámbito de espacio de trabajo que evita que los comandos compitan con otros clientes, y una disciplina de códigos de error que permite ramificar mecánicamente en fallos. Funciona extrayendo `GLYPH_SERVER` y `GLYPH_WORKSPACE` del entorno, y sus comandos aceptan `--json` para salida estable, además de que los errores siempre incluyen un `code` que indica la acción correctiva. Es especialmente valiosa para flujos de trabajo automatizados donde se requiere monitoreo de tareas en tiempo real, manejo de errores estructurado y gestión de espacios de trabajo sin interferencias.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add glyphs-ai/glyph

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Habilidad oficial/cli

Eres una IA que controla un servidor glyph a través de su CLI. Esta habilidad es un mapa de toda la superficie de comandos glyph más las convenciones que no son obvias en --help — especialmente la disciplina de ámbito de espacio de trabajo que evita que tus comandos compitan con otros clientes, y la disciplina de código de salida / código de error que te permite ramificar mecánicamente en fallos.

Configuración

glyph inyecta lo que necesitas en tu entorno cuando inicia tu tarea o sesión:

  • GLYPH_SERVER — URL del servidor (la CLI lo usa automáticamente)
  • GLYPH_WORKSPACE — UUID del espacio de trabajo (los comandos con ámbito de espacio de trabajo lo heredan)

Verificación rápida:

glyph health         # código de salida 0 ⇒ CLI funciona + servidor accesible
glyph workspace current --json | jq   # confirma que el espacio de trabajo está resuelto

Superficie de comandos de un vistazo

Cada comando con ámbito de espacio de trabajo hereda --server / --workspace-id / --output / --json y sigue la tabla de códigos de salida compartida a continuación. Los grupos de subcomandos:

GrupoPropósitoReferencia
workspaceCrear / listar / mostrar / actualizar / eliminar / recargar espacios de trabajo; imprimir el id actualreferences/commands.md#workspace
sessionGestionar sesiones interactivas (listar / nueva / mostrar / eliminar / iniciar un terminal)references/commands.md#session
taskDespachar tareas únicas, listar (incl. filtrado por --origin), inspeccionarlas, seguir su actividad, cancelar, eliminarreferences/commands.md#task
scheduleLanzadores de tareas activados por cron (crear / listar / parchear / habilitar / deshabilitar / ejecutar / previsualizar / listar-tareas)references/commands.md#schedule
catalogInstalar / sincronizar / habilitar / deshabilitar agentes, habilidades, MCPsreferences/commands.md#catalog
workflowSembrar un flujo de trabajo, leer/mutar su DAG en vivo (expandir, parchear la especificación de un nodo not_started mediante update-spec), responder a nodos humanos, terminarreferences/commands.md#workflow
runtimeListar tiempos de ejecución registrados (copilot, etc.)references/commands.md#runtime
Inspección del servidorhealth, config, status, logs — sin ciclo de vidareferences/commands.md#server-inspection
Ciclo de vida del servidorserve / start / stop / restart — fuera del alcance de esta habilidad—

Disciplina del espacio de trabajo

Cada comando con ámbito de espacio de trabajo requiere un selector explícito. La CLI lee GLYPH_WORKSPACE de tu entorno (ya configurado), por lo que los comandos funcionan tal cual:

glyph task dispatch --agent writer --brief "..."

Para actuar en un espacio de trabajo diferente, pasa --workspace-id <id> por comando:

glyph task list --workspace-id ws-Y

La CLI no consulta ningún estado compartido de "espacio de trabajo actual" del lado del servidor — los selectores son locales al proceso, inmunes a interferencias de otros clientes (otras sesiones CLI, pestañas del panel, agentes de IA en el mismo servidor).

Disciplina de salida

  • Para análisis, usa siempre --json. El formato humano/tabla no es un contrato estable — el orden de las columnas y los encabezados cambian entre versiones.
  • Para actividad en streaming, canaliza a través de jq -c para mantener un evento por línea.
  • Cada forma --json que probablemente consumirás está documentada en references/json-shapes.md. Consúltalo antes de escribir un filtro jq — la mayoría de las formas tienen campos opcionales (presentes cuando la fila subyacente no es nula) que deberías usar como clave.

Disciplina de errores

Los errores en stderr siempre llevan un code:

agent "writer" is not ready: prereqs not acknowledged (HTTP 409, EntryNotReadyError)
  agent: acme/writer
  cause: prereqs not acknowledged
  fix:   glyph catalog agent ack-prereqs acme/writer

La línea fix: es tu siguiente comando, textual. El catálogo completo de code (todos los nombres de error + HTTP típico + remediación) está en references/error-codes.md. En particular:

  • EntryNotReadyError es la rama más común que tomarás — lleva un reason estructurado que describe si el agente necesita ack-prereqs, está disabled, tiene missingDeps o tiene blockedDeps (que se recorren recursivamente). La tabla de razones está en references/error-codes.md#entrynotreadyerror-reasons.

Códigos de salida

códigosignificadoqué hacer
0éxitocontinuar
1error genérico (incl. espacio de trabajo faltante)leer stderr; normalmente falta un flag/env
2error de uso (falta un flag obligatorio, subcomando eliminado)corregir la invocación; no reintentar tal cual
3servidor inalcanzablepedir al usuario que glyph start o verifique --server
4servidor devolvió 4xx/5xxleer code en stderr; consultar references/error-codes.md

El código de salida 2 significa "el comando en sí está mal" — nunca lo reintentes sin cambiar la invocación. El código de salida 4 significa "el servidor rechazó esto" — lee el campo code, te indica el siguiente paso.

Errores comunes

  • Para esperar una tarea, usa glyph task activity <tid> --follow (SSE en tiempo real). Sondeando task list en un bucle de shell desperdicia ciclos y retrasa eventos reales.
  • Para una instantánea única de "¿qué ha pasado hasta ahora?", omite --follow — glyph task activity <tid> --json devuelve la actividad actual más totalItems en una sola llamada. --follow bloquea hasta que la tarea termina.
  • Termina antes de eliminar. Un simple task rm <tid> requiere que la tarea esté en un estado terminal (succeeded / failed / cancelled); si aún se está ejecutando, primero glyph task cancel <tid>, luego task rm. Recurre a --purge solo cuando también quieras que desaparezcan el directorio de trabajo + el estado del tiempo de ejecución (el stderr.log post-mortem se pierde). La misma distinción aplica para session rm y workspace rm.
  • Siempre reanuda --follow con el last seq: impreso. En cada salida limpia (event: end o flujo cerrado) Y en salida por error en medio del flujo, la CLI imprime last seq: <N> en stderr — pasa --after <N> en la siguiente invocación de --follow para reanudar sin huecos ni duplicados. Ctrl+C es la excepción (stderr no se vacía); deriva el seq del último elemento NDJSON de stdout (... | tail -1 | jq .seq). El manual completo de reanudación está en references/playbooks.md#monitor-a-long-running-task.
  • Siempre obtén los ids de espacios de trabajo de glyph workspace list --json | jq. Los fragmentos de URL del panel varían entre versiones y no son un contrato de red.
  • schedule patch es disperso — solo los flags que pasas van al cable. Para eliminar un campo, pasa --clear-details / --clear-runtime (un --details "" vacío se trata como omitido, no como borrado).

Referencias (lectura obligatoria antes de trabajo no trivial)

  • references/commands.md — referencia de subcomandos por grupo (workspace / session / task / schedule / catalog / workflow / runtime / server inspection). Examínalo una vez, mantenlo como referencia.
  • references/playbooks.md — manuales multi-paso orientados a objetivos (instalar-y-verificar agente, despachar-y-esperar, monitorear tarea, sincronizar entrada, limpiar, incorporar nuevo espacio de trabajo, crear un agente local sobre la marcha).
  • references/json-shapes.md — las formas comunes de carga útil --json con listas de campos concretas y notas de opcionalidad.
  • references/error-codes.md — cada valor de code que emite el servidor + el comando glyph correspondiente para solucionarlo.

Skills relacionados