> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cost Tracking

> Rastreie custos de token e estimativas de preço por sessão em todos os modos, com dados reais de API e orcamento configurável

O **Cost Tracking** do ChatCLI monitora o consumo de tokens e estima custos em tempo real durante suas sessões, com dados reais de uso da API quando disponíveis. Você pode acompanhar quanto cada conversa esta custando, ver custos por modelo/provedor e configurar limites de orcamento.

***

## Comando /cost

O comando `/cost` exibe um resumo completo do consumo de tokens e custos estimados da sessão atual:

```bash theme={"system"}
/cost
```

```text theme={"system"}
Session Cost Summary
====================

Tokens Used:
  Input:    45.2K tokens
  Output:   12.8K tokens
  Cache:    38.1K tokens (cached)
  Total:    58.0K tokens

Estimated Cost:
  Input:    $0.1356
  Output:   $0.1920
  Cache:    -$0.0914 (savings)
  ─────────────────────
  Total:    $0.2362

Model: claude-sonnet-4-6 (Anthropic)
Requests: 14
Duration: 23m 15s
```

<Info>
  Quando o provedor retorna dados reais de uso de tokens (`Usage.IsReal = true`), os custos sao calculados com precisao. Para provedores que não retornam uso real, o ChatCLI estima tokens a partir do tamanho do texto.
</Info>

***

## Token Tracking por Modo

O ChatCLI rastreia tokens em todos os modos de interação:

<Tabs>
  <Tab title="Chat Mode">
    No modo chat, o tracking conta:

    * Tokens do system prompt (bootstrap + memória + contextos)
    * Tokens de cada mensagem do usuário
    * Tokens de cada resposta do assistente
    * Economia de cache (quando aplicavel)

    ```text theme={"system"}
    [chat] claude-sonnet-4-6> /cost
    Chat mode: 12 messages, 23.4K tokens, ~$0.08
    ```
  </Tab>

  <Tab title="Agent Mode">
    No agent mode, o tracking inclui adicionalmente:

    * Tokens de cada tool call (request + response)
    * Tokens do loop ReAct (raciocinio + ação + observacao)
    * Tokens de workers despachados (multi-agent)
    * Tokens de web tools (webfetch/websearch)

    ```text theme={"system"}
    [agent] claude-sonnet-4-6> /cost
    Agent mode: 8 turns, 45.2K tokens, ~$0.24
      Tool calls: 23 (read: 12, exec: 5, write: 4, search: 2)
    ```
  </Tab>

  <Tab title="Coder Mode">
    No coder mode, o tracking e similar ao agent com detalhes adicionais:

    * Tokens por arquivo editado
    * Tokens de patches aplicados
    * Tokens de execução de testes

    ```text theme={"system"}
    [coder] claude-sonnet-4-6> /cost
    Coder mode: 5 turns, 67.8K tokens, ~$0.35
      Files modified: 8
      Tests executed: 3
    ```
  </Tab>
</Tabs>

***

## Tabela de Precos

O ChatCLI conhece os precos dos modelos mais comuns para calcular estimativas:

### Anthropic

| Modelo                                   | Input (por 1M tokens) | Output (por 1M tokens) | Cache Read |
| :--------------------------------------- | :-------------------- | :--------------------- | :--------- |
| claude-fable-5                           | \$10.00               | \$50.00                | \$1.00     |
| claude-sonnet-5                          | \$3.00                | \$15.00                | \$0.30     |
| claude-opus-4-8                          | \$5.00                | \$25.00                | \$0.50     |
| claude-opus-4-8 (`ANTHROPIC_SPEED=fast`) | \$10.00               | \$50.00                | \$1.00     |
| claude-opus-4-7                          | \$5.00                | \$25.00                | \$0.50     |
| claude-sonnet-4-6                        | \$3.00                | \$15.00                | \$0.30     |
| claude-opus-4                            | \$15.00               | \$75.00                | \$1.50     |
| claude-haiku-3.5                         | \$0.80                | \$4.00                 | \$0.08     |

### OpenAI

| Modelo      | Input (por 1M tokens) | Output (por 1M tokens) | Cache Read |
| :---------- | :-------------------- | :--------------------- | :--------- |
| gpt-4o      | \$2.50                | \$10.00                | \$1.25     |
| gpt-4o-mini | \$0.15                | \$0.60                 | \$0.075    |
| o3-mini     | \$1.10                | \$4.40                 | \$0.55     |

