THEUS — CLI

THEUS HECHO EN PERÚ · AD ASTRA PER ASPERA Dominio: theus.pe · Docs: docs.theus.pe

Theus es un agente de código local-first y multimodelo: abre una sesión interactiva desde cualquier proyecto, lo indexa en tu propia máquina, mantiene memoria y un grafo del código, levanta un dashboard visual, y ejecuta tareas de programación con el modelo que elijas.

Este repo es el producto principal: el CLI theus (Bun + Ink/React en TSX). El lado servidor (web, gateway y consola) vive en MarketrixPE/theus-pe.

🧠 Cómo encaja en el negocio

Theus se puede usar de dos maneras, y las dos son ciudadanas de primera clase:

1. Local-first / BYOK — apunta el CLI a cualquier endpoint OpenAI-compatible (Ollama, LM Studio, un gateway propio, tu propia key). Todo corre en tu máquina; ningún servicio remoto es obligatorio para arrancar.
2. Suscripción Theus (gateway gestionado) — theus login conecta el CLI al gateway de theus.pe. Con una sola API key de Theus accedes a los ~20 mejores modelos (Claude, GPT, Gemini, DeepSeek, Grok, Qwen, GLM…). Theus administra centralmente las keys de cada proveedor; tú solo usas tu suscripción — no traes tus propias keys de proveedor.

En el modo suscripción, el modelo por defecto es titan: el orquestador propio de Theus que analiza cada petición, decide si la resuelve con un modelo o la descompone entre varios, y sintetiza la respuesta final. (Toda la lógica de TITAN, el catálogo y la gestión de keys está documentada en el README de theus-pe.)

Regla de producto: el copy visible es español-first y sin marcas externas. La única excepción es el catálogo de modelos, donde sí aparecen los nombres reales.

🚀 Instalación (usuarios)

Requisito de runtime: Bun (cli.js es un bundle con target bun, no corre bajo Node). El instalador oficial instala Bun por ti si falta, verificando su checksum SHA-256.

curl -fsSL https://theus.pe/install.sh | bash
theus --version

El instalador detecta tu plataforma (macOS/Linux, x64/arm64), descarga el tarball del último release (primario desde theus.pe/dl, con GitHub Releases como respaldo — el repo es privado), lo instala en ~/.theus/app y enlaza theus en tu PATH. Es idempotente: para actualizar, vuelve a ejecutarlo.

Alternativa vía npm (también requiere Bun):

npm install -g theus-cli

Variables del instalador: THEUS_INSTALL_MODE (auto|release|source), THEUS_VERSION (latest o vX.Y.Z), THEUS_HOME, THEUS_BIN_DIR.

Primer uso

cd /ruta/de/tu/proyecto
theus                    # sesión interactiva
theus -p "tu prompt"     # modo no interactivo
theus login              # conectar la suscripción Theus

🧩 Conectar un modelo

Theus lee primero las variables THEUS_*. Apunta a cualquier endpoint OpenAI-compatible:

export THEUS_BASE_URL="http://127.0.0.1:11434/v1"
export THEUS_MODEL="llama3.1"
export THEUS_API_KEY="local"
theus

O define proveedores en ~/.theus/providers.json:

{
  "providers": [
    { "id": "ollama", "adapter": "openai-compatible", "enabled": true,
      "options": { "baseURL": "http://127.0.0.1:11434/v1", "model": "llama3.1", "apiKey": "local" } }
  ],
  "policy": { "text": ["ollama"] }
}

