SnapContext

┌──────────────────────────────────────────────────────────┐
  │                                                          │
  │                                                          │
  │    ███████╗███╗   ██╗ █████╗ ██████╗  ██████╗ ██████╗   │
  │    ██╔════╝████╗  ██║██╔══██╗██╔══██╗██╔════╝██╔════╝   │
  │    ███████╗██╔██╗ ██║███████║██████╔╝██║     ██║        │
  │    ╚════██║██║╚██╗██║██╔═══╝ ██║     ██║     ██║        │
  │    ███████║██║ ╚████║██║  ██║██║     ╚██████╗╚██████╗   │
  │    ╚══════╝╚═╝  ╚═══╝╚═╝  ╚═╝      ╚═════╝ ╚═════╝   │
  │                                                          │
  │    » Selección inteligente de archivos                  │
  │    » Soporte: Gemini · Ollama · DeepSeek · Groq        │
  │    » v0.8.0                                             │
  │                                                          │
  └──────────────────────────────────────────────────────────┘
  

(disponible en desarrollo; versión pública: v0.6.0)

🗺️ Planificador de tareas (v0.12.0)

snapcontext --plan "añadir login con Google" convierte SnapContext en un agente:

1. El proveedor de IA descompone la tarea en pasos JSON: {"descripcion": "...", "accion": "editar|ejecutar|consultar", "archivos": [...], "comando": "..."}
2. Los pasos se muestran numerados y se pide confirmación.
3. Cada paso se ejecuta secuencialmente: editar usa el pipeline completo (_planificar + _bucle_test), ejecutar lanza comandos shell, consultar pregunta al proveedor.
4. Tras cada paso eliges: continuar / reintentar / saltar / abortar. Al final hay un resumen que se guarda en historial.json.

Opciones git:

snapcontext --plan "migrar a null-safety" --branch fix/null-safety   # rama nueva
snapcontext --plan "..." --no-git-commit                             # sin commits por paso
snapcontext --plan "..."                                             # commits 'paso: ...' activados

✨ Novedades v0.10.0

• Claude (Anthropic) como proveedor de IA: snapcontext "..." --provider anthropic (requiere ANTHROPIC_API_KEY y pip install snapcontext[anthropic]). Modelo por defecto: claude-3-5-sonnet-20241022.
• Modo chat interactivo: snapcontext --chat abre un REPL con los comandos /salir, /archivos, /limpiar, /seleccion <consulta>, /provider <proveedor>, /historial y /ayuda. Cualquier otro texto se envía al proveedor actual manteniendo la conversación.
• Memoria persistente: cada tarea se guarda en ~/.snapcontext/historial.json (fecha, consulta, archivos, resultado y duración). Consulta con snapcontext --historial y borra con snapcontext --historial-limpiar.
• Base para el agente autónomo: nuevas utilidades _leer_archivo(ruta) y _ejecutar_comando(comando, directorio) disponibles para el chat y futuros planificadores.
• Chat como REPL de comandos de agente: desde --chat puedes ejecutar /run <comando> (shell), /read <archivo>, /explore <tema> (búsqueda con rg/grep/findstr), /fix | /review | /server <mensaje> (alias del pipeline), /edit <archivo> (VSCode/nano/notepad/$EDITOR), /context (contexto actual), /save (guarda la sesión en historial.json) además de los comandos previos. Los comandos largos (/run, /explore, /fix, /review, /server) se ejecutan en un hilo separado para no bloquear el chat.

🤝 Contribuciones

Las contribuciones son bienvenidas. Si tienes una idea, abre un issue o envía un pull request.

1. Haz un fork del proyecto.
2. Crea tu rama de características (git checkout -b feature/nueva-funcionalidad).
3. Haz commit de tus cambios (git commit -m 'Añadir nueva funcionalidad').
4. Haz push a la rama (git push origin feature/nueva-funcionalidad).
5. Abre un Pull Request.

Combina lo mejor de dos mundos:

• Aider: eficiencia, control y una integración Git impecable.
• Gestión automática de contexto (estilo Claude Code): no hace falta decirle /add archivo — SnapContext averigua los archivos por ti.

Le pasas una tarea en lenguaje natural y SnapContext:

