forgex 0.1.0

Multi-agent AI orchestration system for software development

forge-ai

Sistema multi-agente de orquestacion IA para desarrollo de software. Planifica, ejecuta y monitorea trabajo en multiples proyectos simultaneamente con un equipo de agentes Claude.

---

Que es esto

Un CLI llamado forge que:

1. Guia tu trabajo — forge start abre una sesion interactiva que te lleva de la mano
2. Despacha agentes de Claude para ejecutar tareas en paralelo
3. Monitorea todo en un dashboard web cyberpunk en tiempo real
4. Aprende de errores — los agentes se retroalimentan con lessons learned

---

Prerequisitos

• Python 3.10+
• Claude Code — npm install -g @anthropic-ai/claude-code

Instalacion

# Desde PyPI (cuando este publicado)
pipx install forge-ai[all]

# Modo desarrollo
git clone <este-repo>
cd sistema-gestion-de-tareas
pip install -e ".[all]"

---

Como se usa

Setup (una sola vez)

python -m forge start
# Primera vez: pregunta donde estan tus proyectos (default: ~/Jose)
# Crea la DB central y registra los proyectos existentes

Flujo diario

Terminal 1: python -m forge run          <- daemon + dashboard (queda corriendo)
Terminal 2: cd ~/Jose/mi-proyecto
            python -m forge start        <- el agente te guia

Eso es todo. Dos terminales:

• Terminal 1 vigila todos los proyectos y lanza agentes automaticamente. El dashboard se abre en http://127.0.0.1:8787.
• Terminal 2 (o mas) es donde vos planificas. Vas a la carpeta del proyecto, forge start, y el orchestrator te pregunta que necesitas.

---

forge start — El comando principal

Desde cualquier carpeta de proyecto:

cd ~/Jose/gya-website
python -m forge start

El orchestrator detecta automaticamente:

• Carpeta con codigo sin tareas — ofrece analizar el proyecto y crear tareas
• Proyecto con tareas pendientes — muestra estado y pregunta que hacer
• Carpeta vacia — pregunta que queres construir

No hay flags, no hay opciones. Solo forge start y el agente se encarga.

---

Comandos rapidos (sin sesion Claude)

python -m forge status              # Estado del proyecto actual
python -m forge status --all        # Todos los proyectos
python -m forge list                # Tareas del proyecto actual
python -m forge list --all          # Todas las tareas
python -m forge add "algo" -p high  # Agregar tarea rapida
python -m forge run                 # Daemon + dashboard
python -m forge dashboard           # Solo dashboard

Desde una carpeta de proyecto, no necesitas --project — se auto-detecta.

---

Agentes

Se descubren automaticamente de ~/.forge/agents/. Para agregar uno nuevo, crea un .md ahi.

Agente	Especialidad	Modelo
project-scaffolder	Setup, estructura, CI/CD	sonnet
api-designer	APIs, schemas, endpoints, DB	sonnet
test-engineer	Tests, coverage, QA	sonnet
refactorer	Reestructurar codigo	sonnet
debugger	Bugs, root cause analysis	opus

---

Dashboard

Se abre automaticamente con forge run. Vista de arbol cyberpunk con:

• Proyectos, agentes y tareas en tiempo real
• Animaciones neon con particulas
• Click en agente para ver mini terminal
• Pan/zoom para navegar

---

Cadena de escalacion

Cuando un agente falla:

1er intento  ->  Reintento con contexto del error
2do intento  ->  Escalar a agente especialista (debugger)
3er intento  ->  Marcar como BLOCKED + registro en lessons learned

Las lessons learned se inyectan en futuros prompts para no repetir errores.

---

Arquitectura

~/.forge/
  central.db          # DB centralizada (SQLite + SQLModel + Alembic)
  config.toml         # Configuracion (workspace, agents path)
  agents/             # Definiciones de agentes (.md)

Cada proyecto:
  .forge/config.json  # Marker con project_id (link a central.db)

Todo conecta a la DB central. El daemon, el dashboard, y el CLI leen/escriben ahi. WebSocket con change_counter para updates en tiempo real.

---

Desarrollo

pip install -e ".[dev,dashboard]"
python -m pytest tests/ -v          # 243 tests
python -m forge --help              # Ver todos los comandos