orchestrador 3.0.0
Pipeline de Jobs com SQLite e Auto-Recovery para CLIs de código
License: MIT
Requires Python: >=3.10
Keywords: orchestrator, pipeline, jobs, claude, codex, ai

# Orchestrador v3

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**🇧🇷 [Português](README_pt-BR.md)** | 🇺🇸 English

Job Pipeline with SQLite and Auto-Recovery for code CLIs (Claude Code, Codex CLI).

## ✨ Features

- **Job Pipeline**: Execute multiple jobs in sequence with dependencies
- **SQLite Persistence**: State preserved between restarts
- **Auto-Recovery**: Interrupted jobs are detected and can be resumed
- **Auto-Review**: Automatic build, tests, and code review after each task
- **Multiple CLIs**: Support for Claude Code and Codex CLI
- **Notifications**: Webhook to notify when jobs finish (with channel support)
- **Concurrency**: Run multiple pipelines simultaneously
- **18 Built-in Skills**: Code patterns, security, TDD, and more

## 📦 Installation

```bash
# Via pip (recommended)
pip install orchestrador

# Via pip local (development)
pip install -e /path/to/orchestrador

# Via pip + git
pip install git+https://github.com/Lordymine/orchestrador.git
```

### OpenClaw Integration

After installing, run to add the skill to OpenClaw:

```bash
# Install the orchestrator-client skill
orchestrador install-skill

# The skill allows the OpenClaw agent to control the orchestrator
# Enable in openclaw.json:
# "skills": {"allowBundled": ["orchestrator-client"]}
```

## 🚀 Usage

### CLI

```bash
# Start server
orchestrador start

# Check status
orchestrador status

# View logs
orchestrador logs -f

# Stop server
orchestrador stop

# Recover interrupted jobs
orchestrador recover --auto-retry
```

### API

The server exposes a REST API on port 8765 (configurable):

```bash
# Create job with callback
curl -X POST http://localhost:8765/execute \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "backend",
    "projeto": "my-app",
    "descricao": "Create REST API with Express + TypeScript",
    "callback_session": "agent:main:main",
    "callback_channel": "telegram",
    "callback_to": "123456789"
  }'

# Create pipeline
curl -X POST http://localhost:8765/pipeline \
  -H "Content-Type: application/json" \
  -d '{
    "jobs": [
      {"tipo": "architecture", "projeto": "my-app", "descricao": "Initial setup"},
      {"tipo": "backend", "projeto": "my-app", "descricao": "Create API"},
      {"tipo": "review", "projeto": "my-app", "descricao": "Code review"}
    ],
    "callback_session": "agent:main:main",
    "callback_channel": "telegram",
    "callback_to": "123456789"
  }'

# List pipelines
curl http://localhost:8765/pipelines

# Check job status
curl http://localhost:8765/jobs/{job_id}

# Retry failed job
curl -X POST http://localhost:8765/jobs/{job_id}/retry

# Recover interrupted jobs
curl -X POST http://localhost:8765/recover?auto_retry=true
```

## ⚙️ Configuration

Environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `ORCHESTRADOR_PORT` | `8765` | Server port |
| `ORCHESTRADOR_HOST` | `127.0.0.1` | Server host |
| `PROJECTS_DIR` | `~/workspaces/projects` | Projects directory |
| `JOBS_DIR` | `~/.openclaw/orchestrador/jobs` | SQLite database directory |
| `GATEWAY_URL` | `http://127.0.0.1:18789` | Gateway URL for webhooks |
| `GATEWAY_HOOK_TOKEN` | `orchestrador-hook-token` | Authentication token |

## 📋 Job Types

| Type | CLI | Description |
|------|-----|-------------|
| `backend` | Claude | Backend, API, services |
| `frontend` | Claude | UI, components |
| `fullstack` | Claude | Complete projects |
| `database` | Claude | Schemas, migrations |
| `api` | Claude | REST endpoints |
| `architecture` | Claude | Initial setup, structure |
| `landing` | Claude | Landing pages |
| `ui` | Claude | UI/styling |
| `devops` | Claude | CI/CD, Docker, infra |
| `review` | Codex | Code review |
| `security` | Codex | Security analysis |
| `bugfix` | Codex | Bug fixes |
| `refactor` | Codex | Refactoring |
| `docs` | Codex | Documentation |
| `e2e` | Codex | E2E tests |
| `analysis` | Codex | Code analysis |

## 🔔 Callback Notifications

The orchestrator can notify users when jobs complete:

```json
{
  "callback_session": "agent:main:main",
  "callback_channel": "telegram",
  "callback_to": "123456789"
}
```

Supported channels: `telegram`, `whatsapp`, `discord`, `slack`, `signal`

## 📚 API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/execute` | Start async job |
| POST | `/execute/sync` | Execute and wait |
| POST | `/pipeline` | Create job pipeline |
| GET | `/jobs` | List all jobs |
| GET | `/jobs/{id}` | Job status |
| GET | `/jobs/interrupted` | Interrupted jobs |
| POST | `/jobs/{id}/retry` | Re-execute job |
| GET | `/pipelines` | List pipelines |
| GET | `/pipelines/{id}` | Pipeline status |
| POST | `/recover` | Recover interrupted jobs |
| GET | `/stats` | Database statistics |
| POST | `/cleanup?days=30` | Remove old jobs |
| GET | `/skills` | List skills |
| GET | `/types` | List job types |
| GET | `/health` | Health check |

## 🔧 Development

```bash
# Clone repository
git clone https://github.com/Lordymine/orchestrador.git
cd orchestrador

# Create venv
python3 -m venv venv
source venv/bin/activate

# Install in dev mode
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src/
ruff check src/ --fix
```

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

---

Made with ⚡ by [Lex Luthor Bot](https://github.com/Lordymine)