1. Escanea el repositorio (por defecto las carpetas lib/ y supabase/) y encuentra los archivos más relacionados con tu consulta.
2. El proveedor de IA (Gemini, Ollama local, DeepSeek o Groq) selecciona los archivos más relevantes.
3. Aider recibe esos archivos y la consulta original, y hace los cambios en el código (con commits automáticos en Git).

$ snapcontext "el botón de pago no funciona"
ℹ Repositorio: C:\...\marketplace-productos-locales
ℹ Escaneando el repositorio para encontrar candidatos...
ℹ 24 candidato(s) relevante(s) localmente.
ℹ Seleccionando con Gemini (gemini-2.5-flash)...

✔ Archivos seleccionados (3):
   • lib/pages/pago/pago_page.dart
   • lib/models/pedido.dart
   • supabase/functions/procesar-pago-mp/index.ts

ℹ Ejecutando Aider...
✔ Aider terminó correctamente.

Novedades (v0.9.0)

• Modo demo (--demo): muestra el valor de SnapContext en ~1 minuto, sin necesidad de API key ni Aider. Crea un proyecto de prueba temporal, muestra la selección de archivos (--vista-previa --local) y ejecuta el bucle de pruebas completo con un editor de demostración offline.

Novedades (v0.8.0)

• Auto-detección del tipo de proyecto: ajusta carpetas y extensiones por defecto según el proyecto detectado (Flutter, Node, Python, Go, Rust, Kotlin, Swift) de forma transparente.
• Alias / atajos de comandos: fix, review, server e interactive.
• Interfaz web en tiempo real: spinner/barra de progreso, cronómetro, contadores de archivos escaneados/seleccionados y nuevos eventos coloreados.

Novedades (v0.6.0)

Qué hay de nuevo en esta versión:

• Corrección crítica en --init: ahora usa correctamente questionary.password() para ingresar claves API con Groq y DeepSeek, solucionando un bug anterior que impedía la configuración de estos proveedores.
• Manejo mejorado de errores de configuración: si ~/.snapcontext/config.json está corrupto o no existe, se muestra un aviso claro en lugar de fallar silenciosamente.
• Actualización a versión 0.6.0: todos los metadatos (pyproject.toml, README.md) reflejan la nueva versión.
• Mejoras de instalación: scripts de Linux y Windows actualizados con mensajes claros y fallbacks correctos a pip si uv no está disponible.

Qué hay de nuevo en esta versión:

• Validación de carpeta de proyecto: comprueba al iniciar que existe una carpeta típica (lib/, src/, supabase/, app/, packages/, backend/) y avisa si no (sale con código 1).
• Menú interactivo de proveedor (questionary con flechas y Enter): elige Gemini, Ollama, DeepSeek o Groq sin escribir --provider.
• Configuración persistente: guarda tu proveedor/modelo favorito en ~/.snapcontext/config.json y lo reutiliza en las siguientes ejecuciones.
• Auto-detección de modelos de Ollama: con ollama list, muestra los modelos locales disponibles para elegir.
• Asistente de configuración inicial (--init): guía el alta de claves API, proveedor y modelo favorito, y una prueba opcional de conexión.

Instalación rápida (one-liner)

Linux / macOS:

# Instalar desde GitHub Pages (recomendado)
curl -LsSf https://NicolasBruna24.github.io/snapcontext/install.sh | sh

# Fallback: instalan directamente desde el repositorio raw si GitHub Pages falla
curl -LsSf https://raw.githubusercontent.com/NicolasBruna24/snapcontext/main/install.sh | sh

Windows (PowerShell):

# Instalar desde GitHub Pages (recomendado)
powershell -ExecutionPolicy ByPass -c "irm https://NicolasBruna24.github.io/snapcontext/install.ps1 | iex"

# Fallback: instalan directamente desde el repositorio raw si GitHub Pages falla  
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/NicolasBruna24/snapcontext/main/install.ps1 | iex"

Los scripts detectan automáticamente tu sistema, verifican Python 3.9+, instalan uv (gestor rápido de paquetes Python) si no está presente, y finalmente instalan SnapContext. Al terminar:

• ✅ Windows: El comando snapcontext se añadirá automáticamente al PATH del usuario permanentemente (variable Path). Solo necesitas reiniciar tu terminal o ejecutar refreshenv.
• ✅ Linux/macOS: pip registra el ejecutable en el PATH del usuario de forma automática sin requerir permisos especiales.