<Note>
  **Modelos GPT também mostram usage no envelope do chat**, com as mesmas setinhas `N↑ M↓` que o fluxo Claude usa desde o lançamento. O ChatCLI envia `stream_options: {include_usage: true}` em streaming Chat Completions e parseia o evento `response.completed` na Responses API, então contagens input/output (e cache-hit) aparecem no envelope independente do provider. Cached tokens reportados em `prompt_tokens_details.cached_tokens` (Chat Completions) / `input_tokens_details.cached_tokens` (Responses) mapeiam para `CacheReadInputTokens`, o mesmo campo do prompt caching Anthropic. Reasoning tokens (o-series / GPT-5) ficam em um campo informativo separado `ReasoningTokens` — já estão contabilizados em `CompletionTokens` e cobrados como output.
</Note>

### Google

| Modelo           | Input (por 1M tokens) | Output (por 1M tokens) |
| :--------------- | :-------------------- | :--------------------- |
| gemini-2.0-flash | \$0.10                | \$0.40                 |
| gemini-2.5-pro   | \$1.25                | \$10.00                |

### ZAI (Zhipu AI)

| Modelo                 | Input (por 1M tokens) | Output (por 1M tokens) |
| :--------------------- | :-------------------- | :--------------------- |
| glm-5.2                | \$1.40                | \$4.40                 |
| glm-5                  | \$1.00                | \$3.20                 |
| glm-4.x (fallback ZAI) | \$0.50                | \$0.50                 |

### MiniMax

| Modelo          | Input (por 1M tokens) | Output (por 1M tokens) |
| :-------------- | :-------------------- | :--------------------- |
| MiniMax-M2.7    | \$0.30                | \$1.20                 |
| MiniMax-M2.5    | \$0.30                | \$1.20                 |
| MiniMax-Text-01 | \$0.30                | \$1.20                 |

### Moonshot (Kimi)

| Modelo         | Input (por 1M tokens) | Output (por 1M tokens) | Cache Read |
| :------------- | :-------------------- | :--------------------- | :--------- |
| kimi-k2.6      | \$0.95                | \$4.00                 | \$0.16     |
| kimi-k2.5      | \$0.95                | \$4.00                 | \$0.16     |
| moonshot-v1-\* | \$0.95                | \$4.00                 | \$0.16     |

<Note>
  O cost tracker do ChatCLI bilha o **preço de cache miss** ($0.95/M input) para se manter conservador. O cache-hit ($0.16/M) é uma economia automática da API — quando o mesmo prefixo é reusado dentro da janela do provider — e não é contabilizado em runtime.
</Note>

### DeepSeek

| Modelo            | Input (por 1M tokens) | Output (por 1M tokens) | Cache Read |
| :---------------- | :-------------------- | :--------------------- | :--------- |
| deepseek-chat     | \$0.27                | \$1.10                 | \$0.07     |
| deepseek-reasoner | \$0.55                | \$2.19                 | \$0.14     |

### OpenRouter

| Modelo                    | Input (por 1M tokens) | Output (por 1M tokens) |
| :------------------------ | :-------------------- | :--------------------- |
| openai/gpt-4o             | \$2.50                | \$10.00                |
| openai/gpt-4o-mini        | \$0.15                | \$0.60                 |
| anthropic/claude-sonnet-4 | \$3.00                | \$15.00                |
| google/gemini-2.5-flash   | \$0.15                | \$0.60                 |
| deepseek/deepseek-r1      | \$0.55                | \$2.19                 |

<Tip>
  Os precos sao atualizados periodicamente nas releases do ChatCLI. Para modelos não listados ou provedores custom (via OpenAI-compatible), o custo aparece como "N/A". O OpenRouter disponibiliza precos via API -- o ChatCLI usa o ConfigMap de precos para estimar custos dos modelos mais populares.
</Tip>

***

## Exibicao Visual

O ChatCLI usa indicadores visuais para facilitar o acompanhamento:

### Formato de Tokens

Tokens são exibidos com sufixos K/M para facilitar a leitura:

| Valor     | Exibicao |
| :-------- | :------- |
| 1,234     | `1.2K`   |
| 45,678    | `45.7K`  |
| 1,234,567 | `1.2M`   |

### Progress Bar de Contexto

Quando o contexto se aproxima do limite do modelo, uma barra de progresso indica a utilizacao:

```text theme={"system"}
Context: ████████░░░░░░░░ 52% (104K / 200K tokens)
```

