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 su editor propio (o Aider), planifica trabajos complejos y aprende del proyecto mediante una memoria persistente (CLAUDE.md).

• Proveedores: Gemini · Claude (Anthropic) · Ollama (local) · DeepSeek · Groq · OpenAI-compatible · Intel XPU (Arc B-series)
• Arquitectura: orquestador + agentes (Contexto / Editor / Tester)
• Seguridad: permisos con confirmaciones (~/.snapcontext/permisos.json), sandboxing Docker y validación de rutas

🌐 Landing page: https://nicolasbruna24.github.io/snapcontext/ 📦 Marketplaces: PyPI · extensión VS Code ("SnapContext AI") · plugin JetBrains (IntelliJ/PyCharm). Guía de publicación: docs/RELEASE.md.

🚀 Quick Start (30 segundos)

Opción 1: pipx (recomendado — aislado, sin conflictos de dependencias)

pipx install snapcontext
snapcontext --demo                      # ¡Prueba sin API key!

Opción 2: pip

pip install snapcontext
snapcontext --demo                      # ¡Prueba sin API key!

Opción 3: Desde el código fuente

git clone https://github.com/NicolasBruna24/snapcontext
cd snapcontext
pip install -e ".[all]"
snapcontext --demo

La demo muestra las funcionalidades clave en < 30 segundos, sin necesidad de API key ni configuración previa. Si tienes Ollama corriendo localmente, la demo lo detecta automáticamente para una experiencia más realista.

Para empezar a usar SnapContext con tu propio proyecto:

snapcontext --init                      # asistente inicial: proveedor + API key
snapcontext "describe este proyecto"    # primera consulta

Con tu proyecto detectado automáticamente, ya puedes pedir tareas:

snapcontext "el botón de pago no actualiza el total" --test-loop
snapcontext --plan "migrar los componentes de clases a hooks"

📊 Benchmark de edición

SnapContext se evalúa con una suite de 50 tareas reproducibles para medir objetivamente la fiabilidad del motor de edición.

Resultados

Nota: Los números de Aider/Claude Code provienen de SWE-bench (issues reales de GitHub). Nuestro benchmark usa tareas sintéticas con verificación por AST. El modo light mide el motor de edición; el modo deep (pendiente) medirá el agente completo con LLM local.

Reproducir:

# Modo light (sin API key, ~0.5s)
python benchmarks/runner.py --modo=light

# Modo deep (requiere Ollama)
ollama pull qwen2.5:0.5b
python benchmarks/runner.py --modo=deep

Los resultados detallados se guardan en benchmarks/results.json. Más información en benchmarks/README.md.

✨ Características

📦 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[db]"           # bases de datos (PostgreSQL/MySQL)
pip install "snapcontext[embeddings]"   # búsqueda semántica local (opcional)
pip install "snapcontext[anthropic]"    # Claude
pip install "snapcontext[lsp]"          # servidores LSP de Python (--lsp)
pip install "snapcontext[web]"          # interfaz web (--web)
pip install aider-chat                  # ediciones de código (opcional)

snapcontext --init                      # asistente inicial + API key

También hay instalador .exe para Windows sin Python, y una extensión para VS Code (carpeta vscode/).

🔧 Configuración

Todo vive en ~/.snapcontext/:

• config.json — proveedor, modelo, claves API y preferencias.
• permisos.json — acciones aprobadas/rechazadas por el usuario.
• CLAUDE.md — memoria del proyecto (se genera con --init-claude).

Variables de entorno

Claves API (también configurables con --init): GEMINI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY, GROQ_API_KEY.

🛡️ Robustez (degradación elegante)

Si el servidor LSP no está disponible o falla, SnapContext degrada automáticamente a búsqueda por expresiones regulares (y embeddings sintácticos ligeros) sin interrumpir el flujo ni mostrar tracebacks. La indexación del Graph RAG se ejecuta en segundo plano, así que el CLI arranca al instante y las consultas usan el modo degradado hasta que el grafo termina de indexarse. Más detalles en docs/GRAPH_RAG_LSP.md.

🎯 Perfiles de prompt optimizados por modelo (Fase 17)

