agent-worktree

A git-native orchestration project for coding agents.
Parallel when needed, minimal when not, always quality-first.

English | 简体中文 | 繁體中文 | 日本語

Overview

agent-worktree is a git-native orchestration project for running coding agents in isolated worktrees, with internal verification, selection, and bounded-parallelism Phase 6 prep already present behind non-public boundaries.

The repository started as a documentation-first effort and has now entered an early implementation phase centered on contract clarity, tests, and a thin worktree lifecycle slice.

The long-term goal is broader than "heavy parallelism for only the hardest tasks." This project should also support simpler tasks that still demand quality, using less orchestration when less orchestration is enough.

Design Goals

• Worktree-native: isolate candidate runs at the filesystem level
• Verification-first: prefer deterministic checks over confident prose
• Adaptive: scale from lightweight flows to deeper parallel exploration
• Tool-friendly: support multiple coding-agent tools without vendor lock-in
• Docs-first: write the public contract before code narrows the design

Project Scope

In scope	Out of scope
Worktree-based orchestration patterns	Hosted coding platform
Public specs for config, manifests, and CLI contracts	General-purpose multi-agent framework for every domain
Compatibility layers for coding-agent tools	A new coding agent that replaces existing tools
Research-backed future directions	Premature benchmark marketing

Compatibility Strategy

Tier 1

• Claude Code
• Codex CLI
• Gemini CLI
• OpenCode

Experimental

• OpenClaw
• Other coding-agent CLIs that fit the adapter model

See:

• Compatibility Overview
• Tooling Matrix

Current Phase

This repository is currently focused on:

1. Node/TypeScript core scaffolding
2. config and runtime-manifest contracts
3. machine-readable CLI behavior
4. thin worktree lifecycle commands
5. public compatibility diagnostics via agent-worktree doctor, agent-worktree compat probe <tool>, and the env-gated bounded live agent-worktree compat smoke <tool> path
6. a bounded internal codex-cli execution contract for the first Tier 1 runtime
7. docs and implementation alignment

The repository now has a thin Phase 4 public compatibility baseline. compat smoke codex-cli is the first bounded public compatibility checkpoint for a Tier 1 runtime, while doctor and compat probe keep the remaining Tier 1 runtimes on explicit descriptor-only boundaries until broader execution-backed work exists. In the current implementation, the only concrete execution-backed probe path is codex-cli.

The public baseline is still intentionally narrow. Today it includes compat list, compat show, compat probe, compat smoke, doctor, and the thin attempt create / attempt list / attempt cleanup lifecycle commands, all centered on machine-readable contracts. The public command tree also still exposes init, attempt attach, attempt stop, attempt checkpoint, and attempt merge as explicit NOT_IMPLEMENTED placeholders; they are visible CLI entries, not implemented lifecycle support. Within that narrow JSON surface, compat list / compat show intentionally expose the catalog field name tier, while runtime diagnostics and attempt-facing payloads use supportTier; changing one to match the other would either be a breaking rename or a public-output widening.

The internal baseline is wider than the public one. codex-cli now has a bounded internal execution path around codex exec --json, and the current internal Phase 5 exit criteria are satisfied through verification, selection, promotion/handoff composition, runtime-state/control-plane composition, grouped finalization reporting, and closeout decision coverage. Current internal continuation work now sits above that baseline as bounded-parallelism Phase 6 prep. Those internal buckets remain intentionally non-public and do not widen the public CLI, lifecycle, or manifest contract. Internally, the current continuation also includes bounded spawn-planning helpers, headless wait/close bridge helpers, an internal coordination-task substrate, descendant-coverage truth helpers, and advisory grouping or ready-queue projections, but those remain implementation details rather than public capability. The default entry points stay intentionally narrower than the repo-internal staging surface: the default selection barrel remains empty, while the default control-plane barrel remains limited to the current read-only foundational session helpers. The maintainer-only future harness planning set in docs/maintainers/future-super-agent-harness/ is a later future-branch design brief, not a statement that the current mainline Phase 6 prep has already become that broader harness.

