skip to content
iii / worker
$worker

worktree

v0.2.4

Git worktree lifecycle for parallel agents — mint, claim, and track isolated worktrees per repo, emit lifecycle trigger types, and land branches back through a per-repo FIFO queue (rebase, test gate, ff-only merge).

iiiverified
3 installs0 in 7d0 today
install
$iii worker add worktree
binarygitworktreeparallelagentsbranchesci
  • macOS: arm64 · x64
  • Linux: arm64 · armv7 · x64
  • Windows: arm64 · x64 · x86
12functions6triggers1skills3depsv0.2.4version
repoiii-hq/workers

exact versions are immutable; binary and bundle artifacts are digest-pinned.

functions

12

worktree::claim

function

Claim a worktree for a session. Fails with W210 when another session holds it, unless force is set.

request
  • forceboolean

    Take the claim even when another session holds it.

  • session_idstringrequired

    The claiming session.

  • worktree_idstringrequired

    The worktree to claim.

response
  • claimedbooleanrequired

    True when the claim is now held by `session_id`.

  • previous_session_idstring

    The session that held the claim before, when taken over with force.

  • session_idstringrequired

    The claiming session.

  • worktree_idstringrequired

    The claimed worktree.

worktree::create

function

Create an isolated, locked git worktree off a base ref and register it in the cross-agent registry. Returns the path to hand to an agent as its working directory.

request
  • base_refstring

    Ref to base the worktree on. Defaults to `HEAD`.

  • branchstring

    Branch to create. Defaults to `<branch_prefix><worktree_id>` (or a codename when `branch_naming: codename`).

  • printeger· uint64min 0

    Create the worktree at a GitHub pull request head: fetches `refs/pull/<n>/head` from `origin` and branches `<prefix>pr-<n>` at it. Mutually exclusive with `base_ref` and `branch`.

  • repo_pathstringrequired

    Absolute path of the repository to branch from.

  • session_idstring

    Session to auto-claim the worktree for.

response
  • base_refstringrequired

    The ref the worktree was based on.

  • base_shastringrequired

    The commit `base_ref` resolved to.

  • branchstringrequired

    The branch checked out in the worktree.

  • created_atinteger· int64required

    Creation time, ms since epoch.

  • dev_portinteger· uint16requiredmin 0

    Advisory dev-server port derived from the worktree id.

  • pathstringrequired

    Absolute path of the new worktree; hand this to an agent as its working directory.

  • repo_keystringrequired

    Canonical per-repo key (FIFO group for lands).

  • worktree_idstringrequired

    Stable id, `wt_<12hex>`.

worktree::get

function

Fetch one managed worktree with its current git status.

request
  • worktree_idstringrequired

    The worktree to fetch.

