SnapContext

SnapContext es un asistente de IA con contexto automático para desarrollo: detecta el tipo de proyecto, selecciona los archivos relevantes con IA, ejecuta tareas con Aider, planifica trabajos complejos y aprende del proyecto mediante una memoria persistente (CLAUDE.md).

• Proveedores: Gemini · Claude (Anthropic) · Ollama (local) · DeepSeek · Groq
• Arquitectura: orquestador + agentes (Contexto / Editor / Tester)
• Seguridad: permisos con confirmaciones (~/.snapcontext/permisos.json)

📦 Instalación

# Linux / macOS (one-liner)
curl -fsSL https://raw.githubusercontent.com/NicolasBruna24/snapcontext/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/NicolasBruna24/snapcontext/main/install.ps1 | iex

O manualmente:

pip install snapcontext                 # base
pip install "snapcontext[embeddings]"   # búsqueda semántica local (opcional)
pip install "snapcontext[anthropic]"    # Claude
pip install "snapcontext[web]"          # interfaz web (--web)
pip install aider-chat                  # ediciones de código
snapcontext --init                      # asistente inicial + API key

🚀 Inicio rápido (5 minutos)

# 1. Tarea directa con editor integrado propio
snapcontext "arregla el botón de pago" --editor propio

# 2. Planificador autónomo
snapcontext plan "añadir validación al formulario" --auto

# 3. Chat interactivo
snapcontext --chat

# 4. Interfaz web completa
snapcontext interactive  # o snapcontext --web

Auto-detección de proyecto (Flutter, Node/React, Python, Go, Rust…) que ajusta carpetas, extensiones y comandos de test por defecto.

🛠️ Editor Integrado Propio (v2.2.0)

SnapContext incluye su propio editor integrado con soporte de parches unificados y edición basada en AST (Árbol Sintáctico) para refactorizaciones precisas:

• --editor propio: Aplica cambios directamente y crea copias de seguridad automáticas en ~/.snapcontext/backups/.
• --modo-edicion {auto,parche,sobrescribir,ast}:
  • auto (por defecto): Genera un parche unificado (git apply / patch), pero para refactorizaciones estructurales intenta primero la edición AST y cae a sobrescritura si nada es aplicable.
  • ast: Edita comprendiendo la estructura sintáctica del archivo (Python con ast, otros lenguajes con tree-sitter si está instalado). Soporta renombrar símbolos, insertar imports y recibir el código completo resultante.
  • parche: Fuerza la aplicación de parches unificados para ediciones precisas.
  • sobrescribir: Sobrescribe el archivo completo.
• --editor aider (por defecto): Mantiene el flujo de edición con Aider para máxima compatibilidad.

# Edición precisa mediante diffs unificados
snapcontext "añadir endpoint de métricas" --editor propio

# Forzar modo parche
snapcontext "corregir tipado en login" --editor propio --modo-edicion parche

# Refactorización estructural con AST
snapcontext "renombrar la variable 'usuario' a 'cuenta'" --editor propio --modo-edicion ast

🧭 Modos y alias

Alias: fix (= --test-loop) · review · server (= --server-loop).

🤖 Modo autónomo (v0.17.0)

Añade --auto al planificador para ejecución sin supervisión:

snapcontext --plan "actualizar dependencias y pasar tests" --auto --no-confirmar
snapcontext --plan "refactorizar el módulo de pagos" --auto   # con permisos guardados

• Salta la confirmación del plan y el menú paso a paso.
• Cada paso fallido se reintenta automáticamente hasta 3 veces; si sigue fallando, continúa con el siguiente y lo refleja en el resumen final.
• Sigue respetando ~/.snapcontext/permisos.json: los tipos marcados como "nunca" se deniegan sin preguntar. Con --no-confirmar no hay diferencia adicional (todas las confirmaciones ya están desactivadas).

🧩 Extensión VS Code (v0.16.0)

SnapContext se integra en VS Code como extensión nativa (vscode/), reutilizando la interfaz web y el orquestador existentes.

Instalación (requiere Node.js y snapcontext instalado en el Python del sistema):

./vscode/scripts/empaquetar.ps1          # genera el .vsix
code --install-extension vscode/snapcontext-vscode-1.0.0.vsix

Comandos (paleta de comandos, prefijo SnapContext:):

Configuración (settings.json): snapcontext.pythonPath, snapcontext.provider, snapcontext.apiKey, snapcontext.confirmar.

