pepecode es un agente de codificación interactivo por terminal (CLI) diseñado para funcionar de forma 100% local. Está optimizado específicamente para modelos de lenguaje contenidos (7B-9B parámetros) o modelos de razonamiento ultra-eficientes ejecutándose sobre Ollama o servidores de inferencia locales compatibles con OpenAI (como llama.cpp).
Read this in other languages: English | Español.
For the best balance of speed, tool-calling success, and coding logic on consumer hardware (8GB+ VRAM) using Ollama:
- Google Gemma 4: Highly recommended for low-end hardware or maximum speed. Despite being only 4B parameters, it supports native reasoning (
<think>tokens), image input, and robust tool-calling. Run it with:ollama run gemma4(orollama run gemma4:4b). - Qwen3.5 9B / Qwen3-Coder-Next: The consensus choice for deep codebase editing and multi-file logic. It has excellent tool-calling and code intelligence. Run it with:
ollama run qwen3.5:9borollama run qwen3.5:latest.
- Dual-Step Reasoning loop: Forces the LLM to structure its output into a
<think>block (concept analysis and planning) before executing tools. - Resilient JSON Repairing: Solves the typical hallucination and formatting errors of local models using dynamic regex fallback parsing and
json-repair. - Dynamic AST File Map (Smart Context): Scans your repository using Python's native AST parser, injecting a lightweight hierarchy of classes, methods, and functions into the system prompt.
- Model Context Protocol (MCP) Support: Natively connects to any local stdio MCP server (e.g. databases, search engines, APIs) dynamically registering remote tools.
- Automatic Verifier Pipeline: Runs syntax checking and code linters (
ruffandmypyif available) immediately after any edit. - Flexible Skills Loading: Automatically crawls and loads local directory conventions from
.agentrules,AGENTS.mdor.cursorrules.
Make sure your Ollama instance is running and has the target model ready.
# Runs automatically with your default/first Ollama model:
npx pepecode
# Or specify any Ollama model you want:
npx pepecode --model gemma4If you prefer to clone and run the package locally using Python/uv:
-
Clone the repository and enter the directory:
git clone https://github.com/moisesvalero/pepecode.git cd pepecode -
Create a virtual environment and install the package:
uv venv --python 3.10 source .venv/bin/activate uv pip install -e .
Installing the package locally registers the executable command pepecode (or local-agent) in your environment.
You can connect pepecode to any external stdio-compatible Model Context Protocol (MCP) server (such as databases, search engines, or custom APIs) to dynamically load remote tools:
npx pepecode --mcp-server "npx" --mcp-args "-y @modelcontextprotocol/server-everything"Para obtener el mejor equilibrio entre velocidad, éxito en la llamada de herramientas (tool-calling) y razonamiento lógico en GPUs de consumo (8GB+ VRAM) usando Ollama:
- Google Gemma 4: Muy recomendado para hardware de entrada o máxima rapidez. A pesar de sus 4B parámetros, cuenta con soporte nativo de razonamiento (tokens
<think>), entrada de imágenes y llamadas a herramientas muy robustas. Ejecútalo con:ollama run gemma4(oollama run gemma4:4b). - Qwen3.5 9B / Qwen3-Coder-Next: La opción de consenso para edición profunda de código y lógica multi-archivo. Ofrece capacidades lógicas y de tool-calling excelentes. Ejecútalo con:
ollama run qwen3.5:9boollama run qwen3.5:latest.
- Bucle de Razonamiento en dos pasos: Fuerza al LLM a explicar su plan detallado en un bloque
<think>antes de proponer cambios de código o invocar herramientas. - Parser de JSON Resiliente: Soluciona los errores comunes de sintaxis JSON de modelos de 7B-9B mediante un parseador secundario basado en expresiones regulares y la librería
json-repair. - Mapa de archivos basado en AST: Analiza de forma nativa el repositorio usando el módulo
astde Python, construyendo un mapa de clases, métodos, firmas de funciones y docstrings en el system prompt. - Soporte Nativo de MCP (Model Context Protocol): Se conecta a cualquier servidor local stdio de MCP de forma dinámica, registrando herramientas remotas en el agente.
- Verificador de Código Automático: Valida la sintaxis del código de Python tras cada escritura. Llama automáticamente a
ruffymypysi están instalados en el host. - Carga de Reglas Locales (Skills): Detecta y lee de forma recursiva archivos
.agentrules,AGENTS.mdo.cursorrulesinyectándolos en el prompt de sistema.
Asegúrate de que tu servidor de Ollama esté corriendo.
# Se ejecuta automáticamente con tu primer modelo de Ollama:
npx pepecode
# O especifica el modelo de Ollama que tú quieras:
npx pepecode --model gemma4Si prefieres clonar y ejecutar el paquete en local usando Python/uv:
-
Clona el repositorio e ingresa en él:
git clone https://github.com/moisesvalero/pepecode.git cd pepecode -
Crea el entorno virtual e instala las dependencias:
uv venv --python 3.10 source .venv/bin/activate uv pip install -e .
La instalación del paquete registra de forma automática el comando ejecutable pepecode (o local-agent) en tu terminal.
Puedes conectar pepecode a cualquier servidor externo compatible con Model Context Protocol (MCP) que funcione mediante stdio (como bases de datos, motores de búsqueda o APIs personalizadas) para registrar herramientas remotas de forma dinámica:
npx pepecode --mcp-server "npx" --mcp-args "-y @modelcontextprotocol/server-everything"Distributed under the MIT License. See LICENSE for more information.