Feature request: first-class worktree lifecycle hooks for setup and archive workflows

What problem are you trying to solve?

Codex Desktop has built-in worktree mode, but there does not appear to be a documented, first-class worktree lifecycle hook surface that lets users reliably automate per-workspace setup and cleanup/archive behavior.

This makes it hard to use Codex Desktop with a Conductor-style workflow:

1. choose a target origin/base branch
2. create an isolated worktree/workspace for the task
3. run deterministic setup scripts before the agent starts
4. work in that isolated workspace
5. run archive/cleanup scripts when the workspace/thread is done

Today this can be approximated with external wrapper scripts or generic hooks like SessionStart/Stop, but that is indirect and fragile because those events are session-oriented rather than worktree lifecycle-oriented. They do not clearly distinguish local-project sessions from Codex-managed worktree sessions, permanent worktrees, worktree handoff, archive, or removal.

Related existing issues

This is related to, but more specific than:

• #21753, which lists WorktreeCreate and WorktreeRemove as missing in the hook parity matrix.
• #13576, which asked for root/worktree path environment variables in setup scripts.

The request here is for a documented lifecycle contract for Codex-managed worktrees, including setup and archive/remove phases, not only env vars.

Proposed hook events

Add first-class Codex worktree lifecycle hooks such as:

• WorktreeCreate / PreWorktreeCreate
• WorktreeSetup or WorktreeReady after the worktree exists but before the first agent turn starts
• WorktreeHandoff / PreHandoff / PostHandoff when moving work between local/worktree modes
• WorktreeArchive when a thread/worktree is archived
• WorktreeRemove / PreWorktreeRemove before cleanup/deletion

Exact names are flexible. The important part is that the lifecycle is explicit, documented, and not inferred from generic session hooks.

Useful payload fields

Each event should include stable fields like:

{
  "event": "WorktreeSetup",
  "threadId": "...",
  "projectRoot": "/absolute/path/to/original/checkout",
  "worktreePath": "/absolute/path/to/codex/worktree",
  "baseBranch": "main",
  "baseRef": "origin/main",
  "baseCommit": "...",
  "branchName": "bryce/my-task",
  "isCodexManagedWorktree": true,
  "isPermanentWorktree": false,
  "source": "desktop|cli|ide|automation"
}

At minimum, users need reliable equivalents of:

• original project/root checkout path
• current worktree path
• base branch/ref/commit
• Codex-created branch name or detached HEAD status
• thread/session id
• whether this is a managed disposable worktree or a permanent worktree

Desired behavior

A repo or user should be able to configure scripts like:

{
  "hooks": {
    "WorktreeSetup": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash .codex/worktree/setup.sh",
            "timeout": 300
          }
        ]
      }
    ],
    "WorktreeArchive": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash .codex/worktree/archive.sh",
            "timeout": 300
          }
        ]
      }
    ]
  }
}

Example setup tasks:

• copy .env.local or other ignored files from the root checkout
• install dependencies or restore caches
• link local-only config directories
• allocate a unique dev server port
• seed local databases
• initialize per-worktree tool state

Example archive tasks:

• capture branch/worktree metadata
• summarize or persist workspace state
• stop per-worktree services
• clean local caches
• remove temporary env files or secrets

Why generic hooks are not enough

SessionStart and Stop are useful but do not provide the right abstraction for worktree setup/archive:

• A session can start in a normal checkout, a managed worktree, a permanent worktree, a resumed thread, or a handoff state.
• A session stop is not necessarily a worktree archive/remove event.
• Worktree creation may happen before the agent session starts.
• Users need setup to complete before the first agent turn runs.
• Cleanup/archive should be tied to the worktree lifecycle, not just transcript/session lifecycle.

Why this matters

Conductor-style workspace workflows are valuable because they make parallel agent work deterministic and repeatable. Codex already has the core worktree capability; exposing a stable lifecycle hook surface would let teams adopt Codex Desktop for the same kind of polished multi-workspace workflow without wrapping the app externally or relying on fragile inference.

Thanks for considering this.