Los logs del orquestador aparecen en tiempo real en el canal de salida "SnapContext Output", con el workspace abierto como directorio del proyecto. La webview del chat reutiliza web/static/index.html (copia en vscode/webview/) servida por servidor_webview.py.

📄 Memoria de proyecto (v0.15.0)

SnapContext usa un archivo CLAUDE.md (o SNAPCONTEXT.md) en la raíz del proyecto como memoria persistente: objetivo, tecnologías, estructura, convenciones y comandos útiles. Se carga automáticamente al inicio de cualquier modo y se inyecta como contexto del agente (chat, planificador).

Genera la memoria inicial con:

snapcontext --init-claude     # escanea el proyecto y la redacta con IA

Sin conexión o sin API key, genera una plantilla básica offline que puedes completar a mano. Tras tareas/planes exitosos, SnapContext propone (con tu confirmación) actualizar la memoria con lo aprendido.

En el chat: /claude muestra el contenido; /context muestra memoria + archivos en contexto.

🛠 Herramientas MCP (v0.14.0)

El agente puede usar herramientas externas con resultados estructurados:

En el chat:

/tools                          # listar herramientas disponibles
/tool grep login                # forzar una búsqueda
/tool read_file lib/login.dart  # leer un archivo
/tool execute_command flutter test   # pide confirmación (🔒)

Además, mensajes como "busca donde se usa checkout" o "¿cuál es el estado de git?" hacen que el agente ejecute automáticamente las herramientas de lectura pertinentes y use su salida como contexto para responder. Puedes definir tus propias herramientas en ~/.snapcontext/mcp_tools.json:

{"tools": [{"nombre": "build", "descripcion": "Compilar el proyecto",
            "comando": "npm run build", "requiere_permiso": true}]}

El planificador (--plan) también usa estas herramientas de solo lectura para explorar el proyecto antes de proponer pasos.

🔒 Permisos y confirmaciones (v0.13.0)

Por defecto SnapContext pide permiso antes de acciones sensibles:

• Pasos del planificador (--plan): editar, ejecutar y consultar.
• Comandos /run y /edit del chat.

Pregunta ¿Permitir esta acción? (s/n/t/a) con estas opciones:

Las preferencias se guardan en ~/.snapcontext/permisos.json. Para volver a que pregunte, borra ese archivo o usa --init. Para modo automático (CI, scripts) desactiva todas las preguntas con --no-confirmar:

snapcontext --plan "tarea" --no-confirmar

🗺️ 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|mcp",
    "archivos": ["..."], "comando": "...",
    "dependencias": [1, 2],
    "condicion": "archivo_existe('src/main.py')"}
   

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 y mcp (v2.3.0) ejecuta una herramienta MCP guardando su resultado en el contexto del plan.
4. Tras cada paso eliges: continuar / reintentar / saltar / abortar. Al final hay un resumen que se guarda en historial.json.

Dependencias, condiciones y paralelismo (v1.4.0)

• Dependencias: un paso con "dependencias": [1, 3] solo se ejecuta si los pasos 1 y 3 tuvieron éxito. Si alguno falló o se saltó, el paso queda como saltado.

• Condiciones: campo "condicion" con una de estas funciones:

  • archivo_existe('src/main.py')
  • archivo_contiene('src/main.py', 'def main')
  • comando_exito('flutter test')
  • variable_existe('mi_variable') (v2.3.0)

  Además, desde v2.3.0 acepta comparaciones dinámicas con resultados de pasos previos o variables dejadas en el contexto (por pasos mcp):

  {"condicion": "pasos[0].resultado == 'ok'"}
  {"condicion": "resultados.mi_variable != ''"}
  

  Si la condición es falsa, el paso se salta (con aviso) y el plan continúa.

Pasos MCP y contexto dinámico (v2.3.0)

Un paso con "accion": "mcp" ejecuta una herramienta MCP del registro (grep, read_file, list_files, ast, git_status, git_diff, execute_command, ...) usando los campos "herramienta" y "args". El resultado queda disponible para los pasos posteriores:

 {"descripcion": "buscar referencias", "accion": "mcp",
  "herramienta": "grep", "args": {"patron": "def main"},
  "variable": "coincidencias"}
 {"descripcion": "usar resultado", "accion": "ejecutar",
  "comando": "echo {{coincidencias}}"}

• El resultado siempre se guarda también como {{resultado}}; si el paso define "variable", se guarda bajo ese nombre.

• execute_command soporta background=true (devuelve un pid consultable con execute_command_status) y capture_output=false para mostrar la salida en tiempo real.

