snapcontext

SnapContext

PyPI version PyPI VS Code JetBrains CI Python 3.10+ License Plataformas PRs Welcome

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

🌐 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

Métrica SnapContext (light) SnapContext (deep) Aider Claude Code
Tareas 50 50 ~300 ~500
Completadas 50/50 (100%) ⏳ Pendiente ~74% ~77%
Modo Motor de edición Qwen2.5-0.5B (previsto) GPT-4o Claude Opus
Tiempo medio ~0.01s - - -

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

Área Detalle
🧠 Motor ReAct Razonamiento dinámico con herramientas (por defecto desde v5.2.0)
🤖 Multi-agente Arquitecto, Programador, QA Tester adversarial y Supervisor, en paralelo
🐳 Sandbox Docker Único en su categoría: todo comando peligroso se ejecuta en contenedor
👁️ Visión + Navegador Capturas de pantalla y navegación web con Playwright
🌍 Omnicanalidad Discord, Telegram, web y TUI inmersiva (Textual)
🔌 MCP nativo Herramientas DB, API y Browser, con marketplace de servidores
🕸️ Graph RAG + LSP Grafo de dependencias del código y análisis con servidores LSP
⚡ XPU (Intel Arc) Soporte establecido para Arc serie B vía IPEX-LLM; otros escenarios Intel en estabilización
🗺️ Planificador Planes multi-paso con dependencias, paralelismo y modo autónomo
🧩 Hooks y plugins Ciclo de vida, scripts personalizados y snapcontext plugin
📝 Git profundo Commits por paso, diffs interactivos y snapcontext revert
💾 Memoria persistente SQLite + skills + curador proactivo (CLAUDE.md)

📦 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 sentence-transformers       # búsqueda semántica local (opcional)
pip install "anthropic>=0.30.0"         # Claude (proveedor Anthropic)
pip install "snapcontext[web]"          # interfaz web (--web)
pip install aider-chat                  # ediciones de código (opcional)

--lsp utiliza servidores LSP externos ya instalados en PATH (SnapContext no los instala mediante un extra): pyright-langserver/pylsp (Python), typescript-language-server (JS/TS), gopls, rust-analyzer, jdtls, OmniSharp, clangd (ver lsp_client.py). Si no hay servidor disponible, SnapContext degrada al mecanismo alternativo documentado en docs/GRAPH_RAG_LSP.md.

snapcontext --init                      # asistente inicial + API key

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

🧩 JetBrains (IntelliJ IDEA / PyCharm)

Plugin oficial para IntelliJ IDEA, PyCharm y otros IDEs de la plataforma JetBrains: SnapContext en JetBrains Marketplace.

Dentro del IDE puedes ejecutar consultas de SnapContext, planificar tareas (--plan), corregir con bucle de pruebas (--test-loop), abrir la interfaz web (editor + grafo de dependencias), añadir archivos del Project View al contexto y seguir la salida en tiempo real en la consola «SnapContext».

La extensión de VS Code («SnapContext AI») y el plugin de JetBrains son clientes del mismo CLI: ambos necesitan SnapContext instalado.

Desarrollado y mantenido por Nicolás Bruna Fuentealba · nicobrunaf.dev · GitHub · LinkedIn

🔧 Configuración

Todo vive en ~/.snapcontext/:

Variables de entorno

Variable Función
SNAPCONTEXT_PROVIDER Proveedor por defecto (gemini, anthropic, ollama, …)
SNAPCONTEXT_MODELO Modelo por defecto
SNAPCONTEXT_MODO_DEFAULT Modo de operación inicial
SNAPCONTEXT_MOSTRAR_RAZONAMIENTO Mostrar razonamiento del modelo
SNAPCONTEXT_SANDBOX 1 fuerza sandbox Docker; 0 lo desactiva
SNAPCONTEXT_SANDBOX_IMAGE Imagen Docker del sandbox
SNAPCONTEXT_MULTI_AGENT Activa el flujo multi-agente
SNAPCONTEXT_LSP Activa el análisis LSP
SNAPCONTEXT_GRAPH_RAG Activa el Graph RAG
SNAPCONTEXT_INDEX_BG 0 desactiva la indexación del grafo en segundo plano
SNAPCONTEXT_PROMPT_CACHING Prompt caching por capas
SNAPCONTEXT_COMANDO_TEST Comando de pruebas del bucle agéntico
SNAPCONTEXT_MARKETPLACE_INDEX Índice del marketplace MCP

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 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. El soporte para otros escenarios de hardware Intel continúa en estabilización. Guía completa (drivers, oneAPI 2025+, solución de problemas): docs/XPU.md.

