Relay

Um harness de codificação com IA com fluxo de 10 gates, 22 papéis e 30 skills. Esta é a implementação em Node.js/TypeScript do Relay — a CLI global relay (subcomandos sob relay; alias relay-ai-code-agent) — uma porta fiel do original em Python relay-main.

Versão 0.13.0 · Node.js ≥ 20 · TypeScript (strict) · CommonJS · relay-ai-code-agent no npm

🇺🇸 Read in English

O Relay conduz um agente de codificação com IA através de um fluxo de 14 gates — da descoberta de domínio e especificação até implementação, segurança e teste de invasão — usando um time de 22 papéis (cada um pareado 1:1 com uma skill), 30 skills e 6 regras de turno. Funciona em dois modos complementares:

• Harness nativo — o Relay guarda as próprias credenciais, chama os provedores de LLM diretamente, roda o próprio laço de agente (relay chat / relay auto) e carrega papéis/skills/fluxo nativamente. Funciona com chaves de API ou com modelos locais sem chave (Ollama, llama.cpp, LM Studio, vLLM) — sem chave nenhuma.
• Emissor — o Relay escreve seus papéis/skills/fluxo no layout nativo de outro harness (Claude Code, Codex, Gemini CLI, GitHub Copilot), para você continuar dirigindo a CLI licenciada da sua assinatura, moldada pelo Relay.

A razão de existirem os dois é econômica e ética: a única forma legítima de usar uma assinatura (Claude Max / ChatGPT) é através da CLI licenciada do próprio provedor. O Relay nunca se passa pelo cliente OAuth de outra aplicação para alcançar uma assinatura a partir do laço nativo — assinaturas passam pela emissão; chaves de API e modelos locais rodam nativamente.

Índice

• Principais recursos
• Instalação
• Início rápido
• Usando o Relay nativamente
• Usando o Relay com outro harness (Claude Code, Codex, …)
• O fluxo de 10 gates
• Os comandos condutores
• Papéis, skills e regras
• Referência da CLI
• Estrutura do projeto
• Desenvolvimento
• Documentação
• Projetos relacionados

Três modos de usar o Relay

Um núcleo, três formas de chegar até ele — as três rodando a mesma implementação canônica (mesmo laço, mesmos gates, mesmas tools, mesma decisão de trust, egress, approval, sandbox e redaction). O que muda é quem dirige e onde você está.

| Modo | Como se entra | Quem roda o laço | O que você vê | | --- | --- | --- | --- | | Harness externo, por emissão | relay sync | O outro harness (Claude Code, Codex, Copilot, Gemini) | A UI do harness que você já usa | | Harness nativo, pelo CLI | relay chat, relay auto | O Relay, no processo do CLI | Seu terminal | | Harness nativo, pelo desktop | O app do fork Code - OSS (Agents) | O Relay, num sidecar que o Agent Host spawna | A UI de sessões do desktop |

A nota de arquitetura — incluindo o que deliberadamente não é igual entre os três — está em docs/arch/tres-modos.md.

Principais recursos

O fluxo

• Fluxo de 10 gates (templates/flow.md) — descoberta → especificação (SDD) → segurança desde o design → arquitetura/SLOs → teste primeiro → implementação → CI e cadeia de suprimentos → validação → pentest da aplicação → prontidão para release → observabilidade → aprendizado contínuo → pentest local (réplica local) → pentest de VPS/nuvem. Cada gate tem um protocolo obrigatório, uma calibração de profundidade e um papel/modelo associado.
• Imposição mecânica — dois hooks de git instalados por relay init/relay sync:
  • relay gate guard (hook commit-msg) — o gate de fundamentação: bloqueia um commit de código substantivo que pulou a biblioteca (fail-open por design).
  • relay gate prepush (hook pre-push) — a guarda de pouso: bloqueia um push para develop/main que esteja sem um gate obrigatório {2, 4, 6, 7, 8}, devolvendo um veredicto de três valores allow / deny / could-not-evaluate — falhas de ferramental aparecem em voz alta, nunca colapsam silenciosamente em allow.
• Detecção de falso sucesso (CA4) — um detector heurístico (relay fs status|calibrate) mais uma regra de turno (no-unverified-completion) que dispara quando o assistente afirma "pronto"/"testes passando" sem uma execução de verificação registrada desde a última escrita.
• Quatro condutores — /relay (interativo, para para sua aprovação em cada gate), /relay-intake (a porta de entrada: triagem + especificação rica), /relay-triage (laço não assistido sobre falhas de CI/issues/commits), /relay-auto (execução autônoma dos gates com auto-aprovação, monitoramento de contexto e retomada). Os quatro são slash commands reais dentro do próprio relay chat, não apenas num harness emitido — o relay segue o próprio padrão de emissão para o próprio harness nativo (--target relay, .relay/agents|skills|commands/).
• Isolamento obrigatório por worktree — relay worktree start [slug] cria um worktree git novo a partir de develop para cada tarefa, em qualquer harness; relay worktree finish|prune limpam depois do merge.

