convez.ai
AgenteAutomaçãoAvançado
NeuraCerebra-AI

OpenWeft — Orchestração de Agents de Código

NeuraCerebra-AI/openweft

Batch scheduling resiliente para coding agents com isolamento, checkpoints e merge reconciliation

Ver no GitHub
BomPluginScore · de 0 a 100

Sistema de batch scheduling e recuperação para agents de codificação que transforma uma lista de objetivos em Work Briefs duráveis, executa tarefas Claude Code/Codex em worktrees isoladas e preserva estado para recuperação após crashes. Planeja, executa e reconcilia merges automaticamente sem intervenção.

Instalação

$npx convez-ai NeuraCerebra-AI/openweft

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
1
Acompanhando
0
Saúde
57%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Executar múltiplas features de forma paralela respeitando dependências de arquivo
  • Recuperar automaticamente de crashes mantendo checkpoints e auditoria completa
  • Orquestrar tarefas de refatoração com isolamento em git worktrees
  • Gerenciar backlog de requisições de features com scheduling inteligente baseado em conflitos

Veredito

OpenWeft é uma solução robusta de orquestração real para agents de código, não um wrapper de prompt. Ideal para times que precisam executar múltiplas tarefas de codificação em batch com resiliência, auditoria completa e resolução automática de conflitos — exige confiança no sistema e compreensão da arquitetura subjacente.

README

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

OpenWeft — coding-agent batch scheduling and recovery

OpenWeft is a batch scheduler and recovery layer for coding agents: it turns a list of your entered goals into durable Work Briefs, runs non-conflicting Claude Code/Codex tasks in isolated worktrees, and preserves enough state to recover through crashes, conflicts, and merge reconciliation.

You write a list. You walk away. You come back to commits.

It runs on your existing subscription by default. No API keys required unless you opt into API-key auth.

It is not a replacement for Claude Code or Codex. It is the missing batch-control layer around them: planning, phasing, worktree isolation, checkpoint recovery, merge reconciliation, and auditability.

Architecture deep dive: OpenWeft is designed as a real orchestration system, not a prompt wrapper. See ARCHITECTURE.md for the full breakdown of the planning compiler, scoring algorithm, phase scheduler, worktree isolation, checkpoint recovery, finalization, and runtime diagnostics.

Quick start

npm install -g openweft
openweft                                  # wizard on first run

Queue some features, then let it rip:

openweft add "add password reset flow"
openweft add "refactor auth middleware"
openweft add "add audit log export"
openweft start
$ openweft status

Health: Completed
Meaning: All schedulable work in the current checkpoint has finished.
Next Action: Review the completed features, merge output, and audit trail before adding more work.
Status: completed
Machine State: idle
Background: not running
Pending Queue: 0
Processed Queue Entries: 3
Features: 3 total (3 completed)
Tokens: 384000 input / 4000 output
Completed:
  [001] Add password reset flow (high 0.891)
  [002] Add audit log export (high 0.912)
  [003] Refactor auth middleware (medium 0.544)

Features 1 and 2 ran in parallel — no file overlap. Feature 3 touched the same auth files, so OpenWeft queued it for the next batch and re-planned against the merged code. Three features, two batches, zero babysitting. Status starts with health, meaning, and a safe next action before raw details and token counts.

When to use OpenWeft

✅ Good Fit

  • You have a backlog of independent or semi-independent feature requests.
  • Some tasks may touch overlapping files and need scheduling before execution.
  • You want agents isolated in git worktrees, merged in priority order, and resumed after crashes.
  • You want an inspectable trail of plans, manifests, ledgers, checkpoints, and audit events.

⚠️ Not A Fit

  • You need one quick edit; run Codex or Claude directly.
  • You want interactive pair-programming instead of batch execution.
  • Your repository cannot use git worktrees.
  • You expect a polished 1.0 product surface.

Requires Node.js >=24, Git, and one or both of codex / claude already logged in.


What OpenWeft proves

OpenWeft is an orchestration layer for coding agents, not a prompt wrapper and not another general-purpose agent framework.

Its core claim is narrow: when you have a backlog of coding tasks, the hard part is not merely launching several agents. The hard part is deciding which tasks can safely run together, preserving enough state to recover after failure, and merging the finished work without losing context.

