Workflow execution and worktrees
Workflow execution turns a worker plan into parallel, isolated engineering sessions. It gives each worker a branch, worktree, task record, handoff record, and status record, then runs the worker in a tmux pane so an operator can inspect progress and collect results.
Orchestration model
Worker sessions
The orchestration model treats each worker as a bounded unit of work inside one named session. A plan describes the session and its workers. The launcher turns that plan into Git worktrees, coordination files, and tmux panes.
Workers communicate through artifacts rather than through the parent process. The task file supplies the objective and any local overlays. The launcher owns the status and handoff files. This keeps worker activity inside its assigned worktree while leaving a durable record for inspection.
References: scripts/…/tmux-worktree-orchestrator.js• L175-250 scripts/…/tmux-worktree-orchestrator.js• L314-322 scripts/…/orchestration-session.js• L131-153
Workflow entrypoints
The repository exposes three orchestration entrypoints through package scripts. They cover launch, worker execution, and state inspection.
| Entry point | Role |
|---|---|
orchestrate:tmux | Build or run a multi-worker tmux and worktree session from a JSON plan. |
orchestrate:worker | Run one worker from its task file and write launcher-managed results. |
orchestrate:status | Read a session or plan target and print a normalized session snapshot. |
The launch entrypoint supports a dry run by default. It can instead write coordination artifacts or execute the plan. This separates plan review from resource creation.
References: package.json• L466-468 scripts/orchestrate-worktrees.js• L13-24 scripts/orchestrate-worktrees.js• L69-97
Worker launch flow
Plan materialization
Plan materialization creates the shared coordination directory before any worker starts. Each worker receives a task file with its objective, a pending handoff file, and an initial status file.
The plan also resolves worker names into stable slugs. Those slugs link the branch, worktree path, tmux pane title, and coordination directory. A launcher command can use plan variables such as the worker worktree and artifact paths, so the same plan can start different worker runtimes.
The diagram shows how a plan becomes worker resources and an executable session.
flowchart TD
Plan[JSON worker plan] --> Build[Build worker plans]
Build --> Artifacts[Task, handoff, and status files]
Build --> Trees[Branch-backed worktrees]
Build --> Session[Named tmux session]
Trees --> Panes[Worker tmux panes]
Artifacts --> Panes
Panes --> Launch[Launcher command]
References: scripts/…/tmux-worktree-orchestrator.js• L175-251 scripts/…/tmux-worktree-orchestrator.js• L314-322 scripts/…/tmux-worktree-orchestrator.js• L523-567
Worker execution
The Codex worker launcher is the standard single-worker path. It requires a task file, starts with a running status, and passes the task to Codex in the current worktree. The worker must not modify sibling worktrees or create nested agents.
On success, the launcher captures the worker response in the handoff file and records the current Git status. On failure, it records a failed status and a failure handoff. Missing or unreadable task input fails before Codex runs and still produces those failure artifacts.
References: scripts/orchestrate-codex-worker.sh• L4-11 scripts/orchestrate-codex-worker.sh• L33-49 scripts/orchestrate-codex-worker.sh• L58-78 scripts/orchestrate-codex-worker.sh• L80-106
Review workflow
The native orch-review workflow is a gated review segment rather than a worktree creator. It accepts a unified diff and optional language and changed-file context. It runs a quality review in parallel with a language review when one is known and a security review when the diff matches security-sensitive signals.
The workflow then verifies every high-severity finding with an independent reviewer. It returns blocking and advisory findings. A failed review dimension or an uncertain blocker keeps the result at CHANGES_REQUESTED, so incomplete review cannot pass the gate.
References: workflows/orch-review.workflow.js• L1-31 workflows/orch-review.workflow.js• L177-215 workflows/orch-review.workflow.js• L240-295
Worktree isolation
Worktree setup
Each worker starts from the plan's base reference on its own branch. The worktree sits beside the repository by default, while coordination files remain under the configured coordination root. This lets workers edit in parallel without sharing an index or working directory.
Plans can copy selected seed paths from the repository into each worker worktree. Seed paths must remain inside the repository root. The copy gives a worker local context without changing the branch history of the worktree.
References: scripts/…/tmux-worktree-orchestrator.js• L53-105 scripts/…/tmux-worktree-orchestrator.js• L207-232 scripts/…/tmux-worktree-orchestrator.js• L513-521
Resource cleanup
Execution checks that the repository and tmux are available before it creates resources. It rejects an existing session unless replacement is requested. If setup fails after partial creation, it removes only the resources created by that run and reports cleanup errors with the original failure.
Replacement cleanup removes the old tmux session and matching worktrees and branches. Because this can discard existing work, replacement is an explicit plan choice rather than the default behavior.
References: scripts/…/tmux-worktree-orchestrator.js• L390-423 scripts/…/tmux-worktree-orchestrator.js• L426-480 scripts/…/tmux-worktree-orchestrator.js• L482-508 scripts/…/tmux-worktree-orchestrator.js• L569-579
Worktree lifecycle
The lifecycle report compares every Git worktree with a selected base branch. It distinguishes active work from cleanup candidates by combining branch position, uncommitted changes, predicted merge conflicts, and last-commit age.
The scripts/worktree-lifecycle.js command turns this report into an operator view. It can show all worktrees, limit the view to conflict or stale queues, emit the versioned JSON report, or show a cleanup plan. The default comparison uses main and marks clean work as stale after seven days unless the operator selects different values.
Git access uses the target repository and worktree paths without inherited Git environment settings. This keeps lifecycle checks focused on the selected repository, including when the command runs from a hook or another Git-controlled process. Safe worktree-path parsing requires Git 2.36 or newer.
| State | Meaning for orchestration |
|---|---|
main or detached | Primary or branchless workspace that is not normal worker output. |
dirty | Uncommitted work that must not be removed automatically. |
merge-ready | Clean work with commits ahead of the base and no predicted conflict. |
conflict | Clean work that needs conflict resolution before merge. |
merged | No unique commits remain ahead of the base. |
stale | Unmerged work with no recent activity and a need for salvage before removal. |
idle | Clean work with no current merge contribution. |
The cleanup plan removes only fully merged worktrees. It places stale unmerged work in a salvage queue and keeps dirty, conflicting, and other unmerged worktrees.
References: scripts/worktree-lifecycle.js• L6-17 scripts/worktree-lifecycle.js• L49-68 scripts/…/git.js• L5-17 scripts/…/git.js• L63-95 scripts/…/lifecycle.js• L7-25 scripts/…/lifecycle.js• L27-61 scripts/…/lifecycle.js• L109-145 scripts/…/lifecycle.js• L149-182
Orchestration state
Session inspection
The status entrypoint accepts either a session name or a plan file. A plan target supplies the repository and coordination locations from the plan. A session-name target uses the standard .claude/orchestration/<session> location.
Inspection reads worker task, status, and handoff records and joins them with tmux pane data. The result shows session activity, worker state, pane health, worktree, objective, and reported outputs. Operators can print the result or save the JSON snapshot for another tool.
References: scripts/orchestration-status.js• L9-18 scripts/orchestration-status.js• L30-50 scripts/…/orchestration-session.js• L218-285 scripts/…/dmux-tmux.js• L43-79
Canonical session snapshots
Session adapters convert different runtime records into the shared ecc.session.v1 shape. This gives orchestration state one view even when the runtime is tmux-backed, Codex-backed, or supplied by another host adapter.
The shared view keeps session state separate from worker health. It also keeps worker intent, runtime details, outputs, and artifact paths together. Snapshots can be sent to the configured state store or retained as JSON recordings when no state store writer is available.
References: scripts/…/canonical-session.js• L162-263 scripts/…/canonical-session.js• L388-423 scripts/…/registry.js• L99-141
Codex coordination
Codex session discovery
The Codex worktree adapter treats Codex rollout logs as session records. It accepts a codex: or codex-worktree: target, the special latest target, a session identifier, or a direct rollout file path. It locates append-only JSONL rollout files and uses their recent activity to decide whether the session is active.
The adapter extracts the worktree path, branch, objective, model, origin, and start data. It ignores the injected harness preamble when it derives the worker objective, and it tolerates an incomplete trailing record while a rollout is still being written. This makes a Codex session visible through the same inspection surface as other workers.
References: scripts/…/codex-worktree.js• L10-25 scripts/…/codex-worktree.js• L56-134 scripts/…/codex-worktree.js• L187-203 scripts/…/codex-worktree.js• L278-301
Codex session normalization
A Codex rollout becomes a one-worker canonical session. Its runtime is identified as Codex. Its worktree and branch come from the rollout context. Its activity state becomes active while recent records exist and recorded after activity stops.
The adapter can persist the normalized snapshot through the shared state store or the JSON recording fallback. The registry maps both codex and codex-worktree target types to this adapter, so callers can use a stable target contract without knowing the storage layout.
References: scripts/…/canonical-session.js• L529-577 scripts/…/codex-worktree.js• L304-345 scripts/…/registry.js• L8-17
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the launcher template variables aligned with the task, handoff, and status paths that plan materialization creates.
- Keep the coordination directory rules aligned between plan targets and session-name targets. They use different default roots.
- Preserve the worker artifact headings and fields that session inspection parses into objectives, states, validation, and risks.
- Preserve the
ecc.session.v1shape when changing any adapter. Downstream state storage and operator views depend on its required fields. - Keep cleanup rules conservative when changing lifecycle states. Dirty or unmerged work must not become an automatic removal candidate.
- Keep the lifecycle command's Git version requirement and repository-target rules aligned with the Git runner.
- Keep Codex target prefixes and rollout parsing aligned with the session adapter registry.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A plan has no workers or a worker has no task or launcher | Plan creation stops before resources are created. | Validate the plan before execution. |
| Two worker names produce the same slug | Branches and coordination paths would collide. | Require unique worker slugs. |
| A tmux session with the same name already exists | A new run is rejected. | Inspect the existing session or explicitly choose replacement. |
| A worker setup step fails after resources exist | The run fails and cleanup runs for resources created before the failure. | Use execution rollback and inspect cleanup errors. |
| A task file is missing or unreadable | Codex does not run. Status and handoff record failure. | Materialize and check task artifacts before launch. |
| A worktree is dirty, conflicting, or unmerged | Automatic cleanup can lose work or create an unsafe merge. | Keep it out of removal; use the conflict or salvage queue. |
| Lifecycle checks run with an old Git version or inherited Git repository variables | Worktree paths may not be read safely, or checks may inspect the wrong repository. | Require Git 2.36+ and clear inherited Git environment settings before inspection. |
| A Codex target has no matching rollout or uses an unsupported path | Session inspection fails instead of returning a false session. | Use a supported target prefix, identifier, latest target, or rollout file. |
| A review dimension fails or a high-severity finding cannot be refuted with confidence | The review returns CHANGES_REQUESTED. | Treat incomplete and uncertain review as blocking. |
Key files
| File | Why to read it |
|---|---|
| scripts/orchestrate-worktrees.js | Primary command for dry runs, artifact-only setup, and live multi-worker launch. |
| scripts/…/tmux-worktree-orchestrator.js | Defines the plan-to-worktree-to-tmux flow and resource rollback boundary. |
| scripts/orchestrate-codex-worker.sh | Defines the single-worker Codex contract and handoff behavior. |
| scripts/orchestration-status.js | Provides the operator-facing session inspection command. |
| scripts/…/orchestration-session.js | Shows how coordination files and tmux panes become a session snapshot. |
| scripts/worktree-lifecycle.js | Provides lifecycle reports, conflict and stale queues, and cleanup plans. |
| scripts/…/git.js | Defines the repository-scoped Git checks that support safe lifecycle classification. |
| scripts/…/lifecycle.js | Defines the worktree state model and cleanup safety rules. |
| scripts/…/codex-worktree.js | Connects Codex rollout sessions to worktrees and session inspection. |
| scripts/…/canonical-session.js | Defines the shared session snapshot and persistence contract. |
| workflows/orch-review.workflow.js | Defines the parallel review and adversarial verification segment used by the orchestration workflow. |