Papéis, skills e regras

• 22 papéis — voltados ao desenvolvimento de software em geral (engenharia, arquitetura, dados, ops, qualidade, segurança e design; por exemplo tech-lead, software-engineer, software-architect, security-engineer, qa-guardian, sdet, ux-designer, ...). A relação papel ↔ skill é 1:1 (invariante R7), e o grafo de delegação (spawns) é um DAG validado, executado pela ferramenta task.
• 30 skills — 22 pareadas com papéis + 4 meta-skills (self-learning, quality-baseline, choose-visual-direction, relay — orquestração multiagente entre famílias de modelos, utilizável de forma autônoma) + 5 extra_skills de papéis (incident-response, supply-chain-security, secure-coding-patterns, pentest-infrastructure, audit-visual-design).
• 6 regras — core, grounding-at-commit, no-secrets, no-unverified-completion, schema-change, test-first. As regras carregam frontmatter (condition, scope, interruptMode, alwaysApply) avaliado por um motor de regras de turno (TTSR) no meio do stream, de modo que uma regra dispara enquanto o modelo produz prosa ou uma chamada de ferramenta — não depois do fato.

Harness nativo

• 18 provedores — 13 por chave de API (anthropic, openai, openrouter, deepseek, groq, mistral, google, xai, zai, moonshot, together, fireworks, cerebras), 4 locais sem chave (ollama, llamacpp, lmstudio, vllm) e 1 endpoint customizado compatível com OpenAI.
• Laço de agente (agent/loop.ts) — um motor que não sabe nada de disco, sessão ou política; toda decisão é um callback. Um único laço serve a sessão principal, os subagentes e o consultor.
• Consultor e fallback reativo — um revisor em segundo modelo (--advisor, somente leitura) e fallback de modelo entre provedores quando o principal falha.
• Sessões — árvore de entradas append-only (id/parentId) com fork, branch, undo e compactação (relay session).
• Checkpoint e retomada — estado de tarefa durável e atômico por sessão (src/session/checkpoint.ts, .relay/checkpoints/): objetivo, gate, plano, etapas concluídas com a evidência que as prova, arquivos alterados, testes executados, decisões, erros pendentes, próxima ação segura e uma impressão digital do workspace. Escrito automaticamente a cada turno assentado, antes de uma compactação e no cancelamento; lido de volta por relay session resume.
• Orçamento — controle de tokens/moeda (src/session/budget.ts, .relay/triage.json), respeitado inclusive na delegação a subagentes.
• Ferramentas sob um contrato único — leitura/escrita/edição de arquivo, shell, busca, carregamento de skills, delegação, kernels de avaliação de código, artefatos, ask_user, automação de navegador e mais. As 26 declaram o mesmo contrato — propósito único, timeout, teto de output, se alteram o workspace, se a saída é redigida, se podem ser canceladas — e o dispatcher impõe esse contrato, de modo que uma ferramenta que não declara nada recebe o padrão conservador em vez de uma isenção. Os resultados carregam classe de erro, duração e indicação de mutação; relay obs --tools imprime o inventário completo.
• Observabilidade — relay obs registra o que uma execução realmente fez: cada chamada de ferramenta e cada chamada de modelo, correlacionadas por sessão, turno e id da chamada, com provedor, tokens, latência, tentativas, custo estimado, fallbacks, compactações, checkpoints e o gate atual. Os eventos carregam uma allowlist de campos — nunca um prompt, o conteúdo de um arquivo ou um argumento de ferramenta — e todo texto neles é redigido antes de ser gravado.

Projetos e memória

• Matrícula — relay init / relay sync escrevem .relay/ (perfil da stack, receitas de build/test/lint/run, árvore de memória, política de triagem) e emitem os arquivos adaptadores no harness alvo escolhido.
• Biblioteca / RAG — relay up roda nativamente (um embedder ONNX em processo + um vector store SQLite embutido, nada para rodar) e ingere um corpus de referência empacotado (library/) de livros de engenharia.
• Memória e diário — diário por projeto (relay journal, JSONL) apoiado por um índice de memória local e polifônico (recuperação vetorial + grafo + fatos
  • temporal, sem servidor para manter), e skills de projeto (relay learn distill escreve em .relay/skills/ e sobrepõe a embutida de mesmo nome).
