BytIA KODE

Quick install:

curl -fsSL https://raw.githubusercontent.com/asturwebs/BytIA-KODE/main/install.sh | bash

BytIA KODE es un agente de IA para terminal con identidad configurable, fallback automático de providers y skills extensibles. TUI (Textual) + bot de Telegram, sesiones persistentes en SQLite y arquitectura multi-provider con circuit breaker.

TUI con identidad constitucional cargada

Chat con el agente · Temas disponibles

Comandos integrados · Menú rápido (Ctrl+P)

Benchmark: 4.90x speedup async

Nota: Las capturas muestran la TUI. El bot de Telegram comparte la misma base de datos de sesiones (ver Sesiones Persistentes).

Release actual: 0.7.8 · Identidad: YAML · Instalación: uv

Novedades en v0.7.8 — Code Review Fixes

• Allowlist bash ampliada — rg, bat, eza, tokei, shellcheck añadidos. El agente ya no necesita python -c como workaround para búsqueda y análisis de código.
• Race condition fix en kill() — _active_subprocess capturado en variable local antes del check. Elimina ventana de race si callback sobrescribe durante terminate.
• Test: system message preservation — Verifica que role=system sobrevive a compresión de contexto en cualquier posición. Regresión protegida.
• Session metadata persistence — model y token_count se persisten en SQLite tras cada turno del agentic loop.
• 1 test nuevo: system messages survive compression. Total: 145.

Novedades en v0.7.7 — Session Audit Fixes

• Tool Error Memory fix — Hash normalizado: solo command/path, no todo el JSON. Antes, mismo comando con diferente workdir generaba hash distinto → bypass del memory.
• BashTool df en allowlist — Comando read-only para diagnóstico de disco ya disponible directamente.
• BashTool error hints — Mensajes de rechazo incluyen lista de binarios permitidos y hint contextual (cd → usar workdir).
• pytest testpaths — uv run pytest -q ahora recoge los 144 tests (antes 116 de 142).
• Flaky test fix — test_file_write_tool_handles_relative_path resetea _WORKSPACE_ROOT global.
• 2 tests nuevos: hash normalization + security policy blocking. Total: 144.

Novedades en v0.7.6 — HOTFIX v0.7.2 Cierre + Skills Polish

• FIX-3: Tool Error Memory — comandos rechazados (bash, file_write, file_edit) no se reintentan. Hash MD5 de args como key.
• FIX-4: Workspace Context Awareness — CWD, sandbox y trusted paths inyectados en system prompt dinámico.
• YAML multiline parser — description: > (folded scalar) ahora se parsea correctamente en _parse_skill().
• sync-vendor-skills.sh — nuevo script que transforma formato agentskills.io → flat durante sync.
• Vendor skills auto-update — reinstala solo cuando cambia la versión del paquete.
• 9 tests nuevos: 3 loader edge cases + 3 FIX-3 + 3 FIX-4. Total: 142.

Novedades en v0.7.5 — Skills System v2.0

• Skills System Architecture: Sistema de skills reescrito con arquitectura de capas (vendor/user/bytia). Prioridad: bytia > user > vendor.
• Vendor Skills: Skills core incluidas en src/bytia_kode/vendor/skills/: bytia-constitution, bytia-memory, skills-manager, graphify. Se instalan automáticamente.
• Integración BytIA: Si existe ~/bytia/, install.sh ofrece crear symlink para compartir skills.
• 3 tests nuevos: layer priority, bytia highest priority, all layers loaded.

Novedades en v0.7.4 — Provider Resilience Hotfixes

• DeepSeek V4 thinking mode — reasoning_content incluido en todos los mensajes tras tool calls. Adiós al error 400.
• Streaming timeout — 60s por chunk. Si un provider deja de responder sin error, se detecta y se hace failover en lugar de colgarse.
• Cloud polling fix — Solo el router local recibe polling cada 5s. APIs cloud (DeepSeek, MiniMax, Z.ai) ya no son acosadas con requests inútiles.

