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.8.0 · Identidad: YAML · Instalación: uv

⚠️ Nota sobre las secciones "Novedades en vX.Y.Z" que siguen: son histórico de release. No describen la versión actual — para eso está pyproject.toml:3 y la línea "Release actual" de arriba.

Novedades en v0.7.8 — Code Review Fixes (histórico)

• 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 (cifra histórica de v0.7.8; la suite actual tiene 331 — ver badge).

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

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

Comandos del bot

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: bytia-tts + piper (local)

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

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

Session Tools (para el modelo)

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

TUI

Comandos

Atajos

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

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)

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/:

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.

Seguridad

Modelo de seguridad con defense-in-depth:

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

Guardarraíl JEVAL (pre-ejecución de tools)

src/bytia_kode/guardrail.py clasifica cada llamada a tool antes de ejecutarla (TypeSafe System One) y puede bloquear las arriesgadas.

• Por defecto off — el guardarraíl está apagado hasta que actives JEVAL_MODE explícitamente.
• Requiere TYPESAFE_API_KEY (o ~/.config/typesafe/env). Sin clave, el gate se desactiva aunque JEVAL_MODE=enforce.
• Fail-open: cualquier error o timeout del clasificador permite la llamada — JEVAL nunca rompe el bucle.
• Otras variables: JEVAL_THRESHOLD (0..1, default 0.7), JEVAL_TIMEOUT (default 2.0 s).
• Log de decisiones (JSONL, rotación 600): ~/.local/state/jev-router/kode-guardrail.jsonl.

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.