• Paralelismo: con --paralelo N (junto a --auto) se ejecutan hasta N pasos independientes a la vez; los logs llevan el identificador [paso N]. Desde v2.3.0 el planificador también respeta las dependencias dinámicas: un paso cuya condición usa una variable que otro paso aún no ha producido espera a que esté disponible:

  snapcontext --plan "tarea grande" --auto --paralelo 3 --no-confirmar
  

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), /search <consulta> (búsqueda semántica de archivos), /buscar <consulta> (alias de /search), /grafo (grafo de dependencias en ASCII), /dependencias <archivo> (imports y dependencias inversas), /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.

📚 Casos de uso

Flutter

snapcontext "el botón de pago no actualiza el total" --test-loop
snapcontext fix "el widget de login no muestra errores"
snapcontext review "revisa la navegación del carrito"

Detecta pubspec.yaml, escanea lib/ y test/, y ejecuta flutter test en bucle hasta que pasen.

React / Node

snapcontext --provider anthropic "el formulario no valida el email"
snapcontext plan "migrar componentes a hooks" --branch refactor/hooks --auto

Detecta package.json, escanea src/, y respeta las convenciones anotadas en tu CLAUDE.md.

Python

snapcontext "añade tests para el módulo de pagos"
snapcontext --init-claude      # genera la memoria del proyecto
snapcontext --chat             # /tool ast pagos.py · /tool git_status

Detecta pyproject.toml / requirements.txt y usa pytest como test por defecto.

CI / automatización

snapcontext --plan "corregir tests rotos" --local --no-confirmar --auto

Sin claves (--local usa heurística local) y sin preguntas interactivas.

🤝 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 con el instalador .exe (Windows, sin Python) — v1.5.0

Desde la v1.5.0, en Windows puedes instalar SnapContext sin necesidad de Python con el instalador gráfico:

1. Descarga SnapContext-Setup-<versión>.exe desde GitHub Releases.

2. Ejecútalo: instala en %LOCALAPPDATA%\Programs\SnapContext, añade la carpeta al PATH del usuario y (opcional) crea accesos directos en el Menú Inicio y el Escritorio.

3. Abre una terminal nueva y comprueba:

   snapcontext --version
   snapcontext --demo          # demo sin API key ni Aider
   

El instalador incluye un desinstalador (Panel de control → Aplicaciones o Uninstall.exe en la carpeta de instalación); tu configuración (~\.snapcontext) se conserva.

Notas: el .exe incluye las dependencias ligeras (Gemini/OpenAI, menú interactivo e interfaz web). Los extras pesados (embeddings con sentence-transformers y análisis con tree-sitter) quedan fuera para mantenerlo ligero; si los necesitas, instala la versión Python con pip install snapcontext[embeddings,mcp_avanzado]. Aider (modo edición) se instala aparte: pip install aider-chat.

Regenerar el instalador (mantenedores)

Requisitos: Python 3.9+ con las dependencias del proyecto, pip install pyinstaller y NSIS en el PATH.

.\scripts\empaquetar_exe.ps1          # genera dist\SnapContext-Setup-<versión>.exe
.\scripts\empaquetar_exe.ps1 -Full    # incluye sentence-transformers + tree-sitter

El script ejecuta pyinstaller snapcontext.spec, verifica que el ejecutable responde a --version y después compila installer.nsi con makensis.

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).

🚀 Empezar un proyecto desde cero

¿Carpeta vacía? No hay problema. Desde la v1.3.0 SnapContext puede trabajar en carpetas nuevas o casi vacías:

mkdir mi-app && cd mi-app
snapcontext "crear la estructura inicial de un backend con FastAPI" --iniciar-proyecto

• --iniciar-proyecto (alias --no-validar): omite por completo la validación de carpeta. Ideal para empezar un proyecto desde cero. Muestra el aviso: ⚠️ Modo iniciar-proyecto: se omite la validación de carpeta. Asegúrate de estar en el directorio correcto.

• --local: trabaja sin IA y también desactiva la validación:

  snapcontext "listar archivos del proyecto" --local --vista-previa
  

• --directorio <ruta> explícito: si indicas la carpeta a mano, solo se muestra un aviso (no se bloquea).

• Además, desde v1.3.0 la validación acepta carpetas típicas vacías (lib/, src/, supabase/, app/, packages/, backend/), archivos de código vacíos en la raíz (main.py, main.dart, index.js, ...) y archivos de configuración vacíos (pubspec.yaml, package.json, pyproject.toml, ...). Basta con crear uno para que SnapContext te deje trabajar.

