Metadata-Version: 2.4
Name: snapcontext
Version: 6.37.0
Summary: SnapContext: asistente de IA con contexto automático para desarrollo.
Author-email: Nicolás Bruna <nicolasbruna24@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://www.nicobrunaf.dev
Project-URL: Repository, https://github.com/NicolasBruna24/snapcontext
Keywords: ai,assistant,coding,development,ollama,gemini,claude,agent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: LICENSE.MIT
Requires-Dist: google-generativeai>=0.8.3
Requires-Dist: openai>=1.30.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: web
Requires-Dist: fastapi>=0.100.0; extra == "web"
Requires-Dist: uvicorn[standard]>=0.23.0; extra == "web"
Requires-Dist: websockets>=12.0; extra == "web"
Provides-Extra: browser
Requires-Dist: playwright>=1.40.0; extra == "browser"
Provides-Extra: dev
Requires-Dist: ruff>=0.8.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Provides-Extra: db
Requires-Dist: psycopg2-binary>=2.9.0; extra == "db"
Requires-Dist: pymysql>=1.1.0; extra == "db"
Provides-Extra: tui
Requires-Dist: textual>=0.50.0; extra == "tui"
Provides-Extra: xpu
Requires-Dist: torch>=2.5.0; extra == "xpu"
Requires-Dist: intel-extension-for-pytorch>=2.5.0; extra == "xpu"
Requires-Dist: ipex-llm[cpp]>=2.2.0; extra == "xpu"
Requires-Dist: transformers>=4.40.0; extra == "xpu"
Requires-Dist: accelerate>=0.30.0; extra == "xpu"
Provides-Extra: all
Requires-Dist: fastapi>=0.100.0; extra == "all"
Requires-Dist: uvicorn[standard]>=0.23.0; extra == "all"
Requires-Dist: websockets>=12.0; extra == "all"
Requires-Dist: playwright>=1.40.0; extra == "all"
Requires-Dist: psycopg2-binary>=2.9.0; extra == "all"
Requires-Dist: pymysql>=1.1.0; extra == "all"
Requires-Dist: textual>=0.50.0; extra == "all"
Requires-Dist: torch>=2.5.0; extra == "all"
Requires-Dist: intel-extension-for-pytorch>=2.5.0; extra == "all"
Requires-Dist: ipex-llm[cpp]>=2.2.0; extra == "all"
Requires-Dist: transformers>=4.40.0; extra == "all"
Requires-Dist: accelerate>=0.30.0; extra == "all"
Dynamic: license-file

# SnapContext

[![PyPI version](https://img.shields.io/pypi/v/snapcontext.svg)](https://pypi.org/project/snapcontext/)
[![PyPI](https://badge.fury.io/py/snapcontext.svg)](https://pypi.org/project/snapcontext/)
[![VS Code](https://img.shields.io/badge/VS%20Code-Marketplace-0098FF)](https://marketplace.visualstudio.com/)
[![JetBrains](https://img.shields.io/badge/JetBrains-Plugin-000000)](https://plugins.jetbrains.com/plugin/33750-snapcontext)
[![CI](https://img.shields.io/github/actions/workflow/status/NicolasBruna24/snapcontext/python-package.yml?branch=main&label=tests)](https://github.com/NicolasBruna24/snapcontext/actions)
![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
![Plataformas](https://img.shields.io/badge/platform-windows%20%7C%20linux%20%7C%20macOS-lightgrey.svg)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)

> **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](https://pypi.org/project/snapcontext/) · extensión **VS Code** ("SnapContext AI") · plugin **JetBrains** (IntelliJ/PyCharm). Guía de publicación: [`docs/RELEASE.md`](docs/RELEASE.md).

## 🚀 Quick Start (30 segundos)

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

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

### Opción 2: pip

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

### Opción 3: Desde el código fuente

```bash
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:

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

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

```bash
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:**

```bash
# 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`](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

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

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

O manualmente:

```bash
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`](docs/GRAPH_RAG_LSP.md).

```bash
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](https://plugins.jetbrains.com/plugin/33750-snapcontext).

- **Instalación**: en el IDE, `Settings → Plugins → Marketplace`, busca
  **SnapContext** e instálalo (alternativa: descarga el `.zip` desde la ficha y
  usa `Settings → Plugins → ⚙ → Install Plugin from Disk…`).
- **Requisito**: SnapContext instalado en el sistema — `pip install snapcontext`
  (o `pipx install snapcontext`) — o el ejecutable `snapcontext` disponible.
- **Configuración**: `Settings → Tools → SnapContext` (comando del ejecutable,
  proveedor, clave de API opcional y confirmaciones).

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](https://www.nicobrunaf.dev) ·
[GitHub](https://github.com/NicolasBruna24/snapcontext) ·
[LinkedIn](https://www.linkedin.com/in/nicol%C3%A1s-bruna-fuentealba-6086b8410/)


## 🔧 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

| 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`](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`:

```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`](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:

```bash
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](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

```bash
# 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:**
- 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:

```bash
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`](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

```bash
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`](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](https://github.com/sponsors/NicolasBruna24). 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.