theus login hace el flujo OAuth/PKCE contra theus.pe, intercambia el código por token y deja instalado el proveedor theus-official (https://theus.pe/v1, modelo titan) en ~/.theus/providers.json. A partir de ahí basta con theus.

Orden de selección de proveedor (services/api/theus.ts): THEUS_DISABLE_MAIN_PROVIDER=1 → env THEUS_BASE_URL/THEUS_OPENAI_BASE_URL → primer proveedor con texto en providers.json → motor de compatibilidad. Ningún servicio remoto es obligatorio para arrancar.

Variables útiles

| Variable | Uso | | --- | --- | | THEUS_BASE_URL / THEUS_OPENAI_BASE_URL | endpoint OpenAI-compatible | | THEUS_MODEL / THEUS_API_KEY / THEUS_PROVIDER_ID | modelo, key y nombre del proveedor | | THEUS_DISABLE_MAIN_PROVIDER=1 | fuerza el motor de compatibilidad | | THEUS_NO_PROJECT_INTELLIGENCE=1 | no levanta índice/API/dashboard | | THEUS_NO_OPEN_DASHBOARD=1 | levanta la API sin abrir el navegador | | PROJECT_API_PORT / INDEX_MAX_FILES | puerto local / límite de archivos indexados |

📊 Dashboard e inteligencia local

Al iniciar dentro de un proyecto, el servicio de inteligencia local indexa archivos, extrae símbolos, construye el grafo, detecta esquemas SQL/Prisma, guarda índice y memoria en ~/.theus/knowledge/ y expone un dashboard en 127.0.0.1:

/dashboard   /api/status   /api/graph   /api/database   /api/schema   /api/health

🧭 Ñaupa (motor de inteligencia de código)

Si el binario naupa está instalado, Theus lo monta automáticamente como servidor MCP (theus-naupa) en cada sesión: grafo de conocimiento AST del proyecto (tree-sitter, 158 lenguajes), cadenas de llamadas, consultas Cypher y análisis de impacto en <1 ms — el agente consulta la estructura antes de recurrir a grep/read.

curl -fsSL https://theus.pe/naupa.sh | bash   # instalar Ñaupa
THEUS_NO_NAUPA=1 theus                        # kill-switch por sesión

Las tools de lectura (search_graph, trace_path, query_graph, get_architecture, …) van pre-permitidas; las que escriben (index_repository, delete_project, …) pasan por el flujo de permisos normal. Caché en ~/.theus/naupa/. Código: services/mcpNaupa/. Docs: theus.pe/docs/naupa.

🖥️ Computer-use (control de escritorio — macOS)

Theus puede ver la pantalla y operarla (mouse + teclado). Implementación propia, sin addons compilados: se apoya en herramientas nativas del sistema (screencapture, sips, cliclick, osascript). Es opt-in y solo macOS.

brew install cliclick                     # única dependencia externa
theus --theus-computer-use-selftest       # certifica captura+control en tu Mac
THEUS_COMPUTER_USE=1 theus                # arranca con computer-use montado

Requiere otorgar dos permisos al app que corre Theus (tu terminal), en Ajustes del Sistema → Privacidad y seguridad: Grabación de pantalla y Accesibilidad. Sin ellos, las tools devuelven un error accionable (no rompen el turno). El agente trabaja tomando un screenshot, razonando sobre la imagen y dando coordenadas en píxeles; el server las mapea a puntos lógicos de la pantalla. Tools MCP: mcp__theus-computer-use__{screenshot,left_click,double_click,right_click,mouse_move,left_click_drag,type,key,scroll,cursor_position,wait,permissions} (services/mcpComputerUse/).

🛠️ Desarrollo

bun install
bun run dev                 # corre desde fuente (entrypoints/cli.tsx)
./bin/theus --version       # vía el launcher (preload de shims)
bun run build               # bundle → ./cli.js  (usa el macro feature(); --define feature=false)
bun run typecheck           # tsc --noEmit — ⚠️ ver caveat

Smoke tests (la verificación real, no el typecheck):

THEUS_NO_PROJECT_INTELLIGENCE=1 ./bin/theus --help
THEUS_NO_OPEN_DASHBOARD=1 ./bin/theus
curl http://127.0.0.1:<puerto>/api/status
curl http://127.0.0.1:<puerto>/api/database

Caveat de typecheck: bun run typecheck aún falla por deuda de tipos heredada y stubs reconstruidos. No lo trates como gate. Valida con tests enfocados + smoke tests del CLI + chequeos del dashboard.

Flujo de arranque

bin/theus → entrypoints/cli.tsx → main.tsx → setup.ts → replLauncher.tsx → screens/REPL.tsx → query.ts

bin/theus corre Bun con --preload bun-shims/preload.ts (registra el shim del macro feature()/bun:bundle y stubs internos para correr sin bundlear). login/signin/entrar los intercepta el launcher y los enruta a entrypoints/theus-login.ts.

Mapa de arquitectura

services/api/theus.ts            proveedor de modelos — router OpenAI-compatible + fallback
services/knowledge/              índice local, grafo del proyecto, memoria (~/.theus/knowledge/)
services/projectIntelligence/    API HTTP local + dashboard + DB visual (detección SQL/Prisma)
tools.ts                         registro de herramientas (¡el orden importa!)
commands.ts                      registro de slash-commands (¡el orden importa!)
components/Theus/                 banner (Prometeo ASCII), menú, setup de proveedor
vendor/theus-packages/           paquetes propios (agent-sdk, sdk, mcpb)
vendor/theus-stubs/              stubs reconstruidos de deps privadas/3ras
types/                           tipos públicos + shims

⚠️ Convenciones que NO se rompen (léelas antes de tocar código)

Este CLI es una reconstrucción de un agente upstream: varios invariantes de build son load-bearing y fáciles de romper sin querer.

• Mantén las extensiones .js en imports ESM aunque el archivo fuente sea .ts/.tsx.
• Usa import type para imports de solo-tipo (verbatimModuleSyntax está activo).
• No auto-ordenes ni reordenes tools.ts ni commands.ts — el orden es significativo.
• feature("FLAG") es un macro de build, no un if de runtime. No lo reescribas como condicional normal; el bundler hace dead-code-elimination desde ahí (build pasa --define feature=false). Los módulos gateados por build se cargan con require() condicional dentro de un ternario.
• No renombres mecánicamente process.env.USER_TYPE === 'ant' — es un gate de build heredado.
• Evita editar main.tsx en bloque (entrada grande heredada). Prefiere components/, hooks/, screens/, services/, tools/, commands/.
• No cambies prompts sensibles sin motivo: query.ts, reglas de thinking, permisos, seguridad, prompts de herramientas.

Añadir una herramienta o comando

• Herramienta: buildTool(...) satisfies ToolDef<...>, constante de nombre en prompt.ts/constants.ts, regístrala en getAllBaseTools(), declara permisos + destructividad con precisión, y añádela a constants/tools.ts si los subagentes deben verla.
• Slash-command: vive en commands/<nombre>/, tipo prompt | local | local-jsx. Mantén COMMANDS como función memoizada — no la conviertas en array top-level.

🚢 Releases y distribución

bun run scripts/release.ts --tag vX.Y.Z    # genera dist/release/* + SHA256SUMS

Luego: sube dist/release/* a /var/www/theus.pe/dl/ (y /dl/vX.Y.Z/), crea el release en GitHub (MarketrixPE/theuscode), y publica en npm (theus-cli; requiere OTP salvo con token de automatización). El paquete npm es solo el bundle compilado (cli.js + bin + arte ASCII + README): no expone la fuente privada.

📖 Docs adicionales del subproyecto

• AGENTS.md — reglas de trabajo para agentes.
• THEUS.md — manual de producto/operaciones.
• THEUS_SOURCE_NOTES.md — internals de runtime/build.

Principios de producto

• Local-first por defecto; cada usuario controla su modelo y su llave.
• Cero marca externa en el copy visible (excepto el catálogo de modelos).
• Identidad Theus coherente: theus, .theus, THEUS_*, theus.pe.
• El dashboard explica el proyecto, no solo dibuja puntos.
• Las funciones incompletas se nombran como deuda técnica, no como promesa terminada.