SnapContext puede crear archivos desde cero: Aider escribe los ficheros nuevos que la tarea requiera, incluso en una carpeta que antes estaba vacía.

Validación de carpeta de proyecto

Al iniciar, SnapContext comprueba que el directorio tenga indicios de ser un proyecto (v1.3.0): alguna carpeta típica (lib/, src/, supabase/, app/, packages/, backend/) —aunque esté vacía—, algún archivo de código en la raíz —aunque esté vacío— o algún archivo de configuración típico (pubspec.yaml, package.json, requirements.txt, go.mod, Cargo.toml, setup.py, pyproject.toml). Si no encuentra nada:

• Con --iniciar-proyecto, --local o --directorio <ruta> explícito → solo avisa y continúa.
• Sin ninguno de esos flags → error con sugerencias (código 1):

⚠️ No se detectó una carpeta de proyecto típica (lib/, src/, supabase/, etc.).
Si estás empezando un proyecto desde cero, usa --iniciar-proyecto para saltar esta validación.
O usa --local para trabajar sin IA (también desactiva la validación).
También puedes indicar la carpeta con --directorio <ruta>.

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.

🧠 Extensión para IntelliJ IDEA / PyCharm (v1.7.0)

SnapContext también vive dentro del ecosistema JetBrains (IntelliJ IDEA, PyCharm, WebStorm…) con una extensión en Kotlin ubicada en jetbrains/.

Funcionalidades

La salida se muestra en tiempo real en la herramienta inferior «SnapContext» con barra de progreso cancelable.

Instalación (desde código fuente)

Requisitos: JDK 17+ y conexión a Internet (Gradle descarga el SDK de IntelliJ Community la primera vez).

cd jetbrains
./gradlew buildPlugin        # genera build/distributions/snapcontext-jetbrains-1.7.0.zip
./gradlew runIde             # o prueba el plugin en un IDE sandbox

Para instalar el .zip: Settings → Plugins → ⚙ → Install Plugin from Disk…

Configuración

Settings → Tools → SnapContext:

• Comando: cómo invocar SnapContext (python -m snapcontext por defecto; usa snapcontext si tienes el ejecutable/instalador .exe).
• Proveedor: equivalente a --provider (vacío = el guardado en config).
• Confirmar: desactívalo para pasar --no-confirmar.
• Clave API: opcional; se exporta como GEMINI_API_KEY (y equivalentes).

Nota: el plugin llama a la CLI de SnapContext con ProcessBuilder; no requiere Python embebido ni dependencias adicionales.

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.

🎨 Interfaz web avanzada (v1.6.0)

La web añade un editor de código, un grafo de dependencias y un panel de acciones rápidas para competir con interfaces como las de Claude Code. La UI ahora se organiza en dos columnas: editor + dependencias (izquierda) y progreso + resultados (derecha).

📝 Editor de código (Monaco)

• Monaco Editor (el mismo editor que VS Code) se carga desde CDN (cdnjs) y muestra el contenido de los archivos seleccionados con resaltado de sintaxis para Python, JavaScript, TypeScript, Dart, Go, Rust, Java, C/C++, C#, Swift, etc.
• Edición en vivo con guardado manual (botón Guardar) que escribe el archivo en el proyecto vía WebSocket.
• Fallback limpio: si Monaco no carga (sin red o CSP), se usa un <textarea> funcional, así la web sigue operando.
• Abrir el archivo:
  • Haz clic en cualquier archivo del panel Resultados → se abre en el editor.
  • Los nodos del grafo de dependencias también abren el archivo al hacer clic.
  • En --chat el comando /edit <archivo> sigue abriendo el editor externo; ahora además se puede abrir cada archivo directamente desde la web.

🔗 Visualización de dependencias

• Panel con pestaña Dependencias que dibuja un grafo interactivo (force-directed con d3.js) de los archivos del proyecto.
• Las aristas provienen de los imports reales del código (Python import, JS/TS import/require, Dart import, Go import, Rust use, …), resueltos contra los archivos del repositorio.
• Interactivo (ampliado en v1.6.0): zoom y pan con la rueda (d3.zoom, 0.2–4×), arrastre de nodos, clic para abrir el archivo en el editor y doble clic para resaltar rutas: las conexiones directas del nodo se pintan en verde y el resto se atenúa (doble clic en el fondo limpia).
• Filtros (v1.6.0): por lenguaje (select poblado con los lenguajes presentes en el proyecto) y por nivel de dependencia respecto al archivo abierto — «todos», «1 (directos)», «≤2», «≤3» (BFS).
• Tooltips por nodo con ruta completa, lenguaje y nivel.
• Si d3 no carga, se muestra una lista de <origen → destino>.