response
  • base_refstringrequired

    The ref the worktree was created from.

  • base_shastringrequired

    The commit `base_ref` resolved to at creation time.

  • branchstringrequired

    The branch checked out in the worktree.

  • created_atinteger· int64required

    Creation time, ms since epoch.

  • dev_portinteger· uint16requiredmin 0

    Advisory dev-server port derived from the worktree id: deterministic, collision-improbable, never reserved anywhere.

  • lifecycleall ofrequired

    Current lifecycle (reported `orphaned` when the directory is gone).

    all of (1)
    variant 1
    one of (5)
    variant 1
    valuestringenum: active
    variant 2
    valuestringenum: claimed
    variant 3
    valuestringenum: landing
    variant 4
    valuestringenum: land-blocked
    variant 5
    valuestringenum: orphaned
  • pathstringrequired

    Absolute path of the worktree directory.

  • repo_keystringrequired

    Canonicalized per-repo key.

  • repo_pathstringrequired

    The repository path the worktree was created from.

  • session_idstring

    Owning session, when claimed.

  • statusany of

    Git status, when requested and computable.

    any of (2)
    variant 1
    • aheadinteger· uint64requiredmin 0

      Commits ahead of the comparison base (upstream when set, else `base_sha`).

    • behindinteger· uint64requiredmin 0

      Commits behind the comparison base.

    • cleanbooleanrequired

      True when there are no staged, unstaged, untracked, or conflicted entries.

    • conflictedinteger· uint64requiredmin 0

      Unmerged (conflicted) entry count.

    • diffstatstringrequired

      `git diff --shortstat` of committed work since `base_sha`.

    • head_shastringrequired

      Current HEAD commit.

    • in_rebasebooleanrequired

      True while a rebase is in progress in this worktree.

    • integratedboolean

      True when the branch's work is already contained in its integration target (fast-forward, merge, rebase, or squash merge). Integrated worktrees are prunable even when ahead of their base.

    • integration_reasonstring

      Which check detected the integration: `same_commit`, `ancestor`, `no_added_changes`, `trees_match`, `merge_adds_nothing`, or `patch_id_match`.

    • stagedinteger· uint64requiredmin 0

      Staged entry count.

    • unpushedinteger· uint64requiredmin 0

      Commits not merged upstream (upstream ahead count, else commits past `base_sha`).

    • unstagedinteger· uint64requiredmin 0

      Unstaged entry count.

    • untrackedinteger· uint64requiredmin 0

      Untracked entry count.

    variant 2
    valuenull
  • updated_atinteger· int64required

    Last mutation time, ms since epoch.

  • worktree_idstringrequired

    Stable id, `wt_<12hex>`.

worktree::land

function

Queue a land: rebase onto the target, run the optional test gate via shell::exec, fast-forward the target with an atomic CAS, then clean up. Serialized per repo via the land queue.

request
  • force_restartboolean

    Abort a conflicted rebase left by a previous land and start over.

  • keepboolean

    Keep the worktree and branch after a successful land.

  • target_branchstringrequired

    The branch to fast-forward with the worktree's commits.

  • test_cmdstring

    Optional test command run in the worktree via `shell::exec` before merging (the test gate).

  • worktree_idstringrequired

    The worktree to land.

response
  • job_idstringrequired

    The queued land job.

  • queuedbooleanrequired

    True when the job was enqueued.

worktree::land-step

function

Internal: execute one queued land job. Bound to the land queue; not agent-callable.

request
  • job_idstringrequired

    The job to advance.

  • repo_keystring

    FIFO group key; consumed by the engine's queue config, echoed here.

response
  • donebooleanrequired

    True when the job reached a terminal state (landed or blocked).

  • job_idstringrequired

    The advanced job.

  • phase_completedstringrequired

    The last phase this invocation completed.

worktree::list

function

List managed worktrees, optionally filtered by repo or session and enriched with git status. Also reports unmanaged worktrees of the repo when repo_path is given.

request
  • include_statusboolean

    Compute git status for each worktree (slower).

  • repo_pathstring

    Only worktrees of this repository.

  • session_idstring

    Only worktrees claimed by this session.

