Documentação

Analytics e Painéis

Como monitorar economias de tokens, interpretar painéis, executar benchmarks e compartilhar relatórios.

O lean-ctx rastreia cada token economizado em todas as sessões. Este guia explica como acessar, interpretar e compartilhar seus dados de economia através de painéis no terminal, interface web, relatórios wrapped e benchmarks.

Todos os dados são armazenados localmente em ~/.lean-ctx/stats.json e persistem entre sessões e reinicializações.

Painel no Terminal - lean-ctx gain

A principal forma de verificar suas economias. Execute lean-ctx gain em qualquer terminal para ver um painel visual com cores, barras, sparklines e estimativas em USD.

$ lean-ctx gain

  ◆ lean-ctx  Token Savings Dashboard
  ────────────────────────────────────────────────────────

   7.8M          67.8%          3,994        $43.14
   tokens saved  compression    commands     USD saved

  Top Commands
  ──────────────
  curl     328x  ████████████████████  3.2M saved
  git      412x  ██████████████        1.8M saved
  cargo    156x  ██████████            1.1M saved
  npm       89x  ████                  420K saved

  30-day sparkline: ▁▃▅▇██▇▅█▇▃▁▅▇██▇▅█▇▃▁▅▇██▇▅█▇▃▁▅▇██▇▅█▇▃▁

O que os números significam

MétricaSignificado
tokens savedTotal de tokens removidos do contexto do LLM em todas as sessões.
compressionPercentual médio de tokens removidos. Maior = mais eficiente.
commandsTotal de comandos shell comprimidos pelo shell hook.
USD savedEconomia estimada em custos com base no preço médio de tokens ($2,50/1M tokens de entrada).
Top CommandsQuais ferramentas CLI economizaram mais tokens, classificadas por economia total.
30-day sparklineTendência visual de 30 dias da atividade diária de economia.

Modo Ao Vivo - lean-ctx gain --live

Painel com atualização automática a cada 2 segundos.

$ lean-ctx gain --live

  ◆ lean-ctx  LIVE  refreshing every 2s
  ────────────────────────────────────────────────────────

   7.8M          67.8%          3,994        $43.14
   tokens saved  compression    commands     USD saved

  Session: 42 cmds | 89.2K saved | 94.1% rate ▁▃█▇██▁█

  Press q to quit

Quando usar: Execute em um terminal lateral durante sessões de codificação para monitorar economias em tempo real.

Gráficos e Tabelas

lean-ctx gain --graph

Gráfico de economias de 30 dias com barras diárias.

$ lean-ctx gain --graph

  Token Savings (30 days)
  ──────────────────────────────

  03-20 │ ██████████████████████ 1.0M
  03-21 │ ███████████████       690K
  03-22 │ ████████████████████████ 1.1M
  03-23 │ █                       9.4K
  03-24 │ ██████████████████████ 1.7M

lean-ctx gain --daily

Tabela dia a dia com colunas para tokens economizados, taxa de compressão, contagem de comandos e USD.

$ lean-ctx gain --daily

  ┌────────────┬──────────┬───────┬──────┬────────┐
  │ Date       │ Saved    │ Rate  │ Cmds │ USD    │
  ├────────────┼──────────┼───────┼──────┼────────┤
  │ 2026-03-28 │ 1.7M     │ 72.4% │ 412  │ $4.25  │
  │ 2026-03-27 │ 1.1M     │ 68.9% │ 289  │ $2.75  │
  │ 2026-03-26 │ 690K     │ 71.2% │ 187  │ $1.73  │
  └────────────┴──────────┴───────┴──────┴────────┘

Painel Web - lean-ctx dashboard

Painel interativo no navegador em http://localhost:3333.

lean-ctx dashboard              # default port 3333
lean-ctx dashboard --port=8080  # custom port

Painéis do dashboard

