convez.ai
AgenteAutomaçãoAvançado
johnayoung

Flywheel

johnayoung/flywheel

Orquestrador paralelo para agentes de IA com worktrees isoladas

Ver no GitHub
InicialPluginScore · de 0 a 100

Orquestrador de produção para agentes de IA em codificação, executando tarefas paralelas em worktrees git isoladas com escalonamento ciente de dependências, validação automatizada e recuperação de falhas. Combina event sourcing com reatividade para garantir consistência entre múltiplos workers.

Instalação

$npx convez-ai johnayoung/flywheel

1 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

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 dia
Versão
v0.6.1
Issues abertas
0
Contribuidores
1

Casos de uso

  • Executar múltiplos agentes de IA em paralelo de forma segura
  • Escalonar tarefas com dependências entre agentes
  • Validar resultados de agentes com graders customizáveis
  • Recuperar-se automaticamente de falhas e crashes

Veredito

Solução robusta e bem arquitetada para orquestração de múltiplos agentes de IA em paralelo, com garantias forte via event sourcing. Ainda em pré-release (WIP), requer pinning a commits específicos; adequada para equipes que precisam coordenar múltiplos agentes de codificação com dependências complexas.

README

A tradução para o português deste README ainda está na fila.

Flywheel

Production-grade orchestration loop for AI coding agents.

Status: pre-release (WIP)

Flywheel is under active development. Public APIs, task and lifecycle schemas, CLI flags, and on-disk layouts may change without notice between commits. Pin to a specific commit if you depend on this code, and expect breaking changes until a tagged 1.0 release.

Architecture

Flywheel is layered. A consumer decides which task to run; a single-task loop owns executing one task; an event-sourced store is the source of truth; a reactive layer pushes change to followers.

  • Harness (flywheel.harness.run_task) is the sole owner of lifecycle transitions. It invokes the agent, parses the LOOP_STATUS envelope (agent claims are untrusted), verifies the result through cost-ordered graders, and decides the next transition — done, retry, fail, or pause.
  • Event-sourced lifecycle. Every state change is appended to a domain-event log; the lifecycle and its attempts are projections folded from that log, so state and timeline can never diverge. Grader receipts and the agent transcript are recorded alongside as append-only history.
  • Reactivity. A notifier signals on every store write — in-process, or across hosts via Postgres LISTEN/NOTIFY — so followers react instead of polling. Read-only subscribers observe the audit stream without ever touching authoritative state.
  • Orchestrator (flywheel.orchestrator) reads authoritative state to promote tasks whose prerequisites are done, leases each task so multiple workers never run the same one, and reactively unblocks and resumes paused work — without ever transitioning a lifecycle itself.
flowchart TB
    Task["Task (immutable)<br/>goal · graders · prerequisites"]

    subgraph Consumer["Consumer layer · flywheel.orchestrator"]
        Orch["Orchestrator<br/>promote tasks whose prerequisites are done<br/>lease each task · multi-worker safe<br/>reactively unblock + resume"]
    end

    subgraph HarnessLoop["Single-task loop · run_task — sole owner of transitions"]
        Invoke["Invoke agent (claude-agent-sdk)"]
        Env["Parse LOOP_STATUS envelope<br/>verify · blocked · continue · abort"]
        Grade["Verify, cost-ordered<br/>command → transcript → rubric"]
        Decide["Decide transition<br/>done · failed · failed_validation · interrupted · retry"]
        Invoke --> Env --> Grade --> Decide
    end

    subgraph StoreBox["Event-sourced store · SQLite / Postgres / in-memory"]
        Log[("Domain-event log<br/>append-only · source of truth")]
        Proj["Projections (fold of the log)<br/>lifecycle · attempts"]
        Audit["Audit stream + receipts<br/>telemetry · agent messages · grader results"]
        Log -->|fold| Proj
    end

    subgraph ReactBox["Reactivity & extensibility"]
        Notify["RunNotifier<br/>in-process + Postgres LISTEN/NOTIFY"]
        Subs["Read-only subscribers<br/>plugins · loggers · dashboards"]
    end

    Task --> Orch
    Orch -->|run or resume one task| Invoke
    Decide -->|append domain event| Log
    Grade -->|telemetry · messages · receipts| Audit
    Proj -. authoritative read .-> Orch
    Audit -. notifies .-> Notify
    Notify --> Subs
    Notify -. wake .-> Orch

See docs/task-lifecycle.md for the lifecycle state machine and docs/vision.md for the design principles.

Quickstart

All paths and commands below are relative to the repo root.

1. Confirm Python 3.13. Flywheel requires Python 3.13 or newer; check with python3 --version before continuing.

2. Install uv, then clone and install dependencies:

git clone https://github.com/johnayoung/flywheel
cd flywheel
uv sync

3. Write a minimal task.json at the repo root:

{
  "id": "readme-quickstart",
  "goal": "Print the string 'hello flywheel' to stdout.",
  "graders": [
    {
      "type": "command",
      "name": "smoke",
      "run": "echo hello flywheel | grep -q 'hello flywheel'"
    }
  ]
}

4. Run the task through the workflow CLI:

uv run python -m flywheel.workflow run task.json

The command exits 0 when the lifecycle reaches done and non-zero otherwise. Lifecycle state is persisted to .flywheel/flywheel.sqlite.

For operator workflows above a single task (initializing a project, driving a phase, observing live runs), use the unified product shell:

uv run flywheel init                # scaffold .flywheel/ + flywheel.toml
uv run flywheel worker              # drive the active phase to quiescence
uv run flywheel status              # snapshot every active task
uv run flywheel                     # operator console (alias: fw)

flywheel and fw are byte-identical entries on one implementation.

Documentation

Contributing

Issues and pull requests are welcome at https://github.com/johnayoung/flywheel. Read CONTRIBUTING.md first for dev setup, test commands, and the commit-message convention.

License

License: TBD. No LICENSE file ships with this repository yet -- do not assume any license is granted for reuse or redistribution.

Ver o original no GitHub

Bom para

Relacionados