Tamnora Harness

Harness local para IAs: un agente CLI-first (estilo opencode) en Node puro, con TUI, consola web, tools locales, MCP y evaluacion de modelos.

• Sin dependencias: solo modulos de Node (node:sqlite, node:crypto, ...).
• Local: corre en tu maquina y guarda el estado en tu casa local.
• Multi-proveedor: OpenRouter, OpenAI, Anthropic (Claude), Google Gemini, proveedores compatibles (DeepSeek, Groq, Mistral, xAI, Together, Fireworks, Cerebras, Perplexity) y Ollama.
• Navegador headless: tools screenshot y console_errors (renderiza JS y saca una captura PNG o lista los errores de consola) y preview_url.
• Voz: el agente narra su progreso, puede leer la respuesta final (sin bloques de codigo ni tablas) y mandar audio bajo pedido (speak, /audioresumen).
• Asesor: una capa de comentario sobre el run que interpreta lo que hizo el agente y, si aporta algo, avisa de un problema en el codigo, explica un proceso o da un consejo (con tarjeta en el chat y voz opcional). No lee la respuesta.
• Actualizar desde la consola: la consola avisa cuando hay una version nueva y la instala con un click (el server se reinicia solo).

Instalacion

npx @danieltmn/tamnora --help
# o global
npm i -g @danieltmn/tamnora

Requiere Node.js >= 22.5 (por node:sqlite).

Uso rapido

tamnora init                  # crea la configuracion (proveedor, modelo)
tamnora                       # consola TUI full-screen (REPL si no hay TTY)
tamnora run "hola"            # tarea headless
tamnora eval <dataset.jsonl>  # evaluacion de modelos
tamnora mcp [--json]          # servidores MCP: tools, recursos y prompts
tamnora serve                 # consola web

Consola TUI

tamnora                   # TUI full-screen (REPL si no hay TTY)
tamnora tui --mode plan   # modo plan: solo lectura, sin escritura ni bash

Atajos: enter enviar · ↑/↓ historial · ←/→ cursor · home/end inicio/fin · pgup/pgdn scroll · ctrl+l limpiar · ctrl+c cancelar/salir · /salir, /limpiar. El pegado de bloques multilinea entra como un solo texto y el header muestra el contexto usado (ctx <tokens>). Las tools write/edit muestran un diff lado a lado (viejo en rojo, nuevo en verde, con numeros de linea).

Server como servicio

tamnora server --init         # crea la casa y arranca (segundo plano)
tamnora server --start        # arranca (default)
tamnora server --reload       # reinicia aplicando config/codigo
tamnora server --stop
tamnora server --status
tamnora server --logs --follow
tamnora doctor                # verifica Node, casa, puerto, base y version nueva
tamnora update                # busca/instala una version nueva (reinicia el server)
tamnora autostart install     # arranque automatico del server

tamnora server corre en segundo plano y sobrevive al cierre de la consola (puerto default 4517). La configuracion de la app vive en la casa de Tamnora (override con --home o TAMNORA_HOME):

• Windows: %APPDATA%\tamnora
• macOS: ~/Library/Application Support/tamnora
• Linux: ~/.config/tamnora

Actualizar: en 0.9.5+ la consola avisa cuando hay una version nueva y la instala con un click (el server se reinicia solo); un click en la version del topbar fuerza el chequeo. Por CLI, tamnora update --yes ahora detiene el server antes de instalar (en Windows libera los archivos) y lo reinicia. Si venis de 0.8.0 o anterior y "dice que actualizo pero sigue igual", hace una vez: tamnora server --stop, npm i -g @danieltmn/tamnora@latest y tamnora server --start. Verifica que where tamnora coincida con npm root -g (si no, hay dos instalaciones y el update toca la otra).

Consola web

tamnora serve sirve la consola en http://127.0.0.1:4517. Las pestanas principales son chat, proveedores y ajustes; eval y runs viven en el menu "mas" (los tres puntitos). En el chat:

• Paneles laterales de sesiones y archivos, colapsables desde cada panel (con un tirador en el borde para reabrirlos).
• Pie con modo, proveedor, modelo, estado y el uso de contexto del ultimo turno (contexto 44% · 464k/1.0M) con una barra que cambia de color.
• /new abre otra sesion en la misma carpeta de la sesion activa; el boton "+ nueva sesion" (y /new sin sesion) abre el selector de carpetas. La carpeta predeterminada se elige en Ajustes.
• Actividad colapsable: las tools de lectura (read, list, glob, grep, fetch_url, git_*) salen plegadas y al hacer click se ve el detalle (args + resultado); el volcado completo se pide bajo demanda.
• Markdown con tablas: las respuestas renderizan tablas (|, con alineacion y celdas saneadas) y botones flotantes para saltar al inicio/final del turno.
• Acciones por mensaje: copiar, editar, regenerar y borrar se agrupan en un menu ⋮; el indicador de "pensando/trabajando" vive en el pie (#sb-activity).
• Runs durables: cerrar el celular o cortar la red no cancela el turno; al volver, la consola reconecta y reconstruye el progreso. Para cortarlo se usa el boton de detener (o POST /api/sessions/:id/stop).
• Audio: un unico reproductor encola la narracion, el tool speak, la respuesta final y los consejos del asesor, y reproduce de a uno con pausa y detener (Ajustes -> Voz).
• Asesor: en Ajustes -> Asesor se activa una capa que comenta el turno (problemas de codigo / explicaciones / consejos) con proveedor y modelo activos.
• Actualizar: cuando npm tiene una version nueva aparece un banner para actualizar con un click; el server se reinicia solo.
• Comandos: el input muestra un menu al escribir / (/new, /init, /goal, /resumen, /audioresumen, /compact, /clear, /cwd, /kill, /help).
• Capturas: el tool screenshot muestra la imagen inline en su tarjeta.

Preview

La consola puede levantar un dev server (deteccion de scripts dev/start, Laravel, PHP) y abrir un tunel al puerto para verlo desde el celular. Para sitios estaticos (un index.html sin script de dev) ofrece un chip "sitio estatico" que los sirve con un servidor sin dependencias (harness/scripts/static-server.mjs).

El visor de archivos tiene vista previa: .html/.svg se sirven con sus CSS, JS e imagenes relativas, y .md se renderiza como markdown. Ambas vistas suman selector de tamano (movil/tablet/laptop/pc/adaptable) y boton para maximizar.

Login

tamnora user --name <n> --password <p>   # crea/cambia el usuario local
tamnora user                            # muestra el usuario
tamnora user remove                     # el server deja de pedir login

Con un usuario configurado, todas las rutas /api/* piden sesion (cookie firmada + CSRF) y la landing pasa a ser el login real; sin usuario, el server corre en modo local sin login. Al cambiar el usuario se detiene el server (volvelo a arrancar con tamnora server --start).

Acceso remoto

El acceso remoto usa Tailscale (VPN mesh privada, rapida y sin exponer nada a Internet). El server sigue escuchando en 127.0.0.1; tailscale serve publica HTTPS dentro del tailnet y reenvia por loopback, asi que la consola y todas las tools funcionan igual que en local, sin sincronizar datos (una sola base SQLite).

# 1. Instalar Tailscale en esta PC y en el dispositivo remoto (misma cuenta)
#    https://tailscale.com/download
tamnora user --name yo --password unaClaveLarga

# 2. Server + acceso remoto
tamnora bridge --start          # tailscale serve (URL + QR)
tamnora bridge --status         # https://<pc>.<tailnet>.ts.net
tamnora bridge --stop           # tailscale serve reset

tamnora bridge --start muestra la URL y un QR para abrirlo desde el celu. Sigue protegido por el login del server: configura un usuario antes de exponerlo (ver SECURITY.md).

Los tuneles publicos (tunnelmole, relay) fueron retirados; tunnelmole se conserva solo para el feature de preview.

Telegram (canales de mensajeria)

Con un token de bot (telegram.token en tamnora.json, app.json o TAMNORA_TELEGRAM_TOKEN) podes manejar el harness desde el chat. Cada chat mapea a una sesion y el bot soporta:

• texto, imagenes (entrantes y salientes: el tool screenshot llega como foto) y notas de voz (transcripcion con telegram.transcribeModel, default whisper-1, via POST {baseUrl}/audio/transcriptions);
• aprobaciones ask con botones inline y una explicacion de lo que va a hacer el agente (Permitir / Permitir todo / Denegar); "Permitir todo" deja de preguntar por el resto de la sesion;
• el bot solo manda audio cuando lo pedis (tool speak o /audioresumen);
• comandos /new, /resumen, /audioresumen, /status, /model, /provider, /mode, /stop, /help;
• notificaciones: si un run de la consola pertenece a una sesion vinculada a un chat, el canal avisa el fin, los errores, los subagentes y los permisos.

server/src/lib/channels/ define la interfaz (stop, notify); sumar otro proveedor es implementarla.

MCP

Los servidores MCP se configuran en tamnora.json (mcp[]) y soportan HTTP y stdio. Las tools se exponen como mcp__<servidor>__<tool> y, si el servidor los anuncia, tambien sus recursos y prompts (list_resources, read_resource, list_prompts, get_prompt).

Los MCP stdio no heredan process.env: reciben un baseline minimo mas el env declarado ("KEY": "env:VAR"), y sus resultados pasan por redactSecrets (ver SECURITY.md). Para un servidor de confianza que necesite el entorno completo, "inheritEnv": true.

Tools

Tools locales confinadas al workspace (read, list, glob, grep, write, edit, bash, fetch_url), de navegador (screenshot, console_errors, preview_url), de voz (speak) y de Git (git_status, git_diff, git_log, git_commit), con permisos allow/ask/deny por tool o por patron.

fetch_url lee URLs (HTML a texto) y avisa cuando un sitio exige JavaScript o esta detras de Cloudflare; para esos casos las tools screenshot / console_errors usan el Chrome/Edge/Chromium del sistema como navegador headless (sin dependencias): sacan una captura PNG y recolectan los errores de consola. Para automatizacion mas completa, registra un MCP (por ejemplo Playwright).

Subagentes

El agente puede delegar una subtarea con la tool task: lanza un subagente con contexto y toolset propios (solo lectura por defecto, modo plan) y devuelve un resumen. En la consola la actividad del subagente se anida en una tarjeta plegable; el limite de rondas se ajusta con agents.maxRounds. La tool task tambien esta disponible en modo plan (exploracion delegada).

Documentacion

• CHANGELOG.md — historial de versiones.
• AGENTS.md — arquitectura del harness, tools, MCP, evaluacion y convenciones.
• harness/tamnora.example.json — plantilla de configuracion.
• SECURITY.md — modelo de amenaza y reporte de vulnerabilidades.

El chat SPA (Tamnora Chat) vive en su propio repositorio: tamnora-chat.

Versiones

El proyecto sigue Versionado Semantico. Cada version se documenta en CHANGELOG.md y se publica como un tag vX.Y.Z en git mas npm publish.

Desarrollo

pnpm install
pnpm tamnora        # TUI / REPL
pnpm serve          # consola web
pnpm mock           # proveedor local de prueba (OpenAI-compatible + Ollama)
pnpm test           # tests (node:test)
pnpm lint           # ESLint

Licencia

MIT.