TukiCode Docs

Instalación

Windows — PowerShell 5.1+

macOS y Linux — bash / zsh

Instala tuki en ~/.local/bin y actualiza tu perfil de shell automáticamente. En macOS, si el sistema bloquea el binario en el primer uso: xattr -d com.apple.quarantine ~/.local/bin/tuki

Configuración

Después de la instalación, necesitas configurar qué modelo de IA usará TukiCode. Ejecuta el siguiente comando para iniciar el asistente de configuración:

Esto iniciará un asistente de configuración interactivo donde podrás:

1. Seleccionar tu proveedor de IA: Elige entre Ollama, OpenRouter, Anthropic o Google (Gemini).
2. Ingresar el nombre del modelo: Escribe el identificador específico del modelo (ej. tencent/hy3-preview:free).
3. Proporcionar tu API key: Si seleccionaste un proveedor en la nube, pega tu API key de forma segura. TukiCode la encripta y guarda localmente.
4. Configurar Ajustes Avanzados: (Opcional) Ajusta el tamaño de la ventana de contexto y el límite máximo de tokens dependiendo de las capacidades del modelo elegido.

Para OpenRouter, puedes usar una sola API key para todos los modelos soportados, incluyendo los gratuitos.

TukiCode está diseñado para funcionar con modelos que soporten tool-calling nativo. Esto es fundamental para el comportamiento correcto del agente, incluyendo operaciones de archivos, ejecución de comandos y razonamiento multipaso.

Modelos gratuitos recomendados (con soporte para tool-calling):

• tencent/hy3-preview:free (recomendado)
• moonshotai/kimi-k2.5
• zhipu/glm-4.6
• deepseek/deepseek-chat-v3.2

Recomendamos encarecidamente usar: tencent/hy3-preview:free para obtener el mejor equilibrio entre rendimiento, fiabilidad y ejecución de herramientas en entornos gratuitos.

Comparación de Modos

Modo	Pipeline	Confirmación	Ideal para
Chat	AgentLoop directamente	Por herramienta (según autonomía)	Preguntas, arreglos rápidos, explicaciones
Plan	Planner → muestra pasos → confirma → Executor	Siempre pide antes de ejecutar	Tareas de varios pasos que quieres revisar primero
Build	Planner → muestra pasos → Executor	Sin confirmación — arranca inmediatamente	Generación autónoma de proyectos completos

Chat Mode (Por defecto)

La interfaz conversacional estándar. Tu mensaje entra directamente al loop ReAct: el agente piensa, llama herramientas, observa los resultados y repite hasta tener una respuesta completa. No se genera ningún plan estructurado — el modelo decide cada acción en tiempo real según lo que va descubriendo.

Ideal para: preguntas, explicaciones de código o tareas rápidas y aisladas.

• Punto de entrada: AgentLoop.run_turn()
• Planificación: Ninguna (el modelo razona internamente en tags <thinking>)
• Confirmación: Controlada por tu nivel de /autonomy

Plan Mode

Para tareas complejas, el Plan Mode usa un módulo Planner dedicado para descomponer tu pedido en una lista numerada de pasos atómicos antes de escribir una sola línea de código. Tú revisas y apruebas el plan; solo entonces el Executor ejecuta cada paso.

Ejemplo: "Refactorizar el módulo de autenticación para usar JWT."

1. Tu mensaje se envía a Planner.generate_plan(), que llama al LLM y recibe un array JSON estructurado de pasos.
2. El plan completo se muestra en el chat.
3. El agente se pausa y pregunta: "¿Deseas ejecutar este plan? (y/n)"
4. Si confirmas, Executor.execute_plan() ejecuta cada paso secuencialmente via el AgentLoop, con reintentos automáticos y cambio de modelo en caso de fallo.

(Demostración del Plan Mode creando y ejecutando pasos)

Build Mode

El Build Mode está diseñado para la generación autónoma y completa de proyectos. Sigue el mismo pipeline del Plan Mode, pero omite el paso de confirmación — el agente te muestra el plan y comienza a ejecutar de inmediato.

También soporta reanudación de plan: si una build anterior fue interrumpida, el Build Mode continúa desde el último paso pendiente automáticamente.

1. Si hay pasos pendientes en planner_state.json (de una sesión anterior), la ejecución se reanuda desde donde quedó.
2. Si no hay plan previo, Planner.generate_plan() se invoca automáticamente. El plan generado se muestra en el chat antes de comenzar.
3. Executor.execute_plan() arranca inmediatamente — sin pedir confirmación.

Build vs Plan: Usa Plan cuando quieras revisar y aprobar la estrategia antes de que se ejecute nada. Usa Build cuando confíes en el agente y prefieras velocidad — igual verás el plan, pero la ejecución comienza de inmediato.

