Referência completa do CLI guardian e do protocolo que ele mantém no seu git. Cada comando aqui reflete o --help real da versão instalada. Se algo mudar numa versão nova, o --help do seu CLI é a fonte de verdade.
O GuardianContext é um control plane Git-native: o protocolo de coordenação inteiro vive em arquivos markdown versionados na árvore do seu repositório, sem base de dados separada. Por isso não há setup, o diff fica visível em PR e tudo funciona offline.
O protocolo tem seis peças, todas em arquivo:
Cada caminho é configurável em guardian.json (por exemplo, repositórios que já têm a base de conhecimento em docs/router.md usam guardian init --router docs/router.md).
O modo de trabalho é declarado na linha Modo: shared ou Modo: branches do router.md. Por ser versionado, fica visível a todas as sessões:
wiki/como-trabalhar.md completo nasce com as regras de árvore compartilhada.Trocar de modo depois de instalado é editar o wiki/como-trabalhar.md à mão. O arquivo já existente nunca é sobrescrito por um novo init.
O instalador de uma linha instala o uv se faltar, o pacote guardiancontext[semantic,desktop] (Python 3.11) e abre o Desktop Manager.
irm https://api.ironstack.dev.br/install.ps1 | iexcurl -fsSL https://api.ironstack.dev.br/install.sh | shNo Desktop Manager: criar conta (nome opcional, e-mail, senha, aceite dos Termos de Uso) ou entrar numa conta existente; escolher a pasta do repositório git e o modo de trabalho; o app roda init, hook install, index rebuild, report e license com o log na tela.
O plano free não tem prazo e vale para 1 repositório por conta. A URL do servidor fica em <repo>/.guardian/config.json e a chave de API em ~/.guardian/config.json (fora do repo). Senha e sessão nunca vão a disco.
Alternativa só terminal, sem GUI:
uv tool install --python 3.11 "guardiancontext[semantic]"
cd meu-repo
guardian signup
guardian init
guardian hook install
guardian index rebuild --semantic
guardian reportEm outra máquina ou num clone novo do mesmo projeto, use guardian login: ele lista as instalações da conta e reemite a chave. Esqueceu a senha: guardian reset-password. Chave emitida por um admin ou outro login: guardian configure --api-url … --api-key ….
Depois da conta conectada, o roteiro num repositório novo:
guardian init --mode shared # ou --mode branches
guardian hook install
guardian index rebuild --semantic
guardian report
guardian licenseLayout customizado (repositório que já tem a base de conhecimento em outro lugar):
guardian init --router docs/router.md --wiki docs/wiki --decisoes docs/decisoes \
--trabalho docs/trabalho --quadro docs/quadro.md --quadro-max-linhas 20guardian doctor valida a estrutura inteira (e roda a auditoria); saída diferente de zero indica erro. Rode-o antes de confiar num repositório recém-configurado ou depois de qualquer mudança de layout.
O índice é SQLite híbrido (FTS5 + vetores), derivado dos markdown do protocolo. O rebuild é incremental por sha256: só re-embedda páginas novas ou alteradas.
guardian index rebuild # automático: semântico se disponível, senão lexical
guardian index rebuild --semantic # força o modelo multilíngue
guardian index rebuild --lexical # só FTS5, sem embeddingsA busca combina FTS5 + cosseno com Reciprocal Rank Fusion (RRF):
guardian index search "como fazemos migrations"
guardian index search "regras de push" --tool claude --limit 5
guardian index search "deploy" --kind wiki --lexical --json--tool filtra documentos kind=instrucao (claude|agents|gemini|cursor); os demais tipos de documento valem para qualquer ferramenta. guardian brief empacota o mesmo top-k, mais as regras de instrução da ferramenta escolhida e decisões/trabalho relacionados, pronto para colar num plano:
guardian brief "adicionar rota de cancelamento" --tool claude --limit 5 --max-tokens 2000 --saida .guardian/brief.mdguardian audit é determinística (sem LLM) e cobre: arquivos ausentes, quadro inchado (e artefatos de trabalho inchados, como PLAN.md/PLAN-REVIEW-LOG.md), decisões sem status, claims expirados ou conflitantes, handoffs abandonados e links quebrados entre documentos.
O orçamento do quadro é configurável (--quadro-max-linhas no init, padrão 20 linhas): acima do orçamento é aviso, acima de 3× é erro, sempre com a estimativa de tokens na própria mensagem. guardian doctor roda a auditoria e falha (exit ≠ 0) se houver erro; é o comando indicado para um hook de CI ou uma checagem periódica.
guardian audit
guardian audit --json
guardian doctorClaims reservam um escopo de arquivos com TTL e recusam sobreposição de outro ator; handoffs passam o bastão entre sessões com aceite único (o segundo accept é recusado).
guardian claim --actor claude-sessao-1 --task "rota de cancelamento" --minutes 90 backend/**
guardian release <claim_id> --actor claude-sessao-1guardian handoff create --actor claude-sessao-1 --to codex --work-item "rota de cancelamento" \
--summary "endpoint pronto, falta o teste de idempotência" --files backend/cancelamento.py
guardian handoff accept <handoff_id> --actor codexO hook de pre-commit (guardian hook install) imprime [guardian] branch=<x> head=<sha7> arquivos=<n> a cada commit, recusa staging de arquivo num claim ativo de outro ator (identidade via GUARDIAN_ACTOR ou --actor) e, no modo shared, recusa staging largo (mais de --max-files arquivos, padrão 25, sem um claim do próprio ator cobrindo todos). No modo branches essa checagem não se aplica. O escape é o do próprio git, git commit --no-verify.
Merge: o protocolo em si não tem comando de merge; as regras de merge (fast-forward, PR, nunca --force na principal) ficam no wiki/como-trabalhar.md gerado pelo init --mode branches; claims e handoffs continuam sendo o canal de aviso entre sessões antes do merge.
Cada família de ferramenta lê o próprio arquivo de instrução: Claude Code lê CLAUDE.md; outras famílias leem AGENTS.md, GEMINI.md ou .cursorrules. Sem conciliação, uma regra escrita só num desses arquivos é invisível para as demais famílias.
guardian instrucoes status # tabela por pasta: arquivos, linhas, quem enxerga quem
guardian instrucoes sync # cria/atualiza os blocos de ponteiro nas lacunas (idempotente)O sync nunca copia conteúdo entre arquivos: grava um bloco de ponteiro entre marcadores, apontando para onde a regra da outra família mora. Não muda nenhuma ferramenta nem duplica texto que pode divergir.
guardian benchmark compara, em tokens, quatro cenários de busca no seu próprio repositório: sem base (grep), só um grafo de código, um router bem mantido e o índice do GuardianContext. Sem --casos, o gabarito é derivado da própria tabela do router.md.
guardian index rebuild --semantic
guardian benchmark --markdown relatorio.md --json relatorio.json
guardian benchmark --gerar-casos casos.json # gera o gabarito para você reescrever com suas palavras
guardian benchmark --casos casos.json --markdown relatorio.mdFlags mais usadas: --cenarios nada,router,guardian (escolhe os cenários; o cenário de grafo de código entra por padrão quando já existe um grafo gerado no repositório), --caracteres-por-token (padrão 3.7), --tokenizer cl100k (usa tiktoken em vez da razão caracteres/token, se instalado), --max-linhas-leitura (teto por arquivo lido em todo cenário, padrão 2000 linhas). Os detalhes da metodologia e os números do repositório de referência estão na página de métricas.
A biblioteca curada de padrões é conteúdo da IronStack, alimentada por decisões reais de repositórios instalados, sem nunca centralizar o conteúdo bruto do cliente.
guardian sync-patternsEnvia apenas slug, título, sha256 e embedding do índice local, e nunca o corpo dos documentos.
guardian contribute decisoes/0007-minha-regra.md --tags git,migrationsÉ a única saída que envia corpo de documento: o conteúdo é anonimizado localmente, mostrado inteiro na tela e só sai com sua confirmação (sem terminal interativo, exige --yes). guardian report avisa quando há decisões ou páginas de wiki novas desde o último report; só indica o comando e não envia nada sozinho.
O lado do curador (papel interno da IronStack, exige GUARDIAN_ADMIN_TOKEN):
guardian proposals list --status pending
guardian proposals show <id>
guardian proposals approve <id> --slug meu-slug --tags git,migrations
guardian proposals reject <id> --reason "já coberto pelo padrão X"Claudex Loop: skill de revisão cruzada entre Claude Code e Codex. Antes de cada rodada, concilie as instruções e gere o brief para quem revisa:
guardian instrucoes sync
guardian brief "descrição da tarefa" --tool agents --saida .guardian/brief.mdDetalhes de por que isso resolve o atrito de arquivos de instrução diferentes e sessões sem memória: seção Claudex Loop da página do produto.
Obsidian: para quem mantém um vault do Obsidian junto do repositório:
guardian obsidian-setup # auto-detecta o vault
guardian obsidian-setup /caminho/do/vault --yes
guardian obsidian-monitor /caminho/do/vault --daemon --debounce 2.0Todos os subcomandos de guardian --help, um por linha. Rode guardian <comando> --help para a lista completa de flags de cada um.
| Comando | O que faz |
|---|---|
| guardian init [--mode shared|branches] [--router …] [--quadro …] [--wiki …] [--decisoes …] [--trabalho …] [--claims …] [--handoffs …] [--quadro-max-linhas N] | Bootstrap idempotente da estrutura e do modo de trabalho; grava o layout em guardian.json. |
| guardian doctor | Valida a estrutura e roda a auditoria; falha com exit ≠ 0 se houver erro. |
| guardian hook install [--max-files N] | Instala o pre-commit (idempotente; respeita core.hooksPath). |
| guardian hook uninstall | Remove só o bloco do guardian do pre-commit. |
| guardian hook run {pre-commit} [--actor A] [--max-files N] | Executa o hook; é o que o script em .git/hooks chama. |
| guardian audit [--json] | Auditoria determinística de disciplina (sem LLM). |
| guardian index rebuild [--semantic|--lexical] | Reconstrói o índice SQLite a partir dos markdown; incremental por sha256. |
| guardian index search <query> [--limit N] [--kind K] [--tool T] [--semantic|--lexical] [--json] | Busca full-text/híbrida top-k; --tool filtra documentos kind=instrucao. |
| guardian instrucoes status | Tabela por pasta: arquivos, linhas, quem enxerga quem entre famílias de ferramenta. |
| guardian instrucoes sync | Cria/atualiza os blocos de ponteiro nas lacunas encontradas (idempotente). |
| guardian claim --actor A [--task T] [--minutes N] scope [scope ...] | Reserva um escopo de arquivos (lease); recusa sobreposição de outro ator. |
| guardian release [--actor A] claim_id | Libera um claim ativo. |
| guardian handoff create --actor A --to D --work-item W --summary S [--files ...] | Cria um handoff de continuidade entre sessões. |
| guardian handoff accept --actor A handoff_id | Aceita um handoff pendente (aceite único). |
| guardian signup [--api-url U] [--email E] [--name N] [--repo R] [--invite C] [--aceito-termos] | Cria a conta, a primeira instalação e grava a conexão (o caminho normal de entrada). |
| guardian login [--api-url U] [--email E] [--repo R] [--new] [--yes] | Entra numa conta existente e conecta este repositório; reemite a chave. |
| guardian reset-password [--api-url U] [--email E] | Envia o link de redefinição de senha para o e-mail da conta. |
| guardian configure --api-url U --api-key K | Configura a conexão com o servidor manualmente (chave emitida por outro login/admin). |
| guardian report [--actor A] | Audita e envia o relatório (métricas apenas) ao servidor; enfileira se offline. |
| guardian sync-patterns | Sincroniza patterns locais com o servidor; envia só slug/título/sha256/embedding, nunca o corpo. |
| guardian contribute <arquivo.md> [--tags a,b] [--yes] [--no-embedding] | Propõe uma decisão/regra à biblioteca curada; anonimiza, mostra o texto e pede confirmação. |
| guardian proposals list|show|approve|reject | Curadoria da fila de propostas (admin; token em GUARDIAN_ADMIN_TOKEN). |
| guardian embed <texto> [--semantic|--hashing] [--json] | Gera embedding local de 384 dimensões (para inspeção/depuração). |
| guardian license [--force] | Consulta o estado da licença (validação 1×/dia, com cache e graça offline). |
| guardian benchmark [--casos F] [--gerar-casos F] [--cenarios ...] [--json F] [--markdown F] | Compara em tokens: nada (grep) × grafo de código × router × guardian index. |
| guardian brief "<tarefa>" [--tool claude|agents|gemini|cursor] [--limit N] [--max-tokens N] [--saida F] [--json] | Pacote de contexto em markdown para colar num plano ou briefing de revisão. |
| guardian obsidian-setup [vault_path] [--yes] [--json] | Configura a integração com um vault do Obsidian (auto-detecta ou caminho informado). |
| guardian obsidian-monitor vault_path [--daemon] [--debounce S] | Monitora o vault do Obsidian em segundo plano. |
Sim, para o núcleo local: init, doctor, audit, index, claim, release, handoff e o hook de pre-commit não precisam do servidor. report enfileira e reenvia quando a rede voltar; license usa cache local com carência offline.
Por padrão, nunca o conteúdo dos arquivos. report envia métricas (score da auditoria, contagens, caminhos de arquivo do protocolo, branch/head); sync-patterns envia slug/título/sha256/embedding do índice. A única exceção é contribute, que só envia texto depois de anonimizado localmente e mostrado para você confirmar.
Não. init, doctor, audit, index, claim, release, handoff e hook funcionam sem servidor. A conta entra para report, license, sync-patterns, contribute e a biblioteca curada.
O plano free vale para 1 repositório por conta; a segunda instalação responde com o limite do plano (402). Ver docs/termos-de-uso.md e docs/guia-do-testador.md no repositório do produto.
Removendo os arquivos do protocolo do repositório e rodando guardian hook uninstall. Nada fica preso a um serviço externo, porque o protocolo é git.
Versão publicada · 0.1.9 · 2026-10-02
Sessões de diferentes clientes podem descobrir pares e trocar mensagens no mesmo repositório. O desktop reúne configuração MCP, sessões, envio humano e estado da atualização.
Use o instalador oficial com os extras MCP e update em Python 3.11. No repositório, inicialize o protocolo e instale o hook. Guarde as credenciais apenas na sua máquina. O manual completo do protocolo está em ironstack.dev.br/guardiancontext/manual/.
uv tool install --python 3.11 --refresh "guardiancontext[semantic,desktop,mcp,update]"guardian --versionguardian initguardian hook installguardian-desktopNa aba Operação, escolha o repositório e copie a configuração MCP. Ela inclui os caminhos necessários, sem copiar o token de acesso. O servidor aceita conexões locais autenticadas; mantenha a porta fora da rede. Worktrees do mesmo git common dir compartilham a descoberta de sessões. Clones separados têm identidades distintas. Você escolhe onde colar a configuração do cliente. O servidor MCP não inicia modelos.
guardian --root /caminho/do/repo mcp --configcodex mcp add guardian -- guardian mcpclaude mcp add --scope user guardian -- guardian mcpguardian sessions listInicie a sessão nativa no terminal e mantenha-a em primeiro plano. Forneça a tarefa pelo stdin; o cliente continua usando seu modelo e esforço configurados. No desktop, selecione o destinatário, escreva a mensagem e confirme o envio. A caixa de mensagens pertence à identidade CLI deste worktree. Confirme a leitura apenas depois de ler. Revogar a sessão cancela a identidade; o processo nativo pode levar um ciclo para encerrar. Uma mensagem enfileirada ainda pode estar sem leitura. Se houver dúvida sobre um envio ao provedor, o supervisor não o repete automaticamente. Pipes devem usar UTF-8: tarefas aceitam até 64 KiB e mensagens até 16 KiB. Um BOM inicial é removido; as demais quebras de linha são preservadas. No PowerShell, use $OutputEncoding = [Text.UTF8Encoding]::new($false). As opções --model, --effort e --read-only valem somente para a sessão iniciada. No Codex, --approve-guardian-tools pré-aprova apenas as seis ferramentas Guardian; use após autorização humana. Descarte tem estado discarded e não comprova leitura. messages retry ID --confirm exige ator CLI ativo do mesmo repo e entrega submitted incerta; mantém ID e chave e reconhece o risco de repetição. Purga antiga ambígua fica excluída das confirmações na migração do banco.
guardian sessions start --provider codexguardian sessions start --provider claudeguardian sessions stop IDguardian messages send --to IDguardian messages inboxguardian messages ack IDNa aba Operação você encontra a versão instalada, a política de atualização e o último resultado. Verificar release consulta as versões estáveis compatíveis. Para habilitar uma instalação legada, atualize primeiro os hooks de todos os repositórios e confirme a migração. Fechar e solicitar atualização encerra o desktop antes de preparar ou agendar a troca. Outros clientes ativos podem adiá-la. Reabra depois e confira o resultado. Instalações editable/pip ou de origem desconhecida exigem atualização manual. Preserve locks e journal: removê-los para forçar a troca pode deixar a instalação incompleta.
guardian update statusguardian update check --forceguardian hook installguardian update enable --confirm-legacy-migratedguardian update disableguardian update applydeferred significa que a atualização foi adiada: confira os clientes ativos e a migração dos hooks. journal_failed indica falha antes da instalação; a versão atual foi preservada. rolled_back confirma o retorno após falha no health check. Se aparecer rollback_required ou rollback_failed, reinstale a versão anterior e confira o journal. Mantenha os wheels usados pelo recovery enquanto os receipts apontarem para eles. Uma consulta offline preserva a versão atual. Depois de atualizar, confira a versão instalada e o funcionamento dos clientes usados no seu ambiente. O canário de 2 de outubro de 2026 validou comunicação com modelos reais e recuperação nos cenários registrados; não mede SLA de produção nem comprova todas as formas de upgrade.
Execute a simulação pela aba Operação ou com guardian simulate. Ela cria HOME, GUARDIAN_HOME e repositório descartáveis em outro processo. Os testes usam o SQLite, o protocolo RPC e os bloqueios reais; o modelo, a instalação e o health check são simulados. Os resultados mostram quantos cenários passaram e a latência local. Para avaliar respostas de IA, desempenho de rede ou um SLA, você precisa de medições próprias. As metas do site descrevem o comportamento esperado; os números de simulação valem apenas para os cenários e a amostra informados. Não há uma nota global de qualidade.
guardian simulate --samples 20guardian simulate --samples 20 --json resultado-revisado.jsonguardian benchmarkguardian manual --lang ptO último resultado fica em .guardian/quality-result.json. A gravação usa troca atômica sob lock e mantém um único registro, com versão, data UTC, plataforma, contagens e p50/p95. Corpos de mensagens, IDs de sessões, caminhos e hostname ficam fora do resultado. CLI e desktop consultam esse mesmo arquivo. Você pode exportar o JSON e revisá-lo antes de passá-lo ao gerador do site com --evidence. O aplicativo não envia resultados automaticamente. Uma amostra pequena deixa cenários de produção sem cobertura.