# Economia de tokens no CenaForge Mantido pelo agente `cenaforge-token-auditor`. Princípio: o modelo caro decide e revisa; texto narrativo vai para modelo mais barato; trabalho mecânico vai para script. ## Quem faz o quê | Tarefa | Quem | Por quê | |---|---|---| | Arquitetura, pipeline de render, depuração, revisão final de entrega | modelo principal | erro aqui custa mais que os tokens | | Enredo, bíblia da história, episódios, diálogos, título e opções A/B | `cenaforge-story-writer` (sonnet) | texto criativo não precisa do modelo mais caro; já respeita os limites do JSON | | Dezenas de variações de título/opção, resumo de log, classificação | subagente com `model: haiku` | tarefa curta e repetitiva | | Interface do painel (design, logo, componentes) | `cenaforge-dashboard-designer` (opus) | decisão do usuário: qualidade visual pede o modelo mais capaz | | Atualizar a skill | `cenaforge-skill-updater` | confere fatos sem poluir o contexto principal | | Achar onde algo está no código | agente `Explore` | devolve a conclusão, não os arquivos | | Achar desperdício e criar scripts | `cenaforge-token-auditor` (sonnet) | — | ## Scripts (rode em vez de improvisar comandos) Todos em `.claude/skills/cenaforge/scripts/`, Python 3.10+ só com biblioteca padrão. Rode a partir da raiz do repositório. | Script | Substitui | Uso | |---|---|---| | `runs_summary.py` | ler `report.json`/`render.log` inteiros | `python .claude/skills/cenaforge/scripts/runs_summary.py --last 3 --details` | | `inspect_strip.py` | extrair e ler vários quadros soltos | `python .claude/skills/cenaforge/scripts/inspect_strip.py output/runs/` → lê só `inspect/strip.png` | | `new_scene.py` | ler e reescrever o JSON inteiro | `python .claude/skills/cenaforge/scripts/new_scene.py --id --set overlay.title="..." --set rider.travelMeters=36` (cria e valida) | | `check_skill.py` | conferir caminhos/comandos da skill à mão | `python .claude/skills/cenaforge/scripts/check_skill.py` | | `clean_runs.py` | listar e apagar execuções à mão | `python .claude/skills/cenaforge/scripts/clean_runs.py` (simula) · `--apply` (apaga) | | `frame_check.py` | abrir vários quadros/QA para ver se a cena ficou boa | `python .claude/skills/cenaforge/scripts/frame_check.py --last` · `` · `--config data/tmp/-teste.json [--profile preview]` (renderiza e confere). Resume `report.json` e mede cada `inspect/t*.png` (luminância ESCURO < 0,08 / ESTOURADO > 0,92, contraste CHAPADO < 0,04, movimento PARADO < 0,004, enquadramento FORA se o detalhe foge > 30% do centro) e diz qual UMA imagem abrir. Saída 0 ok · 2 atenção · 1 falha | | `check_script.py` | reler o roteiro à mão | `python .claude/skills/cenaforge/scripts/check_script.py stories/` (ou um `ep*.md`): mesmas regras do leitor do painel (`script-doc.ts`, 2,5 palavras/s, "Duração:", tabela com 1ª coluna t (s)); avisa narração fora de ±15% do alvo, trecho que não cabe no tempo, buracos, coluna Imagem vazia, `meta.json` (title ≤ 60, logline) e `*.choices.json` (≤ 60, distintas) | ## Regras de leitura barata - **Render:** depois do `pnpm render`, leia só o resumo impresso ou `runs_summary.py`. Abra o `render.log` apenas se houver falha, e com `grep` (ex.: `grep -E "ERROR|SCRIPT|frames at"`). - **Imagens:** uma `contact-sheet.png` ou `strip.png` por verificação, não quadros individuais. Recorte ampliado só para checar um detalhe específico. - **Testes:** filtre a saída (`pnpm test 2>&1 | grep -E "✖|^ℹ (pass|fail)|passaram|FALHA"`). - **Código:** `Grep` com o nome da função antes de ler arquivos inteiros; leia por intervalo de linhas. - **Renders:** um render de prévia por iteração; o perfil final só no fim. Não renderize para testar algo que os testes headless ou `--validate-only` já cobrem. - **Comandos longos de saída** (pnpm install, import da Godot): sempre com `| tail -n 5`. - **Imagens, regra dura:** no máximo UMA por render, escolhida pelo `frame_check.py`. Nada de abrir quadros em lote nem gerar imagens de QA próprias (ex.: `output/castaways-qa/`): cada imagem fica no histórico e é reenviada a cada turno. Medido na execução #8 (Codex, cena Godot): ~100 imagens em resolução cheia → 26 milhões de caracteres de saída de ferramenta, 6,83 milhões de tokens de entrada, 54 chamadas, 29 min. - **Pesquisa na web (documental):** busque o termo dentro da página e use 3–5 fontes; página aberta inteira custa 30–40 mil caracteres (execução #6: 1,06 milhão de tokens de entrada). - **Retomada (resume)** nas duas CLIs reenvia todo o histórico (vem do cache, mas conta): conversa longa fica cara a cada mensagem. Com contexto já grande, abra nova execução com o resumo do que falta. ## Custo fixo dos agentes do painel (medido em 17/11/2026) Código: `panel/src/lib/agents.ts`. Detalhes e correções de sintoma em [gotchas.md](gotchas.md) (itens 133–135). | Provedor | O que o painel passa | Efeito medido | |---|---|---| | Claude CLI | `CLAUDE_LEAN_FLAGS`: `--setting-sources project,local --strict-mcp-config --tools Read,Edit,Write,Glob,Grep,Bash,Agent,Skill,TodoWrite` | prompt trivial no Haiku: 1º turno 62,4 mil → 14,9 mil tokens de entrada só com as flags (18,6 mil com o conjunto completo do painel, que inclui Agent); partida 8,0 s → 4,3 s. Sem as flags carregava plugins/MCP/hooks/skills do usuário (61 ferramentas, 5 MCPs, 310 skills, 78 agentes, 442 comandos). Subagentes do projeto (`.claude/agents`) e a skill `cenaforge` continuam visíveis | | Claude CLI | `--max-budget-usd` por tarefa (`CLAUDE_BUDGET_USD`: story 1,5 · script 1,5 · branches 2,5 · scene 1 · godot 3 · free 3) | `error_max_budget_usd` vira "continue a conversa". A CLI não tem `--max-turns` | | Codex | `codexLeanOverrides`: `-c model_reasoning_effort` por tarefa (story/script/branches/godot = medium, scene = low, free = o do `config.toml`), `mcp_servers..enabled=false` para cada servidor do `config.toml`, plugins `computer-use@openai-bundled` e `unified-computer-use@openai-bundled` desligados (tira `cua_repl`, ~6,5 mil caracteres por turno) | fixo do Codex ~18–19 mil tokens no 1º turno; `base_instructions` ~21 mil caracteres | Referência de peso: na execução #7 (cena Godot, Opus, US$ 3,09, 26 chamadas) o fixo era ~49 mil tokens por chamada e somou 2,8 milhões de tokens lidos do cache — por isso o corte do fixo vale mais que qualquer ajuste de prompt. ### Juiz do Clipador (`clipper/app/judge.py`, medido em 17/11/2026) Cada chamada é um processo novo de CLI: 2 por candidato (analista com 6–8 quadros 768×432 + editor só texto). Live de 3,7 h = 75 candidatos = ~150 chamadas; padrão Codex `gpt-6-luna`, esforço low. | Provedor | O que o juiz passa | Efeito medido | |---|---|---| | Codex | `codex_lean_overrides(search)`: sem `--search`, `features.{plugins,apps,shell_tool,unified_exec,code_mode_host,sleep_tool,skill_search,tool_suggest,in_app_browser,browser_use}=false` + `computer_use,image_generation,goals,hooks=false`, `mcp_servers..enabled=false`, plugins computer-use off, e o `system` num instructions.md temporário via `-c model_instructions_file=''` (stdin só com o prompt). Com `--search` saem só os extras e o `system` fica no stdin. `view_image` fica ligado | antes: ~77 mil caracteres fixos (~19 mil tokens: instruções 18 mil, ferramentas 46,5 mil, skills/apps ~12 mil) ≈ 2,9 mi tokens naquela live, a mesma cota que bloqueou o agente do painel. Depois: instruções 105 caracteres, ferramentas 29 mil (sobram `exec` e `collaboration`, que `-c` não remove), fixo ≈ 35 mil caracteres (~9 mil tokens, −55%, estimativa). Imagem chega como `input_image`. **Resposta do modelo não validada** (cota esgotada até 16h27 de 17/11) | | Claude | `--setting-sources project,local` (além de `--system-prompt`, `--tools`, `--strict-mcp-config`, `--no-session-persistence`) | Haiku: fixo 3,7 → 2,6 mil tokens (−31%), 5,5 → 2,8 s por chamada | Propostas não implementadas (mudam recall; exigem decisão do usuário): na sessão 3, o juiz descartou 33 de 75 candidatos (44%) e, na origem `face`, 15 de 21 (heurística média 3,07). Opções: pré-filtro por pontuação antes do LLM ou juntar analista+editor numa chamada. Os prompts do painel (`panel/src/lib/prompts.ts`) já mandam: godot usa `frame_check.py` e uma imagem por render; story/script/branches terminam com `check_script.py`; nenhum agente aciona `cenaforge-skill-updater` nem `cenaforge-token-auditor`. `CLAUDE_ALLOWED_TOOLS` libera `frame_check.py` e `check_script.py` via Bash.