OpenWeft turns raw feature requests into durable Work Briefs and execution plans, schedules them by file-level risk, executes each feature in a separate git worktree, merges completed branches in priority order, and keeps enough state on disk to recover after interruptions.

The core design separates model cognition from orchestration control:

LayerResponsibility
Prompt pipelineConvert requests into worker briefs, then executable plans.
Domain modelScore risk, detect manifest overlap, assign phases, classify failures.
OrchestratorDrive the planning, execution, merge, re-analysis, and recovery loop.
Git layerOwn worktree lifecycle, dirty-tree-safe merges, conflict handling, and cleanup.
State layerPersist strict checkpoints, token usage, audit events, Work Briefs, plans, and recovery artifacts.
Adapter layerNormalize Codex CLI, Claude Code, and deterministic mock execution behind one contract.

For the full architecture, see ARCHITECTURE.md.


Core loop

Queue -> Plan -> Score -> Phase -> Execute -> Merge -> Re-plan -> Checkpoint
          ^                                                |
          └──────────────── repeat until queue empty ──────┘

Each queue item becomes a feature plan. Each plan declares the files it expects to create, modify, or delete. OpenWeft scores those plans by risk, groups non-overlapping features into execution phases, launches each feature in an isolated worktree, merges completed branches back to the base branch, feeds real edit summaries into remaining plans, and repeats until no runnable work remains.

The normal path is batch-oriented, but not blind. Every stage produces durable artifacts under feature_requests/ or .openweft/, so the system can explain what it tried, what changed, and what still needs attention.


Planning pipeline

OpenWeft uses a two-stage planning compiler:

Raw request
  -> Brief Compiler
  -> Work Brief
  -> Feature Plan
  -> ## Ledger + ## Manifest

Stage 1 sends the raw request through the Brief Compiler (prompts/prompt-a.md). The compiler does not implement the feature; it generates a Work Brief, a detailed operating brief saved under feature_requests/briefs/.

Stage 2 sends the Work Brief to the selected backend. The result is a Markdown feature plan saved under feature_requests/, validated as an execution artifact instead of treated as disposable chat output.

Every plan must include a manifest:

{
  "create": [],
  "modify": [],
  "delete": []
}

The manifest is parsed structurally with remark, validated with strict Zod schemas, and repaired with jsonrepair / JSON5 fallback when possible. If OpenWeft can only recover a manifest from a last-known-good fallback, it preserves that stale provenance and moves the feature to review instead of silently scheduling it. Every plan also needs a ## Ledger section with reconstructible Constraints, Assumptions, Watchpoints, and Validation anchors, making execution inspectable before agents touch code.


Scheduling and conflict avoidance

OpenWeft treats parallel coding as a scheduling problem. It does not simply launch a group of agents and hope git sorts it out later.

MechanismWhat it doesWhy it matters
Manifest overlap detectionCompares create, modify, and delete paths across plans.Features that touch the same file never run in the same phase.
Hot-file isolationIsolates schema migrations, config/CI files, and high-fan-in shared libraries.Changes to central files get serialized even when manifests do not collide.
Blast-radius scoringWeighs file type, operation type, fan-in, and directory spread.Risky work is visible to the scheduler before execution begins.
Success likelihoodPenalizes broad, modification-heavy, external-API-heavy, high-coupling work.Smaller and safer tasks can land first.
EWMA + hysteresisSmooths priority changes and prevents tier flicker across cycles.Re-planning stays stable instead of bouncing between noisy rankings.

OpenWeft ranks features with a score designed to favor work that is likely to land cleanly without ignoring important high-impact changes:

rawPriority = successLikelihood / (normalizedBlastRadius^0.6 + 0.01)

blastRadius comes from the files in the manifest: schema migrations, config/CI, shared libraries, high-fan-in modules, broad directory spread, and operation type all affect risk. successLikelihood starts from a baseline and is reduced for wide file counts, heavy modification ratios, external API work, high coupling, and complex plans. The ^0.6 exponent means blast radius matters, but does not dominate the queue so completely that a large-but-straightforward feature can never move.

