Orchestra
Hisslyn/orchestra
Fluxos multi-agente Claude via YAML, personas + code workers
Ver no GitHubOrquestrador de fluxos multi-agente com Claude config-driven. Coordena personas assessoras (com transcrição persistente) e subagentes autônomos (workers headless de código), roteando tarefas e mantendo estado compartilhado entre execuções.
Instalação
npx convez-ai Hisslyn/orchestra1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Pipelines de revisão de código com arquitetos e testadores
- Fluxos de auditoria de segurança com personas especializadas
- Automação de tarefas de desenvolvimento com handoff entre agentes
Veredito

Orchestra é uma abordagem sofisticada para orquestração multi-agente, separando pensamento estratégico (personas) de execução (subagentes). Excelente para pipelines complexos, mas requer Python 3.10+, CLI do Claude e compreensão profunda da arquitetura.
README
A tradução para o português deste README ainda está na fila.
Orchestra
Formalized multi-agent Claude workflows from the command line. Orchestra coordinates two kinds of agents: advisory personas (long-lived strategic roles backed by the Anthropic Messages API with persistent transcripts) and autonomous subagents (task-scoped, headless Claude Code workers). All behavior is config-driven: roles, prompts, and handoff rules live in orchestra.config.yaml.
Concept
Real multi-agent work splits naturally into thinking and doing. Personas think: an architect critiques a plan, a security reviewer audits a diff. Subagents do: an implementer writes code, a tester runs and fixes the suite. Orchestra makes that split explicit, routes work between them via handoff rules, and persists shared state so a pipeline survives interruption and can resume.
Architecture
┌──────────────────────────────┐
│ orchestra CLI │
│ (click entrypoint, cli.py) │
└──────┬───────────────┬───────┘
│ │
┌──────────▼─────┐ ┌──────▼──────────┐
│ Config Loader │ │ State Manager │
│ (config.py) │ │ (state.py) │
└──────────┬─────┘ └──────▲──────────┘
│ │ read/write
┌──────────────┼───────────────┤ .orchestra/state.json
│ │ │
┌───────▼────────┐ ┌───▼──────────────┴───┐
│ Persona Runner │ │ Subagent Dispatcher │
│ (personas.py) │ │ (subagents.py) │
│ │ │ │
│ architect │ │ implementer │
│ security-rev. │ │ tester │
└───────┬────────┘ └───────┬──────────────┘
│ advice/verdicts │ spawns
│ ▼
│ claude (Claude Code CLI,
│ headless: -p / --print)
└───────► handoff engine (handoffs.py)
routes (agent, event) → target
The persona / subagent model
| Persona | Subagent | |
|---|---|---|
| Backed by | Anthropic Messages API | Claude Code CLI (headless -p) |
| Lifetime | Whole session (transcript persisted) | One task |
| Output | Advice, verdicts, plans | Code changes, test results |
| State | .orchestra/transcripts/<name>.json | Working dir + .orchestra/logs/ |
Install
pip install orchestra-cli
# or from source:
pip install -e .
Requirements: Python ≥ 3.10; ANTHROPIC_API_KEY exported (personas); claude CLI installed and authenticated (subagents).
Usage
orchestra init # write example config + .orchestra/
orchestra status # agents, rules, pipeline state
orchestra ask architect "Is a queue or a cron job better here?"
orchestra ask architect "" --reset # wipe its transcript
orchestra dispatch implementer --task "Add a /health endpoint"
orchestra run "Add OAuth login" # full pipeline per handoff rules
orchestra run --resume # continue after a failure
orchestra run "goal" --max-steps 6 # tighten the cycle cap
orchestra --config other.yaml status
Configuration
One YAML file defines the whole orchestra. Add a persona or subagent by adding a block and referencing it in handoffs — no code changes.
personas:
architect:
role: Senior software architect.
prompt: |
Produce a verdict (APPROVED or REVISE) and a step-by-step plan.
events: [plan_approved, plan_rejected]
subagents:
implementer:
role: Writes code to satisfy an approved plan.
command: claude
args: ["-p", "--output-format", "json", "--max-turns", "{max_turns}"]
prompt: |
Implement the following plan exactly.
{payload}
events: [done, blocked]
handoffs:
- on: { agent: architect, event: plan_approved }
to: implementer
payload: "{architect.plan}"
Events
Each agent declares its possible outcome events. Convention: events[0] is success, events[1] is failure. Agents may end output with an explicit EVENT: <name> line, which always wins; personas are automatically instructed to do so. Otherwise personas fall back to verdict keywords (APPROVED/REVISE/PASS/FAIL) and subagents map exit status to success/failure events.
Payload variables
| Variable | Resolves to |
|---|---|
{goal} | The goal passed to orchestra run |
{<agent>.output} | That agent's latest output (aliases: .plan, .summary, .report, .findings, .text, .result) |
{git.diff} | git diff HEAD in the project workdir |
{payload} | (subagent prompts) the incoming handoff payload |
{max_turns}, {model} | Values from defaults / agent override |
Unresolved variables are left intact rather than erroring.
Pipeline semantics
orchestra run GOAL starts at the source agent of the first handoff rule, passing the goal as its input. After each step the resulting (agent, event) is matched against the rules; the first match routes a rendered payload to the target. No match ends the pipeline: done normally, stalled if the last event was error. A --max-steps cap (default 10) prevents infinite revision loops. State is persisted to .orchestra/state.json after every step; a crashed step saves a resume point for orchestra run --resume.
Examples
See examples/:
refactor-flow.yaml— reviewer plans, refactorer executes, tester gates behavior.- the default config (
orchestra init) — architect → implementer → tester → security-reviewer with failure loops back to architect/implementer.
Development
pip install -e ".[dev]"
pytest
See CONTRIBUTING.md. MIT licensed.