Sistema de Autonomía de Tres Niveles

TukiCode te da control total sobre el proceso de toma de decisiones del agente. Ajusta el nivel de autonomía con /autonomy:

Explorador de Proyectos Interactivo

TukiCode incluye un árbol de directorios en vivo en el panel izquierdo de la interfaz de terminal:

• Contexto Visual: Siempre ve exactamente dónde estás en la estructura de tu proyecto.
• Selección Inteligente: Al hacer clic en cualquier archivo del árbol, le indica instantáneamente al agente que lo lea y analice— la forma más rápida de alimentar contexto sin escribir rutas.

Política de No-Tocar Git

La historia de tu proyecto te pertenece. TukiCode está codificado para ignorar cualquier comando relacionado con .git. Nunca inicializará, hará commit o push de cambios. Esto asegura que tu control de versiones se mantenga limpio y estrictamente manual.

Modelos recomendados

Ollama (Local) — Sin límites, sin costos, sin internet

Ollama es la opción ideal para TukiCode porque no tiene rate limits, funciona offline, es completamente privado y no tiene costo por token.

Modelo	RAM requerida	VRAM requerida	Velocidad estimada
qwen2.5-coder:7b	8GB RAM	6GB VRAM	~50-70 tok/s en RTX 3060
qwen2.5-coder:14b	16GB RAM	10GB VRAM	~40-60 tok/s en RTX 3060
qwen2.5-coder:32b	32GB RAM	20GB VRAM	~20-30 tok/s en RTX 3060

Comandos de instalación:

• ollama pull qwen2.5-coder:7b
• ollama pull qwen2.5-coder:14b
• ollama pull qwen2.5-coder:32b

OpenRouter (Cloud) — Requiere internet y API key

OpenRouter permite usar modelos en la nube, incluyendo modelos gratuitos y de pago. Los modelos gratuitos tienen limitaciones importantes que el usuario debe conocer antes de usarlos.

Modelos gratuitos recomendados para TukiCode:

• tencent/hy3-preview:free — Mejor para agentes, soporta tool calling nativo
• qwen/qwen3-coder-480b:free — El más potente disponible gratis, 262K contexto
• deepseek/deepseek-r1:free — Excelente razonamiento para tareas complejas
• meta-llama/llama-3.3-70b-instruct:free — Estable y confiable para tareas simples

Limitaciones importantes de los modelos gratuitos de OpenRouter:

• Rate limits: 20 requests por minuto y 200 requests por día máximo.
• Timeouts frecuentes: En horas pico (horario USA) los modelos pueden tardar más de 60 segundos en responder, causando errores de timeout.
• Disponibilidad variable: Los modelos gratuitos pueden estar saturados o fuera de servicio sin previo aviso.
• Calidad inconsistente: En horas de alta demanda la calidad de las respuestas puede degradarse.
• No recomendado para: Tareas largas como migraciones de proyectos completos, generación de múltiples archivos grandes, o sesiones de trabajo intensivas.

TukiCode tiene un sistema de fallback automático entre modelos gratuitos, pero esto no elimina completamente las interrupciones.

Modelos de pago recomendados via OpenRouter (alta calidad garantizada):

• anthropic/claude-sonnet-4-5 — $3/1M tokens entrada, $15/1M tokens salida
• anthropic/claude-haiku-3-5 — $0.80/1M tokens entrada, $4/1M tokens salida (mejor relación calidad/precio)
• openai/gpt-4o — $2.50/1M tokens entrada, $10/1M tokens salida

Para referencia: una sesión intensa de 30 minutos con TukiCode consume aproximadamente 10,000-40,000 tokens dependiendo de la tarea. Con claude-haiku-3-5 eso equivale a menos de $0.20 USD.

Requisitos de hardware

Para usar TukiCode con Ollama (local)

Mínimo recomendado:

• CPU: 8 núcleos modernos (Intel i7 10th gen+ / AMD Ryzen 5 5000+)
• RAM: 16GB
• GPU: NVIDIA RTX 3060 (12GB VRAM) o equivalente
• Almacenamiento: 20GB libres para modelos

Óptimo:

• CPU: Intel i9 / AMD Ryzen 9 o Apple Silicon
• RAM: 32GB+
• GPU: NVIDIA RTX 3080+ / RTX 4070+ o Apple M1/M2/M3
• Almacenamiento: SSD NVMe con 50GB libres

Apple Silicon (M1/M2/M3/M4):