⚡ Panel de acciones rápidas

Todos los botones tienen tooltip descriptivo con lo que hacen.

✨ UX (v1.6.0)

• Guardar con confirmación: 💾 Guardar o Ctrl+S pide confirmación antes de sobrescribir el archivo en disco.
• Notificaciones toast (info/ok/aviso/error) para selecciones, guardados, errores de conexión y acciones.
• Historial de sesión: las últimas tareas ejecutadas; clic para reutilizar la consulta en el campo principal.
• Resultados mejorados: ruta completa visible + botón «Abrir» por archivo.
• Atajos de teclado: Ctrl+Enter ejecutar · Ctrl+S guardar · Ctrl+D pestaña Dependencias · Ctrl+R/Ctrl+O modal de comandos · Esc cerrar modales.

🔌 Comunicación con el orquestador (WebSockets)

El servidor (web/app.py) amplía el protocolo del endpoint /ws:

• archivo_seleccionado → contenido + lenguaje para el editor.
• archivo_guardado → confirmación de escritura en disco.
• dependencias_actualizadas → nodos + enlaces del grafo.
• semanticos / exploracion → resultados de búsqueda.
• accion_ejecutada → cierre de cada acción rápida.
• tarea (o el consulta clásico) → pipeline del orquestador como siempre.

La CLI y la extensión VS Code no se ven afectadas; la webview de VS Code sigue siendo una copia de web/static/index.html (vscode/webview/), y si el entorno de la webview bloquea los CDN se usa el respaldo sin romper nada.

🧠 Búsqueda semántica con embeddings (v1.1.0)

SnapContext puede indexar tu proyecto con embeddings semánticos locales usando sentence-transformers + torch (modelo all-MiniLM-L6-v2). Esto permite buscar archivos por su significado —no solo por palabras clave— mejorando drásticamente la selección de contexto y acercándose a la calidad de Claude Code.

Instalación

pip install "snapcontext[embeddings]"   # incluye sentence-transformers + torch

Opcional: sin este extra, SnapContext funciona exactamente como v1.0.0 (heurística + selección con IA). La búsqueda semántica se activa de forma automática solo cuando la librería está disponible.

Cómo funciona

1. Indexación: al primer uso (o cuando cambia el proyecto), SnapContext escanea recursivamente los archivos de código (.py, .js, .ts, .dart, .go, .rs, …), respetando .gitignore, divide cada archivo en fragmentos de ~512 tokens y genera embeddings para cada uno.
2. Caché persistente: el índice se guarda en ~/.snapcontext/index/. SnapContext almacena un hash del proyecto y, si detecta cambios, reindexa automáticamente (con aviso). Los archivos sin cambios reutilizan sus embeddings cacheados —solo se recomputan los fragmentos nuevos o modificados.
3. Búsqueda: en cada ejecución, SnapContext genera un embedding de la consulta, calcula la similitud de coseno con todos los fragmentos y prioriza los archivos más relevantes.

Uso en el pipeline

Durante snapcontext "<consulta>" (o --plan, --chat, etc.), si está el extra de embeddings y hay más candidatos que max_archivos, SnapContext:

1. Carga (o indexa) el proyecto.
2. Ejecuta _seleccionar_archivos_con_embeddings() para obtener los archivos más similares a la consulta (umbral configurable, por defecto 0.6).
3. Reordena los candidatos locales poniendo primero los archivos priorizados por embeddings, de modo que el proveedor de IA refine sobre un subconjunto de alta calidad.

Esto reduce drásticamente el número de llamadas al proveedor y mejora la precisión de la selección final.

Búsqueda desde el chat (--chat)

En modo chat interactivo, el comando /search <consulta> ejecuta una búsqueda semántica y muestra los archivos más relevantes con su puntuación:

snapcontext --chat
/search botón de pago no funciona
📄 lib/pagos/pago_service.dart  (similitud: 0.89)
📄 lib/ui/pago_form.dart        (similitud: 0.76)
📄 test/pago_test.dart          (similitud: 0.65)

Uso directo desde Python

import snapcontext as sc

if sc._embeddings_disponibles():
    resultados = sc._buscar_semanticamente("gestión de usuarios", directorio=".")
    for r in resultados:
        print(r["archivo"], r["similitud"])

    archivos = sc._seleccionar_archivos_con_embeddings(
        "gestión de usuarios", directorio=".", max_archivos=3, umbral=0.6
    )
    print(archivos)

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.