SnapContext detecta el proveedor en uso y aplica un perfil de prompt específico (system_prompt, plantilla de usuario y parámetros como temperature/max_tokens) que explota las fortalezas de cada modelo: Claude razona profundamente (y aprovecha cache_control), Gemini recibe instrucciones claras y directas, y los modelos locales (Ollama/XPU) obtienen contexto e instrucciones reducidos para evitar divagaciones. Si un proveedor no tiene perfil, se usa uno genérico sin romper el flujo.

Puedes personalizar o añadir perfiles sin tocar el código, con la clave prompt_profiles de config.json:

{
  "prompt_profiles": {
    "mistral": {
      "system_prompt": "Sé conciso.",
      "user_prompt_template": "Pregunta: {consulta}\n\nContexto: {contexto}",
      "config": {"temperature": 0.5, "max_tokens": 1000}
    }
  }
}

Más detalles en docs/PROMPT_PROFILES.md.

🧪 Intel XPU (Arc B-series) — Fase 18

Soporte oficial para GPUs Intel Arc serie B (Battlemage) — p. ej. la Arc B70 de 32 GB — mediante IPEX-LLM con cuantización low-bit (sym_int4 por defecto) y fallback a IPEX clásico. Es un extra opcional:

pip install "snapcontext[xpu]"
snapcontext "hola" --provider xpu --xpu-model Qwen/Qwen2.5-7B

Si hay una GPU Intel detectable, el CLI te lo sugiere automáticamente al arrancar; si faltan dependencias, el aviso indica el comando exacto. Guía completa (drivers, oneAPI 2025+, solución de problemas): docs/XPU.md.

🧭 Comandos

🧭 Comandos

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

Subcomandos: snapcontext plugin · snapcontext hook list · snapcontext revert <step> · snapcontext curador estado · snapcontext discord setup · snapcontext telegram setup · snapcontext github setup.

Casos de uso rápidos

# Flutter: detecta pubspec.yaml y ejecuta flutter test en bucle
snapcontext "el widget de login no muestra errores" --test-loop

# React/Node con Claude
snapcontext --provider anthropic "el formulario no valida el email"

# Python: añade tests y genera memoria del proyecto
snapcontext "añade tests para el módulo de pagos"
snapcontext --init-claude

# CI / automatización sin claves ni preguntas
snapcontext --plan "corregir tests rotos" --local --no-confirmar --auto

🧩 Módulos y Funcionalidades

🧠 Motor ReAct (por defecto)

El agente razona en bucle: elige herramientas (leer archivo, buscar código, navegar, consultar el grafo…), observa el resultado y ajusta el plan. El razonamiento se puede mostrar con --mostrar-razonamiento.

🤖 Multi-agente en paralelo

Flujo con Arquitecto (plan técnico), Programador (ediciones), QA Tester adversarial (pruebas de hasta 2 iteraciones) y Supervisor. Los sub-agentes independientes se ejecutan con un pool paralelo (--multi-agent).

🐳 Sandboxing con Docker (único)

Detecta comandos peligrosos (_es_comando_peligroso) y los ejecuta dentro de un contenedor efímero (--sandbox) o en una sesión persistente por proyecto (--sandbox-session). Autocuración: si la sesión se corrompe, se recrea.

👁️ Visión y navegador

Capturas de pantalla de la app (Flutter/web) y navegación con Playwright para verificar cambios visualmente o extraer contenido.

🌍 Omnicanalidad

Gateways para Discord, Telegram, web (--web) y TUI (--tui), todos sobre el mismo orquestador.

🔌 MCP nativo

SnapContext incluye un cliente MCP estándar que le permite conectarse a servidores MCP externos (como los que usan Claude Code, Cline o OpenCode) y exponer sus herramientas al agente ReAct.

Herramientas MCP integradas:

• Bases de datos (mcp_tools_db)
• APIs HTTP (mcp_tools_api)
• Navegador (mcp_tools_browser)
• Marketplace de servidores (snapcontext plugin)

Cliente MCP estándar (Fase 3): conecta con servidores MCP de terceros configurando ~/.snapcontext/mcp_servers.json y expone sus herramientas con el prefijo mcp_<servidor>_<herramienta>. Comandos:

snapcontext mcp list                          # lista servidores y herramientas
snapcontext mcp add fs npx -y @modelcontextprotocol/server-filesystem .
snapcontext mcp remove fs                     # elimina un servidor

Documentación completa: docs/MCP.md.

🕸️ Graph RAG y LSP

Grafo de dependencias del código (parser universal + tree-sitter) para contexto expandido, y servidores LSP para símbolos, referencias y tipos — la misma tecnología de Cursor y Claude Code.

⚡ XPU (Intel Arc)

Soporte experimental de aceleración Intel vía OpenVINO/onnx para embeddings y modelos locales (--xpu-model, --xpu-max-tokens, --xpu-temperature).

🗺️ Planificador de tareas

--plan genera un plan multi-paso con dependencias, lo confirma el usuario y se ejecuta paso a paso (o en paralelo). Modo autónomo con --auto: reintentos automáticos (3 por paso) y respetando siempre permisos.json.

🧩 Hooks y plugins

Scripts personalizados en eventos del ciclo de vida (snapcontext hook list, manifiesto hooks.json) y paquetes de plugins instalables.

📝 Git profundo

Commit por paso del plan, diffs interactivos antes de aplicar, backups automáticos del editor y deshacer con snapcontext revert <step>.

💾 Memoria y aprendizaje

Memoria SQLite de decisiones, skills dinámicos, curador proactivo (daemon opcional) y CLAUDE.md como memoria del proyecto.

⚖️ Comparativa

🛠️ Instalación para desarrollo

git clone https://github.com/NicolasBruna24/snapcontext.git
cd snapcontext
pip install -e ".[dev]"     # dependencias de desarrollo (ruff, mypy, pytest-cov)

# Calidad de código (Fase 10)
python -m ruff check .      # linting
python -m ruff format .     # formateo
python -m mypy .            # tipos (configuración básica)
python -m pytest            # tests + cobertura

# Umbral estricto de cobertura (objetivo: 60%)
python -m pytest --cov --cov-fail-under=60

El proyecto se refactoriza por fases desde un monolito (snapcontext.py) hacia módulos independientes: seguridad, instalador, presentacion, configuracion, planificador, permisos, hooks y mcp_tools.

🤝 Contribuir

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. Asegúrate de que pasan ruff check . y pytest.
4. Haz push a la rama y abre el pull request.

❓ FAQ

¿Necesito una API key? No obligatoriamente: --local usa heurísticas y modelos locales (Ollama) sin clave. Para proveedores en la nube, snapcontext --init configura y prueba la clave.

¿Qué modelos locales funcionan? Cualquiera servido por Ollama. Con modelos pequeños se activa automáticamente --modelo-ligero y los prompts se adaptan.

¿Es seguro dejarlo trabajar solo? Las acciones se confirman según ~/.snapcontext/permisos.json, los comandos peligrosos van al sandbox Docker y las escrituras validan que la ruta esté dentro del proyecto. Con --auto se respetan los permisos guardados.

¿Windows, Linux y macOS? Sí, los tres. Hay instaladores one-liner y .exe para Windows.

🗺️ Roadmap

• Limpieza de hallazgos de ruff/mypy restantes y subida de cobertura (Fase 10c).
• Extracción completa del orquestador y de los gateways de omnicanalidad.
• Mejoras del Graph RAG multi-repositorio.
• Estabilización de XPU en más hardware Intel.

📜 Historial de cambios

Todas las versiones y sus cambios están en CHANGELOG.md.

💖 Support the Development

If snapcontext has saved you time, optimized your local workflow, or if you want to support an independent student engineer building the future of local AI agents, please consider sponsoring the project. Your sponsorship directly funds cloud evaluation tokens, testing on alternative hardware architectures (like Intel XPU), and speeds up the development roadmap.

📄 Licencia

SnapContext está licenciado bajo Apache License 2.0 a partir de la versión 6.35.0. Las versiones anteriores (hasta 6.34.19 inclusive) permanecen bajo MIT License (ver LICENSE.MIT).

Este cambio añade protección explícita de patentes, reconocida por los equipos legales de organizaciones empresariales.