• Redação de segredos — uma camada de redação compartilhada protege segredos em exportações e em qualquer outro lugar em que o harness emita conteúdo; as credenciais são guardadas com proteção do sistema operacional (DPAPI no Windows).

Inteligência, integração e aprendizado

• Grafo de estrutura do projeto (relay graph) — um grafo da forma DESTE projeto (stack, árvore de módulos, ADRs/features/bugs/lacunas), reconstruído sob demanda e exportado como um cofre pronto para Obsidian em .relay/graph/obsidian/, para navegar visualmente por toda a estrutura.
• Inteligência entre projetos — grafo de conhecimento extraído da biblioteca (relay library graph), insights anonimizados de frota (relay fleet), mais módulos de confiança, contradição, efetividade, padrões, predição, risco e similaridade de projetos (src/intelligence/).
• MCP — as memórias do Relay (biblioteca + diário) expostas como um servidor MCP em stdio (relay mcp); servidores MCP externos podem ser consumidos dentro do relay chat (relay mcp add ...).
• Geração de documentos — relay doc renderiza qualquer arquivo Markdown para docx/pdf; relay export monta um intervalo de gates/sessões num entregável redigido e compartilhável.
• Aprendizado e feedback — relay learn distill destila uma skill reutilizável de uma sessão bem-sucedida (automático ao fim da sessão); relay feedback conta ao scaffolder o que deu errado para ele aprender entre projetos.
• Contexto — relay context status|files|explain|reload mostra quais arquivos de instrução (AGENTS.md, CLAUDE.md, ~/.relay/SYSTEM.md) o modelo realmente recebeu, em que ordem, qual prevalece, quanto cada um consumiu e o que foi truncado, resumido, sombreado ou descartado. /context faz o mesmo dentro do relay chat.
• Confiança no projeto — um repositório é entrada não confiável. relay trust status|add|remove|deny|list é a decisão explícita, vinculada ao caminho canônico do projeto (com symlinks resolvidos) e à identidade da pasta no sistema de arquivos, que fica entre clonar um repositório e deixar rodar seus .relay/plugins, .relay/mcp.json, skills, papéis, regras ou receitas. Sem ela, um projeto que traz essas coisas roda em modo limitado: nada fornecido pelo projeto é carregado, e rodar um comando sempre pede um sim. Todo o resto continua funcionando.
• Operação — relay doctor (saúde), relay config, relay stats (uso de tokens/custo por gate/papel/modelo), relay obs (o que uma execução de fato fez: durações e desfechos de ferramentas, chamadas de modelo com provedor/tokens/latência/tentativas/custo estimado, fallbacks, compactações, checkpoints, gate atual — humano ou --json; --tools imprime o inventário do contrato das ferramentas), relay fs (status/calibração da detecção de falso sucesso), relay skill transform|skill-lab (ferramental de layout de skills com Progressive Disclosure), relay completions, relay update.

Instalação

Pré-requisito: Node.js ≥ 20.

O caminho mais simples — instalar o pacote npm publicado globalmente:

npm install -g relay-ai-code-agent
# expõe `relay` e `relay-ai-code-agent` no seu PATH
relay version

A partir do código-fonte (para contribuir, ou para acompanhar a main):

git clone https://github.com/eltonssouza/relay-ai-code-agent.git
cd relay-ai-code-agent
npm install
npm run build
npm link            # expõe `relay` e `relay-ai-code-agent` no seu PATH

De qualquer forma, o próximo passo é o mesmo:

relay up               # stack RAG nativa, in-process; a primeira execução baixa o modelo de embedding (depois fica em cache)

Início rápido

# 1. Instale (veja acima) e suba a biblioteca de referência.
relay up

# 2. Matricule um projeto e emita o Relay no seu harness.
cd /caminho/do/seu-projeto
relay init            # stack .relay/, receitas, árvore de memória + emissão (padrão: claude)
relay detect          # veja as linguagens/frameworks do projeto
relay up              # rode de novo A PARTIR do projeto: ingere também os livros da stack dele

# 3. Recarregue seu harness de IA nesse projeto e conduza uma feature:
#    /relay implement <sua feature>   (interativo — para em cada gate)

Úteis pelo caminho:

relay library "<pergunta>"              # fundamente uma resposta nos livros de referência (RAG)
relay journal recall "<pergunta>"       # o que este projeto já decidiu
relay sync                              # depois de atualizar: renove um projeto matriculado
relay chat --gate 9 --role application-security-engineer   # conversa nativa, modelo do gate + papel

Usando o Relay nativamente

No modo nativo o relay é o harness — ele guarda as próprias credenciais (ou fala com um servidor de modelo local sem chave), roda o próprio laço de agente e lê papéis/skills/fluxo direto de templates/ sem emitir nada. Nada mais precisa ser instalado.