After the first scoring passes, OpenWeft smooths priority with EWMA and assigns tiers with hysteresis. In plain English: priorities can change when the repository changes, but they do not jitter wildly between phases. That matters because every merge feeds real edit summaries back into the remaining plans before the next phase runs.

The phasing algorithm is intentionally conservative:

for feature in priority order:
  if feature touches hot files:
    isolate in its own phase
  else if a phase has capacity and no manifest overlap:
    add feature to that phase
  else:
    create the next phase

Example:

FeatureManifest filesPhase
Password resetsrc/auth/reset.ts, src/email.ts1
Audit exportsrc/audit/export.ts1
Auth middleware refactorsrc/auth/middleware.ts, src/auth/reset.ts2

The first two features can run together. The third overlaps with the password-reset work, so it waits for the next phase and re-plans against the merged result.


Execution and merge safety

Each feature gets its own physical git worktree under .openweft/worktrees/:

base branch
  ├─ .openweft/worktrees/001 -> feature branch -> merge --no-ff
  ├─ .openweft/worktrees/002 -> feature branch -> merge --no-ff
  └─ .openweft/worktrees/003 -> waits for re-plan

The orchestrator owns topology. Workers are told to use the assigned worktree only; they do not create extra branches, clone the repo, or decide where their output lands.

Merges happen back on the base branch in priority order using --no-ff, preserving a visible merge commit for each completed feature. If your base branch has staged, unstaged, or untracked changes, OpenWeft stashes them before merge and restores them afterward. If a merge conflicts, OpenWeft aborts the base merge, stages the base changes into the feature worktree, asks the agent to resolve the conflict with the original plan context, commits the resolution, and retries within bounded reconciliation rounds.

On resume, OpenWeft can also detect reusable completion commits. If a worker already finished before the process died, the system queues that branch for merge recovery instead of spending another agent run on identical work.


Recovery model

Fire-and-forget only works if the process can survive bad timing: terminal exits, Ctrl+C, power loss, background jobs, and half-finished agent sessions.