response
  • unmanagedobject[]required

    Non-primary worktrees of the repo without a record (only populated when repo_path is given). Never auto-adopted.

    • branchstring

      Checked-out branch ref, when not detached.

    • pathstringrequired

      Absolute path of the worktree.

  • worktreesobject[]required

    Managed worktrees, oldest first.

    • base_refstringrequired

      The ref the worktree was created from.

    • base_shastringrequired

      The commit `base_ref` resolved to at creation time.

    • branchstringrequired

      The branch checked out in the worktree.

    • created_atinteger· int64required

      Creation time, ms since epoch.

    • dev_portinteger· uint16requiredmin 0

      Advisory dev-server port derived from the worktree id: deterministic, collision-improbable, never reserved anywhere.

    • lifecycleall ofrequired

      Current lifecycle (reported `orphaned` when the directory is gone).

      all of (1)
      variant 1
      one of (5)
      variant 1
      valuestringenum: active
      variant 2
      valuestringenum: claimed
      variant 3
      valuestringenum: landing
      variant 4
      valuestringenum: land-blocked
      variant 5
      valuestringenum: orphaned
    • pathstringrequired

      Absolute path of the worktree directory.

    • repo_keystringrequired

      Canonicalized per-repo key.

    • repo_pathstringrequired

      The repository path the worktree was created from.

    • session_idstring

      Owning session, when claimed.

    • statusany of

      Git status, when requested and computable.

      any of (2)
      variant 1
      • aheadinteger· uint64requiredmin 0

        Commits ahead of the comparison base (upstream when set, else `base_sha`).

      • behindinteger· uint64requiredmin 0

        Commits behind the comparison base.

      • cleanbooleanrequired

        True when there are no staged, unstaged, untracked, or conflicted entries.

      • conflictedinteger· uint64requiredmin 0

        Unmerged (conflicted) entry count.

      • diffstatstringrequired

        `git diff --shortstat` of committed work since `base_sha`.

      • head_shastringrequired

        Current HEAD commit.

      • in_rebasebooleanrequired

        True while a rebase is in progress in this worktree.

      • integratedboolean

        True when the branch's work is already contained in its integration target (fast-forward, merge, rebase, or squash merge). Integrated worktrees are prunable even when ahead of their base.

      • integration_reasonstring

        Which check detected the integration: `same_commit`, `ancestor`, `no_added_changes`, `trees_match`, `merge_adds_nothing`, or `patch_id_match`.

      • stagedinteger· uint64requiredmin 0

        Staged entry count.

      • unpushedinteger· uint64requiredmin 0

        Commits not merged upstream (upstream ahead count, else commits past `base_sha`).

      • unstagedinteger· uint64requiredmin 0

        Unstaged entry count.

      • untrackedinteger· uint64requiredmin 0

        Untracked entry count.

      variant 2
      valuenull
    • updated_atinteger· int64required

      Last mutation time, ms since epoch.

    • worktree_idstringrequired

      Stable id, `wt_<12hex>`.

worktree::on-config-change

function

Internal: hot-reload the worktree worker from the authoritative configuration when it changes — swaps the per-call snapshot and re-binds the prune cron on a schedule change.

request
  • idstring

    Configuration id that changed (advisory; the handler re-fetches).

response
  • okbooleanrequired

worktree::prune

function

Sweep managed worktrees: reconcile records whose directories are gone and remove clean, unclaimed, expired worktrees. Cron-safe: an empty payload uses defaults; dry_run reports without acting.

request
  • dry_runboolean

    Report what would be pruned without acting.

  • repo_pathstring

    Only sweep worktrees of this repository.

response
  • prunedstring[]required

    Worktree ids pruned (or prunable, with dry_run).

  • skippedobject[]required

    Records left alone, with reasons.

    • idstringrequired

      The skipped worktree.

    • reasonstringrequired

      Why it was skipped.

worktree::release

function

Release a session's claim. Fails with W211 when the caller does not hold the claim, unless force is set.

request
  • forceboolean

    Release even when another session holds the claim.

  • session_idstringrequired

    The releasing session (must hold the claim unless force is set).

  • worktree_idstringrequired

    The worktree to release.

response
  • releasedbooleanrequired

    True when the worktree is now unclaimed.

  • worktree_idstringrequired

    The released worktree.

worktree::remove

function

Remove a managed worktree. Refuses dirty (W220) or unmerged (W221) work unless force is set; optionally deletes the branch.

request
  • delete_branchboolean

    Also delete the worktree's branch.

  • forceboolean

    Remove even when dirty or carrying unmerged commits.

  • worktree_idstringrequired

    The worktree to remove.

response
  • branch_deletedbooleanrequired

    True when the branch was deleted too.

  • removedbooleanrequired

    True when the worktree (and its record) are gone.

worktree::status

function

Git status for one worktree: cleanliness, ahead/behind, diffstat, rebase-in-progress, lifecycle.

request
  • worktree_idstringrequired

    The worktree to inspect.