Novedades en v0.7.3 — Agent Loop Optimizations

• SP cache — system prompt cacheado por número de mensajes (~500ms ahorrados por iteración).
• Router polling — pausado durante procesamiento del agente.
• Batch compression — 5 mensajes comprimidos a la vez, últimos 4 siempre preservados.

Novedades en v0.7.2 — DeepSeek V4 Provider

• DeepSeek V4 — 5º provider: deepseek-v4-flash (MoE rápido) y deepseek-v4-pro (thinking/reasoning).
• Provider pinning — F3 fija el provider manualmente. Sin auto-fallback en modo pinned.
• Context-aware switching — Límite de contexto actualizado en cada cambio de provider.

Novedades en v0.7.1 — Circuit Breaker Hardening

• Reasoning leak fixed — <reasoning> tags ya no se almacenan en el historial de mensajes.
• Fallback notification — TUI muestra "Switched to: Fallback" en tiempo real durante cambios de provider.
• Circuit breaker recovery — get_healthy() recorre prioridad completa. Primary se reintenta automáticamente tras 60s.
• Security fix — rmdir añadido al BashTool allowlist. Previene bypass vía file_write + python script.py.
• No duplicate messages — Notificación única desde chunk handler, sin duplicados del watcher reactivo.

Novedades en v0.7.0 — Circuit Breaker y Provider Resilience

• Circuit Breaker — Fallback automático de providers (CLOSED → OPEN → HALF_OPEN). Si el primario falla, el agente cambia al siguiente sin intervención del usuario.
• Auto-recuperación — Tras 60s, el provider caído se reactiva automáticamente.
• System messages — TUI y Telegram muestran avisos cuando se cambia de provider.
• 24 tests nuevos — CircuitBreaker (8), ProviderManager (7), Agent fallback (3), fixes (6)

Novedades en v0.6.0

• Panic Buttons — Cancelación de dos niveles: Escape interrumpe la generación, Ctrl+K hace kill nuclear (cancela + mata subprocess + limpia). Telegram: /stop y /kill.
• Auto-selección de skills — Las skills relevantes al query del usuario se inyectan automáticamente en el system prompt con contenido completo.
• Sandbox hardening — cat, head, tail eliminados de bash allowlist. Ahora file_read es la única vía de lectura de archivos.
• Session fixes — load_session_by_id ya no crashea por type mismatch, y _persisted_count se actualiza correctamente (sin duplicados en SQLite).
• Telegram guard — No apila mensajes mientras procesa (race condition corregida).
• Native exploration tools — grep, glob, tree implementados en Python puro. El agente ya no necesita bash para explorar el codebase. GrepTool (regex + include filter), GlobTool (pattern matching), TreeTool (directory tree con tamaños).
• 130 tests — 6 tests nuevos de agentic loop (v0.6.1) cubriendo terminación del agentic loop.
• /session command — Muestra la sesión activa (ID + mensajes). También en Ctrl+P.
• Reasoning persistence — El razonamiento del modelo se guarda en la sesión. Al cargar sesiones anteriores, ve su propio thinking previo.

Novedades en v0.5.4

• Sistema de memoria persistente — Directorio ~/.bytia-kode/memoria/ con 4 categorías (procedimientos, contexto, tecnología, decisiones) + index auto-generable. Skill memory-manager para almacenar, buscar, indexar y recuperar conocimiento entre sesiones.
• Trusted paths — _resolve_workspace_path() ahora acepta directorios confiados además del workspace. ~/.bytia-kode/ es trusted por defecto, permitiendo al agente gestionar su memoria desde cualquier proyecto sin comprometer la sandbox del código del usuario.
• Allowlist expandida — BashTool: binarios permitidos ampliados. Nuevos: mv, cp, rm, wc, date, chmod, curl, wget, scp, ssh, pip, pip3. (head y tail fueron eliminados en v0.6.0, rmdir añadido en v0.7.1; total actual: 25)
• EXTRA_BINARIES configurable — Variables de entorno para expandir la allowlist sin modificar código. EXTRA_BINARIES=graphify en .env.
• Skill graphify — Análisis de código con knowledge graphs (tree-sitter). Requiere uv tool install graphifyy.