relay auth                          # veja quais provedores estão configurados
relay auth login                    # entre / cole uma chave — sem precisar de sessão de chat
relay models                        # o que o Relay consegue chamar de fato, por provedor

relay chat                                  # fale com o modelo; /login /models /effort por dentro
relay chat --gate 9 --role application-security-engineer   # modelo do gate + papel, pontual
relay auto "adicionar rate limiting na API"                # conduz os 10 gates autonomamente,
                                                           #   registrado no diário, para só numa
                                                           #   aprovação humana obrigatória

relay session list|inspect|resume|checkpoint|abandon|log|branch inspeciona, retoma e bifurca a árvore append-only de sessões por trás de cada execução de relay chat/relay auto. Uma execução faz checkpoint de si mesma conforme avança — objetivo, gate, plano, etapas concluídas com a evidência que as prova, arquivos alterados, testes executados, decisões, erros pendentes e a próxima ação segura — então relay session resume <id> retoma a tarefa depois de um Ctrl+C, de um terminal fechado, de uma falha do provedor, de um token expirado ou de uma compactação de contexto, e se recusa até você confirmar quando o workspace divergiu desde o checkpoint. Este é o modo a escolher quando você não tem (ou não quer gastar) uma assinatura Claude/ChatGPT — traga sua chave de API, ou rode totalmente offline contra Ollama/llama.cpp/LM Studio/vLLM. Veja docs/features/pt-BR/native-harness.md e docs/features/pt-BR/auth-providers-models.md.

Vendo quanto uma execução custou e quão lenta foi

relay stats imprime duas tabelas no mesmo eixo gate/papel/modelo: tokens com preço estimado, e latência com tentativas (chamadas, média, máximo). As duas leem os arquivos de sessão, então funcionam depois do fato sobre qualquer execução registrada; relay stats --session <id> restringe a uma, e relay stats --json imprime os mesmos números como documento. O tempo é opcional no schema da sessão — uma chamada que o harness nunca cronometrou é contada mas fica fora da média, e a tabela diz quantas foram, em vez de fazer média com zero.

relay obs responde a outra metade da pergunta: não quanto os modelos custaram, mas o que o harness fez. Toda chamada de ferramenta é registrada com sua duração, desfecho, classe de erro, se alterou o workspace e se a saída foi truncada; toda chamada de modelo com provedor, tokens, latência, tentativas e custo estimado; mais o motivo de um modelo ter sido escolhido ou trocado, cada compactação, cada checkpoint e o gate atual — correlacionados por sessão, turno e id da chamada de ferramenta. --json para um documento, --events para o stream cru, --tools para o contrato que cada ferramenta declara (propósito, timeout, teto de output, se altera o workspace, se redige a saída, se pode ser cancelada). Os eventos nunca carregam um prompt, o conteúdo de um arquivo ou um argumento de ferramenta: cada tipo de evento tem uma allowlist de campos e todo texto neles é redigido antes de ser gravado. Fica em .relay/telemetry/observability/, e desliga com RELAY_OBS=0 ou {"observability": {"enabled": false}} em .relay/triage.json. Veja docs/harness-parity-priority-6.md.

Apontando um provedor para outro lugar

O endpoint de qualquer provedor pode ser sobrescrito com RELAY_<PROVEDOR>_BASE_URL (hífens no slug viram underscores: RELAY_AZURE_OPENAI_BASE_URL). Isso cobre Ollama numa máquina com GPU, um vLLM auto-hospedado atrás de outro host, ou um recurso Azure OpenAI, que não tem endpoint compartilhado nenhum — azure-openai também lê AZURE_OPENAI_ENDPOINT. O relay sonda o host resolvido quando atualiza a lista de modelos de um provedor, não o padrão do registro.

Três protocolos, não dois

O Relay fala Anthropic Messages, OpenAI Chat Completions e OpenAI Responses. O terceiro importa para modelos de raciocínio: Completions não tem item reasoning, então um modelo da família gpt-5 re-deriva o próprio pensamento do zero a cada ida e volta de chamada de ferramenta. Por Responses o item de raciocínio volta criptografado e é reproduzido literalmente na próxima requisição, de modo que o pensamento sobrevive ao turno. Nada é armazenado no servidor (store: false).

openai-responses chega lá com a mesma OPENAI_API_KEY que o provedor openai já usa — uma chave, dois protocolos, escolhidos pelo modelo (/model gpt-5.4). O provedor openai continua falando Completions, que segue sendo o protocolo certo para modelos sem raciocínio e para todo o ecossistema compatível com OpenAI (Groq, Together, Ollama, …). Veja a ADR-0051.

Entrar com login em vez de colar uma chave

