tokmon-app 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mateus Castro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# tokmon
+
+[![test](https://github.com/MateusCastro2203/tokmon/actions/workflows/test.yml/badge.svg)](https://github.com/MateusCastro2203/tokmon/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Skill do [Claude Code](https://claude.com/claude-code) que lê o transcript JSONL que o próprio Claude Code já grava por sessão e mostra: total de tokens gasto, ranking de qual prompt custou mais, quebra por skill/subagente, e % de context window usado. Sem hook, sem API externa, sem auth — só lê o arquivo que já existe em `~/.claude/projects/<projeto>/<sessão>.jsonl`.
+
+Fora de escopo: custo em $, e cota/limite de plano (5h/semanal/mensal) — isso já é resolvido pelo [CodexBar](https://github.com/steipete/CodexBar).
+
+## Instalar
+
+```bash
+npm install -g tokmon-app
+```
+
+Isso expõe o comando `tokmon` no seu terminal.
+
+## Usar
+
+```bash
+tokmon snapshot        # snapshot de texto da sessão ativa no diretório atual
+tokmon watch           # dashboard ao vivo, atualiza sozinho (Ctrl+C sai)
+tokmon help            # ajuda
+```
+
+`tokmon watch` mostra algo assim, com cor de contexto mudando (verde/amarelo/vermelho) conforme o uso sobe:
+
+```
+╭─ token-monitor — meu-projeto (sessão) ───────────╮
+│ 🔥 Total: 7.7M tok                                │
+│    in 47.5k · out 103.5k · cache-w 419.3k · ...   │
+│ 🧠 Contexto: 70.1% usado (140.2k / 200.0k)         │
+╰────────────────────────────────────────────────────╯
+╭─ 🏆 Top prompts ──────────────────────────────────╮
+│  1.    6.0M  "Base directory for this skill..."    │
+│  2.    1.5M  "coloque a experiencia em mobile..."  │
+╰────────────────────────────────────────────────────╯
+╭─ 🧩 Por skill/agente ─────────────────────────────╮
+│  main            7.7M                             │
+╰────────────────────────────────────────────────────╯
+```
+
+## Integração com o Claude Code
+
+Pra ter a skill disponível dentro do próprio Claude Code (slash command `/tokens` + statusline nativa sempre visível), rode:
+
+```bash
+tokmon setup
+```
+
+Isso:
+1. Symlinka o pacote pra `~/.claude/skills/token-monitor` (a skill em si, com `SKILL.md`).
+2. Copia o comando `/tokens` pra `~/.claude/commands/tokens.md`.
+3. Registra a `statusLine` em `~/.claude/settings.json` automaticamente — preserva todo o resto do arquivo, e nunca sobrescreve uma `statusLine` diferente que você já tenha configurado (a menos que rode `tokmon setup --force`).
+
+Depois disso, uma linha compacta (`🔥 sessão: ... · contexto: ...% usado · prompt mais caro: ...`) aparece sozinha no rodapé do terminal do Claude Code, sem precisar rodar nada manualmente.
+
+## Privacidade
+
+Roda 100% local. Não faz nenhuma chamada de rede, não envia telemetria, não tem chave de API. A única coisa que lê é o `.jsonl` que o próprio Claude Code já grava no seu disco (`~/.claude/projects/**/*.jsonl`) — nada sai da sua máquina.
+
+## Desenvolvimento
+
+```bash
+git clone git@github.com:MateusCastro2203/tokmon.git
+cd tokmon
+npm install
+npm link        # expõe `tokmon` local pra testar sem publicar
+npm test        # node:test — sem dependência extra de test runner
+```
+
+## Licença
+
+MIT — veja [LICENSE](LICENSE).

package/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: token-monitor
+description: Mostra consumo de token da sessão atual do Claude Code — total, ranking de prompt mais caro, quebra por skill/subagente e % de context window. Use quando o usuário perguntar "quanto gastei de token", "qual prompt custou mais", "quebra por skill" ou similar.
+---
+
+# token-monitor
+
+Skill pra responder perguntas sobre consumo de token da sessão atual, lendo o transcript JSONL que o próprio Claude Code já grava (sem hook, sem API externa).
+
+## Quando usar
+
+Quando o usuário perguntar algo como:
+- "quanto gastei de token nessa sessão"
+- "qual prompt custou mais token"
+- "quebra o consumo por skill/agente"
+- "quanto da context window já usei"
+
+## Como usar
+
+Rode:
+```bash
+node ~/.claude/skills/token-monitor/scripts/snapshot.mjs "$(pwd)"
+```
+e mostre a saída pro usuário — ela já vem formatada, não precisa reformatar.
+
+## Dashboard ao vivo (manual, opcional)
+
+Pra visão contínua tipo `htop`, o usuário roda isso numa aba de terminal separada (fora do Claude Code):
+```bash
+node ~/.claude/skills/token-monitor/scripts/watch.mjs
+```
+
+## Statusline (visão passiva, sem rodar nada)
+
+Se `tokmon setup` (ou `install.sh`) já rodou, `scripts/statusline.mjs` fica registrado em `~/.claude/settings.json` (`statusLine`) e mostra uma linha compacta sempre visível no terminal do Claude Code, atualizando sozinha.

package/bin/tokmon.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { runSnapshot } from '../scripts/snapshot.mjs';
+import { runWatch } from '../scripts/watch.mjs';
+import { runStatusline } from '../scripts/statusline.mjs';
+import { runSetup } from '../scripts/setup.mjs';
+
+function printHelp() {
+  console.log(`tokmon — monitor de consumo de token do Claude Code
+
+Uso:
+  tokmon setup [--force]  Configura a integração com o Claude Code (skill, /tokens, statusLine)
+  tokmon snapshot [cwd]   Snapshot de texto: total, ranking de prompt, quebra por skill, context window
+  tokmon watch [cwd]      Dashboard ao vivo no terminal (atualiza sozinho)
+  tokmon statusline       Modo statusLine — lê JSON do stdin (uso interno, configurado em ~/.claude/settings.json)
+  tokmon help             Mostra esta ajuda`);
+}
+
+async function main() {
+  const [subcommand, ...rest] = process.argv.slice(2);
+
+  switch (subcommand) {
+    case 'setup':
+      runSetup(rest);
+      break;
+    case 'snapshot':
+      runSnapshot(rest);
+      break;
+    case 'watch':
+      await runWatch(rest);
+      break;
+    case 'statusline':
+      runStatusline();
+      break;
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      printHelp();
+      break;
+    default:
+      console.error(`tokmon: comando desconhecido "${subcommand}"\n`);
+      printHelp();
+      process.exitCode = 1;
+  }
+}
+
+main();

package/commands/tokens.md

@@ -0,0 +1,9 @@
+---
+description: Mostra snapshot de consumo de token da sessão atual (total, ranking de prompt, quebra por skill, % context window).
+---
+
+Rode:
+```bash
+node ~/.claude/skills/token-monitor/scripts/snapshot.mjs "$(pwd)"
+```
+Mostre a saída do comando pro usuário tal como veio (já formatada), sem resumir ou reformatar.

package/install.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if [ ! -d "$REPO_DIR/node_modules" ]; then
+  echo "Instalando dependências (ink, react)..."
+  (cd "$REPO_DIR" && npm install --no-audit --no-fund)
+fi
+
+node "$REPO_DIR/bin/tokmon.mjs" setup "$@"

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "tokmon-app",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Skill do Claude Code para monitorar consumo de token por sessao (ranking de prompt, breakdown por skill, context window).",
+  "bin": {
+    "tokmon": "bin/tokmon.mjs"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "commands",
+    "SKILL.md",
+    "install.sh",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "claude-code",
+    "cli",
+    "token-usage",
+    "monitor",
+    "dashboard"
+  ],
+  "author": "Mateus Castro",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MateusCastro2203/tokmon.git"
+  },
+  "homepage": "https://github.com/MateusCastro2203/tokmon#readme",
+  "bugs": {
+    "url": "https://github.com/MateusCastro2203/tokmon/issues"
+  },
+  "dependencies": {
+    "ink": "^5.0.1",
+    "react": "^18.3.1"
+  }
+}

package/scripts/dragon-sprite.mjs

@@ -0,0 +1,38 @@
+// 16x16 pixel-art "Coral Drake" mascot, same design approved in the landing
+// page brainstorm (docs/superpowers/specs/2026-07-23-landing-page-design.md).
+// One character per pixel; rendered in the terminal as two space-wide
+// background-colored cells so it reads roughly square in a monospace font.
+export const DRAGON_SPRITE_ROWS = [
+  '................',
+  '.....h....h.....',
+  '.....bbbbbb.....',
+  '.....bebbeb.....',
+  '.....bbbbbb.....',
+  '.www.bbhhbb.www.',
+  'wwwwbbbbbbbbwwww',
+  'wwwwbbllllbbwwww',
+  'wwwwbbllllbbwwww',
+  '.wwwbbllllbbwww.',
+  '....bbbbbbbb....',
+  '.....bb..bbb....',
+  '.....bbggbb.b...',
+  '......ffff...ff.',
+  '.......gg....ff.',
+  '................',
+];
+
+export const DRAGON_PALETTE = {
+  h: '#641220', // horn / outline / mouth
+  b: '#e63946', // body
+  e: '#1a1a1a', // eye
+  w: '#1d3557', // wings
+  l: '#f1faee', // belly
+  g: '#ffb703', // fire (breath / tail glow)
+  f: '#fb8500', // fire (breath / tail tip, brighter)
+};
+
+export function hpBarSegments(percentage, totalSegments = 10) {
+  const pct = Math.max(0, Math.min(100, percentage ?? 0));
+  const filled = Math.round((pct / 100) * totalSegments);
+  return { filled, empty: totalSegments - filled, totalSegments };
+}

package/scripts/lib.mjs

@@ -0,0 +1,277 @@
+import { readdirSync, statSync, existsSync, readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+
+export function encodeProjectDir(cwd) {
+  return cwd.replace(/[\/._]/g, '-');
+}
+
+export function isMainModule(moduleUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return moduleUrl === `file://${realpathSync(process.argv[1])}`;
+  } catch {
+    return false;
+  }
+}
+
+export function listSessionFiles(projectDir) {
+  if (!existsSync(projectDir)) return [];
+  return readdirSync(projectDir)
+    .filter((name) => name.endsWith('.jsonl'))
+    .map((name) => path.join(projectDir, name))
+    .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+}
+
+export function findActiveSession(projectDir) {
+  const files = listSessionFiles(projectDir);
+  return files[0] ?? null;
+}
+
+function isRealUserMessage(entry) {
+  if (entry.message?.role !== 'user') return false;
+  if (entry.toolUseResult) return false;
+  const content = entry.message.content;
+  if (typeof content === 'string') return content.trim().length > 0;
+  if (Array.isArray(content)) {
+    const hasToolResult = content.some((block) => block.type === 'tool_result');
+    if (hasToolResult) return false;
+    return content.some((block) => block.type === 'text' && block.text.trim().length > 0);
+  }
+  return false;
+}
+
+export function truncatePreview(text, maxLen = 60) {
+  const trimmed = text.trim().replace(/\s+/g, ' ');
+  if (trimmed.length <= maxLen) return trimmed;
+  const sliced = trimmed.slice(0, maxLen);
+  const lastSpace = sliced.lastIndexOf(' ');
+  const cut = lastSpace > 0 ? sliced.slice(0, lastSpace) : sliced;
+  return `${cut}…`;
+}
+
+function extractTextPreview(entry) {
+  const content = entry.message?.content;
+  let text = null;
+  if (typeof content === 'string') text = content;
+  else if (Array.isArray(content)) {
+    const block = content.find((b) => b.type === 'text' && typeof b.text === 'string');
+    text = block?.text ?? null;
+  }
+  if (!text) return null;
+  return truncatePreview(text);
+}
+
+function normalizeEvent(entry) {
+  const role = entry.message?.role;
+  if (role !== 'user' && role !== 'assistant') return null;
+  const usageRaw = entry.message?.usage;
+  const usage = usageRaw
+    ? {
+        input_tokens: usageRaw.input_tokens ?? 0,
+        output_tokens: usageRaw.output_tokens ?? 0,
+        cache_creation_input_tokens: usageRaw.cache_creation_input_tokens ?? 0,
+        cache_read_input_tokens: usageRaw.cache_read_input_tokens ?? 0,
+      }
+    : null;
+  return {
+    role,
+    ts: entry.timestamp ?? null,
+    uuid: entry.uuid ?? null,
+    parentUuid: entry.parentUuid ?? null,
+    isSidechain: entry.isSidechain === true,
+    attributionSkill: entry.attributionSkill ?? null,
+    model: entry.message?.model ?? null,
+    isRealUserText: isRealUserMessage(entry),
+    textPreview: extractTextPreview(entry),
+    usage,
+  };
+}
+
+export function parseSession(filePath) {
+  const raw = readFileSync(filePath, 'utf8');
+  const lines = raw.split('\n').filter((l) => l.trim().length > 0);
+  const events = [];
+  let warnings = 0;
+  for (const line of lines) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      warnings += 1;
+      continue;
+    }
+    const normalized = normalizeEvent(entry);
+    if (normalized) events.push(normalized);
+  }
+  return { events, warnings };
+}
+
+export function groupIntoTurns(events) {
+  const turns = [];
+  let current = null;
+  for (const event of events) {
+    if (event.role === 'user' && event.isRealUserText && !event.isSidechain) {
+      current = {
+        id: event.uuid,
+        ts: event.ts,
+        textPreview: event.textPreview ?? '',
+        usage: { input_tokens: 0, output_tokens: 0, cache_creation_input_tokens: 0, cache_read_input_tokens: 0, total: 0 },
+        bySkill: {},
+      };
+      turns.push(current);
+      continue;
+    }
+    if (!current || !event.usage) continue;
+    const bucket = event.isSidechain ? (event.attributionSkill ?? 'subagent') : 'main';
+    const turnTotal =
+      event.usage.input_tokens +
+      event.usage.output_tokens +
+      event.usage.cache_creation_input_tokens +
+      event.usage.cache_read_input_tokens;
+    current.usage.input_tokens += event.usage.input_tokens;
+    current.usage.output_tokens += event.usage.output_tokens;
+    current.usage.cache_creation_input_tokens += event.usage.cache_creation_input_tokens;
+    current.usage.cache_read_input_tokens += event.usage.cache_read_input_tokens;
+    current.usage.total += turnTotal;
+    current.bySkill[bucket] = (current.bySkill[bucket] ?? 0) + turnTotal;
+  }
+  return turns;
+}
+
+export const DEFAULT_MODEL_LIMITS = { sonnet: 200000, opus: 200000, haiku: 200000 };
+
+export function formatTokenCount(n) {
+  if (n < 1000) return String(Math.round(n));
+  if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`;
+  return `${(n / 1_000_000).toFixed(1)}M`;
+}
+
+function resolveModelLimit(modelId, modelLimits) {
+  if (!modelId) return 200000;
+  const lower = modelId.toLowerCase();
+  for (const [key, limit] of Object.entries(modelLimits)) {
+    if (lower.includes(key.toLowerCase())) return limit;
+  }
+  return 200000;
+}
+
+export function computeTotals(events, turns, opts = {}) {
+  const modelLimits = opts.modelLimits ?? DEFAULT_MODEL_LIMITS;
+
+  const totals = { input_tokens: 0, output_tokens: 0, cache_creation_input_tokens: 0, cache_read_input_tokens: 0, total: 0 };
+  const bySkillMap = {};
+  for (const turn of turns) {
+    totals.input_tokens += turn.usage.input_tokens;
+    totals.output_tokens += turn.usage.output_tokens;
+    totals.cache_creation_input_tokens += turn.usage.cache_creation_input_tokens;
+    totals.cache_read_input_tokens += turn.usage.cache_read_input_tokens;
+    totals.total += turn.usage.total;
+    for (const [skill, tokens] of Object.entries(turn.bySkill)) {
+      bySkillMap[skill] = (bySkillMap[skill] ?? 0) + tokens;
+    }
+  }
+  const bySkill = Object.entries(bySkillMap)
+    .map(([skill, total]) => ({ skill, total }))
+    .sort((a, b) => b.total - a.total);
+  const topTurns = [...turns].sort((a, b) => b.usage.total - a.usage.total);
+
+  let contextWindow = null;
+  const lastMainAssistant = [...events].reverse().find((e) => e.role === 'assistant' && !e.isSidechain && e.usage);
+  if (lastMainAssistant) {
+    const totalInputTokens =
+      lastMainAssistant.usage.input_tokens +
+      lastMainAssistant.usage.cache_read_input_tokens +
+      lastMainAssistant.usage.cache_creation_input_tokens;
+    const contextWindowSize = resolveModelLimit(lastMainAssistant.model, modelLimits);
+    contextWindow = {
+      totalInputTokens,
+      contextWindowSize,
+      usedPercentage: Math.round((totalInputTokens / contextWindowSize) * 1000) / 10,
+    };
+  }
+
+  return { totals, bySkill, topTurns, contextWindow };
+}
+
+export function formatStatusLine({ totals, contextWindowOverride }) {
+  const top = totals.topTurns[0];
+  const parts = [`🔥 sessão: ${formatTokenCount(totals.totals.total)} tok`];
+  const pct = contextWindowOverride ?? totals.contextWindow?.usedPercentage ?? null;
+  if (pct !== null) parts.push(`contexto: ${pct}% usado`);
+  if (top) parts.push(`prompt mais caro: ${formatTokenCount(top.usage.total)} tok`);
+  return parts.join(' · ');
+}
+
+export function formatSnapshot(totals, meta) {
+  const { sessionId, projectLabel, warnings = 0, topN = 5 } = meta;
+  const lines = [];
+  lines.push(`Sessão ativa: ${sessionId} (${projectLabel})`);
+  const t = totals.totals;
+  lines.push(
+    `Total: ${formatTokenCount(t.total)} tok  (in ${formatTokenCount(t.input_tokens)} / out ${formatTokenCount(
+      t.output_tokens
+    )} / cache-w ${formatTokenCount(t.cache_creation_input_tokens)} / cache-r ${formatTokenCount(
+      t.cache_read_input_tokens
+    )})`
+  );
+  if (totals.contextWindow) {
+    lines.push(
+      `Context window: ${totals.contextWindow.usedPercentage}% (${formatTokenCount(
+        totals.contextWindow.totalInputTokens
+      )} / ${formatTokenCount(totals.contextWindow.contextWindowSize)})`
+    );
+  }
+  lines.push('');
+  lines.push('Top prompts:');
+  const top = totals.topTurns.slice(0, topN);
+  if (top.length === 0) {
+    lines.push(' (nenhum prompt registrado ainda)');
+  } else {
+    top.forEach((turn, i) => {
+      lines.push(` ${i + 1}. ${formatTokenCount(turn.usage.total)}  "${turn.textPreview}"`);
+    });
+  }
+  lines.push('');
+  lines.push('Por skill/agente:');
+  if (totals.bySkill.length === 0) {
+    lines.push(' (sem dados)');
+  } else {
+    totals.bySkill.forEach(({ skill, total }) => {
+      lines.push(` ${skill.padEnd(12)} ${formatTokenCount(total)}`);
+    });
+  }
+  if (warnings > 0) {
+    lines.push('');
+    lines.push(`(${warnings} linha(s) de log ignorada(s) por estarem corrompidas)`);
+  }
+  return lines.join('\n');
+}
+
+export function buildViewModel(totals, meta) {
+  const { sessionId, projectLabel, warnings = 0 } = meta;
+  const pct = totals.contextWindow?.usedPercentage ?? null;
+  const contextSeverity = pct === null ? null : pct >= 80 ? 'danger' : pct >= 50 ? 'warn' : 'ok';
+  return {
+    header: `token-monitor — ${projectLabel} (${sessionId})`,
+    totalTokens: formatTokenCount(totals.totals.total),
+    breakdown: `in ${formatTokenCount(totals.totals.input_tokens)} · out ${formatTokenCount(
+      totals.totals.output_tokens
+    )} · cache-w ${formatTokenCount(totals.totals.cache_creation_input_tokens)} · cache-r ${formatTokenCount(
+      totals.totals.cache_read_input_tokens
+    )}`,
+    contextPercentage: pct,
+    contextSeverity,
+    contextDetail: totals.contextWindow
+      ? `${formatTokenCount(totals.contextWindow.totalInputTokens)} / ${formatTokenCount(
+          totals.contextWindow.contextWindowSize
+        )}`
+      : null,
+    topRows: totals.topTurns.slice(0, 8).map((turn, i) => ({
+      rank: i + 1,
+      tokens: formatTokenCount(turn.usage.total),
+      preview: turn.textPreview,
+    })),
+    skillRows: totals.bySkill.map(({ skill, total }) => ({ skill, tokens: formatTokenCount(total) })),
+    warningsLine: warnings > 0 ? `${warnings} linha(s) ignorada(s) (log corrompido)` : null,
+  };
+}

package/scripts/setup.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync, symlinkSync, lstatSync, copyFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isMainModule } from './lib.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.join(__dirname, '..');
+
+export function mergeStatusLine(existingSettings, statusLineConfig, opts = {}) {
+  const { force = false } = opts;
+  const current = existingSettings.statusLine;
+  if (current) {
+    const same = JSON.stringify(current) === JSON.stringify(statusLineConfig);
+    if (same) return { settings: existingSettings, changed: false, skippedReason: null };
+    if (!force) {
+      return {
+        settings: existingSettings,
+        changed: false,
+        skippedReason: 'statusLine já configurada com outro comando — rode `tokmon setup --force` pra sobrescrever',
+      };
+    }
+  }
+  return { settings: { ...existingSettings, statusLine: statusLineConfig }, changed: true, skippedReason: null };
+}
+
+export function runSetup(argv = process.argv.slice(2)) {
+  const force = argv.includes('--force');
+  const claudeHome = process.env.TOKEN_MONITOR_HOME ?? path.join(process.env.HOME ?? '', '.claude');
+  const skillLink = path.join(claudeHome, 'skills', 'token-monitor');
+  const commandFile = path.join(claudeHome, 'commands', 'tokens.md');
+  const settingsFile = path.join(claudeHome, 'settings.json');
+
+  mkdirSync(path.join(claudeHome, 'skills'), { recursive: true });
+  mkdirSync(path.join(claudeHome, 'commands'), { recursive: true });
+
+  if (existsSync(skillLink)) {
+    if (!lstatSync(skillLink).isSymbolicLink()) {
+      console.error(`erro: ${skillLink} existe e não é um symlink — remova manualmente antes de rodar o setup.`);
+      process.exitCode = 1;
+      return;
+    }
+  } else {
+    symlinkSync(PACKAGE_ROOT, skillLink, 'dir');
+  }
+  console.log(`✓ skill linkada em ${skillLink}`);
+
+  copyFileSync(path.join(PACKAGE_ROOT, 'commands', 'tokens.md'), commandFile);
+  console.log(`✓ comando /tokens copiado pra ${commandFile}`);
+
+  let settings = {};
+  if (existsSync(settingsFile)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsFile, 'utf8'));
+    } catch {
+      console.error(`erro: ${settingsFile} não é um JSON válido — corrija manualmente antes de rodar o setup.`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  const statusLineConfig = {
+    type: 'command',
+    command: `node ${path.join(skillLink, 'scripts', 'statusline.mjs')}`,
+  };
+  const { settings: merged, changed, skippedReason } = mergeStatusLine(settings, statusLineConfig, { force });
+  if (skippedReason) {
+    console.log(`⚠ statusLine não alterada: ${skippedReason}`);
+  } else if (changed) {
+    writeFileSync(settingsFile, `${JSON.stringify(merged, null, 2)}\n`);
+    console.log(`✓ statusLine configurada em ${settingsFile}`);
+  } else {
+    console.log('✓ statusLine já configurada corretamente');
+  }
+
+  console.log('\nPronto. Abra uma nova sessão do Claude Code pra ver a statusline, e rode `tokmon watch` ou `tokmon snapshot` quando quiser.');
+}
+
+if (isMainModule(import.meta.url)) {
+  runSetup();
+}

package/scripts/snapshot.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import {
+  encodeProjectDir,
+  findActiveSession,
+  parseSession,
+  groupIntoTurns,
+  computeTotals,
+  formatSnapshot,
+  isMainModule,
+} from './lib.mjs';
+
+export function runSnapshot(argv = process.argv.slice(2)) {
+  const cwd = argv[0] ?? process.cwd();
+  const home = process.env.HOME ?? '';
+  const projectDir = path.join(home, '.claude', 'projects', encodeProjectDir(cwd));
+  const sessionFile = findActiveSession(projectDir);
+  if (!sessionFile) {
+    console.log(`token-monitor: nenhuma sessão encontrada em ${projectDir}`);
+    console.log('Rode este comando de dentro de um projeto com uma sessão ativa do Claude Code.');
+    return;
+  }
+  const { events, warnings } = parseSession(sessionFile);
+  const turns = groupIntoTurns(events);
+  const totals = computeTotals(events, turns);
+  const sessionId = path.basename(sessionFile, '.jsonl');
+  console.log(formatSnapshot(totals, { sessionId, projectLabel: path.basename(cwd), warnings }));
+}
+
+if (isMainModule(import.meta.url)) {
+  runSnapshot();
+}

package/scripts/statusline.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { parseSession, groupIntoTurns, computeTotals, formatStatusLine, isMainModule } from './lib.mjs';
+
+export function runStatusline() {
+  let input;
+  try {
+    input = JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    console.log('token-monitor: sem sessão');
+    return;
+  }
+  const transcriptPath = input?.transcript_path;
+  if (!transcriptPath) {
+    console.log('token-monitor: sem sessão');
+    return;
+  }
+  let totals;
+  try {
+    const { events } = parseSession(transcriptPath);
+    const turns = groupIntoTurns(events);
+    totals = computeTotals(events, turns);
+  } catch {
+    console.log('token-monitor: sem sessão');
+    return;
+  }
+  const contextWindowOverride = input?.context_window?.used_percentage ?? null;
+  console.log(formatStatusLine({ totals, contextWindowOverride }));
+}
+
+if (isMainModule(import.meta.url)) {
+  runStatusline();
+}

package/scripts/watch.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+import { watch } from 'node:fs';
+import path from 'node:path';
+import {
+  encodeProjectDir,
+  findActiveSession,
+  parseSession,
+  groupIntoTurns,
+  computeTotals,
+  buildViewModel,
+  isMainModule,
+} from './lib.mjs';
+import { DRAGON_SPRITE_ROWS, DRAGON_PALETTE, hpBarSegments } from './dragon-sprite.mjs';
+
+function loadViewModel(cwd) {
+  const home = process.env.HOME ?? '';
+  const projectDir = path.join(home, '.claude', 'projects', encodeProjectDir(cwd));
+  const sessionFile = findActiveSession(projectDir);
+  if (!sessionFile) return { error: `sem sessão ativa em ${projectDir}`, sessionFile: null };
+  const { events, warnings } = parseSession(sessionFile);
+  const turns = groupIntoTurns(events);
+  const totals = computeTotals(events, turns);
+  const sessionId = path.basename(sessionFile, '.jsonl');
+  return {
+    model: buildViewModel(totals, { sessionId, projectLabel: path.basename(cwd), warnings }),
+    sessionFile,
+  };
+}
+
+// Packs 2 sprite rows into 1 terminal row using the ▀ (upper half block)
+// trick: foreground = top pixel, background = bottom pixel. Halves both the
+// width (1 char/pixel instead of 2) and the height (2 sprite rows/line) of
+// the previous flat-block rendering, and the character's own ~1:2 aspect
+// ratio makes each original square sprite pixel read correctly proportioned.
+function renderDragonSprite({ Box, Text, h }) {
+  const lines = [];
+  for (let i = 0; i < DRAGON_SPRITE_ROWS.length; i += 2) {
+    const top = DRAGON_SPRITE_ROWS[i];
+    const bottom = DRAGON_SPRITE_ROWS[i + 1] ?? '.'.repeat(top.length);
+    lines.push(
+      h(
+        Text,
+        { key: `row-${i}` },
+        ...top.split('').map((topCode, x) => {
+          const topColor = DRAGON_PALETTE[topCode];
+          const bottomColor = DRAGON_PALETTE[bottom[x]];
+          if (!topColor && !bottomColor) return h(Text, { key: x }, ' ');
+          if (topColor && !bottomColor) return h(Text, { key: x, color: topColor }, '▀');
+          if (!topColor && bottomColor) return h(Text, { key: x, color: bottomColor }, '▄');
+          return h(Text, { key: x, color: topColor, backgroundColor: bottomColor }, '▀');
+        })
+      )
+    );
+  }
+  return h(Box, { flexDirection: 'column' }, ...lines);
+}
+
+function renderStatsPanel({ Box, Text, h }, model, contextColor) {
+  const bar = hpBarSegments(model.contextPercentage);
+  return h(
+    Box,
+    { flexDirection: 'column', marginLeft: 2 },
+    h(Text, { bold: true, color: 'cyan' }, model.header),
+    h(Text, null, ' '),
+    h(Text, null, `🔥 Total: ${model.totalTokens} tok`),
+    h(Text, { dimColor: true }, model.breakdown),
+    h(Text, null, ' '),
+    model.contextPercentage !== null
+      ? h(
+          Text,
+          null,
+          'CTX ',
+          h(Text, { color: contextColor }, '█'.repeat(bar.filled)),
+          h(Text, { dimColor: true }, '░'.repeat(bar.empty)),
+          ` ${model.contextPercentage}% (${model.contextDetail})`
+        )
+      : h(Text, { dimColor: true }, 'CTX sem dados ainda'),
+    h(Text, null, ' '),
+    model.topRows[0]
+      ? h(Text, { dimColor: true }, `Top: "${model.topRows[0].preview}"`)
+      : h(Text, { dimColor: true }, 'Top: (nenhum prompt registrado ainda)')
+  );
+}
+
+function createApp({ Box, Text, useState, useEffect, h }) {
+  return function App({ cwd }) {
+    const [state, setState] = useState(() => loadViewModel(cwd));
+
+    useEffect(() => {
+      const reload = () => setState(loadViewModel(cwd));
+      const interval = setInterval(reload, 2000);
+      const watcher = state.sessionFile ? watch(state.sessionFile, { persistent: false }, reload) : null;
+      return () => {
+        clearInterval(interval);
+        watcher?.close();
+      };
+    }, [cwd, state.sessionFile]);
+
+    if (state.error) {
+      return h(
+        Box,
+        { borderStyle: 'round', borderColor: 'yellow', paddingX: 1 },
+        h(Text, { color: 'yellow' }, `⚠ token-monitor: ${state.error}`)
+      );
+    }
+    const { model } = state;
+    const contextColor =
+      model.contextSeverity === 'danger' ? 'red' : model.contextSeverity === 'warn' ? 'yellow' : 'green';
+
+    return h(
+      Box,
+      { flexDirection: 'column' },
+      h(
+        Box,
+        { flexDirection: 'row', borderStyle: 'round', borderColor: 'cyan', paddingX: 1, marginBottom: 1 },
+        renderDragonSprite({ Box, Text, h }),
+        renderStatsPanel({ Box, Text, h }, model, contextColor)
+      ),
+      h(
+        Box,
+        { flexDirection: 'column', borderStyle: 'round', borderColor: 'magenta', paddingX: 1, marginBottom: 1 },
+        h(Text, { bold: true, color: 'magenta' }, '🏆 Top prompts'),
+        ...(model.topRows.length
+          ? model.topRows.map((row) =>
+              h(Text, { key: String(row.rank) }, ` ${row.rank}. ${row.tokens.padStart(7)}  "${row.preview}"`)
+            )
+          : [h(Text, { dimColor: true }, ' (nenhum prompt registrado ainda)')])
+      ),
+      h(
+        Box,
+        { flexDirection: 'column', borderStyle: 'round', borderColor: 'blue', paddingX: 1 },
+        h(Text, { bold: true, color: 'blue' }, '🧩 Por skill/agente'),
+        ...(model.skillRows.length
+          ? model.skillRows.map((row) =>
+              h(Text, { key: row.skill }, ` ${row.skill.padEnd(12)} ${row.tokens.padStart(7)}`)
+            )
+          : [h(Text, { dimColor: true }, ' (sem dados)')])
+      ),
+      model.warningsLine ? h(Text, { color: 'red' }, `⚠ ${model.warningsLine}`) : null
+    );
+  };
+}
+
+export async function runWatch(argv = process.argv.slice(2)) {
+  let React, ink;
+  try {
+    [{ default: React }, ink] = await Promise.all([import('react'), import('ink')]);
+  } catch {
+    console.error('token-monitor: dependências não instaladas. Rode `npm install` na pasta da skill (~/.claude/skills/token-monitor).');
+    process.exitCode = 1;
+    return;
+  }
+  const h = React.createElement;
+  const App = createApp({ Box: ink.Box, Text: ink.Text, useState: React.useState, useEffect: React.useEffect, h });
+  const cwd = argv[0] ?? process.cwd();
+  ink.render(h(App, { cwd }));
+}
+
+if (isMainModule(import.meta.url)) {
+  runWatch();
+}