🧭 Comandos

🧭 Comandos

Modo Comando
Tarea snapcontext "<consulta>" (+ --test-loop)
Editor propio --editor propio (por defecto, con backups automáticos)
Aider (opcional) --editor aider
Chat interactivo --chat
Planificador --plan "<tarea>"
Autónomo --plan "<tarea>" --auto
TUI inmersiva --tui
Web --web (alias interactive)
API REST --api
Vista previa / revisión --vista-previa · alias review
Memoria e historial --init-claude · --historial / --historial-limpiar
Diagnóstico --diagnostico · --benchmark

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

📁 Escritura segura de archivos (no publicado)

B9.63-A: esta característica pertenece al bloque ## [Unreleased] del CHANGELOG. Todavía no hay release publicada (último tag real: v6.35.3), por lo que no debe describirse como una versión disponible.

Todas las escrituras de archivos dentro del proyecto pasan por utils.escribir_archivo_seguro(), que valida la ruta y abre el descriptor atómicamente (O_NOFOLLOW) para eliminar la ventana TOCTOU. Rechaza symlinks que apuntan fuera del proyecto y rutas con .. que intenten escapar.

Clave relacionada en config.json: ninguna (es comportamiento fijo, no configurable, por seguridad).

🐳 Sandboxing con Docker (default-deny)

Los comandos se clasifican en 3 niveles (sandbox_utils.clasificar_comando):

  1. Allowlist — ejecución directa, fricción cero: comandos sin metacaracteres de shell (|, ;, >, $(...), `, $VAR, …) cuyo binario base está en sandbox_allowlist_binarios.
  2. Sandbox obligatorio — default-deny: todo lo demás (pipes, redirecciones, expansión de variables, binarios fuera de la allowlist) se ejecuta dentro del contenedor, ya sea efímero (--sandbox) o en una sesión persistente por proyecto (--sandbox-session). Autocuración: si la sesión se corrompe, se recrea.
  3. Blocklist legacy — defensa en profundidad: los patrones de alto riesgo (rm -rf /, fork bombs, escrituras a discos, curl | sh…) fuerzan el sandbox y muestran un warning explícito con el motivo exacto.

Nota sobre sandbox_allowlist_binarios (clave del nivel superior de ~/.snapcontext/config.json; ejemplo completo en config.example.json): define qué binarios corren directos sin metacaracteres de shell. Si la defines, sobrescribe por completo la lista por defecto (no hace merge), así que incluye en ella también los binarios de tu stack (p. ej. flutter, dart, cargo, go). Cualquier binario fuera de la lista va al sandbox Docker por defecto; con --no-sandbox se pide confirmación explícita mostrando el motivo, y los procesos en segundo plano sin sandbox se rechazan directamente.

👁️ 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:

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)

Aceleración Intel vía IPEX-LLM para modelos locales, con fallback a IPEX clásico. Para GPUs Intel Arc serie B/Battlemage, la ruta IPEX-LLM requiere ipex-llm>=2.2.0. Consulta la sección Fase 18 y docs/XPU.md para instalación y uso (--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

Característica SnapContext Claude Code Aider Hermes
Contexto automático del proyecto ✅ ✅ ⚠️ manual (repo-map) ⚠️
Sandbox Docker para comandos ✅ ❌ ❌ ⚠️
Planificador multi-paso con dependencias ✅ ✅ ❌ ✅
Modo autónomo con reintentos ✅ ✅ ❌ ⚠️
Multi-agente (QA adversarial) ✅ ⚠️ ❌ ✅
Omnicanalidad (Discord/Telegram/web/TUI) ✅ ❌ ❌ ⚠️
MCP nativo + marketplace ✅ ✅ ❌ ⚠️
Graph RAG + LSP ✅ ✅ ⚠️ ❌
Modelos 100% locales (Ollama) ✅ ❌ ✅ ✅
Git profundo (revert por paso) ✅ ❌ ⚠️ ❌
Visión + navegador integrados ✅ ⚠️ ❌ ⚠️
Open source (MIT) ✅ ❌ ✅ ✅

🛠️ 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

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

This site is open source. Improve this page.