relay auth login <provedor> — e /login <provedor> dentro do relay chat, que é o mesmo serviço (ADR-0055) — oferece login pelo navegador onde houver um disponível, e cai para entrada mascarada de chave de API caso contrário. --device-code toma o caminho headless e --no-browser imprime a URL em vez de abri-la. Os tokens são guardados no mesmo cofre de credenciais protegido por DPAPI que as chaves, renovados automaticamente antes de expirarem, e descartados (token de acesso e de refresh) por relay auth logout. relay auth mostra signed in para um provedor mantido assim.

Um login não para na credencial: ele valida a chave antes de gravá-la (uma chave recusada nunca é armazenada), depois sincroniza o catálogo de modelos daquele provedor e relata o que encontrou, de forma que autenticado → catálogo sincronizado → modelo selecionado → pronto é um único comando. Quando a atualização do catálogo falha depois, o login continua valendo — você recebe a lista em cache e o comando que corrige, nunca um "faça login de novo".

OpenRouter é o login que funciona de imediato. O Relay deliberadamente não distribui o client_id OAuth de primeira parte de nenhum outro fornecedor: fazer isso é como uma ferramenta de terceiros se passa pela CLI ou pelo editor do próprio fornecedor para alcançar uma assinatura, e este repositório recusa isso (ADR-0050, imposto pelo teste no borrowed client identity em tests/providers.test.ts). Os fluxos de Anthropic, xAI, Kimi For Coding e GitHub Copilot estão implementados e testados, mas cada um se recusa a rodar até que RELAY_<PROVEDOR>_OAUTH_CLIENT_ID nomeie um app OAuth registrado para o Relay — a recusa nomeia a variável exata. Anthropic, xAI e Moonshot (Kimi) aceitam uma chave de API comum hoje, o que não precisa de nada disso.

Usando o Relay com outro harness (Claude Code, Codex, …)

No modo emissor o relay escreve os papéis, skills e fluxo do Relay no layout nativo de outra CLI e depois sai da frente — você continua dirigindo a CLI da sua assinatura exatamente como sempre, só que moldada pelos gates e papéis do Relay. Cinco alvos são suportados — incluindo o próprio relay chat, para que o harness siga o próprio padrão em vez de ser um caso especial:

| Alvo | Chave | Emitido em | |---|---|---| | Claude Code | claude | .claude/ (agents, skills, commands) + CLAUDE.md | | Codex | codex | .agents/skills/ (papéis + condutor como skills) + AGENTS.md + .codex/config.toml | | Gemini CLI | gemini | .gemini/commands/*.toml (papéis + condutor + skills) + GEMINI.md + .gemini/settings.json | | GitHub Copilot | copilot | .github/skills/ (papéis + condutor como Agent Skills) + .github/copilot-instructions.md + .github/mcp.json | | Relay (o relay chat nativo) | relay | .relay/ (agents, skills, commands) + AGENTS.md (compartilhado com o Codex) |

relay target list                   # veja o que está disponível
relay init --target claude          # ou: codex, gemini, copilot, relay, uma lista separada por vírgula, ou "all"
relay target update codex           # troque/adicione um alvo depois, sem rematricular

Exemplo — Claude Code

relay init --target claude
# escreve .claude/agents/<papel>.md, .claude/skills/<skill>/SKILL.md,
#         .claude/commands/relay.md (+ relay-auto.md, relay-intake.md, relay-triage.md),
#         CLAUDE.md (conectores MCP ficam em .relay/mcp.json, compartilhado por todos os alvos)

Recarregue o Claude Code no projeto e conduza o trabalho com os slash commands emitidos: /relay <demanda> (interativo), /relay-intake <demanda> (triagem + especificação primeiro), /relay-auto <demanda> (autônomo). Os papéis rodam como subagentes do Claude Code (.claude/agents/); o grafo de delegação em src/gate/roles.ts decide quem pode invocar quem.

Exemplo — Codex

relay init --target codex
# escreve .agents/skills/<skill>/SKILL.md (uma por papel),
#         .agents/skills/relay/SKILL.md (+ relay-intake/, relay-auto/, relay-triage/),
#         AGENTS.md, .codex/config.toml

O Codex não tem superfície nativa de comandos nem campo de modelo por skill, então cada papel é entregue como uma skill invocável ($relay, $relay-intake, ...) e a seleção de modelo/tier é carregada pela meta-skill relay, em vez de um ajuste por alvo.

Exemplo — o próprio relay chat

relay init --target relay
# escreve .relay/agents/<papel>.md, .relay/skills/<skill>/SKILL.md,
#         .relay/commands/relay.md (+ relay-auto.md, relay-intake.md, relay-triage.md),
#         AGENTS.md (conectores MCP ficam em .relay/mcp.json, compartilhado por todos os alvos)

Rode relay chat no projeto e conduza o trabalho com os mesmos slash commands do Claude Code — /relay <demanda>, /relay-intake <demanda>, /relay-auto <demanda>, /relay-triage — sem precisar de scaffolding, aliás: o relay chat resolve esses comandos contra as próprias cópias embutidas mesmo sem relay init --target relay jamais ter rodado; a cópia emitida em .relay/commands/ é uma sobreposição editável e local ao projeto, não um pré-requisito. Um .relay/commands/<nome>.md do próprio projeto vira /<nome> do mesmo jeito.

Todo alvo segue a mesma forma: papéis/skills/fluxo caem nos diretórios do próprio harness, AGENTS.md ou CLAUDE.md vira o guia do projeto que o harness lê ao carregar, e os comandos condutores são adaptados ao dialeto de comandos daquele harness (formato do frontmatter, invocação $nome vs /nome, subagentes vs skills). Detalhe completo por alvo: docs/features/pt-BR/dual-mode-emission.md.

O fluxo de 10 gates

| # | Gate | Papel de modelo | |---|---|---| | 1 | Descoberta de domínio e especificação | plan | | 2 | Segurança e privacidade desde o design (shift-left) | slow | | 3 | Arquitetura, design defensivo e SLOs | plan | | 4 | Teste primeiro / especificação executável | default | | 5 | Implementação com código limpo | default | | 6 | Integração contínua, cadeia de suprimentos + gate de qualidade | smol | | 7 | Validação contra a especificação (laço de feedback) | slow | | 8 | Teste de invasão da aplicação | slow | | 9 | Prontidão para release, entrega progressiva e observabilidade | default | | 10 | Aprendizado contínuo | smol |

Os papéis de modelo (slow / plan / default / smol) decidem qual modelo roda cada gate e com quanto esforço. No harness nativo isso é uma decisão executada; na emissão é delegado à CLI licenciada que honra a dica. Os gates 2, 4, 6, 7 e 8 são obrigatórios — a guarda de pouso os impõe no momento do push.

Os comandos condutores

| Comando | O que faz | |---|---| | /relay-intake <demanda> | A porta de entrada. Faz a triagem da demanda — greenfield / feature / bugfix — por risco × complexidade × criticidade, opcionalmente escreve um documento de perguntas ao cliente em linguagem acessível, depois uma especificação rica, e entrega para o /relay. Para antes de gerar documentos para o cliente e antes de entregar. | | /relay <demanda> | O condutor interativo. Conduz a demanda pelos 10 gates, parando para sua aprovação em cada gate — recusa-se a rodar sem supervisão. Calibra a profundidade, nunca pula o checkpoint, nunca colapsa os gates 2, 4, 6, 7, 8. Os papéis dos gates rodam como subagentes. Também pode ser digitado direto no relay chat (veja "Exemplo — o próprio relay chat" acima); o relay auto <demanda> do terminal é o primo não assistido. | | /relay-triage | O laço não assistido (templates/automations/triage.md). Roda em agenda (por exemplo, toda manhã): varre falhas recentes de CI, issues abertas e commits, registra achados no diário, entrega trabalho acionável a subagentes maker/checker. Lê .relay/triage.json (orçamento de tokens, condições de parada) e roda headless. Também pode ser digitado no relay chat para uma passada sob demanda. | | /relay-auto | Execução autônoma dos 10 gates com auto-aprovação, monitoramento de contexto e retomada. Também pode ser digitado no relay chat; o equivalente no terminal é relay auto <demanda>. |

Papéis, skills e regras

• 22 papéis em src/gate/roles.ts — cada um um template de agente em templates/agents/, cada um pareado 1:1 com uma skill. O grafo de delegação (spawns) é um DAG validado de papéis conhecidos (invariante R23).
• 30 skills em templates/skills/*/SKILL.md — cada uma com uma seção "When to use" e passos numerados (invariante R6).
• 6 regras em templates/rules/ — core.md, grounding-at-commit.md, no-secrets.md, no-unverified-completion.md, schema-change.md, test-first.md — regras sempre ativas ou condicionais que disparam em tempo de turno pelo motor TTSR.

A documentação técnica mais profunda de cada template, skill e categoria de livro de referência fica em docs/about/.

Referência da CLI

relay chat [mensagem] [--gate N] [--role R] [--advisor]   # /login, /logout, /models, /effort por dentro
relay auto <demanda>                          # conduz o fluxo de 10 gates autonomamente (nativo)
relay session list|inspect <id>|resume <id> [--yes]|abandon <id> [--reason T]
relay session checkpoint [--session ID] [--objective T] [--gate N] [--next T]
             [--complete ETAPA --evidence PROVA]   # nunca concluída sem evidência