That Phase 4 closeout does not mean full runtime orchestration exists. Other runtimes remain descriptor-only, and resume, MCP transport execution, public execution commands, public wait/close/spawn commands, and public manifest-backed execution or session-lifecycle semantics remain intentionally deferred. A bounded internal session block may still appear in the runtime manifest, but it remains non-public metadata: public CLI output does not expose it, it is limited to backend plus sessionId, and it is not attach/resume or lifecycle-control truth. The current public promise is compatibility-only: direct-shell verification and the env-gated Vitest smoke harness may support it locally, but the Vitest harness remains narrower and is not a default validation path. The current codex-cli executable probing policy is intentionally internal: execution helpers may resolve a different codex binary than shell command -v codex when PATH contains shadow binaries, but that is not a public adapter contract. The same is true for internal --profile passthrough and relay-compatible env overlays. The bounded parser tolerates obvious non-JSON prelude lines, including bracket-prefixed log noise, while malformed JSON-looking records still fail loudly. The current manifest contract also includes a thin lineage/source foundation for attempt provenance. Attempts may record sourceKind plus an optional parentAttemptId, but this remains audit metadata only: attempt create emits sourceKind: "direct" today, while delegated runtime behavior, public fork/resume lifecycle semantics, and any public session-backed execution contract remain deferred. Manifest persistence may begin at attempt create, so a durable manifest can exist before any runtime execution has started. The current TypeScript verification-ingest surface intentionally keeps AttemptVerification wider than the stricter manifest schema vocabulary so verification ingestion can still classify legacy or unknown payloads internally. The default public manifest barrel does not export standalone verification-ingest helper types, but AttemptManifest still carries that wider in-memory verification shape until persistence hits the stricter manifest validation boundary. The stricter five-value verification.state vocabulary applies at manifest validation boundaries, not as a blanket promise that every in-memory verification object is already narrowed. The same pattern applies to the bounded internal session block: schema and persistence currently limit it to backend plus sessionId, while in-memory objects may still carry additive extra keys until manifest validation runs. This does not forbid a durable audit manifest or bounded internal session metadata; it only means public execution/session persistence semantics are not implemented.

Why This Matters

Most coding-agent workflows today live somewhere between:

• one overloaded context window
• several ad hoc terminal sessions with no durable orchestration model

agent-worktree aims to provide a cleaner middle ground:

• use minimal orchestration for simple work
• use isolated parallel attempts for harder work
• keep the controller deterministic where it matters
• stay explicit about what is verified, experimental, or deferred

Start Here

The committed documentation order starts with SPEC.md, then this README.md, then docs/index.md. Use AGENTS.md as the repository-specific execution rules and boundary companion, not as a replacement for the committed spec/doc set.

• SPEC.md
• README.md
• docs/index.md
• AGENTS.md
• ROADMAP.md

Key References

• docs/compat/overview.md
• ROADMAP.md
• docs/maintainers/development-phases.md
• docs/compat/tooling-matrix.md
• docs/research/vision-synthesis.md

Documentation Policy

• Public repo content should contain durable, sanitized, shared knowledge.
• Raw research notes, transcripts, local AI state, and session handoff logs stay local and ignored.
• Local handoff files such as PROJECT_STATUS.local.md and CODING_PHASE_PROMPT.local.md are operational overlays only and must not be committed.

Near-Term Focus

• Continue hardening the current config, manifest, and CLI contracts
• Keep the public compatibility diagnostics, probe, and smoke slices accurate and machine-readable
• Keep the current create/list/cleanup lifecycle baseline stable without widening public lifecycle surfaces
• Continue hardening the bounded internal codex-cli execution contract without expanding it into a full runtime framework
• Keep the codex-cli smoke scaffold env-gated and non-default while it remains a bounded compatibility probe
• Keep docs, tests, and implementation boundaries aligned

License

License selection is intentionally deferred until the public project surface is clearer.