Memoria, trazabilidad y control de costos para desarrollo asistido por agentes IA
Rutea tareas entre Claude, OpenAI, DeepSeek y Gemini según el contexto del proyecto,
con dashboard en vivo, tracking de costo y memoria RAG.
Los agentes IA (Claude Code, Codex, DeepSeek) generan valor en tareas acotadas, pero el historial queda disperso en archivos de sesión separados, sin visibilidad de costos ni contexto acumulado entre conversaciones. Sin memoria estructurada, cada sesión empieza desde cero y el gasto es opaco.
ai-orchestrator centraliza ese historial localmente: indexa respuestas previas en ChromaDB, rutea cada tarea al modelo más eficiente según el contexto del proyecto, y registra tokens y costo USD de cada run en SQLite. El dashboard SSE muestra el estado en tiempo real. El servidor MCP expone 12 herramientas para que cualquier agente pueda leer y escribir en el historial sin salir de su entorno de trabajo.
PowerShell
# 1. Crear entorno virtual
cd C:\ruta\ai-orchestrator
python -m venv .venv
.venv\Scripts\activate
# 2. Instalar dependencias
pip install -r requirements.txt
pip install -e .
# 3. Crear directorio de configuración y copiar plantillas
New-Item -ItemType Directory -Force "$env:USERPROFILE\.ai-orchestrator"
Copy-Item config.example.yaml "$env:USERPROFILE\.ai-orchestrator\config.yaml"
Copy-Item index.example.yaml "$env:USERPROFILE\.ai-orchestrator\index.yaml"
# 4. Completar las API keys
notepad "$env:USERPROFILE\.ai-orchestrator\config.yaml"Git Bash
# 1. Crear entorno virtual
cd /c/ruta/ai-orchestrator
python -m venv .venv
source .venv/Scripts/activate
# 2. Instalar dependencias
pip install -r requirements.txt
pip install -e .
# 3. Crear directorio de configuración y copiar plantillas
mkdir -p ~/.ai-orchestrator
cp config.example.yaml ~/.ai-orchestrator/config.yaml
cp index.example.yaml ~/.ai-orchestrator/index.yaml
# 4. Completar las API keys
notepad ~/.ai-orchestrator/config.yamlAPI Keys — obtené cada key en su plataforma y pegala en
config.yaml:
Proveedor Plataforma Obligatorio Claude (Anthropic) https://console.anthropic.com → API Keys Sí (proveedor destino) DeepSeek https://platform.deepseek.com → API Keys Sí (router) OpenAI https://platform.openai.com → API keys Opcional Gemini (Google) https://aistudio.google.com/apikey Opcional El mínimo funcional es DeepSeek (router) + Claude (proveedor destino). Ver guía detallada en
docs/api-keys.md.
# 5. Verificar instalación
ai-orchestrator --help
# 6. Registrar tu primer proyecto y levantar el dashboard
ai-orchestrator add mi-proyecto --path "C:\ruta\al\proyecto"
ai-orchestrator serve # abre http://127.0.0.1:8080| Capacidad | Descripción |
|---|---|
| Ruteo inteligente | DeepSeek Flash analiza la tarea y el context.yaml del proyecto para decidir qué modelo usar — sin hardcodear |
| Control de costos | Tokens de entrada, salida y cache por run. Costo en USD calculado con un catálogo de precios versionado (ai-orchestrator pricing show/refresh/validate), con override en config.yaml |
| Discovery de modelos | Consulta el API de cada proveedor configurado (ai-orchestrator models list/refresh) y compara contra el catálogo de precios — best-effort, un proveedor caído no rompe a los demás |
| Agentes (presets) | Perfiles reutilizables de provider/model/system-prompt (ai-orchestrator agents add/list/show/remove), asignables a un paso de un contexto. Capa de conveniencia sobre el router — no ejecuta nada por sí sola |
| Memoria RAG | ChromaDB indexa docs y respuestas previas por proyecto. Cada tarea recupera contexto semántico relevante (threshold L2=0.9 ≈ cosine_sim≥0.60) antes de llamar al modelo. Re-indexación idempotente: upsert por ID determinístico |
| Dashboard en vivo | Panel web con SSE — las filas aparecen en tiempo real sin recargar. Gauge de presupuesto, filtros y panel de detalle |
| Inspector DB | Vista interna de ChromaDB (colecciones + breakdown por proyecto) y SQLite (counts + últimos registros) |
| Contextos y pasos | Flujos estructurados multi-paso con checkpoints de alineación y registro de tool calls |
| Barra de actividad | Spans en tiempo real: Router → RAG → API → Index. Duración de cada operación visible mientras corre |
| Sync Claude Code | Importa sesiones de ~/.claude/projects/ al historial. Ejecutable vía hook Stop automáticamente |
| Sync Codex | Importa sesiones de OpenAI Codex CLI (~/.codex/state_N.sqlite) al historial, incluyendo tokens, costo y respuesta completa |
| Doctor / Fix | doctor diagnostica el estado completo en 4 secciones (config, MCP Claude/Codex, proyectos, DB). fix aplica correcciones automáticas: crea .mcp.json, .codex/config.toml, context.yaml, registra MCP global, sincroniza e indexa |
| Menú de acciones | Botones doctor, fix, sync, index en la barra de actividad del dashboard. Ejecutan las mismas acciones que la CLI y trazan resultados en tiempo real en el log de actividad |
Fuera del alcance: no es un proxy de API (el proceso corre localmente), no orquesta agentes en paralelo, no mantiene historial de conversación entre runs.
El servidor MCP expone 12 herramientas que cualquier agente compatible (Claude Code, Cursor, Codex, Gemini Code Assist, etc.) puede invocar directamente sin usar la CLI:
| Tool | Propósito |
|---|---|
get_context |
Retorna el objetivo y estado del contexto activo del proyecto |
list_steps |
Lista los pasos ordenados de un contexto con su estado |
confirm_alignment |
Registra un checkpoint antes de una acción significativa |
record_tool_call |
Registra cada herramienta invocada durante un paso |
advance_step |
Marca el paso actual como completado y activa el siguiente |
skip_step |
Marca un paso como omitido sin ejecutarlo |
create_context |
Crea un nuevo contexto de trabajo con pasos opcionales |
add_step |
Agrega un paso a un contexto existente durante la ejecución |
update_context |
Edita título, descripción o estado de un contexto |
update_step |
Edita título, descripción, notas o agente de un paso |
import_agent_context |
Importa trabajo de un agente externo al historial + ChromaDB |
list_agents |
Lista los agentes (presets de provider/model/system-prompt) registrados |
Instalación automática: ai-orchestrator fix genera el .mcp.json en el proyecto, registra Codex en .codex/config.toml y registra Gemini en ~/.gemini/settings.json. Para Claude global, usá ai-orchestrator fix --global-mcp.
CLI / HTTP Server cli.py · Typer + BaseHTTPRequestHandler
│
├── Router router.py
│ Analiza tarea + context.yaml + keyword_hints
│ Llama a DeepSeek Flash para decidir provider
│ Enforce de step.provider si hay contexto activo
│
├── RAG rag.py · ChromaDB / FTS5 fallback
│ retrieve_docs() — chunks de docs del proyecto
│ retrieve_responses() — respuestas previas similares
│
├── Providers providers/
│ claude.py → Anthropic API
│ openai.py → OpenAI API
│ deepseek.py → DeepSeek API
│ gemini.py → Google Generative Language API
│
├── DB db.py · SQLite WAL
│ runs, contexts, steps, chunks, alignments, tool_calls
│
├── SSE Bus sse.py
│ Eventos: run_started · run_done · run_failed · trace · budget_warning
│
└── Dashboard dashboard.py · HTML server-side + JS vanilla
Dashboard / CLI → submit_run() → Router → RAG retrieval
↓
Dashboard ← SSE ← DB update ← Provider API → Index response
C:\ruta\ai-orchestrator\ ← repo
├── orchestrator\
│ ├── cli.py ← servidor HTTP + comandos Typer
│ ├── router.py ← decisión de proveedor
│ ├── db.py ← SQLite WAL + migraciones
│ ├── rag.py ← ChromaDB / FTS5 fallback
│ ├── tracer.py ← spans al SSE bus
│ ├── background.py ← worker threads
│ ├── dashboard.py ← HTML del panel web
│ ├── sse.py ← Server-Sent Events
│ ├── codex_watcher.py ← importador de sesiones Codex CLI
│ └── providers\ ← claude · openai · deepseek · gemini
└── docs\
├── index.html ← documentación completa en /docs
└── img\ ← banner, logo, favicons
~\.ai-orchestrator\ ← runtime (no versionado)
├── config.yaml ← API keys, modelos, pricing
├── index.yaml ← alias → path de cada proyecto
├── runs.db ← historial SQLite
└── chroma\ ← índice vectorial
mi-proyecto\ ← versionado en cada repo
└── .orchestrator\
└── context.yaml ← stack, convenciones, reglas de ruteo
| Tabla | Contenido |
|---|---|
runs |
Cada llamada a un proveedor. Tokens, costo USD, duración, respuesta completa |
contexts |
Flujos de trabajo multi-paso (título, descripción, estado) |
steps |
Pasos de un contexto. Provider sugerido, orden, estado |
chunks |
Archivos indexados por RAG (proyecto, path, cantidad de chunks) |
alignments |
Checkpoints de alineación confirmados por el agente |
tool_calls |
Herramientas invocadas durante un paso (nombre, input, output, duración) |
ai-orchestrator add mi-proyecto --path "C:\ruta\al\proyecto"
ai-orchestrator list
ai-orchestrator remove mi-proyecto
ai-orchestrator rename mi-proyecto nuevo-alias # renombra alias en índice e historial# El router decide el proveedor automáticamente
ai-orchestrator run --project mi-proyecto --task "revisar el endpoint de login"
# Forzar proveedor
ai-orchestrator run --project mi-proyecto --task "..." --model claude
# Modo investigación (Claude Opus)
ai-orchestrator run --project mi-proyecto --task "..." --researchai-orchestrator serve # http://127.0.0.1:8080
ai-orchestrator serve --port 9090 --no-openEl dashboard tiene dos pestañas:
- Dashboard — tabla de runs en tiempo real, formulario de nueva tarea, panel de detalle, gauge de presupuesto, barra de actividad con spans
- Inspector — estado interno de ChromaDB y SQLite, registro de proyectos con folder picker nativo
Tipo de cambio USD/CLP (opcional): El dashboard incluye un panel para consultar el tipo de cambio vía la API del Banco Central de Chile (
si3.bcentral.cl). Es una feature opcional y específica de Chile — requiere credenciales gratuitas en ese sitio. Usuarios fuera de Chile pueden ignorarla; el resto del dashboard funciona sin configurarla.
La documentación completa está en http://127.0.0.1:8080/docs una vez levantado el servidor.
ai-orchestrator index-docs mi-proyecto
ai-orchestrator index-docs mi-proyecto --exclude "vendor,storage,public/build" # excluir carpetas
ai-orchestrator index-docs mi-proyecto --exclude "vendor" --save # guardar exclusiones en context.yamlSin costo de IA — usa embeddings locales (
all-MiniLM-L6-v2). También disponible desde el Inspector del dashboard. Re-indexar es siempre seguro: el upsert usa IDs determinísticos (proyecto::ruta::chunk_idx), no acumula duplicados.
Parámetros RAG configurables en rag.py:
| Parámetro | Valor | Descripción |
|---|---|---|
_CHUNK_SIZE |
1500 | Caracteres por chunk |
_CHUNK_OVERLAP |
200 | Solapamiento entre chunks |
_DISTANCE_THRESHOLD |
0.9 | Umbral L2 (≈ cosine_sim≥0.60). Bajar = más permisivo |
_MAX_FILE_BYTES |
100 000 | Tamaño máximo de archivo a indexar |
_MAX_PY_FILES |
30 | Máximo de archivos .py por proyecto |
Extensiones indexadas: .md .txt .yaml .yml .toml .rst .json (docs) + .py (código, hasta 30 archivos).
Directorios siempre excluidos: .venv venv __pycache__ .git node_modules vendor build dist .claude .codex .aws .ssh.
Exclusión automática por stack (detectada desde context.yaml):
| Stack | Carpetas sugeridas |
|---|---|
laravel / php |
vendor storage bootstrap |
node / react |
node_modules dist .next build |
python |
.venv venv __pycache__ dist build |
go |
vendor |
ruby |
vendor tmp log |
ai-orchestrator history
ai-orchestrator history --project mi-proyecto --last 50ai-orchestrator create-context mi-proyecto "Implementar autenticación JWT"
ai-orchestrator list-contexts mi-proyectoUn agente es un preset con nombre, global (no por proyecto): opcionalmente fija provider/model y agrega texto al system prompt de la tarea. Es una capa de conveniencia sobre el router — sigue haciendo falta disparar cada run manualmente (CLI, dashboard o MCP), no ejecuta nada de forma autónoma.
ai-orchestrator agents add security-reviewer --provider claude --model claude-opus-4-8 `
--system-prompt-addition "Priorizá riesgos de seguridad y validación de inputs antes que estilo."
ai-orchestrator agents list
ai-orchestrator agents show security-reviewer
ai-orchestrator agents remove security-reviewerSe guardan en ~/.ai-orchestrator/agents.yaml (editable a mano). Para asignar un agente a un paso, usá agent_preset en los tools MCP add_step / update_step / create_context, o el tool list_agents para ver los disponibles. GET /agents expone el registro vía HTTP local.
# Verificar el estado completo del orquestador
ai-orchestrator doctor
ai-orchestrator doctor --verbose # muestra paths, modelos y chunk counts
ai-orchestrator doctor -p mi-proyecto # limitar a un proyecto específico
# Aplicar correcciones automáticas
ai-orchestrator fix # crea .mcp.json + .codex/config.toml + context.yaml faltantes
ai-orchestrator fix --global-mcp # + registra MCP en ~/.claude/settings.json global
ai-orchestrator fix --sync # + importa sesiones Claude Code y commits Git
ai-orchestrator fix --index # + indexa proyectos sin chunks en ChromaDB
ai-orchestrator fix --all # aplica todas las mejoras anteriores juntasdoctor verifica cuatro secciones y muestra ✓ / ⚠ / ✗ por cada ítem:
| Sección | Qué revisa |
|---|---|
| Entorno | Python version, .venv activo |
| Configuración global | config.yaml cargable, API keys de los 3 providers, index.yaml, runs.db, ChromaDB |
| MCP / Claude Code / Codex | .mcp.json en el proyecto, .codex/config.toml, MCP en ~/.claude/settings.json global |
| Proyectos | Ruta existe, context.yaml generado, indexado en ChromaDB |
fix aplica mejoras en orden determinista: .mcp.json → .codex/config.toml → context.yaml → MCP global → sync → index. Salta automáticamente lo que ya está en orden y reporta cada acción tomada.
Dashboard:
doctor,fix,synceindextambién están disponibles como botones en la barra de actividad (franja inferior del dashboard). Los resultados se muestran en tiempo real en el log de actividad sin recargar la página.
# Registrar en el historial una sesión realizada por otro agente
ai-orchestrator import-context mi-proyecto \
--task "revisar performance de queries" \
--response "Se detectaron 3 queries N+1 en el listado de usuarios..." \
--agent deepseek --model deepseek-v4-flash
# Limpiar runs importados de un proyecto/proveedor
ai-orchestrator clear-imports mi-proyecto
ai-orchestrator clear-imports mi-proyecto --provider deepseek# Importar sesiones de Claude Code (~/.claude/projects/)
ai-orchestrator sync-cc # importa sesiones nuevas
ai-orchestrator sync-cc --quiet # para hooks
# Importar sesiones de OpenAI Codex CLI (~/.codex/state_N.sqlite)
ai-orchestrator sync-codex
ai-orchestrator sync-codex --quietIntegración automática con Claude Code — agregar en ~/.claude/settings.json:
{
"hooks": {
"Stop": [{
"matcher": "",
"hooks": [{
"type": "command",
"command": "C:\\Fuentes\\ai-orchestrator\\.venv\\Scripts\\ai-orchestrator.exe sync-cc --quiet"
}]
}]
}
}Los precios efectivos se resuelven con esta precedencia: override en config.yaml → cache local (~/.ai-orchestrator/pricing-cache.json, con TTL) → catálogo remoto (solo si se pide refresh explícito y catalog.allow_remote: true) → catálogo estático bundleado (docs/pricing/models.json) → DEFAULT_PRICING como último fallback. Ver docs/pricing/README.md para el detalle.
ai-orchestrator pricing show # tabla efectiva, fuente y fecha
ai-orchestrator pricing refresh # fuerza refresh remoto si allow_remote está activo
ai-orchestrator pricing validate # modelos usados en runs.db sin precio
ai-orchestrator models refresh # consulta el API de cada proveedor configurado (best-effort)
ai-orchestrator models list # modelos disponibles vs. con precio en el catálogoGET /pricing, POST /pricing/refresh, GET /models y POST /models/refresh exponen lo mismo vía HTTP local.
providers:
claude:
api_key: "sk-ant-..."
model: "claude-sonnet-4-6"
openai:
api_key: "sk-..."
model: "gpt-4o"
deepseek:
api_key: "sk-..."
model: "deepseek-v4-flash"
gemini:
api_key: "AIza..."
model: "gemini-2.5-flash"
router:
provider: "deepseek"
fallback_provider: "claude"
defaults:
default_provider: "claude"
pricing:
claude-sonnet-4-6:
input: 3.00
output: 15.00
cache_write: 3.75
cache_read: 0.30
deepseek-v4-flash:
input: 0.14
output: 0.28
gemini-2.5-flash:
input: 0.30
output: 2.50
gemini-2.5-pro:
input: 1.25
output: 10.00
budgets:
default_daily_budget_usd: 5.00
warning_threshold: 0.80
config.yamlvive en~/.ai-orchestrator/y nunca se versiona. Verconfig.example.yamlpara la plantilla completa ydocs/api-keys.mdpara obtener cada API key.
name: mi-proyecto
stack: PHP/Laravel
description: Aplicación web con autenticación y roles
# Límite de gasto diario en USD para este proyecto (sobreescribe el default de config.yaml)
daily_budget_usd: 2.00
conventions:
- Form Requests para validación
- PSR-12
preferred_models:
default: claude
notes: >
Autenticación y permisos van a Claude.
Tests y seeders pueden ir a DeepSeek.
Refactors frontend van bien con OpenAI.
# Palabras clave que influyen en la decisión del router (weight 1-5)
keyword_hints:
- { match: "seguridad", provider: claude, weight: 3 }
- { match: "test", provider: deepseek, weight: 2 }
- { match: "refactor", provider: openai, weight: 1 }Ver esquema completo en docs/context-schema.md.
La fuente de verdad es el catálogo versionado en docs/pricing/models.json (validado contra docs/pricing/schema.json), no una tabla estática en este README — así no se desincroniza. Para ver los precios efectivos vigentes:
ai-orchestrator pricing showPrecios en USD por millón de tokens. Los modelos Claude soportan cache write/read.
gemini-2.5-prorequiere billing habilitado en Google Cloud — en el free tier la cuota es 0. Usargemini-2.5-flashpara cuentas sin billing.
| Problema | Causa | Solución |
|---|---|---|
ProjectNotFoundError: alias 'X' no está registrado |
El alias no existe en el índice | ai-orchestrator add X --path "C:\ruta" |
ChromaDB no inicializa |
Permisos o directorio faltante | Verificar escritura en ~/.ai-orchestrator/chroma/ |
API key inválida |
Key incorrecta o expirada | Revisar config.yaml, regenerar key en la plataforma |
429 Too Many Requests con Gemini |
Cuota free tier agotada para gemini-2.5-pro |
Usar gemini-2.5-flash (tiene cuota free) o habilitar billing en Google Cloud |
ModuleNotFoundError: chromadb |
ChromaDB no instalado | pip install chromadb — sin él el RAG usa FTS5 como fallback |
| Mojibake en contextos MCP desde Codex (Windows) | sys.stdin hereda encoding cp1252 |
Ya resuelto: el servidor fuerza utf-8 al arrancar. Datos previos: reparar con update_context / update_step |
| Panel de actividad se abre solo | Comportamiento esperado en la primera traza | Colapsarlo manualmente — el estado se respeta para el resto de la sesión |
doctor muestra ✗ en ChromaDB |
ChromaDB no inicializa o colección vacía | Ejecutar ai-orchestrator index-docs <alias> por proyecto |
Ver la guía paso a paso en Quick Start al inicio de este documento.
requirements.txt ya incluye ChromaDB. Sin él el router usa FTS5 (SQLite full-text search) como fallback automático; con él la búsqueda semántica está disponible.
VS Code: Ctrl+Shift+P → Tasks: Run Task → Orchestrator: Dashboard
El orquestador nunca envía datos del proyecto a servidores externos, excepto el texto del prompt al provider elegido (Claude, OpenAI, DeepSeek).
El indexador RAG excluye automáticamente:
- Por nombre de archivo:
.env,credentials.json,id_rsa,secrets.yaml,.npmrc,auth.json,terraform.tfvars, etc. - Por extensión:
.pem,.key,.p12,.pfx,.cer,.crt,.tfstate,.tfvars - Por directorio:
.aws,.ssh,.kube,.gcloud,.claude,.codex - Por contenido: patrones de API keys (Anthropic
sk-ant-..., OpenAIsk-proj-..., MercadoPago) y bloques de clave privada PEM
El dashboard HTTP escucha solo en 127.0.0.1 (loopback). No hay autenticación porque el servidor no es accesible desde la red local ni desde internet.