relay session log <id> [--all]|branch <id> [--at ENTRY_ID] [--label X]
relay auth [--all] [--json]                   # provedores que o Relay conhece / quais estão configurados
relay auth login [provedor] [--method account|api-key] [--device-code] [--no-browser]
                 [--api-key-stdin] [--model SLUG] [--json]
relay auth logout <provedor> [--json] | relay auth refresh <provedor> | relay auth setup
relay models [provedor] [--all] [--json] | models refresh [provedor] | models use <p> <slug>
relay stats [--session <id>] [--json] | relay stats --skills [--by gate|role|skill] [--eru]
relay obs [--session <id>] [--kind K] [--limit N] [--events] [--tools] [--json]
                                              # durações/desfechos de ferramentas, chamadas de modelo
                                              # com provedor/tokens/latência/tentativas/custo,
                                              # fallbacks, compactações, checkpoints, gate atual
relay skill transform <slug> --to pd|flat [--write]
relay skill-lab <skill> --trials N --conditions none,flat,pd
relay fs status|calibrate                     # detecção de falso sucesso (CA4)
relay context [status|files|explain|reload] [--json] [--project P] [--cwd D]
                                              # quais arquivos de instrução o modelo recebeu, em que
                                              # ordem, quanto cada um custa, o que ficou de fora
relay init [caminho] [--target spec] | relay sync [caminho] | relay detect [caminho] | relay list
relay worktree start [slug] | list | finish <ref> [--force] | prune
relay target list|show [caminho]|update <spec> [caminho]   # alvos de emissão (modo duplo)
relay library "<pergunta>" | map|status|stacks|reindex|update|add|export|import|compact
relay journal add|recall|log                  # diário do projeto
relay journal edit <id> [texto] --mode update|forget|invalidate
relay learn distill                           # destila uma skill (automático: SessionEnd)
relay gate guard|status                       # gate duro de fundamentação (automático: commit-msg)
relay gate prepush|land-status                # guarda de pouso (automático: pre-push)
relay rules remind                            # imprime as regras de turno deste projeto
relay up | down | ingest                      # stack RAG nativa, in-process
relay mcp [status|add|remove|enable|disable|reconnect ...]   # configuração de servidor/cliente MCP
relay doc <arquivo.md> [--format docx|pdf|both]  # renderiza docx/pdf a partir de markdown
relay export [--gates N-M] [--kind k1,k2] [--format docx|pdf|html]
relay graph <entidade>|build|stats            # grafo de estrutura DESTE projeto -> cofre Obsidian
relay library graph <entidade>|build|stats    # grafo de conhecimento da biblioteca de referência
relay fleet [--save|--json]                   # insights entre projetos
relay feedback "<...>"|report|list|consent    # feedback para o scaffolder
relay config get|set|validate
relay sandbox status [--path P]               # guarda de segredos / backend de sandbox efetivo
relay trust status|add|remove|deny|list [CAMINHO] [--subtree] [--force] [--json]
                                              # se o Relay pode carregar e executar o que um projeto
                                              # traz: plugins, servidores MCP, skills, receitas
relay doctor [--json] [caminho] | relay completions <shell>
relay update [--reinstall]
relay quickstart | version | help

Todo comando aceita relay <comando> --help para ver as opções; comandos desconhecidos recebem uma sugestão "você quis dizer ...?". Referência completa: docs/features/pt-BR/cli-reference.md.

Estrutura do projeto

src/ é organizado com um subdiretório por domínio (nenhum arquivo fica na raiz dele exceto cli.ts, o ponto de entrada de despacho/uso/quickstart):