response
  • aheadinteger· uint64requiredmin 0

    Commits ahead of the comparison base (upstream when set, else `base_sha`).

  • behindinteger· uint64requiredmin 0

    Commits behind the comparison base.

  • branchstringrequired

    The branch checked out in the worktree.

  • cleanbooleanrequired

    True when there are no staged, unstaged, untracked, or conflicted entries.

  • conflictedinteger· uint64requiredmin 0

    Unmerged (conflicted) entry count.

  • dev_portinteger· uint16requiredmin 0

    Advisory dev-server port derived from the worktree id.

  • diffstatstringrequired

    `git diff --shortstat` of committed work since `base_sha`.

  • head_shastringrequired

    Current HEAD commit.

  • in_rebasebooleanrequired

    True while a rebase is in progress in this worktree.

  • integratedboolean

    True when the branch's work is already contained in its integration target (fast-forward, merge, rebase, or squash merge). Integrated worktrees are prunable even when ahead of their base.

  • integration_reasonstring

    Which check detected the integration: `same_commit`, `ancestor`, `no_added_changes`, `trees_match`, `merge_adds_nothing`, or `patch_id_match`.

  • lifecycleall ofrequired

    Current lifecycle.

    all of (1)
    variant 1
    one of (5)
    variant 1
    valuestringenum: active
    variant 2
    valuestringenum: claimed
    variant 3
    valuestringenum: landing
    variant 4
    valuestringenum: land-blocked
    variant 5
    valuestringenum: orphaned
  • stagedinteger· uint64requiredmin 0

    Staged entry count.

  • unpushedinteger· uint64requiredmin 0

    Commits not merged upstream (upstream ahead count, else commits past `base_sha`).

  • unstagedinteger· uint64requiredmin 0

    Unstaged entry count.

  • untrackedinteger· uint64requiredmin 0

    Untracked entry count.

  • worktree_idstringrequired

    The inspected worktree.

worktree::validate

function

Validate a path as a managed worktree (console picker surface). Unmanaged worktrees are reported but never adopted.

request
  • pathstringrequired

    Absolute path to validate.

response
  • managedbooleanrequired

    True when a record manages this path.

  • reasonstring

    Why the path is not valid.

  • validbooleanrequired

    True when the path is a live, managed worktree.

  • worktree_idstring

    The managing record's id, when one exists.

triggers

6

worktree::claimed

trigger

A session took ownership of a worktree.

invocation
  • repo_pathstring

    Only deliver events for this repository path.

  • session_idstring

    Only deliver events for worktrees claimed by this session.

  • worktree_idstring

    Only deliver events for this worktree.

return
valueunknown

worktree::created

trigger

A new managed worktree exists.

invocation
  • repo_pathstring

    Only deliver events for this repository path.

  • session_idstring

    Only deliver events for worktrees claimed by this session.

  • worktree_idstring

    Only deliver events for this worktree.

return
valueunknown

worktree::land-blocked

trigger

A land ended blocked (conflict, failed tests, dirty tree, moved target).

invocation
  • repo_pathstring

    Only deliver events for this repository path.

  • session_idstring

    Only deliver events for worktrees claimed by this session.

  • worktree_idstring

    Only deliver events for this worktree.

return
valueunknown

worktree::landed

trigger

A land completed; the target branch was fast-forwarded.

invocation
  • repo_pathstring

    Only deliver events for this repository path.

  • session_idstring

    Only deliver events for worktrees claimed by this session.

  • worktree_idstring

    Only deliver events for this worktree.

return
valueunknown

worktree::released

trigger

A worktree claim was released.

invocation
  • repo_pathstring

    Only deliver events for this repository path.

  • session_idstring

    Only deliver events for worktrees claimed by this session.

  • worktree_idstring

    Only deliver events for this worktree.

return
valueunknown

worktree::removed

trigger

A managed worktree was removed.

invocation
  • repo_pathstring

    Only deliver events for this repository path.

  • session_idstring

    Only deliver events for worktrees claimed by this session.

  • worktree_idstring

    Only deliver events for this worktree.

return
valueunknown