Isolated Git worktrees, tmux-native execution, replayable control, sealed evidence, and policy-bounded recovery.
Status: pre-public-release. The single-host execution, evidence, workflow, messaging, evaluation, trusted plugin host, optional MCP-read, and foreground supervision foundations are implemented. Bounded root-orchestrator → team-lead → worker orchestration is approved as an explicitly enabled feature. Its immutable contracts, append-only journals, deterministic replay, and digest-sealed team/root receipts are implemented and awaiting independent review; tmux topology, team runtime, hierarchy messaging, scheduling, and recovery remain separately gated by
docs/BACKLOG.md.
Coding agents are useful, but unattended work becomes difficult to trust when the only record is a terminal pane someone happened to watch. agent-workflow turns delegation into a reconstructable process:
- every run starts from immutable launch authority;
- implementation work is isolated in a Git worktree;
- control messages and acknowledgements are durable and replayable;
- process, terminal, permission, incident, and remediation evidence survive the interactive session;
- completion claims are validated against substantive evidence;
- review and acceptance remain explicit human authority.
The application favors deterministic control code around probabilistic agents. tmux is the presentation layer; durable records and sealed receipts are the source of truth.
| Capability | Current implementation |
|---|---|
| Isolated execution | Ticket worktrees, clean-source checks, bounded executor argv/environment, named tmux sessions and panes |
| Durable run evidence | Launch contract, source baseline, prompt, command, output, provider events, patch, completion handoff, process result, final receipt |
| Two-way control | Append-only steer, progress, acknowledgement, watch, cooperative control-file-v1 delivery, replay-safe outcomes |
| Workflow scheduling | Restart-safe DAGs, bounded parallelism, approval gates, result bindings, retries, aggregate receipts |
| Unattended diagnosis | Separate runner liveness and semantic progress, interactive terminal snapshots, process/resource samples, permission and incident journals |
| Bounded self-correction | Foreground supervisor, projection repair, one-shot progress probes, opt-in interruption and lineage-preserving restart |
| Searchable evidence | Rebuildable SQLite projection for cross-run, workflow, incident, permission, and performance queries |
| Evaluation | Deterministic templates, provider-neutral usage evidence, cohort comparison, sealed-run assessment and ledgers |
| Optional MCP feature | Bounded read-only local stdio adapter for command and run context; installed with the mcp extra |
| Trusted plugin host | Explicit entry-point enablement, atomic top-level command registration, digest-bound installed schema/asset resources, installed provenance, and --no-plugins recovery |
| Hierarchy authority layer | Fixed-depth immutable contracts, capability/budget narrowing, append-only journals, deterministic replay, and digest-sealed team/root receipts; runtime topology remains gated |
The application does not merge branches, approve permissions, expand filesystem/network authority, accept work automatically, or silently retry without preserved lineage.
The graphic shows the approved target topology. The current runtime implements the worker/run, durable evidence, messaging, workflow, and supervisor foundations. The multi-window team-lead layer is described in docs/HIERARCHICAL_MULTI_TEAM_ORCHESTRATION_DESIGN.md and remains backlog-gated.
Immutable authority Recoverable projections
──────────────────────────────── ────────────────────────────────
launch-contract.json status.json
append-only messages/journals tmux session/window/pane layout
workflow snapshot + events terminal capture returned by status
sealed completion and receipts derived summaries and dashboards
rebuildable SQLite evidence index
A projection may be rebuilt. Authority-changing actions—permission grants, policy expansion, acceptance, merge, destructive cleanup—cannot be inferred from a projection or delegated to an unverified agent.
- Python 3.11+
- Git
- tmux
- Bash
- GNU tar and zstd for deterministic archives
- Codex, Claude, or an explicit executor command
./install.sh
export PATH="$HOME/.local/bin:$PATH"
agent-workflow doctorThe installer creates an editable local installation, links repository skills into supported discovery roots, and writes a starter XDG configuration without replacing unrelated files. Add --extras mcp only on hosts that need the optional MCP adapter. Jenkins CI and local server-job files remain in the source repository and are never installed as runtime files. See docs/INSTALLATION.md.
For a released Linux, WSL2, or macOS wheel, use the immutable-tag bootstrap
documented in docs/INSTALLATION.md. Native Windows is
out of scope.
agent-workflow worktree create /path/to/repo TICKET-1 HEAD
agent-workflow launch \
ticket-1 \
/path/to/worktrees/ticket-1 \
./ticket.md \
--ticket TICKET-1 \
--executor codex
agent-workflow status ticket-1 --capture 50
agent-workflow attach ticket-1Use an explicit command after -- when the executor is not configured:
agent-workflow launch ticket-1 /path/to/worktree ticket.md -- \
codex exec --sandbox workspace-write --skip-git-repo-check -agent-workflow steer ticket-1 \
"Run the focused tests before editing." \
--actor orchestrator
agent-workflow watch ticket-1 --after 0 --timeout 300
agent-workflow progress ticket-1 "Focused tests pass." --actor child
agent-workflow ack ticket-1 MESSAGE_ID "Applied." --actor childThe journal commit happens before any tmux wake hint. A request remains pending until durable delivery and acknowledgement evidence records its disposition.
# One evidence/reconciliation cycle.
agent-workflow supervisor once --json
# Continuous foreground supervision; safe status probes are enabled by default.
agent-workflow supervisor run --interval-seconds 10
# Authority-changing recovery is always explicit.
agent-workflow supervisor run \
--interrupt-stalled \
--restart-orphaned \
--max-remediation-attempts 1
The supervisor is deliberately foregroundable rather than a hidden daemon. It automatically repairs mutable status projections and may send a bounded progress probe. Interrupt and restart rules remain disabled unless the operator authorizes them in configuration or on the command line. Permission grants and acceptance never become automatic.
The configured state root normally contains:
~/.local/state/agent-workflow/runs/<session-id>/
├── launch-contract.json immutable launch authority
├── source-baseline.json source identity and cleanliness evidence
├── output.log normalized non-interactive output
├── executor-events.jsonl structured provider stream
├── terminal-events.jsonl bounded change-driven interactive snapshots
├── run-health-samples.jsonl process, resource, and progress samples
├── permission-events.jsonl observed permission waits and denials
├── incident-events.jsonl typed unattended-diagnosis findings
├── remediation-events.jsonl attempted correction and verification trail
├── process-result.json exit, signal, timeout, byte, and truncation facts
├── completion.json validated child handoff
├── patch.diff collected implementation delta
└── final-receipt.json sealed artifact inventory and checksums
Worktree .delegations/ entries are only discoverability links. The XDG state directory remains the evidence authority.
JSON/JSONL artifacts and sealed receipts remain the source of truth. A host-local SQLite database provides a disposable, transactionally consistent projection for operational search and analysis:
agent-workflow index status
agent-workflow index sync
agent-workflow index query runs --state possibly_stalled --limit 25
agent-workflow index query incidents --category permission_wait
agent-workflow index query performance --executor codex --model MODEL
agent-workflow index verify [--full] [--review SESSION]
# Delete and reconstruct every indexed row from authoritative evidence.
agent-workflow index rebuildWith --review SESSION, verification reports the named run's direct gate as
review_valid separately from global valid; the scoped result never hides
unresolved host integrity blockers.
Each query reports whether the projection is current, stale, or incomplete before presenting rows. The index stores normalized searchable fields, source paths, record sequence, and SHA-256 provenance. It deliberately excludes raw prompts, terminal bodies, message bodies, and large logs. One indexer owns writes; reporting surfaces use read-only queries. Database loss or corruption does not lose execution history: agent-workflow index rebuild recreates the projection from validated source artifacts. See docs/SQLITE_EVIDENCE_INDEX_ARCHITECTURE.md and DEC-007.
agent-workflow workflow validate ./workflow.json
agent-workflow workflow start ./workflow-run ./workflow.json
agent-workflow workflow status ./workflow-run ./workflow.json
agent-workflow workflow resume ./workflow-run ./workflow.json
agent-workflow workflow seal ./workflow-run ./workflow.json
agent-workflow workflow verify ./workflow-run ./workflow.jsonWorkflow state is reconstructed from an immutable normalized snapshot and append-only event journal. Child tasks use the same launch and receipt path as direct runs.
Authorized templates include:
agent-workflow workflow template pipeline ./spec.json --output ./workflow.json
agent-workflow workflow template parallel-review-fan-in ./spec.json --output ./workflow.json
agent-workflow workflow template implementation-independent-review ./spec.json --output ./workflow.jsonagent-workflow pack scaffold ./my-pack --phases 3
agent-workflow pack validate ./my-pack
agent-workflow pack archive ./my-pack ./my-pack.tar.zst
agent-workflow eval template evaluation-plan --output ./evaluation.json
agent-workflow eval validate ./evaluation.json --pack ./my-pack
agent-workflow eval score SESSION
agent-workflow eval report SESSION --format markdownPrompt-pack dependencies form a validated cross-phase DAG. Evaluation evidence keeps provider totals, local estimates, unavailable values, retry lineage, source identity, and cohort comparability distinct. See docs/PROMPT_PACKS.md and docs/EVIDENCE_AND_EVALUATION.md.
agent-workflow is local-first, but local does not mean unbounded.
- subprocesses use argv arrays rather than shell strings;
- child environments are allowlisted;
- executor identity and configured permission arguments are recorded;
- launch, scope, model, and budget authority is immutable for the run;
- terminal and journal capture is bounded;
- automatic remediation cannot expand authority;
- review, acceptance, and merge remain human decisions.
The remaining governed-sandbox and authenticated-principal work is tracked under HARD-003, HARD-006, and HARD-007 in docs/BACKLOG.md. See docs/SECURITY.md for the complete trust model.
The searchable evidence projection and bounded supervisor foundations are implemented and in review. The bounded hierarchy durable-authority layer—contracts, journals, replay, and sealed team/root receipts—is also implemented and awaiting HIER-GATE-0; hierarchy runtime remains gated by its ticket-specific prerequisites:
root orchestrator
├── team-lead window A
│ ├── worker pane A1
│ └── worker pane A2
└── team-lead window B
├── worker pane B1
└── worker pane B2
The root will create and reconcile team windows, while each team lead coordinates worker panes under a narrowed delegation contract. Durable records remain authoritative across tmux loss and restart. The dependency order is explicit in docs/BACKLOG.md; the full design is in docs/HIERARCHICAL_MULTI_TEAM_ORCHESTRATION_DESIGN.md.
Public distribution remains blocked on release-governance and security decisions in docs/PUBLIC_RELEASE_READINESS.md.
The built-in benchmark family runs the same task concurrently through isolated control_raw and workflow_full worktrees. priority-picker-v1 preserves historical scoring, priority-picker-v2 provides the corrected full task, and priority-picker-fast-v1 retains the same paired scoring/browser/human-review lifecycle in one model phase capped at 150 seconds.
agent-workflow benchmark suite-export /tmp/priority-picker-fast-v1 \
--benchmark-id priority-picker-fast-v1
agent-workflow benchmark readiness /tmp/priority-picker-fast-v1/benchmark-spec.json \
--executor /tmp/priority-picker-fast-v1/executors/codex-subscription.json \
--policy /tmp/priority-picker-fast-v1/policies/development.json
agent-workflow benchmark fixture-create \
/tmp/priority-picker-fast-v1/benchmark-spec.json /tmp/priority-picker-fixture
agent-workflow benchmark plan /tmp/priority-picker-fast-v1/benchmark-spec.json \
--executor /tmp/priority-picker-fast-v1/executors/codex-subscription.json \
--policy /tmp/priority-picker-fast-v1/policies/development.json \
--repo /tmp/priority-picker-fixture --run-id priority-picker-smoke
# Run this command from inside an existing tmux pane.
agent-workflow benchmark run priority-picker-smoke
agent-workflow benchmark status priority-picker-smokeA run adds exactly two panes to the invoking tmux window, reuses them for both arms, and streams provider progress visibly. Automated evaluation starts one LAN-reachable live application per selected arm on a distinct ephemeral port, then preserves those apps and panes for browser capture and blinded human assessment. Default cleanup preserves those apps and worktrees; explicit benchmark live-stop or cleanup --stop-live-apps --remove-worktrees performs teardown. Destructive cleanup refuses to remove worktrees when any live process cannot be confirmed stopped, and benchmark-owned panes remain available for diagnosis. Digest-verified evidence remains in the coordinator under benchmarks/runs/<run-id>.
See the operations guide, implementation, task/evaluation/scoring explanation, and owned corrective prompt pack.
./scripts/bootstrap-dev.sh
.venv/bin/python -m pytest -q
./scripts/release-check.shThe suite is acceptance-first: build a wheel, install it, and exercise public commands through real filesystem, Git, and process journeys. A compact invariant layer protects replay, security, accounting, evidence, and release boundaries. Live tmux/provider checks remain opt-in. See docs/TESTING.md.
GitHub Flavored Markdown supports headings, tables, fenced code, images, and a sanitized subset of inline HTML. It does not provide repository authors with arbitrary page CSS or a full-page background. This README therefore uses repository-owned SVG assets and <picture> elements for polished light/dark presentation without depending on unsupported styles.
The project is not yet accepting a public compatibility promise. Internal contributors should begin with docs/CONTRIBUTING.md, run the release checks, and preserve durable evidence contracts. Support and disclosure guidance is in docs/SUPPORT.md.
agent-workflow is licensed under the Apache License 2.0.