📝 En Windows, si prefieres una instalación manual paso a paso o instalaste directamente con pip install snapcontext (sin usar el one-liner), puedes ejecutar:

snapcontext --setup-path

Esto añadirá automáticamente la carpeta de SnapContext al PATH del usuario.

Requisitos

Aider usa su propia configuración de modelo y API keys (variables AIDER_* o el fichero .env del proyecto). Configura Aider una vez y SnapContext lo reutilizará.

Instalación

# 1. Clonar / copiar el proyecto y entrar en él
cd SnapContext

# 2. (Recomendado) entorno virtual
python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/Mac:
source .venv/bin/activate

# 3. Instalar en modo editable → expone el comando "snapcontext" globalmente
pip install -e .

# 3b. (Opcional) Menú interactivo para elegir proveedor con flechas ↑↓
#     (si no lo instalas, SnapContext usa Gemini por defecto con un aviso)
pip install "snapcontext[interactive]"     # o simplemente:  pip install questionary

# 4. Dependencia externa (Aider arrastra más paquetes por eso va aparte)
pip install aider-chat

# 5. Configurar la clave del proveedor que vayas a usar
#    PowerShell:
$env:GEMINI_API_KEY = "tu_clave"        # o DEEPSEEK_API_KEY / GROQ_API_KEY
#    Linux/Mac:
export GEMINI_API_KEY=tu_clave

Uso

# Ejemplo básico: escaneo + IA + Aider
snapcontext "el botón de pago no funciona"

# Selección de proveedor: sin --provider ni --local, aparecerá un menú
# interactivo (↑↓ + Enter) para elegir entre Gemini, Ollama, DeepSeek y Groq.
# Requiere questionary (ver instalación); sin él se usa Gemini con un aviso.
snapcontext "revisar el login"

# Elegir proveedor y modelo directamente (sin menú interactivo)
snapcontext "..." --provider groq
snapcontext "..." --provider deepseek --model deepseek-reasoner
snapcontext "..." --provider ollama --model qwen2.5   # Ollama local

# Modo offline (sin IA): no muestra menú interactivo
snapcontext "..." --local

# Modo experto: revisar/añadir/eliminar archivos antes de Aider
snapcontext "revisar pago" --experto

# Si el proyecto usa carpetas distintas a lib/ y supabase/
snapcontext "arreglar login" --carpetas src migrations

# Solo ver qué archivos elegiría (sin tocar código)
snapcontext "revisar carrito" --vista-previa

# Bucle agéntico: ejecutar flutter test tras Aider y repetir si falla
snapcontext "añadir validación al formulario" --test-loop

# Cambiar el número de archivos que recibe Aider
snapcontext "agregar índice a pedidos" --max-archivos 4

# Opciones extra para Aider (modelo, etc.)
snapcontext "..." --aider-opciones "--model sonnet --no-auto-commits"

# Modo offline (sin Gemini) por si solo quieres la heurística local
snapcontext "..." --local

# Interfaz web (FastAPI + WebSockets) con logs en tiempo real
snapcontext --web              # http://localhost:8000
snapcontext --web --web-puerto 8123

# Alias / atajos para tareas frecuentes
snapcontext fix "el botón de pago no funciona"    # = --test-loop
snapcontext review "revisar el login"             # = --vista-previa --experto
snapcontext server "iniciar servidor"             # = --server-loop
snapcontext interactive                           # = --web

# Demo: valor de SnapContext en ~1 min, sin API key
snapcontext --demo

Auto-detección del tipo de proyecto

SnapContext detecta automáticamente el tipo de proyecto buscando archivos clave en la raíz resuelta por --directorio (o el directorio actual):

Además ajusta las extensiones consideradas en el escaneo (por ejemplo, .dart para Flutter, .js/.ts/.jsx/.tsx para Node, .py para Python…).

La detección es transparente: no imprime nada salvo que uses --depurar. Si no se detecta ningún tipo, se mantiene el comportamiento actual (lib/, supabase/, …). Si pasas --carpetas manualmente, tu valor tiene prioridad.

Alias / atajos de comandos

Para tareas frecuentes existen subcomandos cortos (siempre se pueden combinar con el resto de flags):