Novedades en v0.5.3

• TTS (Text-to-Speech) — Botón 🔊 Escuchar en cada respuesta del asistente. Voz femenina mexicana (es-MX-DaliaNeural), reproducción con mpv, toggle play/stop.
• Logging de provider — Errores HTTP (400/500) loggeados antes de raise_for_status en client.py.

Novedades en v0.5.2

• Multi-workspace context — CONTEXT.md auto-generado por proyecto. El agente detecta lenguaje, estructura, git y herramientas del workspace actual.
• Logging a archivo — Logs rotativos en ~/.bytia-kode/logs/bytia-kode.log (1MB, 3 backups).
• Copiar respuestas — Ctrl+X copia último bloque de código, Ctrl+Shift+C copia respuesta completa.
• Panic Buttons — Escape para interrumpir, Ctrl+K para kill. Implementado en v0.6.0.

Novedades en v0.5.1

• Session awareness — Resumen de sesión anterior inyectado en el prompt. El modelo sabe qué hizo antes.
• Directivas proactivas — Session tools disponibles para uso autónomo del modelo.

Novedades en v0.5.0

• Sesiones persistentes — Todas las conversaciones se guardan automáticamente en SQLite WAL. No se pierde nada al reiniciar.
• Acceso cruzado TUI ↔ Telegram — Desde la TUI puedes ver sesiones de Telegram y viceversa. El modelo también puede acceder a sesiones pasadas.
• Aislamiento por usuario en Telegram — Cada usuario tiene su propia sesión e historial privado.
• Session tools — El modelo puede listar, buscar y cargar contexto de sesiones pasadas.
• Contexto ampliado — MAX_CONTEXT_TOKENS subido a 128k (antes 16k), optimizado para modelos GGUF con 256k.

Instalación

Instalación rápida (recomendada)

curl -fsSL https://raw.githubusercontent.com/asturwebs/BytIA-KODE/main/install.sh | bash

Esto instala todo automáticamente: clona el repo, configura el entorno Python, crea el wrapper bytia-kode en ~/.local/bin, y genera el .env con valores por defecto. Solo necesitas editar el .env con tu provider y API key.

Instalación manual

Requiere uv.

git clone https://github.com/asturwebs/BytIA-KODE.git
cd BytIA-KODE
uv sync
cp .env.example .env   # editar con tu provider y API key
uv run bytia-kode

Build como paquete