bin/relay.js            ponto de entrada da CLI (require dist/cli.js)
src/
  cli.ts               despacho de comandos, uso, quickstart
  agent/                harness nativo: laço, host, consultor, comandos
                        chat/auto, frontends tui/plain/json_ui, keybindings
  auth/                 credenciais (DPAPI no Windows), fluxos oauth, arquivo de
                        chaves, provedores habilitados e login_service.ts — o
                        único serviço por trás de `relay auth login` e do
                        `/login` dentro do chat
  core/                 registro de capacidades (skills/papéis/comandos/regras —
                        surfaces.ts), resolução de projeto/.relay/, detect,
                        walk, fs_retry
  gate/                 papéis (a tabela de 22 papéis + grafo de delegação),
                        gate duro de fundamentação, guarda de pouso, asserções
  llm/                  provedores (anthropic, compatíveis com openai), catálogo,
                        compatibilidade de schema, dialeto de tool-call, streaming JSON
  rag/                  núcleo do RAG, ingestão, stack nativa,
                        exportação/importação portátil, busca remota de livros
  memory/               diário (JSONL), backend de memória local,
                        engenharia de contexto (compactação/poda)
  session/              árvore de sessão append-only (fork/branch/undo),
                        checkpoints duráveis de tarefa e retomada, orçamento, stats
  obs/                  observabilidade: eventos tipados, recorder NDJSON,
                        agregação e o comando `relay obs`
  security/             redação, sandbox/jail, detecção de falso sucesso (CA4),
                        CNE (could-not-evaluate), taxonomia de falhas
  skill/                ciclo de vida de skills: resolver, transform, lab,
                        review, telemetria, efetividade, verificador, autoaprendizado
  targets/              emissores de harness: claude, codex, gemini, copilot,
                        e o alvo `.relay/` nativo do próprio relay
  intelligence/         grafo de estrutura do projeto, grafo de conhecimento da
                        biblioteca, frota, RAG ciente de código, confiança,
                        contradição, efetividade, padrões, predição, risco
  worktree/             isolamento obrigatório por worktree git, por tarefa
  tools/                ferramentas do agente: arquivos, shell, busca, skills,
                        task, kernels de eval, artefatos, ask_user, plugins, ...
                        (contract.ts define o contrato comum de todas)
  mcp/                  cliente/servidor MCP (nas duas direções)
  commands/             scaffold (init/sync), doctor, config, docgen,
                        export, feedback, completions
  browser/              ferramentas de navegador com Playwright (ações,
                        asserções, snapshots, artefatos)
  harness/              o runner de testes do próprio repositório (test:lanes)
  ai/                   pequenos helpers compartilhados (metadados de ferramenta)
templates/            superfícies neutras de harness: agents, skills, rules,
                      commands, automations, flow.md, starters de teste e2e/api
library/              corpus de referência empacotado — todas as categorias,
                      incluindo os livros de linguagem e framework. Nada é
                      baixado em runtime (veja rag/stack_catalog.ts)
docs/                 docs de features (en + pt-BR), docs técnicos (about/),
                      ADRs, specs, modelos de ameaça, relatórios de QA
tests/                suítes vitest (portes dos testes do original em Python)
tools/                ferramental de dev do repo: validador de templates, benchmarks

A documentação técnica de tools/, library/ e templates/ fica em docs/about/.

Desenvolvimento

Requer Node.js ≥ 20.

npm install          # instala dependências
npm run build        # tsc -> dist/
npm run dev          # roda a CLI a partir do fonte via tsx (src/cli.ts)
npm test             # vitest run (tests/surfaces, e2e_init, budget, ...)
npm run test:watch   # vitest em watch
npm run lint         # eslint src tests
npm run typecheck    # tsc --noEmit
npm run validate     # invariantes de template/papel/skill do repositório

A suíte de testes é hermética: redireciona RELAY_HOME para um diretório temporário e não precisa de rede para passar.

Todas as versões de dependência são fixas e exatas (sem faixas ^/~; o .npmrc define save-exact=true) — veja o CHANGELOG.md para notas de bump de versão e avisos de depreciação conhecidos/aceitos vindos de dependências transitivas.

Status da porta

Esta é uma porta deliberada, linha a linha, do relay-main em Python, e a maior parte do comportamento é verificada por testes portados e por uma auditoria de paridade completa (mantida junto ao workspace). Ferramentas MCP invocáveis no meio do turno no relay chat interativo, subagentes em worktree isolado e indexação HNSW no núcleo do RAG — outrora as lacunas de destaque da auditoria — já estão implementadas e cobertas por testes (tests/chat_cmd_mcp_wiring.test.ts, o spawn({isolated: true}) de src/agent/host.ts, tests/rag_hnsw.test.ts). As lacunas restantes vivem na própria auditoria de paridade; contribuições para fechá-las são bem-vindas.

Documentação

• Guia de funcionalidades (PT-BR) — um tópico por arquivo: visão geral, fluxo de gates, papéis/skills/regras, harness nativo, provedores/modelos, emissão, biblioteca RAG, memória e diário, exportação e redação, MCP, aprendizado, inteligência entre projetos, referência da CLI.
• Features reference (EN)
• Documentação técnica (docs/about/) — o que há de fato em tools/, infra/, library/ e templates/, arquivo por arquivo.
• Registros de decisão de arquitetura — ADRs cobrindo a costura de redação, o motor TTSR, a guarda de pouso, consultor/fallback, detecção de falso sucesso, hardening e mais.
• Specs, Modelos de ameaça, Relatórios de QA, Postmortems.

Projetos relacionados

• relay-main — o original em Python que este projeto porta.
• relay-library / relay-viewer — o corpus de referência e seu visualizador, parte do ecossistema Relay.

English: this README in English is at README.md.