Si el primer argumento no coincide con ninguno de estos alias, se trata como consulta (comportamiento habitual).

Validación de carpeta de proyecto

Al iniciar, SnapContext comprueba que el directorio contiene carpetas típicas de proyecto (lib/, src/, supabase/, app/, packages/, backend/). Si no encuentra ninguna, avisa y sale (código 1):

⚠️ No parece que estés en una carpeta de proyecto. SnapContext espera carpetas como
lib/, src/, supabase/, etc. Puedes especificar una carpeta con --directorio <ruta> o
navega a la raíz de tu proyecto y vuelve a intentarlo.

Menú interactivo de proveedor (↑↓ + Enter)

Si ejecutas snapcontext "consulta" sin --provider ni --local, SnapContext te pregunta si quieres elegir el proveedor y, si aceptas, muestra un menú con las flechas ↑/↓ y Enter:

🤖 Selecciona el proveedor de IA:
  ❯ Gemini (Google)
    Ollama (local)
    DeepSeek (API)
    Groq (API)

Usa la librería questionary (pip install snapcontext[interactive]). Si no está instalada, se muestra un aviso y se usa Gemini por defecto. Para evitarlo, pasa siempre --provider o --local.

Configuración persistente

SnapContext guarda tus preferencias (proveedor favorito, modelo y claves API de los proveedores que configures) en ~/.snapcontext/config.json:

{
  "provider": "groq",
  "model": "llama-3.3-70b-versatile",
  "api_keys": {
    "gemini": "AIza...",
    "groq": "gsk_..."
  }
}

• Primera vez (sin configuración): pregunta si quieres elegir proveedor con el menú interactivo y ofrece guardarlo como predeterminado.
• Siguientes veces: usa directamente el proveedor guardado, sin menú.
• --provider ... (y opcional --model ...): usa ese proveedor y sobrescribe la preferencia guardada.
• --no-persist: ignora la configuración guardada y fuerza el menú interactivo (no guarda nada).
• También respeta la variable de entorno SNAPCONTEXT_PROVIDER si no hay configuración guardada.

Cómo editarlo: abre ~/.snapcontext/config.json con cualquier editor, cambia provider y model, y guarda. La próxima ejecución lo lee (la carpeta se crea automáticamente con --init o al elegir "guardar").

Asistente de configuración inicial (--init)

Para no configurar claves y proveedor a mano, existe un asistente guiado:

snapcontext --init

Flujo del asistente:

1. Pide la clave de API de Gemini (campo oculto).
2. Pregunta si quieres configurar otros proveedores (Groq, DeepSeek) y guarda sus claves.
3. Te deja elegir el proveedor y modelo favorito con el menú interactivo.
4. Guarda todo en ~/.snapcontext/config.json.
5. (Opcional) Prueba la conexión con la API del proveedor elegido.

Si ya existe una configuración, pregunta si quieres sobrescribirla. Si questionary no está instalada, se muestra el aviso: pip install questionary (o pip install snapcontext[interactive]).

--init es independiente: no necesita consulta, ni escaneo, ni Aider; solo configura y sale (el resto de flags sigue funcionando igual).

Auto-detección de modelos de Ollama

Si eliges Ollama (en el menú o como preferencia guardada) sin pasar --model, SnapContext ejecuta ollama list en segundo plano, listo los modelos locales y te deja elegir con las flechas:

🤖 Selecciona el modelo de Ollama:
  ❯ llama3.2
    qwen2.5

• Los modelos se parsean de la primera columna de la salida de ollama list.
• Si ollama no está instalado o no hay modelos, se avisa y se ofrece volver al menú de proveedores o usar Gemini por defecto.
• Si pasas --provider ollama --model <nombre> por CLI, se omite la detección y se usa directamente ese modelo.

Opciones principales

Cómo funciona por dentro

 consulta ──▶ [1] Escaneo local        ◀── git ls-files / os.walk
                     │
                     ▼
    candidatos ordenados (heurística: ruta + contenido)
                     │
                     ▼
      [2] Proveedor IA (JSON) ─▶ 3 archivos más relevantes
      (Gemini | Ollama | DeepSeek | Groq)
                     │
                     ▼
 [3] Aider --yes --file A --file B --message "consulta"
                     │
                     ▼
 [4] (opcional) verificación: flutter test / flutter run ─ si falla, Aider arregla
                     │                                     │
                     └── pasa ─────────────── fin (aprobado)

