🧮 Tokens Counter

Una herramienta CLI rápida y eficiente para contar tokens en proyectos de código, diseñada específicamente para trabajar con los límites de contexto de Cursor (120K tokens).

✨ Características

• 🚀 Procesamiento en paralelo para máxima velocidad
• 🎯 Optimizado para Cursor - compara automáticamente con el límite de 120K tokens
• 📁 Exclusión inteligente - ignora node_modules, .git, dist, build y otros directorios innecesarios
• 🎨 Salida colorizada y fácil de leer
• 📊 Estadísticas detalladas por tipo de archivo
• 🔧 Altamente configurable con múltiples opciones
• 🌍 Instalación global - úsalo en cualquier proyecto

📦 Instalación

Instalación Global (Recomendada)

# Clona el repositorio o descarga los archivos
git clone https://github.com/tu-usuario/tokens-counter.git
cd tokens-counter

# Instala las dependencias
npm install

# Instala globalmente
npm install -g .

# O usando el script incluido
npm run install-global

Ahora puedes usar tokens-counter o tc desde cualquier directorio.

Instalación Local

npm install
npm start -- [opciones]

🚀 Uso

Comando básico

# Analizar directorio actual
tokens-counter

# Analizar un directorio específico
tokens-counter /ruta/a/tu/proyecto

# Usando el alias corto
tc /ruta/a/tu/proyecto

Ejemplos de uso

# Análisis básico del directorio actual
tokens-counter

# Análisis con información detallada
tokens-counter -v

# Solo mostrar el número total de tokens
tokens-counter -q

# Mostrar archivos con más tokens
tokens-counter -f

# Incluir solo archivos JavaScript y TypeScript
tokens-counter -e .js,.ts,.jsx,.tsx

# Ignorar directorios adicionales
tokens-counter -i "tests/**,docs/**"

# Salida en formato JSON
tokens-counter -j

# Estadísticas rápidas sin contar tokens
tokens-counter stats

# Procesar con más paralelismo
tokens-counter -c 20

📋 Comandos disponibles

count (comando por defecto)

Cuenta tokens en el directorio especificado.

Opciones:

• -v, --verbose - Mostrar información detallada
• -q, --quiet - Mostrar solo el resultado total
• -f, --files - Mostrar lista de archivos con más tokens
• -e, --extensions <extensions> - Extensiones específicas a incluir (ej: .js,.ts,.py)
• -i, --ignore <patterns> - Patrones adicionales a ignorar (ej: dist/,build/)
• -c, --concurrency <number> - Número máximo de archivos a procesar simultáneamente (por defecto: 10)
• -j, --json - Salida en formato JSON
• --no-progress - No mostrar barra de progreso

stats

Muestra estadísticas rápidas del directorio sin calcular tokens.

🎯 Tipos de archivo soportados

La herramienta incluye automáticamente estos tipos de archivo:

Código:

• JavaScript/TypeScript: .js, .jsx, .ts, .tsx, .mjs, .cjs
• Python: .py, .pyx, .pyi
• Java/Kotlin/Scala: .java, .kt, .scala
• C/C++: .c, .cpp, .cxx, .cc, .h, .hpp, .hxx
• C#: .cs, .vb
• PHP: .php, .phtml
• Ruby: .rb, .rake
• Go: .go
• Rust: .rs
• Swift: .swift
• Shell: .sh, .bash, .zsh, .fish

Web y markup:

• HTML/CSS: .html, .htm, .css, .scss, .sass, .less
• Vue/Svelte: .vue, .svelte
• XML/SVG: .xml, .svg

Configuración y datos:

• JSON/YAML: .json, .yaml, .yml, .toml, .ini, .env
• SQL: .sql

Documentación:

• Markdown: .md
• Texto: .txt, .rst

🚫 Directorios excluidos automáticamente

• node_modules/
• .git/
• dist/, build/
• .next/
• coverage/, .nyc_output/
• vendor/
• __pycache__/, .pytest_cache/
• target/ (Rust/Java)
• bin/, obj/ (.NET)
• .vscode/, .idea/
• tmp/, temp/

📊 Ejemplo de salida

🚀 TOKENS COUNTER
Analizando: /home/usuario/mi-proyecto
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 RESUMEN DE TOKENS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Total de tokens: 45,230
📁 Archivos procesados: 125/127
⏱️  Tiempo: 2.34s
💾 Tamaño total: 2.1 MB

📋 POR TIPO DE ARCHIVO
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
.js      18,450 tokens (40.8%) 45 archivos
.ts      12,330 tokens (27.3%) 23 archivos
.tsx      8,920 tokens (19.7%) 18 archivos
.css      3,210 tokens (7.1%)  12 archivos
.md       1,890 tokens (4.2%)  8 archivos
.json       430 tokens (1.0%)  19 archivos

📐 COMPARACIÓN CON CURSOR
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Tu proyecto está dentro del límite de Cursor
   Usando: 45,230 / 120,000 tokens (37.7%)
   Disponible: 74,770 tokens

⚙️ Algoritmo de cálculo de tokens

La herramienta utiliza una aproximación inteligente basada en:

1. Tokenización por palabras y símbolos para código
2. Ajuste por tipo de archivo (código vs markup vs datos)
3. Consideración de palabras largas que pueden ser múltiples tokens
4. Aproximación de ~4 caracteres por token como base

Aunque no es 100% exacto como los tokenizadores oficiales de GPT-4/Claude, proporciona una estimación muy cercana y útil para planificar el uso del contexto en Cursor.

🛠️ Desarrollo

# Instalar dependencias
npm install

# Ejecutar tests
npm test

# Ejecutar localmente
node bin/cli.js

# Instalar globalmente para desarrollo
npm link

📄 Licencia

MIT License - ve el archivo LICENSE para más detalles.

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

📞 Soporte

Si encuentras algún problema o tienes sugerencias, por favor abre un issue en GitHub.

¡Hecho con ❤️ para la comunidad de desarrolladores que usan Cursor!