costwise 1.2.0

Token cost monitor for Claude Code — know the cost, ship with confidence

costwise

Know the cost. Ship with confidence.
Saiba o custo. Entregue com confiança.

Monitor de tokens e custo real do Claude Code — por projeto, por cliente, por período.
Token and real dollar cost monitor for Claude Code — per project, per client, per period.

---

✨ Por que usar / Why use it

🇧🇷	🇺🇸
Saiba exatamente quanto cada projeto custa em dólar	Know exactly what each project costs in dollars
Compare Sonnet vs Opus vs Haiku na hora	Compare Sonnet vs Opus vs Haiku instantly
Precifique clientes freelancer com precisão	Price freelance clients accurately
Decida se o plano Pro/Max compensa	Decide if Pro/Max plan pays off
Zero config — lê os arquivos locais do Claude Code	Zero setup — reads Claude's local files
Dashboard web bilíngue PT 🇧🇷 / EN 🇺🇸	Bilingual web dashboard PT 🇧🇷 / EN 🇺🇸

---

🆓 Free vs ★ Pro

Feature	Free	Pro
CLI ranking por projeto	✅	✅
Filtros --today --week --month	✅	✅
Dashboard web local (costwise dashboard)	✅	✅
Gráficos diários, mensais, por projeto	✅	✅
Histórico mensal completo	✅	✅
Sonnet / Opus / Haiku pricing	✅	✅
Toggle PT 🇧🇷 / EN 🇺🇸	✅	✅
Alerta de uso da sessão	✅	✅
Export CSV	—	★
Relatório PDF por cliente	—	★
Custo por hora trabalhada	—	★
"Quanto cobrar?" — margem freelancer automática	—	★
Comparativo Pro vs Max — qual plano vale?	—	★
Breakdown por cliente (multi-projeto)	—	★

Pro: $27 lifetime · $7/month
👉 gumroad.com/salvatini95/costwise-pro

---

📦 Instalação / Installation

Pré-requisitos / Prerequisites

• 🐧 Linux / WSL2 — Python 3 instalado
• 🪟 Windows — Use WSL2 (recomendado)
• 🍎 macOS — Python 3 instalado
• 🤖 Claude Code instalado e com sessões registradas

Opção 1 — Git (recomendado)

git clone https://github.com/Salvatini95/costwise.git
cd costwise
chmod +x install.sh
./install.sh

Opção 2 — ZIP (sem Git)

1. Baixe o arquivo costwise-free.zip na seção Releases
2. Extraia em qualquer pasta
3. No terminal (Linux/WSL2/macOS):

cd costwise-free
chmod +x install.sh
./install.sh

Verificar instalação / Verify

costwise --version
costwise

---

🚀 Uso / Usage

CLI — Terminal

# Ranking geral (todo o histórico)
costwise

# Apenas hoje
costwise --today

# Esta semana
costwise --week

# Este mês
costwise --month

# A partir de uma data
costwise --since 2026-06-01

# Recalcular como se fosse Opus
costwise --model opus

# Incluir sessões de subagentes
costwise --subagents

# Sem cores (para scripts/logs)
costwise --no-color

Dashboard Web

costwise dashboard
# Abre automaticamente → http://localhost:8080

O dashboard inclui:

• KPIs: custo total, tokens, projeto top, média diária
• Gráfico de barras por projeto
• Gráfico de linha — evolução diária
• Gráfico de pizza — distribuição input/output/cache
• Tabela detalhada com barra de participação
• Histórico mensal
• Seção educacional: "Como o custo é calculado?"
• Toggle PT 🇧🇷 / EN 🇺🇸

---

💡 Dicas / Tips

Qual plano Claude compensa?

# Compara o que você gastaria em cada modelo
costwise --model sonnet --month
costwise --model opus   --month
costwise --model haiku  --month

Precificar um cliente freelancer

# Veja o custo desde o início do projeto
costwise --since 2026-06-01
# Adicione sua margem e saberá exatamente quanto cobrar

Exemplo real

Cliente: SV Finance

Tokens:       64.3M
Custo real:   $48.97
Horas gastas: 12h
Margem 30%:   $63.66 → R$ 318,00

---

🔧 Como funciona / How it works

O costwise lê os arquivos ~/.claude/projects/**/*.jsonl — sessões que o Claude Code grava localmente — e soma input_tokens, output_tokens, cache_read_input_tokens e cache_creation_input_tokens de cada mensagem, aplicando os preços públicos da Anthropic para estimar o custo.

Nota: funciona apenas com Claude Code. O Claude.ai (chat web) não grava arquivos locais.

Tabela de preços (por 1M tokens)

Modelo	Input	Output	Cache leitura
Haiku 4.5	$1.00	$5.00	$0.10
Sonnet 4.6	$3.00	$15.00	$0.30
Opus 4.7	$5.00	$25.00	$0.50

---

🗺️ Roadmap

• ✅ v1.0 — CLI: ranking all-time e filtros por data
• ✅ v1.1 — Dashboard web bilíngue com gráficos
• ⬜ v1.2 — Pro: export CSV
• ⬜ v1.3 — Pro: relatório PDF por cliente
• ⬜ v1.4 — Pro: custo por hora + margem freelancer
• ⬜ v2.0 — Pro: breakdown por cliente multi-projeto

---

🤝 Contributing

PRs e issues são bem-vindos. Se encontrar um bug com uma estrutura .jsonl específica, compartilhe as chaves relevantes (não o conteúdo) em uma issue.

---

📄 Licença / License

MIT — versão free.
Funcionalidades Pro exigem licença válida do Gumroad.

---

Made with ☕ by @Salvatini95