Mención especial — la memoria unificada de Apple Silicon es ideal para Ollama. Un M1 con 16GB puede correr qwen2.5-coder:14b a ~30-40 tokens/segundo. Un M3 con 16GB es aún mejor. Es probablemente la mejor opción calidad/precio para usar TukiCode con Ollama.

GPUs compatibles verificadas:

• NVIDIA RTX 3060 (12GB) [SÍ] — qwen2.5-coder:14b fluido
• NVIDIA RTX 2060 (8GB) [SÍ] — qwen2.5-coder:7b fluido
• NVIDIA RTX 4070 (12GB) [SÍ] — qwen2.5-coder:32b fluido
• AMD RX 6700 XT (12GB) [SÍ] — compatible con ROCm
• Intel Arc A770 (16GB) [ADVERTENCIA] — soporte experimental
• NVIDIA GTX 1080 (8GB) [ADVERTENCIA] — funciona pero lento
• GPUs con menos de 6GB VRAM [NO] — no recomendado para Ollama

¿Mi PC no tiene GPU dedicada?

Si tu máquina no tiene GPU dedicada o tiene menos de 6GB VRAM, Ollama correrá en CPU y será muy lento (2-5 tokens/segundo). En ese caso, OpenRouter con un modelo de pago como claude-haiku-3-5 es la opción más práctica — rápido, confiable y casi sin costo.

Para usar TukiCode con OpenRouter (cloud)

• Cualquier computador con conexión a internet
• No se requiere GPU
• RAM mínima: 4GB (para correr TukiCode en sí)
• Python 3.10+

¿Qué modelo debo usar?

Situación	Recomendación
Tengo GPU con 6GB+ VRAM	Ollama con qwen2.5-coder:7b o 14b
Tengo Mac con Apple Silicon	Ollama con qwen2.5-coder:14b
No tengo GPU pero quiero gratis	OpenRouter modelos free (con limitaciones)
Quiero la mejor experiencia posible	OpenRouter claude-haiku-3-5 (< $0.20/sesión)
Trabajo en empresa / privacidad crítica	Ollama local obligatorio
Soy estudiante con PC básico	OpenRouter free + paciencia en horas pico

/model — Cambio de Inteligencia

El comando más potente en TukiCode. Cambia entre modelos de IA:

• Sin argumentos: Abre un modal semi-transparente para seleccionar entre modelos Ollama (local), Gemini, Claude u OpenRouter.
• Detección Inteligente: Escribe /model gemini-1.5-pro y el agente se configura automáticamente.
• Auto-Config: Si un modelo en la nube requiere una API key que no has proporcionado, TukiCode muestra una caja de entrada segura para guardarla permanentemente.
• Historial: TukiCode recuerda cada modelo que usas, manteniendo tus favoritos en la parte superior de la lista.

/autonomy — Controla el Agente

Alterna cuánto pide permiso TukiCode. Usa /autonomy high para iteraciones rápidas o /autonomy low cuando quieras revisar cada línea que el agente lee o escribe.

/risk — Gestión de Sensibilidad

Ajusta cómo el agente clasifica el "peligro" de sus herramientas:

• Riesgo Bajo: Operaciones estándar.
• Riesgo Medio/Alto: Comandos que alteran el sistema. TukiCode usa esta configuración para determinar cuándo activar advertencias de seguridad según tu nivel de autonomía actual.

/copy — Exporta tu Código

¿Encontraste la solución perfecta? Escribe /copy para copiar instantáneamente el último bloque de código generado por la IA a tu portapapeles. Pégalo directamente en VS Code, IntelliJ o cualquier editor.

/history — Continuidad del Proyecto

Muestra una lista de tus sesiones más recientes. Te ayuda a hacer seguimiento de lo que has trabajado y mantener contexto a través de diferentes partes de tu ciclo de desarrollo.

/clear y /exit

• /clear: Borra el registro actual del terminal para un entorno libre de distracciones.
• /exit: Guarda tu configuración actual y cierra el agente de forma segura.

Arquitectura Asíncrona

TukiCode opera con un motor asíncrono nativo (httpx y asyncio). Esto garantiza que la terminal siga siendo increíblemente rápida y no se bloquee, incluso al generar textos con LLM en segundo plano o al ejecutar grandes procesos de shell concurrentemente.

Lógica ReAct: Cómo "Piensa" TukiCode

A diferencia de los chatbots simples, TukiCode sigue una lógica técnica ReAct:

Arquitectura Asíncrona

TukiCode opera con un motor asíncrono nativo (httpx y asyncio). Esto garantiza que la terminal siga siendo increíblemente rápida y no se bloquee, incluso al generar textos con LLM en segundo plano o al ejecutar grandes procesos de shell concurrentemente. Más detalles en TukiCode GitHub .