El escaneo usa git ls-files -c -o --exclude-standard (respeta .gitignore e incluye archivos nuevos), con caída automática a recorrer el árbol si no hay Git. Luego puntúa cada archivo: coincidencias en la ruta (un nombre de archivo como pago_page.dart pesa más que el directorio pagos/) y coincidencias en las primeras líneas del contenido (con tildes normalizadas: botón → boton).

El proveedor de IA recibe la lista de candidatos y responde en JSON (con validación y fallback si el modelo no devuelve rutas válidas). Gemini usa google.generativeai; DeepSeek, Groq y Ollama usan la librería openai (sus APIs son compatibles con la de OpenAI). El modo --local usa solo la heurística local, sin llamar a ningún proveedor.

Bucle agéntico (--test-loop)

El modo --test-loop implementa el paso 4 de la arquitectura: Aider → flutter test → si falla, Aider recibe el error real y lo arregla, hasta un máximo de --max-iteraciones.

snapcontext "arreglar el flujo de pago" --test-loop --max-iteraciones 5

Este es el punto natural para extender SnapContext: por ejemplo, añadir flutter analyze, linters o más herramientas dentro de ejecutar_bucle_test().

Modo experto (--experto / --expert)

Con --experto, antes de ejecutar Aider SnapContext te deja revisar y editar la lista de archivos que la IA seleccionó:

snapcontext "revisar el flujo de pago" --experto

1. Tras la selección pregunta: ¿Quieres revisar los archivos seleccionados? (s/n).

   • n → ejecuta Aider directamente (comportamiento normal).
   • s → abre el menú experto.

2. En el menú se muestran los archivos numerados y las opciones:

   ── Modo experto ─────────────────────────
     [1] lib/pago/pago_page.dart
     [2] lib/models/pedido.dart
     [3] supabase/functions/procesar-pago-mp/index.ts
   Opciones: [a]gregar   [e]liminar   [l]impiar   [c]ontinuar
   

   Opción	Qué hace
   a	Pide una ruta y la añade (se valida que exista y esté dentro del repo)
   e	Elimina por índice (fuera de rango se rechaza)
   l	Vacía la lista (con confirmación)
   c	Usa la lista final y ejecuta Aider

3. Con c (continuar) se muestran los archivos finales, se los pasa a Aider y se ejecuta cualquiera de los bucles elegidos (--test-loop, --server-loop, etc.)

Bucle agéntico con servidor (--server-loop / --manual-loop)

En vez de solo probar, SnapContext lanza la app con flutter run en segundo plano, detecta que el servidor arrancó (buscando Running on, Synced, served at, etc., o la URL real) y deja verificar la app.

Modo automático (--server-loop):

snapcontext "arreglar la pantalla de pago" --server-loop
snapcontext "..." --server-loop --max-intentos 5      # reintentos (por defecto 3)
snapcontext "..." --server-loop --dispositivo chrome  # abrir Chrome

1. Aider edita los archivos.
2. Se lanza flutter run (por defecto -d web-server --web-port 5000).
3. Si el servidor arranca → pregunta ¿Quieres probar la app manualmente? (s/n); con s abre el navegador con la URL real y espera a que pulses Enter. Termina con éxito.
4. Si el servidor falla → captura el error, se lo pasa a Aider (Arregla este error: ...) y reintenta, hasta --max-intentos.
5. Si se agotan los intentos → pregunta ¿Quieres cambiar a modo manual? (s/n); con s pasa a --manual-loop, con n termina con error.

Modo manual (--manual-loop):

snapcontext "revisar el flujo de login" --manual-loop

Tras cada intento (arranque o fallo) pregunta siempre ¿La app funciona correctamente? (s/n). Si respondes n, te pide que describas el error y esa descripción se pasa a Aider (Arregla este error: <tu texto>), repitiendo el ciclo.

El servidor se cierra solo al finalizar (o con Ctrl+C), sin dejar procesos huérfanos. Configura tu proyecto para que flutter run use web si pruebas la interfaz en el navegador.

Interfaz Web (--web)