<Warning>
  Quando o uso de contexto ultrapassa 80%, o ChatCLI sugere automaticamente executar `/compact` para liberar espaco e reduzir custos.
</Warning>

***

## Economia com Cache

O ChatCLI otimiza custos usando cache de prompt quando o provedor suporta:

```text theme={"system"}
Cache Savings:
  System prompt cached: 38.1K tokens
  Savings this session: $0.09 (38% reduction)
  Cache hit rate: 92%
```

### Tokens de Cache (Anthropic)

O ChatCLI rastreia tokens de cache específicos da Anthropic:

| Metrica               | Descricao                                  |
| :-------------------- | :----------------------------------------- |
| `CacheCreationTokens` | Tokens usados para criar entradas de cache |
| `CacheReadTokens`     | Tokens lidos do cache (custo reduzido)     |

O custo de cache read e tipicamente 10% do custo de input normal, resultando em economia significativa em conversas longas com system prompts grandes.

<Info>
  A economia de cache e calculada com base na diferença entre o preço de input normal e o preço de cache read. Veja [Bootstrap e Memória](/pt/features/bootstrap-memory) para detalhes sobre a otimização de contexto.
</Info>

***

## Dados Reais de API

O CostTracker suporta duas fontes de dados:

| Fonte                    | Precisao   | Quando Usado                         |
| :----------------------- | :--------- | :----------------------------------- |
| **Dados reais da API**   | Alta       | Provedor retorna `Usage` no response |
| **Estimativa por chars** | Aproximada | Provedor não retorna dados de uso    |

Quando o provedor retorna dados reais (`HasRealData = true`), o tracking usa contagens exatas de tokens. Isso e suportado por 13+ provedores incluindo Anthropic, OpenAI, ZAI, MiniMax, DeepSeek e OpenRouter.

### Custo por Modelo

Em sessões com múltiplos modelos (ex: fallback chain), o `/cost` mostra breakdown por modelo:

```text theme={"system"}
Per-Model Breakdown:
  anthropic:claude-sonnet-4-6    32 reqs   $0.1845  (real data)
  openai:gpt-4o-mini              5 reqs   $0.0023  (real data)
```

***

## Persistencia de Sessão

Os dados de custo sao persistidos em disco para que possam ser consultados após o termino da sessão:

```text theme={"system"}
~/.chatcli/sessions/<session_id>/cost.json
```

O arquivo contem o snapshot completo (`SessionCostData`) com uso por modelo, custos e timestamps.

***

## Orcamento de Sessão

Configure um limite de gastos por sessão para evitar custos inesperados:

| Variável de Ambiente         | Descricao                                      | Default        |
| :--------------------------- | :--------------------------------------------- | :------------- |
| `CHATCLI_SESSION_BUDGET_USD` | Limite máximo de gastos por sessão em USD      | 0 (sem limite) |
| `CHATCLI_BUDGET_WARNING_PCT` | Percentual para aviso de proximidade do limite | 0.80 (80%)     |

### Niveis de Orcamento

| Nivel            | Condicao                      | Comportamento            |
| :--------------- | :---------------------------- | :----------------------- |
| `BudgetOK`       | Gasto abaixo de 80% do limite | Normal                   |
| `BudgetWarning`  | Gasto entre 80-100% do limite | Aviso exibido            |
| `BudgetExceeded` | Gasto acima do limite         | Sessão pode ser limitada |

```bash theme={"system"}
# Exemplo: limitar sessão a $5.00
export CHATCLI_SESSION_BUDGET_USD=5.00

# Avisar quando atingir 70% do limite
export CHATCLI_BUDGET_WARNING_PCT=0.70
```

<Warning>
  Quando o orcamento e excedido, o ChatCLI exibe um aviso mas **não interrompe a sessão automaticamente**. O usuário pode decidir continuar ou encerrar.
</Warning>

***

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Controle de Conversa" icon="clock-rotate-left" href="/pt/features/conversation-control">
    Use /compact para reduzir tokens e custos.
  </Card>

  <Card title="Modo One-Shot" icon="terminal" href="/pt/features/non-interactive-mode">
    Monitore custos em pipelines automatizados.
  </Card>

  <Card title="Resultados de Tools" icon="database" href="/pt/features/tool-result-management">
    Orcamento de tool results que impacta uso de tokens.
  </Card>

  <Card title="Recuperação de Contexto" icon="life-ring" href="/pt/features/context-recovery">
    Estrategias automáticas quando o contexto transborda.
  </Card>
</CardGroup>