PainelConteúdo
Visão Geral de EstatísticasTotal de tokens economizados, taxa de compressão, USD, contagem de comandos - mesmos dados do gain
Atividade MCPChamadas recentes de ferramentas MCP, quais ferramentas são mais usadas, tempos de resposta
Agentes AtivosAgentes de IA atualmente registrados via ctx_agent. Mostra nome do agente, função, status e heartbeat.
Conhecimento do ProjetoFatos armazenados via ctx_knowledge, agrupados por categoria com pontuações de confiança.

Endpoints da API

O painel serve uma API JSON que você pode consultar diretamente:

EndpointDados
GET /api/statsEstatísticas de economia de tokens (mesmo que gain --json)
GET /api/mcpDados de uso de ferramentas MCP
GET /api/agentsRegistro de agentes ativos
GET /api/knowledgeRepositório de conhecimento do projeto

Relatórios Wrapped - lean-ctx wrapped

"Spotify Wrapped" das suas economias de tokens. Gera um cartão-relatório compartilhável.

lean-ctx wrapped           # current week
lean-ctx wrapped --week    # current week (explicit)
lean-ctx wrapped --month   # current month
lean-ctx wrapped --all     # lifetime stats

Exemplo de saída

$ lean-ctx wrapped --month

  ◆ Your March 2026 Wrapped
  ────────────────────────────────

  4.9M tokens saved
  3,241 commands compressed
  $12.16 USD saved

  Top pattern: curl (97% compression)
  You're in the top 5% of lean-ctx users

  Best day: March 24 - 1.7M tokens saved
  Most used mode: map (42% of reads)

Relatório CEP - lean-ctx cep

O relatório do Cognitive Efficiency Protocol mostra como o lean-ctx otimiza o raciocínio do LLM.

$ lean-ctx cep

  CEP Impact Report
  ────────────────────────────────

  Score trend:  ▁▃▅▇██▇█  (improving)
  Cache hits:   94.2% (re-reads served from cache)
  Mode distribution:
    full:        42%  ████████████████
    map:         31%  ████████████
    signatures:  18%  ███████
    diff:         9%  ███

Benchmarking

Meça economias exatas de tokens em arquivos reais do projeto usando tiktoken.

lean-ctx benchmark run [path] [--json]

$ lean-ctx benchmark run src/

  Benchmarking 42 files...

  src/auth.ts (123 lines)
    full:       3,517 tokens
    map:          412 tokens (88% saved)
    signatures:   252 tokens (93% saved)
    entropy:      312 tokens (91% saved)

  src/server.ts (456 lines)
    full:       8,234 tokens
    map:          891 tokens (89% saved)
    signatures:   534 tokens (94% saved)

  ── Summary ──────────────────────
  42 files | 89,412 total tokens
  Average savings: map 87% | signatures 92% | entropy 85%

lean-ctx benchmark report [path]

Gere um relatório em Markdown que você pode compartilhar ou fazer commit no seu repositório.

lean-ctx benchmark report src/ > BENCHMARK.md

O relatório inclui detalhamento por arquivo, comparações de modos e estatísticas agregadas.

Exportação JSON - lean-ctx gain --json

Exporte todas as estatísticas como JSON para scripts, integração CI/CD ou painéis personalizados.

lean-ctx gain --json > stats.json

O JSON inclui:

  • Total de tokens economizados e taxa de compressão
  • Detalhamento por comando (nome do comando, contagem, tokens economizados)
  • Histórico diário (data, economizado, taxa, comandos)
  • Estimativas em USD

Exemplo: extrair total de economias em um script de CI:

SAVED=$(lean-ctx gain --json | jq '.total_saved')
echo "lean-ctx saved $SAVED tokens this session"

Cálculo em USD

O lean-ctx estima economias em USD com base no preço médio de tokens de entrada de LLM. A taxa padrão é $2,50 por 1M de tokens de entrada.

A fórmula é:

USD saved = (tokens saved / 1,000,000) × $2.50

Esta é uma estimativa conservadora - as economias reais podem ser maiores se você usar modelos mais caros ou menores se usar modelos mais baratos.