Communitygithub.com

glyphs-ai/glyph

Glyph é uma bancada para compor as formas que a inteligência assume hoje — e descobrir a linguagem que ela falará amanhã.

O que é glyph?

Esta skill transforma um modelo de IA em um controlador de servidor Glyph via CLI. Ela mapeia completamente a superfície de comandos `glyph`, incluindo a disciplina de escopo de workspace que evita conflitos entre múltiplos clientes e o sistema de códigos de saída que permite ramificar mecanicamente com base em falhas. A skill detalha como usar os grupos de subcomandos (`workspace`, `session`, `task`, `schedule`, `catalog`, `workflow`, `runtime`, além de inspeção e ciclo de vida do servidor) e enfatiza a importância de sempre passar `--json` para análise previsível. Também cobre a disciplina de erros, com códigos estruturados e linhas `fix:` que fornecem o próximo comando exato, e tabelas de códigos de saída que orientam a ação em cada cenário. A documentação é projetada para uso com agentes de IA (Claude Code, Cursor, Codex, etc.) e inclui referências essenciais para trabalho não trivial, como playbooks, formatos JSON e catálogo de erros.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add glyphs-ai/glyph

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

skill oficial/cli

Você é uma IA controlando um servidor glyph através de sua CLI. Esta skill é um mapa de toda a superfície de comandos glyph além das convenções que não são óbvias a partir de --help — mais importante, a disciplina de escopo de workspace que impede que seus comandos entrem em conflito com outros clientes, e a disciplina de código de saída / código de erro que permite ramificar mecanicamente com base em falhas.

Configuração

glyph injeta o que você precisa em seu ambiente quando inicia sua tarefa ou sessão:

  • GLYPH_SERVER — URL do servidor (a CLI usa automaticamente)
  • GLYPH_WORKSPACE — UUID do workspace (comandos com escopo de workspace o herdam)

Verificação rápida:

glyph health         # saída 0 ⇒ CLI funciona + servidor acessível
glyph workspace current --json | jq   # confirma workspace resolvido

Superfície de comandos de relance

Todo comando com escopo de workspace herda --server / --workspace-id / --output / --json e segue a tabela de código de saída compartilhada abaixo. Os grupos de subcomandos:

GrupoPropósitoReferência
workspaceCriar / listar / exibir / atualizar / remover / recarregar workspaces; imprimir id atualreferences/commands.md#workspace
sessionGerenciar sessões interativas (listar / nova / exibir / remover / iniciar um terminal)references/commands.md#session
taskDespachar tarefas únicas, listar (incluindo escopo por --origin), inspecioná-las, acompanhar atividade, cancelar, removerreferences/commands.md#task
scheduleLançadores de tarefas acionados por cron (criar / listar / patch / habilitar / desabilitar / executar / visualizar / listar-tarefas)references/commands.md#schedule
catalogInstalar / sincronizar / habilitar / desabilitar agentes, skills, MCPsreferences/commands.md#catalog
workflowSemear um workflow, ler/mutar seu DAG ativo (expandir, aplicar patch na especificação de um nó not_started via update-spec), responder a nós humanos, encerrarreferences/commands.md#workflow
runtimeListar runtimes registrados (copilot, etc)references/commands.md#runtime
Inspeção do servidorhealth, config, status, logs — sem ciclo de vidareferences/commands.md#server-inspection
Ciclo de vida do servidorserve / start / stop / restart — fora do escopo desta skill—

Disciplina de workspace

Todo comando com escopo de workspace requer um seletor explícito. A CLI lê GLYPH_WORKSPACE do seu ambiente (já definido), então os comandos funcionam como estão:

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

Para atuar em um workspace diferente, passe --workspace-id <id> por comando:

glyph task list --workspace-id ws-Y

A CLI não consulta nenhum estado compartilhado de "workspace atual" no lado do servidor — os seletores são locais ao processo, imunes a interferências de outros clientes (outras sessões CLI, abas do dashboard, agentes de IA no mesmo servidor).

