# Izanagi AI > **v3.24.7** · npm estável: **3.24.5**. Runtime de execução de trabalho orientado a agentes. **Executa sem API key e sem modelo local**: se você já tem o `claude` (Claude Code CLI) instalado e autenticado, `izanagi run` faz trabalho de verdade usando essa autenticação, por subprocesso. > > Arquitetura: **Commander** → contrato de tarefa → roteamento por papel (por TAREFA, não por run) → grafo → verificação por evidência → healing → replan → memória. O run **lê o projeto** antes de decidir e **entrega arquivo** no fim, os dois por nós de tool com permissão declarada. Todo teto declarado (tokens, custo, tempo, retries, agentes, tool calls, concorrência, allowlist de tool) **é aplicado e tem teste que mede o teto**; `Ctrl-C` cancela o run e o `resume` retoma do último batch gravado. 23 agentes especializados, incluindo um coordenador orchestration-only, catálogo de skills v2, CLI publicada no npm (`izanagi-ai`), SDK programático e **topologia poliglota** (Rust · Go · Python · TypeScript) ao lado do runtime legado. **Filosofia:** Arquitetura primeiro. Código depois. Qualidade medida. Evolução contínua. Zero "cara de IA". --- ## Instalação Requisito: Node.js ≥ 18. ```bash npm install -g izanagi-ai # instalação global npx izanagi # ou execução direta sem instalar izanagi --version ``` > O pacote é publicado como `izanagi-ai`; bins: `izanagi` e `izanagi-ai`. --- ## Executar sem API key O Izanagi precisa de um **executor**: alguém que rode os nós do grafo. Existem três caminhos, e o primeiro não pede chave nenhuma. ```bash izanagi doctor # diz qual executor está disponível AGORA ``` | Caminho | O que exige | Como o runtime o chama | |---|---|---| | **CLI de agente** (recomendado) | um agente de codificação já instalado e autenticado: hoje o `claude` no PATH | provider `claude-cli`, por subprocesso em modo print. **Zero configuração**: detectado no PATH | | API key | `IZANAGI_ANTHROPIC_API_KEY`, `IZANAGI_OPENAI_API_KEY`, `IZANAGI_GOOGLE_API_KEY`, `IZANAGI_OPENROUTER_API_KEY` | HTTP direto no provider | | Modelo local | `IZANAGI_OLLAMA_ENABLED=1` ou `IZANAGI_LMSTUDIO_ENABLED=1` | endpoint OpenAI-compatible em localhost | Sem nenhum dos três, o run continua funcionando em **modo headless**: planeja, roteia e verifica de verdade, mas SIMULA o conteúdo dos nós. É o comportamento antigo, e agora ele é o último recurso, não o default de quem nunca configurou nada. ```bash # nada além do Claude Code instalado: izanagi run "Escreva a função validarCPF em TypeScript" --output out # ✔ Execução real: claude-cli # via CLI de agente já autenticado (sem API key) # tools do executor: none (--agent-tools read liga leitura do repositório) ``` ### Os agentes valem em TODO projeto (escopo pessoal) Agente e skill são descobertos **por projeto**: abrir a CLI em outro diretório não encontra nenhum dos 22 agentes nem a biblioteca de skills, e a conclusão natural de quem vê isso é que o framework não funciona. Instale no escopo pessoal uma vez: ```bash izanagi export --cli claude --global # ~/.claude/{agents,commands,skills} ``` Nunca escreve `~/CLAUDE.md`: esse arquivo é a memória global de quem usa, e sobrescrevê-lo injetaria a descrição de um framework em todo repositório aberto. Agentes e skills são aditivos e ficam inertes até serem chamados. ### O orquestrador escolhe o modelo de cada agente O Commander é **determinístico**: classificar, decidir o modo, gerar contratos e estimar custo não gasta um token. O gasto acontece só nos nós, e cada nó recebe o modelo do PAPEL dele, com o agente tendo voz: ``` izanagi run agent-architect --task "desenhar um agente novo" execute agent-architect commander claude-opus-5 <- o agente declara `opus` no JSON dele verify qa specialist claude-sonnet-5 <- papel specialist: tier balanced evaluation - worker claude-haiku-4-5 <- tarefa pequena: tier fast ``` Precedência: `--model` / pin por papel (`IZANAGI_MODEL_SPECIALIST`, config `roles`) > tier declarado pelo agente > default do papel. O hint é um TIER, não um id: `opus` num catálogo sem premium cai para o melhor disponível, e o mesmo agente roda em Anthropic, OpenAI, modelo local ou CLI de agente sem mudar nada. ### Política de tools do executor O subprocesso roda **sem nenhuma tool por padrão** (`--restricted --tools ""`): nada de shell, nada de escrita, nenhum settings do projeto carregado. É o mais barato, o mais determinístico e o mais seguro. ```bash izanagi run "..." # tools: none (default) izanagi run "..." --agent-tools read # Read/Grep/Glob: o executor LÊ o repositório izanagi run "..." --agent-tools write # + Write/Edit: altera arquivos (opt-in explícito) ``` `write` é o único valor que autoriza alteração de arquivo, e Bash nunca entra em nenhuma das políticas. ### Custo, medido O CLI devolve o custo real de cada chamada (`total_cost_usd`), então neste executor o custo do run **é medido, não estimado** por tabela de preço. Números observados nesta máquina, num nó de specialist com chain de skills: | Política | Tokens do nó | Observação | |---|---|---| | `none` | ~20.000 no modo `direct`, ~30.000 num nó de specialist | inclui o system prompt do CLI, cobrado em toda chamada | | `read` | ~68.000 | várias voltas de tool e contexto do repositório multiplicam o consumo | Por isso `--budget` apertado estoura no primeiro nó, e por isso **você não precisa passar `--budget`**: quando o executor é o CLI de agente, o teto default do run sobe sozinho para o piso desta tabela. Piso recomendado: **65.000** por nó com `none`, **148.000** com `read` (a CLI avisa quando um `--budget` explícito fica abaixo disso). O piso não é a média medida: é o topo da faixa observada, com folga de variância, dividido pela menor fatia que a fase `execution` recebe do teto (0,6). O erro aqui não é simétrico. Teto folgado não gasta um token a mais, porque o gasto é o que o nó consome e quem limita dinheiro é `--max-cost`, cobrado sobre custo MEDIDO; teto curto aborta o run **depois** de todo o custo já ter sido pago. Medido: com um piso dimensionado pela média, um run orchestrated produziu cinco artefatos válidos (7,4KB + 13,7KB + 23,7KB) e terminou sem gravar arquivo nenhum. Teto não é gasto: num run orchestrated real o teto ficou em 260.000 e o consumo medido foi 147.140 (US$ 0,94). Para limitar dinheiro, use `--max-cost`. Controles: `IZANAGI_AGENT_CLI_DISABLED=1` desliga o executor · `IZANAGI_AGENT_CLI_TIMEOUT_MS` ajusta o timeout (default 300.000) · `IZANAGI_AGENT_CLI_TOOLS=read|write` é o equivalente de `--agent-tools` por ambiente. Dentro de um test runner o executor fica desligado por padrão, para que `npm test` nunca gaste cota real (`IZANAGI_AGENT_CLI_IN_TESTS=1` libera). --- ## Pesquisa aplicada: design, agentes e segundo cérebro As referências encontradas nos posts salvos foram separadas entre inspiração e evidência. O framework absorve apenas padrões verificáveis: - **Design:** Apple HIG e Playwright reforçam decisões centradas no usuário, contratos explícitos e teste do comportamento visível; isso alimenta `anti-ai-slop`, `design-directions`, `motion-design` e o QA visual. - **Processo:** Spec Kit confirma o valor de separar constituição, especificação, plano, tarefas, implementação e convergência. O Izanagi já faz isso por contratos, grafo, verificação e journal; a especificação deve ser um artefato de entrada, não um prompt descartável. - **Segurança:** Strix e o padrão “produzir → refutar → corrigir” inspiram uma etapa adversarial, mas qualquer ferramenta externa deve ser validada por fonte oficial antes de entrar no catálogo. - **Segundo cérebro:** **Markdown é a fonte canônica e Obsidian é uma interface humana opcional**. Use `raw/`, `wiki/`, `decisions/` e `output/`; não introduza banco vetorial até um benchmark provar ganho. O grafo visual ajuda navegação, não substitui `MemoryStore`, `DecisionJournal` ou `EvidenceRegistry`. Fontes e classificação: [`references/instagram-ai-leads-2026.md`](references/instagram-ai-leads-2026.md). **Integridade das skills:** o build valida que toda `SKILL.md` v2 tem alias no resolver e que toda skill declarada por um agent resolve para um arquivo real. No runtime, skills explícitas do nó são preservadas quando o ranking dinâmico adiciona contexto; cada tarefa recebe no máximo três skills ranqueadas. Em uma medição local de `--prompt-only --compact`, uma landing page gerou cerca de 13k tokens de prompt, antes do overhead do executor; use `--compact` para discovery e reserve `read`/`write` para nós que realmente precisam do projeto. ## Quick Start ```bash # 1. Inicializa um projeto com .agents/ e seleção interativa de packs de skills izanagi init my-project # ou sem interação: izanagi init my-project --packs core,agents,coding,database # 2. Executa uma tarefa. O modo é decidido pelo Commander, não fixo. # Sem API key: basta ter o Claude Code CLI instalado (izanagi doctor confirma). izanagi run "Converta 10 dólares para reais" # modo direct: 1 chamada, sem grafo izanagi run "Criar uma landing page de um SaaS de analytics" # modo composto, com verificação izanagi run "..." --mode autonomous --max-cost 0.50 # teto de custo respeitado no plano izanagi run "adicionar paginação em GET /users" --output docs # lê o projeto e entrega o arquivo izanagi run "..." --acceptance "o endpoint aceita ?page e ?limit" # o que o usuário pediu, cobrado izanagi run "..." --output src --verify-tests # a métrica de teste vem do exit code do projeto izanagi run "..." --min-quality 0.3 # a estratégia mais barata que atinge o piso izanagi run "..." --reuse-artifacts # segundo run da mesma pergunta não repaga a chamada izanagi run "..." --agent-tools read # o executor lê o repositório antes de responder # 3. Observabilidade, custo e auditoria izanagi trace # spans, healing, graph, avaliação izanagi budget # para onde foi o orçamento: tokens por fase, custo, cache, degradação izanagi models # qual modelo cada papel receberia agora, e por quanto izanagi explain # por que o Izanagi decidiu o que decidiu izanagi doctor # integridade da instalação (--deep inclui security scan das skills) ``` ### Execução proporcional ao problema O Commander classifica o objetivo (complexidade 1 a 5 + domínios) e escolhe um dos quatro modos. Antes, toda tarefa virava um grafo de 3 a 9 nós, inclusive "converta 10 dólares para reais". | Modo | Quando | Forma | |---|---|---| | `direct` | tarefa trivial de um domínio | 1 chamada, sem grafo, sem crítica | | `assisted` | tarefa simples | 1 especialista + verificação determinística | | `orchestrated` | problema composto | grafo com verificação, sem cauda opcional | | `autonomous` | problema amplo (5/5 ou 3+ domínios) | grafo + healing + replan + verificação final | `--mode` força o modo. Sem override, um teto `--max-cost` faz o plano **degradar** de modo em vez de estourar o orçamento em silêncio. ### Inteligência assimétrica Cada tarefa recebe o modelo do seu papel, não o modelo do run: `commander` (tier premium) planeja e coordena, `specialist` (balanced) executa, `worker` (fast) faz extração, formatação e validação. Uma retentativa **escala** o papel em vez de repetir o modelo que já falhou. Fixe modelos por papel em `.izanagi/izanagi.config.json`: ```json { "roles": { "commander": { "model": "claude-opus-4-1" }, "specialist": { "model": "claude-sonnet-4-5" }, "worker": { "model": "gemini-2.0-flash" } } } ``` ### Verificação por evidência Nenhuma tarefa termina porque o agente disse que terminou. Cada contrato carrega critérios de aceite derivados do schema real do artefato **e os que o usuário declarou** (`--acceptance`), e a Verification Engine devolve `VERIFIED`, `FAILED` ou `UNVERIFIED`. Com `--verify-tests`, um dos critérios é o **exit code** do comando de teste do projeto: a única camada do runtime que decide por execução, e não por leitura de texto. Critério semântico é julgado por um modelo barato (papel `worker`, artefato resumido); com `--no-judge`, ou sem provider, ele **nunca vira aprovação**: fica `UNVERIFIED`, e o run reporta isso. Juiz que não conseguiu decidir também não reprova. Com `--prompt-only`, apenas compila `izanagi-prompt.md` para colar manualmente em outra ferramenta, sem executar nada. Nós de aprovação (`human-in-the-loop`) pausam a execução até `izanagi approve `. ### O run lê o projeto e entrega arquivo Dois nós do plano não chamam modelo nenhum: eles passam pela `ToolRegistry`, com permissão declarada no contrato, trust tier pela origem e política aplicada **antes** de executar. | Nó | Quando | Permissão | O que faz | |---|---|---|---| | `survey` | default num diretório com manifesto reconhecido; `--no-survey` desliga | `fs:read` | Levanta stack, manifestos, árvore por extensão, entrypoints e o começo do README. O resultado entra no contexto mínimo das tarefas raiz | | `materialize` | `--output `, e só quando o plano produz artefato que pode carregar código | `fs:write` | Escreve os arquivos que o agente declarou (`### FILE: ` + bloco de código) em `//` | | `deliver` | `--output ` | `fs:write` | Grava o que o run produziu num documento único dentro do projeto | Nenhum nó de agente recebe permissão nenhuma: um agente não escreve, não lê arquivo e não executa comando. Há teste que percorre o plano inteiro conferindo isso nó a nó. O survey existe porque a alternativa era pior e invisível: um agente escrevia sobre um projeto que nunca viu, inventava a stack e os caminhos, e o artefato passava na verificação — o schema pergunta se os campos existem, não se correspondem a alguma realidade. O levantamento é determinístico (não custa token), tem teto de profundidade e de entradas, e **declara o próprio corte**. Só as raízes do grafo dependem dele: repetir o mesmo levantamento em sete prompts seria a duplicação de contexto que a arquitetura proíbe. A materialização tem uma fronteira que a torna defensável: os arquivos vão para um subdiretório da saída, **nunca por cima do código do projeto**. Aplicar sobre a fonte exigiria uma garantia que nenhuma verificação determinística consegue dar hoje; quem quer aplicar revisa e copia — e é aí que uma pessoa olha o diff. A escrita é **tudo ou nada**: a validação roda sobre o manifesto inteiro antes de qualquer arquivo tocar o disco, porque "6 arquivos escritos, 3 recusados" é o relatório que engana. Arquivo vazio, caminho absoluto, escape de diretório e marca de trabalho não feito (`TODO`, `FIXME`, `implement later`) recusam o manifesto inteiro. A entrega muda o que a verificação significa. Um critério `file-exists` sobre um arquivo que ninguém escreveu passa quando o arquivo já existia por outro motivo; aqui o arquivo é gravado pela `ToolRegistry` e conferido depois, então o critério passa a significar "o runtime gravou isto". O nome do arquivo sai do objetivo, então repetir o mesmo objetivo reescreve a mesma entrega em vez de acumular um arquivo por execução — entrega é produto, e o histórico continua em `.izanagi/state/`. ### SDK ```ts import { izanagi } from 'izanagi-ai'; // Estimar antes de gastar: nenhum token é consumido aqui. const plan = izanagi.plan({ objective: 'auditar a API de login' }); console.log(plan?.mode, plan?.estimate.maxCostUsd); const run = izanagi.run({ objective: 'auditar a API de login', budget: { maxCost: 0.5 }, output: 'docs', // grava a entrega em /docs; fora da raiz, run() rejeita antes de planejar // survey: false // default: ligado quando baseDir tem manifesto reconhecido }); run.on('task:start', (e) => console.log(e.data)); const result = await run; console.log(result.status, result.telemetry?.estimatedCostUsd, result.verification); console.log(result.deliveredTo); // só presente quando a gravação REALMENTE aconteceu ``` --- ## Arquitetura Poliglota O crescimento novo vive numa topologia poliglota que coexiste com o runtime npm legado em padrão Strangler Fig (ADR-001): contratos IPC, error codes e env vars canônicos em [`docs/POLYGLOT.md`](docs/POLYGLOT.md). | Componente | Linguagem | O que faz | Como testar | |---|---|---|---| | `crates/izanagi_core` | Rust | Quality engine: 7 heurísticas anti-slop sobre TS/Python/Go; protocolo NDJSON stdin/stdout (`validate`/`rules`/`version`) + op `scan-rationalizations`; bindings WASM feature-gated | `cargo test --workspace` (126 testes declarados no fonte) | | `crates/izanagi_mcp` | Rust | Cliente MCP JSON-RPC 2.0 sobre stdio: discovery + invocação pontual (`izanagi-mcp call --tool=`) | incluso no `cargo test --workspace` | | `go-services/swarm_orchestrator` | Go | Orquestrador de swarm (Uber Fx): pipeline architect→engineer→qa→security via JSON-RPC 2.0 sobre UDS com event push | `go build ./... && go vet ./... && go test ./...` | | `python-engine/ast_analyzer` | Python ≥ 3.10 | Análise semântica multilíngue: símbolos, complexidade ciclomática, imports (tree-sitter + fallback estrutural) | `.venv/bin/python -m pytest tests/ -q` (41 testes) | | `packages/sdk` (`@izanagi/sdk`) | TypeScript | Clientes tipados strict para os 4 núcleos + catálogo de skills; zero dependências de runtime | `npm test` dentro de `packages/sdk` (42 testes) | | `packages/cli` (`izanagi-next`) | TypeScript | CLI de nova geração: run em 4 fases com auto-heal (N=2) + gate anti-racionalização; `agent list`, `skill list/show --ref`, `gates check` | `npm test` dentro de `packages/cli` (13 testes) | Diagnóstico rápido de todos os componentes: ```bash izanagi polyglot status # saúde dos núcleos poliglotas (--json | --strict) node packages/agent-migrator/cli.mjs --check # drift YAML ↔ JSON dos agentes node packages/skill-migrator/cli.mjs --dry-run # valida migração skills v1 → v2 sem escrever ``` ### Estrutura do Repositório ```text izanagi-ai/ ├── bin/ Executável da CLI legado (bin/izanagi.js → dist/cli) ├── src/ Runtime real em TypeScript (orchestrator, evaluation, resolver, scanner, factories, tools, tracer, llm, cli) ├── core/ Engines (.md) + skill-resolver.json (aliases → targets + compositions) ├── agents/ 22 definições de agentes em JSON (fonte da verdade dos comandos) ├── skills/ Skills legado v1 (skills//SKILL.md + references.md opcional) ├── .skills/ Catálogo ativo v2 (.skills//SKILL.md + references/) ├── crates/ Rust: izanagi_core (quality engine + WASM) e izanagi_mcp (cliente MCP stdio) ├── go-services/swarm_orchestrator/ Orquestrador de swarm em Go (Uber Fx, JSON-RPC 2.0 sobre UDS) ├── python-engine/ Analisador AST multilíngue (tree-sitter + fallback estrutural) ├── packages/ sdk (@izanagi/sdk) · cli (izanagi-next) · agent-migrator · skill-migrator ├── references/ Curadoria de referências reais por domínio (webgl-3d, scrollytelling, stack-2026...) ├── .agents/memoria/ Memória persistente anti-repetição (contexto, decisoes, erros-corrigidos, learnings) ├── .opencode/ Comandos slash do Opencode (adapters em .claude/, .codex/, .cursor/...) ├── docs/POLYGLOT.md Contratos IPC, error codes, env vars e resumo dos ADRs ├── AGENTS.md Instruções de operação do framework ├── ARCHITECTURE.md Visão arquitetural ├── SYSTEM.md Fundação do sistema (arquitetura real do runtime) └── RULES.md Regras operacionais (Anti-Generic High-Craft & Cinematic UI) ``` --- ## Comandos Principais da CLI CLI legado (`izanagi`, publicada no npm): | Comando | Descrição | |---|---| | `izanagi init [dir] [--packs a,b,c]` | Cria projeto com `.agents/` e seleção de packs de skills. | | `izanagi run [agent] --task ""` | Commander decide o modo, roteia por papel, executa o grafo, verifica contra os critérios de aceite e persiste trace + telemetria de custo. Flags: `--mode direct\|assisted\|orchestrated\|autonomous`, `--budget N`, `--max-cost N`, `--model `, `--local` (só providers locais, e serializa o pool: GPU única não ganha com paralelismo), `--max-concurrency N` (teto de tarefas em voo), `--cache`, `--output ` (grava a entrega no projeto), `--survey` / `--no-survey` (força ou desliga o levantamento do projeto antes de decidir), `--acceptance ""` (repetível: o que a ENTREGA precisa cumprir, além do schema), `--verify-tests` (roda o comando de teste do projeto no fim do grafo e a métrica de teste passa a vir do exit code), `--min-quality 0..1` (compara estratégias e escolhe a mais barata que atinge o piso de VERIFICAÇÃO), `--reuse-artifacts` (reaproveita artefato de run anterior com a mesma pergunta), `--allow-tool ` (allowlist de tools do run), `--agent-tools none\|read\|write` (política de tools do EXECUTOR de processo, diferente de `--allow-tool`: aqui se decide se o subprocesso do agente lê o repositório ou altera arquivos). **Ctrl-C cancela o run** em vez de matar o processo: o batch em voo é abortado, o progresso já gravado fica no checkpoint e `izanagi resume ` retoma dali, `--no-commander` (planejamento legado por categoria), `--no-judge` (desliga o juiz semantico), `--prompt-only`. | | `izanagi models [--json]` | Catálogo de modelos, providers configurados e qual modelo cada papel (commander/specialist/worker) receberia agora, com custo por 10k tokens. | | `izanagi budget [run-id] [--json]` | Para onde foi o orçamento daquele run: tokens por fase, custo estimado, cache local e do provider, contexto poupado, escaladas, degradação e verificação por tarefa. | | `izanagi chat` | REPL interativo da CLI. | | `izanagi dashboard [--port N]` | Dashboard local (Run Explorer, Arena, Memory). | | `izanagi agent create "" [--name=slug] [--skills=a,b]` | Agent Factory: gera agente com genome completo em `agents/generated/` (detecta lacuna vs. 22 core). | | `izanagi agent list \| inspect ` | Lista/inspeta agentes (inclui `agents/generated/`) com genome. | | `izanagi skill create --gap="" [--force]` | Skill Factory: cria skill com frontmatter, security scan pré-escrita e recusa de lacuna já coberta. | | `izanagi skill list \| search \| inspect ` | Lista, busca e detalha skills (catálogo v2, com progressive disclosure). | | `izanagi create ` | Cria scaffold cru de agente (JSON) ou skill (SKILL.md), sem validação. | | `izanagi compile [arquivo]` | Compila um System Prompt completo do agente + fundação do sistema. | | `izanagi workflow list \| inspect