uv build
uv pip install ./dist/*.whl
bytia-kode

Modos de ejecución

uv run bytia-kode          # TUI (por defecto)
uv run python -m bytia_kode --bot  # Telegram bot

Bot de Telegram

El bot de Telegram comparte la misma base de datos de sesiones que la TUI (~/.bytia-kode/sessions.db), lo que permite:

• Continuar conversaciones entre interfaces — empieza un chat en Telegram y résumelo en la TUI (y viceversa).
• Aislamiento por usuario — cada chat_id tiene su propia sesión e historial privado. No hay filtrado de contenido.
• Acceso del modelo — el agente puede usar session_list(source="telegram") para acceder a sesiones de Telegram desde la TUI.

Configuración

Variable	Descripción
TELEGRAM_BOT_TOKEN	Token del bot (obtener de @BotFather)
TELEGRAM_ALLOWED_USERS	User IDs permitidos (comma-separated), ej: 123456,789012

Sin TELEGRAM_ALLOWED_USERS configurado, el bot deniega todos los mensajes (fail-secure).

Comandos del bot

Comando	Descripción
/start	Info del bot y modelo activo
/help	Lista comandos disponibles
/reset	Limpiar conversación del usuario
/model	Mostrar provider y modelo activos
/sessions	Listar sesiones del usuario
/context	Regenerar contexto del workspace

Arquitectura resumida

__main__.py
  ├─ tui.py
  └─ telegram/bot.py

agent.py
  ├─ prompts/bytia.kernel.yaml + bytia.runtime.kode.yaml
  ├─ session.py                    ← SQLite WAL persistence
  ├─ providers/manager.py
  ├─ providers/circuit.py          ← Circuit breaker (CLOSED/OPEN/HALF_OPEN)
  ├─ providers/client.py
  ├─ tools/registry.py
  ├─ tools/session.py              ← session_list, session_load, session_search
  └─ skills/loader.py

audio.py                             ← TTS: edge-tts + mpv

Documentación adicional:

• Manual de la TUI
• Arquitectura técnica
• Guía de desarrollo
• Guía de contribución
• Código de conducta
• Historial de cambios

Configuración principal

Variable	Descripción	Valor por defecto
PROVIDER_BASE_URL	Endpoint principal (router llama.cpp)	http://localhost:8080/v1
PROVIDER_API_KEY	API key del provider principal	vacío
PROVIDER_MODEL	Modelo principal (auto = auto-detect del router)	auto
FALLBACK_BASE_URL	Endpoint fallback (nube)	https://api.z.ai/api/coding/paas/v4
FALLBACK_API_KEY	API key del fallback	vacío
FALLBACK_MODEL	Modelo fallback	glm-5-turbo
LOCAL_BASE_URL	Endpoint local (Ollama)	http://localhost:11434/v1
LOCAL_MODEL	Modelo local	gemma4:26b
TELEGRAM_BOT_TOKEN	Token del bot	vacío
DATA_DIR	Directorio persistente	~/.bytia-kode
LOG_LEVEL	Nivel de logging (DEBUG, INFO, WARNING, ERROR)	INFO
LOG_FILE	Path custom para logs (vacío = ~/.bytia-kode/logs/bytia-kode.log)	vacío
EXTRA_BINARIES	Binarios adicionales para BashTool (comma-separated)	vacío

Sesiones Persistentes

Las sesiones se almacenan en ~/.bytia-kode/sessions.db (SQLite WAL mode). Tanto la TUI como el bot de Telegram comparten la misma base de datos.

Características

• Auto-save — Cada mensaje y tool result se guarda automáticamente. No hay que hacer nada.
• O(1) por mensaje — Solo INSERT, nunca reescribe el historial completo.
• Concurrencia segura — SQLite WAL permite múltiples lectores y un escritor simultáneo.
• Acceso cruzado — TUI y Telegram pueden acceder a las sesiones de la otra interfaz.
• Sin límite — Todas las sesiones se guardan indefinidamente.

Comandos TUI

Comando	Descripción
/sessions	Listar sesiones guardadas (tabla con ID, source, título, msgs, fecha)
/load <session_id>	Cargar una sesión específica
/new	Crear nueva sesión (limpia historial, habilita auto-save)
/reset	Limpiar conversación en memoria (no borra la sesión del disco)

Session Tools (para el modelo)

El modelo puede acceder a sesiones pasadas durante la conversación:

Tool	Descripción
session_list	Listar sesiones (filtro por source opcional)
session_load	Cargar contexto de una sesión pasada
session_search	Buscar sesiones por título

TUI

Comandos

Comando	Descripción
/help	Ayuda integrada
/quit, /exit, /q	Salida
/reset	Reinicia conversación (en memoria)
/new	Nueva sesión con auto-save
/sessions	Listar sesiones guardadas
/load <id>	Cargar sesión
/clear	Limpia chat
/model, /provider	Proveedor y modelo activos
/tools	Tools registradas
/skills	Listar skills guardadas
/skills save <name>	Crear skill nueva (contenido multiline)
/skills show <name>	Mostrar contenido de skill
/skills verify <name>	Marcar skill como verificada
/models	Listar modelos del provider activo
/use <model>	Seleccionar modelo del provider activo
/history	Historial reciente
/cwd	Directorio actual
/safe	Estado visual de safe mode
/context	Regenerar contexto del workspace

Atajos

Atajo	Acción
Ctrl+P	Menú de comandos
Ctrl+Q	Salir
Ctrl+R	Reset conversación
Ctrl+L	Limpiar chat
Ctrl+M	Mostrar modelo
Ctrl+T	Mostrar tools
Ctrl+S	Mostrar skills
Ctrl+D	Toggle reasoning
Ctrl+E	Alternar safe mode
Ctrl+X	Copiar último bloque de código
Ctrl+Shift+C	Copiar respuesta completa del agente
F2	Cambiar tema cíclicamente
F3	Cambiar provider (primary/fallback/local)
↑ / ↓	Historial de entrada
Enter	Enviar prompt

Temas

Pulsa F2 para cambiar entre los 19 temas disponibles (12 oscuros + 7 claros, por defecto gruvbox). El tema se guarda en ~/.bytia-kode/theme.json.

Tools

Tool	Propósito	Seguridad
bash	Ejecutar comandos shell	Allowlist de binarios, sandbox CWD
file_read	Leer archivos	Path traversal bloqueado
file_write	Escribir archivos	Path traversal bloqueado
file_edit	Editar archivos (search/replace + create)	Backup automático, sandbox CWD
web_fetch	Fetch URLs (HTTP GET)	Solo http/https, content type validation
read_context	Contexto del workspace actual	Solo lectura, auto-genera si no existe
session_list	Listar sesiones guardadas	Solo lectura
session_load	Cargar contexto de sesión pasada	Solo lectura
session_search	Buscar sesiones por título	Solo lectura
grep	Búsqueda regex en archivos	v0.6.0
glob	Pattern matching de archivos	v0.6.0
tree	Jerarquía de directorios	v0.6.0

Consulta docs/DEVELOPMENT.md para crear nuevas tools.

Skills System

BytIA KODE incluye un sistema de skills persistente. Las skills son procedimientos reutilizables en formato Markdown+YAML que el agente carga en su system prompt según relevancia.

Arquitectura de Capas

Las skills se organizan en capas con prioridad (alta → baja):

~/.bytia-kode/skills/
├── bytia/      # Ecosistema BytIA (opcional, si ~/bytia existe)
├── user/       # Skills creadas por el usuario (writable)
└── vendor/     # Skills incluidas con KODE (read-only)

Capa	Prioridad	Writable	Descripción
bytia/	1 (más alta)	No (symlink)	Ecosistema BytIA compartido con otros assistants
user/	2	Sí	Skills propias del usuario
vendor/	3 (más baja)	No	Skills core incluidas con KODE

Capas superiores sobrescriben las inferiores con el mismo nombre.

Vendor Skills (Core)

KODE incluye por defecto:

• bytia-constitution — Identidad y valores BytIA OS
• bytia-memory — Gestión de memoria entre sesiones
• skills-manager — Gestión del sistema de skills
• graphify — Knowledge graphs de código

Extensibilidad

Las skills evolucionarán hacia unidades más autónomas:

• Tools dinámicas — scripts en skills/<name>/scripts/ auto-registrados como tools
• Sub-agentes — una skill puede definir su propio SP y ejecutarse como agente dedicado
• Skills Hub — instalar skills desde repos GitHub
• write_skill tool — el agente crea skills programáticamente

Estructura Completa

~/.bytia-kode/
├── sessions.db           # SQLite WAL — sesiones persistentes
├── theme.json            # Tema seleccionado
├── logs/
│   └── bytia-kode.log   # Logs rotativos (1MB, 3 backups)
├── contexts/
│   └── <hash>.md        # CONTEXT.md por workspace
├── memoria/
│   ├── procedimientos/   # How-tos, workflows
│   ├── contexto/         # Decisiones, hitos
│   ├── tecnologia/       # Stacks, arquitecturas
│   ├── decisiones/       # ADRs
│   └── index.md          # Índice auto-generado
└── skills/
    ├── bytia/           # Symlink a ~/bytia/skills/ (si existe)
    ├── user/            # Skills propias (writable)
    │   └── my-procedure/
    │       ├── SKILL.md
    │       └── scripts/
    └── vendor/           # Skills core (read-only, se actualiza con KODE)
        ├── bytia-constitution/
        ├── bytia-memory/
        ├── graphify/
        └── skills-manager/

## Validación y release

```bash
uv run python scripts/validate_metadata.py
uv run pytest -q
uv build
uv run python -m twine check dist/*

Hook local versionado

git config core.hooksPath .githooks

BytIA OS Kernel + Runtime

El agente carga su identidad desde dos archivos YAML: bytia.kernel.yaml (identidad y valores inmutables) + bytia.runtime.kode.yaml (adaptación al entorno). Se empaquetan dentro del wheel como recursos del paquete.

Personalizar la identidad

Para personalizar la identidad, edita los YAML en src/bytia_kode/prompts/:

Sección	Qué contiene	Personalizar
identity	Nombre, versión, naturaleza, creador, runtime (capacidades, comandos)	Tu nombre y rol
valores	Jerarquía de prioridades (seguridad, privacidad, precisión...)	Tus prioridades
protocols	Comportamiento ante errores, overrides, auto-evaluación	Ajustar a tu flujo
interfaz	Idioma, estilo de comunicación, formato	Tu idioma y tono
contexto	Perfil del usuario, ubicación, infraestructura	Tu perfil y entorno
runtime_profile	Variables del motor (se rellenan en tiempo de ejecución)	No modificar

Después de editar, reconstruye el wheel para que los cambios se empaqueten:

uv build

Stack técnico

BytIA KODE se construye sobre librerías open-source de terceros. Consulta ARCHITECTURE.md para el detalle completo con versiones y uso específico.

Librería	Rol
Textual	Framework TUI
Rich	Renderizado (Markdown, Panel, Table)
httpx	Cliente HTTP async / streaming SSE / web_fetch
Pydantic	Modelos de datos y validación
PyYAML	Parseo de identidad y skills
python-dotenv	Variables de entorno
python-telegram-bot	Bot de Telegram
sqlite3	Persistencia de sesiones (stdlib)
edge-tts	TTS: voz neuronal (CLI, no Python dep)
mpv	Reproductor de audio (sistema)

Seguridad

Modelo de seguridad con defense-in-depth:

Capa	Mitigación
Command injection	Allowlist de binarios + shell=False + shlex.split()
Path traversal	_resolve_workspace_path() con sandbox a CWD + trusted paths
Telegram abierto	Fail-secure por defecto (deniega sin allowlist)
Sesiones cruzadas	Aislamiento por chat_id

Motor I/O asíncrono con benchmark: 4.90x speedup frente a ejecución secuencial.

Limitaciones conocidas

• safe_mode sigue siendo principalmente visual y no implementa aislamiento backend completo.
• Las skills no registran tools dinámicas todavía (previsto para v0.6.0).
• El estimador de tokens es una heurística (chars/3), no un tokenizer real.
• PromptTextArea no soporta Shift+Enter para newline (limitación de Textual).

Contribuir

Contribuciones, issues y sugerencias son bienvenidas.

1. Fork del repositorio
2. Rama para tu feature (git checkout -b feature/mi-mejora)
3. Commit con cambios (git commit -m 'feat: descripción')
4. Push a la rama (git push origin feature/mi-mejora)
5. Abre un Pull Request

Consulta CONTRIBUTING.md para los criterios de validación.

Autores

• Pedro Luis Cuevas Villarrubia (AsturWebs) <pedro@asturwebs.es>
• BytIA v12.3.0 — coautoría operativa — BytIA OS RFC-001

Licencia

Licencia MIT. Consulta LICENSE.