TokenWise — Roteador de Modelos Guiado por Medição

Visão Geral

Uma habilidade do Claude Code que roteia automaticamente sub-tarefas para o modelo mais barato que pode lidar com elas (Haiku para trabalho braçal, Sonnet para raciocínio com escopo, Opus apenas para síntese), então registra cada tarefa roteada em um NDJSON local com números reais de tokens + custo. Inclui um subcomando de teste A/B que executa a mesma tarefa em múltiplos níveis e pontua a qualidade, para que as decisões de roteamento sejam verificadas contra a carga de trabalho real do usuário — não estimadas.

O próprio rastreador de bugs da Anthropic (Issue #27665) relata que 93,8% dos tokens do Claude Code de assinantes Max fluem para o Opus. Roteadores existentes (claude-router, wshobson, VoltAgent) fixam modelos estaticamente ou roteiam por heurísticas baseadas em "vibes" sem medição. TokenWise preenche a lacuna de medição.

Quando usar

• Reduzir o gasto de tokens do Claude Code sem sacrificar a qualidade da saída
• Validar se Haiku/Sonnet é "bom o suficiente" para uma classe de tarefa específica antes de confiar no roteamento automático
• Auditar onde os tokens do Opus estão sendo realmente consumidos
• Registrar dados de custo por sessão para finanças ou chargeback

Subcomandos

• /tokenwise:install — instalador guiado com pré-visualização de diff, backups automáticos e modo --dry-run
• /tokenwise:report — resumo de tokens + custo por sessão vs. linha de base de todos os Opus
• /tokenwise:summary [--week|--month|--all] — agregado histórico com tendência
• /tokenwise:ab "<task>" — teste A/B da mesma tarefa em múltiplos níveis, gera uma comparação em markdown
• /tokenwise:undo — restaura CLAUDE.md / settings.json do backup

Taxonomia de roteamento

Limites de segurança:

• Haiku nunca gera subagentes adicionais
• Profundidade máxima de geração = 2
• Subagentes que precisam de um modelo mais inteligente retornam ao pai — eles nunca escalam por conta própria
• Tarefas com menos de 100 caracteres e sem contexto de arquivo são executadas inline (custo adicional do subagente > economia)
• Contexto do subagente >30k tokens aumenta o nível

Privacidade

Zero telemetria. Todos os logs em .tokenwise/log.ndjson são locais para o projeto. Descrições de tarefas truncadas para 80 caracteres e sem conteúdo de arquivo antes do registro. Nenhum endpoint de análise existe no código-fonte.

Instalação

Em qualquer sessão do Claude Code:

/plugin marketplace add CodeShuX/tokenwise
/plugin install tokenwise@tokenwise

Em seguida, execute /tokenwise:install e siga as instruções guiadas.

Limitações

• Contagens de tokens aproximadas com ±2% em relação à fatura da Anthropic
• O modo de teste A/B custa tokens extras (uma tarefa × N níveis) — validação intencional única
• Apenas Anthropic por design (use LiteLLM ou OpenRouter para fornecedores cruzados)
• O parâmetro de subagente model: tem bugs conhecidos de falha silenciosa em algumas compilações do Claude Code — a habilidade verifica isso na instalação e se recusa a configurar se o roteamento estiver quebrado

Código-fonte

• Repositório: https://github.com/CodeShuX/tokenwise
• Licença: MIT
• Autor: CodeShuX