Disciplina de saída

  • Para análise, sempre passe --json. O formato humano/tabela não é um contrato estável — a ordem das colunas e cabeçalhos mudam entre versões.
  • Para atividade em streaming, use pipe com jq -c para manter um evento por linha.
  • Cada formato --json que você provavelmente consumirá está documentado em references/json-shapes.md. Consulte-o antes de escrever um filtro jq — a maioria dos formatos tem campos opcionais (presentes quando a linha subjacente não é nula) dos quais você deve depender.

Disciplina de erros

Erros em stderr sempre carregam um code:

agent "writer" não está pronto: pré-requisitos não reconhecidos (HTTP 409, EntryNotReadyError)
  agent: acme/writer
  cause: pré-requisitos não reconhecidos
  fix:   glyph catalog agent ack-prereqs acme/writer

A linha fix: é seu próximo comando, exatamente como está. O catálogo completo de code (todos os nomes de erro + HTTP típico + remediação) está em references/error-codes.md. Em particular:

  • EntryNotReadyError é o ramo mais comum que você encontrará — ele carrega um reason estruturado descrevendo se o agente precisa de ack-prereqs, está disabled, tem missingDeps, ou tem blockedDeps (que recursam). A tabela de razões está em references/error-codes.md#entrynotreadyerror-reasons.

Códigos de saída

códigosignificadoo que fazer
0sucessocontinue
1erro genérico (incl. workspace ausente)leia stderr; geralmente flag/ambiente ausente
2erro de uso (flag obrigatória ausente, subcomando removido)corrija a invocação; não repita como está
3servidor inacessívelpeça ao usuário para glyph start ou verifique --server
4servidor retornou 4xx/5xxleia code em stderr; consulte references/error-codes.md

Código de saída 2 significa "o comando em si está errado" — nunca repita sem alterar a invocação. Código de saída 4 significa "o servidor rejeitou isso" — leia o campo code, ele informa o próximo passo.

Armadilhas

  • Para aguardar uma tarefa, use glyph task activity <tid> --follow (SSE em tempo real). Polling de task list em um loop de shell desperdiça ciclos e atrasa eventos reais.
  • Para um instantâneo único "o que aconteceu até agora?", remova --follow — glyph task activity <tid> --json retorna a atividade atual mais totalItems em uma chamada. --follow bloqueia até a tarefa terminar.
  • Encerre antes de remover. task rm <tid> simples requer que a tarefa esteja em um estado terminal (succeeded / failed / cancelled); se ainda estiver em execução, use glyph task cancel <tid> primeiro, depois task rm. Recorra a --purge apenas quando também quiser que o diretório de trabalho + estado de runtime desapareçam (o stderr.log pós-mortem é perdido). A mesma distinção se aplica a session rm e workspace rm.
  • Sempre retome --follow com o last seq: impresso. Em cada saída limpa (event: end ou fluxo fechado) E em saída por erro no meio do fluxo, a CLI imprime last seq: <N> em stderr — passe --after <N> na próxima invocação de --follow para retomar sem lacunas ou duplicatas. Ctrl+C é a exceção (stderr não é liberado); derive o seq do último item NDJSON em stdout (... | tail -1 | jq .seq). O manual completo de retomada está em references/playbooks.md#monitor-a-long-running-task.
  • Sempre obtenha ids de workspace de glyph workspace list --json | jq. Fragmentos de URL do dashboard variam entre versões e não são um contrato de interface.
  • schedule patch é esparso — apenas as flags que você passar vão para a rede. Para remover um campo, passe --clear-details / --clear-runtime (um --details "" vazio é tratado como omitido, não como limpeza).

Referências (leitura obrigatória antes de trabalho não trivial)

  • references/commands.md — referência de subcomandos por grupo (workspace / session / task / schedule / catalog / workflow / runtime / server inspection). Leia superficialmente uma vez, mantenha como consulta.
  • references/playbooks.md — playbooks orientados a metas de várias etapas (instalar e verificar agente, despachar e aguardar, monitorar tarefa, sincronizar entrada, limpar, integrar novo workspace, criar um agente local rapidamente).
  • references/json-shapes.md — os formatos comuns de payload --json com listas de campos concretas e notas de opcionalidade.
  • references/error-codes.md — todo valor code que o servidor emite + o comando glyph correspondente para corrigi-lo.

Habilidades Relacionadas