ArtifactPurpose
.openweft/checkpoint.jsonCurrent run state, feature statuses, phase, queue order, merge summaries, and usage totals.
.openweft/checkpoint.json.backupLast known checkpoint fallback.
.openweft/audit-trail.jsonlAppend-only event history for real runs.
.openweft/costs.jsonlToken usage per agent call.
feature_requests/*.mdValidated Markdown execution plans.
feature_requests/briefs/*.work-brief.mdDurable Work Briefs.
.openweft/shadow-plans/Internal mirrors used during execution and recovery.
.openweft/evolved-plans/Worktree-updated plans preserved when merge or reconciliation cannot safely promote them.
.openweft/codex-home/Minimal isolated Codex homes for worker turns; cleaned after successful runs by default.

Checkpoint writes are atomic and Zod-validated. The first save seeds both primary and backup checkpoints; later saves keep the previous primary as the backup snapshot. Loading prefers the primary checkpoint, falls back to the backup if the primary is corrupt, and rejects unexpected schema fields.

Recovery is conservative about your work in three specific ways. Worktree and branch identity is persisted to the checkpoint the moment a worktree is created, so a crash mid-phase cannot orphan a finished feature branch. Startup pruning never force-deletes a branch that has commits not merged into the base — even when the checkpoint is missing or was deleted. And queue rewrites re-read queue.txt immediately before each write, so requests you add while planning is running (or while a crashed run is down) survive instead of being clobbered.

openweft start and openweft resume use the same checkpoint path. If a stopped checkpoint still has actionable work, OpenWeft reopens it, records run.resumed_from_stopped in the audit trail, and continues from persisted state. In-flight features reset to planned unless OpenWeft can prove there is already a reusable completion or recorded merge. Clean re-execution from the persisted Work Brief, plan, and checkpoint is safer than trying to resurrect half-valid model context.

Completion is also verified after the run. OpenWeft checks that recorded merge commits are reachable from final HEAD; if durability verification fails, the run is downgraded instead of pretending success.


Runtime model

OpenWeft piggybacks on the agent CLIs you already use.

BackendAuth modesNotes
Codex CLIsubscription or api_keyUses your existing Codex CLI login by default.
Claude Codesubscription or api_keyUses your existing Claude Code login by default.
MocknonePowers --dry-run and deterministic tests.

A standard subscription CLI login is enough. API keys are optional if you want that deployment model, but not required for normal use. Status output reports input and output tokens, not speculative subscription-price estimates.

The adapter contract normalizes command construction, working directory, prompts, model, effort level, auth, sandbox mode, session reuse, token usage, and classified failure results across backends.


Operational guardrails

OpenWeft has explicit boundaries for failure and retry behavior:

GuardrailBehavior
Failure taxonomyErrors are classified as transient, agent, or fatal, with auth, permission, missing-command, disk, config, and template failures treated as setup blockers.
Retry policyRetryable execution failures can reset the worktree and rerun within configured limits.
Review statesUnsafe planning or adjustment results become planning-needs-review or adjustment-needs-review instead of being silently scheduled or skipped.
Continue unrelated workA terminal failed feature blocks overlapping work as blocked-by-failed-feature, while unrelated eligible features may continue. The final run still reports failed until unresolved work is handled.
Circuit breakerExcessive failures can stop the run rather than burning through the rest of the queue.
Bounded conflict resolutionMerge conflicts get a limited number of agent-assisted resolution rounds.
Post-merge re-analysisRemaining plans whose manifests overlap with real changed paths get adjusted before execution.
Token accountingEvery agent call records input and output tokens by stage and feature.
Honest exit codesRuns that end failed — real, dry-run, streamed, or TUI — exit non-zero, as does a stop that had to force-kill. openweft start && deploy actually gates.
Run identityPID records carry process identity (start time + marker), so stop/status never signal or trust a recycled PID. Stop escalation also terminates agent subprocess groups, not just the orchestrator.
Repo hygiene.openweft/ runtime artifacts are excluded from feature commits via the shared git exclude file plus commit-time filtering, and never count as agent work.

This is the main distinction: OpenWeft operationalizes AI coding agents as schedulable workers. The model performs cognition inside a bounded worktree; the orchestrator owns state, ordering, recovery, and reconciliation.


Commands

Common flow:

openweft init
openweft add "add password reset flow"
openweft start --dry-run
openweft start
openweft resume
openweft status
openweft stop

Full command reference:

openweft                       setup wizard (first run) · dashboard (returning)
openweft init                  set up config, directories, prompts, and work protocol
openweft add "feature"         queue a request (also accepts stdin)
openweft start                 run the queue with interactive dashboard
openweft resume                alias for start; resumes through the same checkpoint path
openweft start --model gpt-5.5 run once with a model override
openweft start --effort high   run once with a reasoning effort override
openweft start --bg            detach — PID tracked, logs to .openweft/output.log
openweft start --stream        stream raw agent output to your terminal
openweft start --tmux          launch in a tmux session
openweft start --dry-run       full pipeline simulation with mock adapter
openweft status                queue state, tokens, feature breakdown
openweft stop                  finish the current phase, then stop

Configuration

openweft init writes .openweftrc.json, creates runtime directories, starter prompt templates, a repo-local skills/openweft-work-protocol/ skill, and a .gitignore entry for .openweft/. Config loads via cosmiconfig, with discovery bounded to the current git repository (or the nearest package.json outside one) — a stray openweft config in a parent directory or $HOME can never redirect repoRoot, and a changed config only blocks resume while the checkpoint still has genuinely unfinished work. Verified config forms include .openweftrc.json, .openweftrc.yaml, openweft.config.js, openweft.config.cjs, and the openweft key in package.json. JS config syntax follows Node package mode: CommonJS packages can use module.exports = { ... } in openweft.config.js; type: "module" packages should use export default { ... } in openweft.config.js or module.exports = { ... } in openweft.config.cjs.

SettingDefaultMeaning
backendcodexAgent backend for live runs.
auth.*.methodsubscriptionUse existing CLI login unless configured for API-key mode.
models.codexgpt-5.5Default Codex model.
models.claudeclaude-sonnet-4-6Default Claude model.
approvalalwaysFire-and-forget by default; can be per-feature or first-only.
concurrency.maxParallelAgents3Maximum workers per compatible phase.
concurrency.staggerDelayMs5000Delay between worker launches.
rateLimits.*.modesubscriptionRate-limit profile for subscription or API-key auth.
status.usageDisplaytokensStatus reports token counts.
runtime.codexHomeRetentionon-success-cleanClean isolated Codex worker homes after successful runs, or preserve for debugging.
budget.*nullOptional legacy budget thresholds; status still reports token counts.

After onboarding, run openweft and press m in the ready dashboard to save a new default model/effort, or use openweft start --model <model> --effort <level> for a one-run override.

{
  "backend": "codex",
  "auth": {
    "codex": { "method": "subscription" },
    "claude": { "method": "subscription" }
  },
  "prompts": {
    "promptA": "./prompts/prompt-a.md",
    "planAdjustment": "./prompts/plan-adjustment.md"
  },
  "featureRequestsDir": "./feature_requests",
  "queueFile": "./feature_requests/queue.txt",
  "models": {
    "codex": "gpt-5.5",
    "claude": "claude-sonnet-4-6"
  },
  "effort": {
    "codex": "medium",
    "claude": "medium"
  },
  "approval": "always",
  "concurrency": {
    "maxParallelAgents": 3,
    "staggerDelayMs": 5000
  },
  "rateLimits": {
    "codex": {
      "mode": "subscription",
      "maxConcurrentRequests": 3,
      "retryBackoffMs": 5000,
      "retryMaxAttempts": 5
    },
    "claude": {
      "mode": "subscription",
      "maxConcurrentRequests": 2,
      "retryBackoffMs": 5000,
      "retryMaxAttempts": 5
    }
  },
  "status": {
    "usageDisplay": "tokens"
  },
  "runtime": {
    "codexHomeRetention": "on-success-clean"
  },
  "budget": {
    "warnAtUsd": null,
    "pauseAtUsd": null,
    "stopAtUsd": null
  }
}

Repository layout

src/
├── adapters/       Backend contracts for Codex CLI, Claude Code, and mock runs
├── orchestrator/   Planning, execution, merge, re-analysis, finalization
├── domain/         Pure scoring, phasing, manifest, queue, cost, and error logic
├── state/          Strict checkpoint schema, save, load, and backup recovery
├── git/            Worktree lifecycle, branch merge, conflicts, cleanup, auto-gc
├── config/         Zod config schema and cosmiconfig loading
├── cli/            Commander commands and handler wiring
├── fs/             Atomic writes, retry reads, JSONL helpers, runtime paths
├── status/         Runtime diagnostics and status rendering
├── ui/             Ink onboarding, dashboard state, keyboard, terminal behavior
└── tmux/           Optional tmux launch and slot log integration

The important boundary is that domain/ stays pure, git/ owns repository topology, state/ owns recovery durability, and adapters/ keep backend-specific CLI behavior out of the orchestrator.


Design principles

Work Briefs are first-class. The generated operating brief is persisted, inspectable, and recoverable. It is not throwaway glue between a user request and an agent turn.

OpenWeft owns topology. Agents work inside assigned worktrees. The orchestrator decides branches, merges, cleanup, and recovery.

Real diffs beat declared intent. Manifests guide scheduling, but actual repository changes are the final truth for merge summaries and downstream re-analysis.

Separate cognition from orchestration. The model investigates and edits. OpenWeft controls state, ordering, retries, isolation, and reconciliation.

Simplicity is role clarity. The system is easier to reason about because each layer has one job: plan, score, phase, execute, merge, recover.


Contributing

PRs welcome. Useful local checks:

npm run typecheck
npm test
npm run build
npm run release:check

Release readiness

npm run release:check is the package/repo readiness gate. It proves the TypeScript build, tests, packaged installed-CLI smoke, and npm publish --dry-run path are healthy for the current repository state.

Live backend claims require separate smoke evidence from the same release window:

OPENWEFT_LIVE_SMOKE_TIMEOUT_MS=<timeout> npm run smoke:live:codex:resume
npm run smoke:live:claude

Claim Codex-ready only after the Codex resume smoke passes. Claim Claude-ready only after the Claude live smoke passes. Claim both-backend readiness only when both commands pass in the same release window. CI and release documentation assume npm 11.6.0, matching packageManager.

License

MIT


If OpenWeft saves you time, consider giving it a star. It helps others find it.

Ver o original no GitHub

Bom para

Relacionados