# Claudebot Workspace
Workspace reorganized to keep the active system separate from older experiments.
## What To Use
- **Referencia primaria de gobernanza**: [docs/PROJECT_CONSTITUTION.md](D:/IA/CODE/claudebot/docs/PROJECT_CONSTITUTION.md).
- **Nombre operativo**: **Sistema local CLI-first para automatización personal en PC**.
- **Prioridades**: operación local primero, CLI-first, routing pragmático.
- [orchestrator/README.md](D:/IA/CODE/claudebot/orchestrator/README.md): núcleo activo de operación local CLI-first con routing pragmático.
- [tools/](D:/IA/CODE/claudebot/tools): external tooling and support repos.
- [.claude/](D:/IA/CODE/claudebot/.claude): local editor and agent config.
- [run_browser.py](D:/IA/CODE/claudebot/run_browser.py): direct browser automation wrapper.
- [run_windows.py](D:/IA/CODE/claudebot/run_windows.py): direct Windows automation wrapper.
- [run_worker.py](D:/IA/CODE/claudebot/run_worker.py): full `worker-core` wrapper.
- [run_agent.py](D:/IA/CODE/claudebot/run_agent.py): high-level recommended entrypoint with locked agent selection.
- [skills_bridge.py](D:/IA/CODE/claudebot/skills_bridge.py): shared bridge to discover, read, and execute local skills from one CLI.
- [self_model/README.md](D:/IA/CODE/claudebot/self_model/README.md): shared self-model used by Claude, Gemini, Codex, and wrappers.
- [self_model_cli.py](D:/IA/CODE/claudebot/self_model_cli.py): inspect or simulate the shared self-model from the repo root.
- [episodic_memory/README.md](D:/IA/CODE/claudebot/episodic_memory/README.md): shared episodic memory for concrete attempts, failures, and fixes.
- [episodic_memory_cli.py](D:/IA/CODE/claudebot/episodic_memory_cli.py): inspect similar past episodes from the repo root.
- [world_model/README.md](D:/IA/CODE/claudebot/world_model/README.md): shared desktop world model for live environment state.
- [world_model_cli.py](D:/IA/CODE/claudebot/world_model_cli.py): inspect the current world-state slice from the repo root.
- [orchestrator/docs/CAPABILITIES_MATRIX.md](D:/IA/CODE/claudebot/orchestrator/docs/CAPABILITIES_MATRIX.md): matriz de capacidades reales vs experimentales del sistema.
- [orchestrator/docs/EXECUTION_HIERARCHY.md](D:/IA/CODE/claudebot/orchestrator/docs/EXECUTION_HIERARCHY.md): pirámide oficial de ejecución, escalado por niveles y fallback extremo mouse/visión.
- [docs/SKILLS_CATALOG.md](D:/IA/CODE/claudebot/docs/SKILLS_CATALOG.md): catálogo de skills operativas (dominio, IO, costo, fallbacks y owner).
- [docs/DEPRECATION_POLICY.md](D:/IA/CODE/claudebot/docs/DEPRECATION_POLICY.md): estados oficiales (`active`, `discouraged`, `deprecated`, `archived`) y checklist de migración.
## Qué NO es
- No es AGI.
- No es mouse-first. **Status: deprecated**
- No es multimodelo por defecto. **Status: discouraged**
## Valor práctico hoy
Este workspace aporta valor cuando te resuelve tareas diarias de forma directa y repetible:
- **Limpieza**: ordenar carpetas de trabajo, mover archivos temporales y dejar resultados en rutas consistentes.
- **Organización**: crear resúmenes, notas operativas y salidas en `tasks/output/` con estructura clara.
- **Instalación**: ejecutar pasos de setup y validaciones básicas de herramientas desde flujos guiados por CLI.
- **Reparación de entorno**: diagnosticar fallos típicos (dependencias, rutas, comandos) y aplicar correcciones verificables.
- **Automatización web**: abrir sitios, extraer datos concretos y guardar resultados sin depender de interacción manual constante.
> **Si esto te ahorra tiempo real, estás en el camino correcto.**
## Archived
- [legacy/](D:/IA/CODE/claudebot/legacy): previous prototypes not used by the current flow. **Status: archived**
## Minimal Structure
```text
claudebot/
|-- orchestrator/ active project
|-- tools/ external utilities and helper repos
|-- legacy/ archived prototypes
|-- self_model/ shared routing self-model
|-- episodic_memory/ shared execution episodes
|-- world_model/ shared desktop world state
`-- .claude/ local config
```
## Natural Language Automation
The main orchestrator now auto-routes plain language desktop and browser tasks.
You do not need to remember prefixes like `browser:` or `windows:`.
Examples:
```bash
cd D:/IA/CODE/claudebot/orchestrator
run_orchestrator.bat "Abre Chrome y ve a https://example.com"
run_orchestrator.bat "Abre Notepad y escribe hola mundo"
run_orchestrator.bat "Abre https://example.com y guarda un resumen en tasks/output/resumen.txt"
```
Behind the scenes:
- browser tasks go to `worker-core:browser`
- Windows desktop tasks go to `worker-core:windows`
- multi-step automation flows go to `worker-core:orchestrator`
The skills taxonomy used by these wrappers is documented in [docs/SKILLS_CATALOG.md](D:/IA/CODE/claudebot/docs/SKILLS_CATALOG.md).
Recommended high-level entrypoint:
```bash
python run_agent.py --agent claude_code --tool auto "Abre https://example.com y extrae el titulo"
python run_agent.py --agent codex_cli --tool browser "Abre https://example.com y extrae el titulo"
python run_agent.py --agent minimax_cli --tool worker "Abre https://example.com y guarda un resumen en tasks/output/resumen.txt"
```
You can still call the low-level wrappers directly if you want explicit control:
```bash
python run_browser.py "Abre https://example.com y extrae el titulo"
python run_windows.py "Abre Notepad y escribe hola mundo"
python run_worker.py "Abre https://example.com y guarda un resumen en tasks/output/resumen.txt"
```
## Shared Skill Bridge
The workspace now includes a local bridge that can discover and reuse skills across:
- `gemini_skills/` for compatible executable skills,
- `skills/` and `skills/.codex/skills/` for `SKILL.md`-based skills,
- `legacy/local-agent/SKILLS/`,
- packaged skills under `tools/browser-use/skills/` and related tooling.
Examples:
```bash
python skills_bridge.py list gemini --limit 10
python skills_bridge.py suggest "Necesito automatizar browser y extraer datos"
python skills_bridge.py show gemini.mouse
python skills_bridge.py run gemini.mouse -- --request-json "{\"x\":0.5,\"y\":0.8,\"coordinate_space\":\"normalized\",\"action\":\"move\"}"
python gemini_bridge.py skills gemini --limit 10
python gemini_bridge.py skill-info gemini.chatgpt --content
python gemini_bridge.py skill-run gemini.vision_world
```
Operational rule:
- `instruction` skills are discoverable and readable through the bridge.
- `executable` skills can be launched through the bridge.
- The orchestrator now injects relevant skill matches into model context alongside self-model, episodic memory, and world model.
For direct coordinate-driven desktop control with calibration and verification:
```bash
python run_mouse.py 960 540 --action click --label "boton enviar" --verify cursor
python run_mouse.py 640 360 --action click --coordinate-space image --image-path screenshot.png --verify screen_change
python run_mouse.py --request-json "{\"x\":0.5,\"y\":0.8,\"coordinate_space\":\"normalized\",\"action\":\"move\"}"
```
`run_mouse.py` stores a learned calibration profile per app and resolution, retries around the predicted point, and records successes/failures into the shared self-model and episodic memory.
Status: **deprecated** as default strategy; keep only as explicit fallback for cases where CLI/browser/OS routes are not viable.
## Telegram Voice Notes
`telegram_bridge.py` now accepts Telegram `voice` and `audio` messages.
The bridge downloads the note, transcribes it locally with Whisper, and then sends the transcript through the same Gemini CLI flow used by plain text messages.
Recommended local runtime:
- `faster-whisper` on CTranslate2.
- Default bridge config is `tiny` + `cpu` + `int8` to keep GPU impact close to zero while still supporting Spanish and other multilingual voice notes.
- If you want a newer and more accurate model later, set `TELEGRAM_WHISPER_MODEL=turbo`, but expect much higher memory usage.
Install:
```bash
pip install faster-whisper
```
Optional `.env` overrides:
```bash
TELEGRAM_WHISPER_MODEL=tiny
TELEGRAM_WHISPER_DEVICE=cpu
TELEGRAM_WHISPER_COMPUTE_TYPE=int8
TELEGRAM_WHISPER_LANGUAGE=es
TELEGRAM_WHISPER_BEAM_SIZE=1
TELEGRAM_WHISPER_DOWNLOAD_ROOT=D:/IA/CODE/claudebot/models_stt/whisper
TELEGRAM_WHISPER_VAD_FILTER=true
```
## Capacidades avanzadas (secundario)
Estos componentes son útiles, pero no son el núcleo del valor diario:
- `self_model/` para conocimiento acumulado de routing.
- `episodic_memory/` para reusar aprendizajes de ejecuciones previas.
- `world_model/` para estado operativo compartido entre agentes.
Si tu caso de uso principal es productividad cotidiana, empieza por el flujo CLI-first y añade estas capas cuando ya tengas una rutina estable.
## Shared Self-Model
The repo now includes a live `self_model/` directory at the root.
This is the explicit model of how the system understands itself.
It is shared across:
- Claude-style orchestrator runs
- Gemini bridge runs
- Codex or other CLI agents using the root wrappers
Examples:
```bash
python self_model_cli.py summary
python self_model_cli.py plan "Fix this broken project and validate the output"
python gemini_bridge.py auto "Abre Chrome y ve a https://example.com"
python run_browser.py --agent codex_cli "Abre https://example.com y extrae el titulo"
```
The key point is that routing decisions and outcomes now update the same structured state instead of living only in ad-hoc logs.
## Episodic Memory
The repo now also includes a separate `episodic_memory/` layer.
This is not the self-model.
- `self_model/` answers "what am I generally good or bad at?"
- `episodic_memory/` answers "what happened last time in a similar task, app, page, or failure?"
Each episode can store:
- attempted task
- executed steps
- app, web, and screen context
- exact failure
- working fix or successful route
Examples:
```bash
python episodic_memory_cli.py summary
python episodic_memory_cli.py find "Abre Chrome y ve a https://example.com y revisa el login" --task-type browser_automation
```
Claude-style orchestrator runs, Gemini bridge runs, and the root wrappers all write into the same episodic layer.
## World Model
The repo now also includes a separate `world_model/` layer.
This is the live desktop/browser/filesystem state that agents can consult before acting.
It tracks things like:
- open apps
- active window
- files created or touched
- downloads in progress
- browser tabs associated with tasks
- pending objectives
Examples:
```bash
python world_model_cli.py summary --refresh
python world_model_cli.py focus "Abre Chrome y ve a https://example.com y guarda un resumen"
```
The main orchestrator, Gemini bridge, and root wrappers all update the same shared world state.
Ler o README original