SnapContext incluye una interfaz web ligera sobre la arquitectura de agentes para seguir en tiempo real lo que hacen el orquestador y los agentes (escaneo, selección, Aider, pruebas, cierre) sin mirar la terminal.

Requisito: instala las dependencias opcionales:

pip install snapcontext[web]
#   o, en desarrollo: pip install -e '.[web]'

Arranque (bloquea hasta Ctrl+C):

snapcontext --web                      # http://localhost:8000
snapcontext --web --web-puerto 8123    # puerto personalizado

Después abre http://localhost:8000 en el navegador. La página ofrece:

• Campo consulta + botón Ejecutar (también con Enter).
• Logs en tiempo real: panel que muestra cada evento log que emite el orquestador (info/aviso/error) vía WebSocket.
• Resultados: archivos seleccionados, avance de Aider y cierre de la tarea (éxito/error).
• Opciones rápidas: Selección local (sin IA), Vista previa, Bucle de pruebas y campos opcionales de directorio y --max-archivos.

Eventos que emite el orquestador (visible en la web):

En la consola, si no hay dependencias web instaladas, snapcontext --web muestra el mensaje: "La interfaz web necesita dependencias opcionales…" y sale sin romper el resto de la CLI.

Solución de problemas

Extenderlo

El código está pensado como un único script claro y comentado. Puntos de extensión fáciles:

• escanear_repositorio() → cambiar la heurística de relevancia local.
• construir_prompt_seleccion() → mejorar las instrucciones a Gemini.
• ejecutar_bucle_test() → añadir más herramientas al bucle agéntico.
• Constantes de configuración → ajustar el comportamiento por defecto.

Variables de entorno

Ejemplo de configuración en Linux/macOS (bash/zsh):

export GEMINI_API_KEY="tu_clave"
export DEEPSEEK_API_KEY="tu_clave"
export GROQ_API_KEY="tu_clave"
export OLLAMA_URL="http://localhost:11434"

Ejemplo de configuración en Windows (PowerShell):

$env:GEMINI_API_KEY = "tu_clave"
$env:DEEPSEEK_API_KEY = "tu_clave"
$env:GROQ_API_KEY = "tu_clave"
$env:OLLAMA_URL = "http://localhost:11434"

Compatibilidad y Permisos (Linux / macOS / Windows)

• Windows: Al instalar con pip install snapcontext o usando el one-liner (install.ps1), el instalador configura automáticamente el PATH del usuario permanentemente. Si instalaste manualmente sin usar el one-liner, ejecuta snapcontext --setup-path para añadir la carpeta al PATH.
• Permisos de ejecución: En Linux/macOS, al instalar con pip install -e . o pip install snapcontext, pip registra el ejecutable en el PATH del usuario de forma automática sin requerir permisos especiales. Si ejecutas snapcontext.py directamente como script en Unix, puedes asignarle permisos de ejecución con chmod +x snapcontext.py.
• Servidor y Navegador: En Linux y macOS, si webbrowser.open() no responde en entornos sin interfaz gráfica o con configuraciones personalizadas, SnapContext usa de forma automática los comandos nativos xdg-open (Linux) u open (macOS) como respaldo sin usar shell=True.
• Manejo de Señales: En Linux/macOS y Windows, la interrupción por teclado (Ctrl+C / SIGINT) o la señal de terminación (SIGTERM en Unix) capturan el evento, cierran limpiamente cualquier subproceso en segundo plano (como flutter run) y salen de forma ordenada con código 0.

Publicación en PyPI

SnapContext está preparado para publicarse en PyPI (el nombre snapcontext está disponible; alternativas: snapcontext-cli, snapcontext-tool). Antes de publicar, edita en pyproject.toml el campo authors (y [project.urls]) con tus datos reales.

Sigue la guía completa en PUBLISHING.md (build + twine):

pip install build twine
python -m build
python -m twine check dist/*
python -m twine upload dist/*
pip install snapcontext   # verificar en un entorno limpio

🙌 Agradecimientos

• Aider por su excelente motor de edición de código.
• Google Gemini por su generoso plan gratuito.
• Ollama, DeepSeek y Groq por sus modelos open-source.
• La comunidad open-source por las herramientas que hacen posible este proyecto.

Licencia

MIT. Open-source y libre de usarlo, estudiarlo y mejorarlo.