WorkTrunk for Codex

Codex plugin bundle for wt: repo-local WorkTrunk skills, branch activity markers, and guardrails that keep Codex on wt instead of raw git worktree.

What it adds

• Synced WorkTrunk reference docs inside a Codex skill
• Codex hooks that set wt branch markers:
  • 🤖 while Codex is working
  • 💬 when Codex is waiting for the next prompt
• A Bash guard hook that blocks git worktree add/remove and blocks raw branch switches away from the default branch in primary worktrees, keeping Codex on wt for branch work
• Codex command docs for common WorkTrunk flows
• Agent handoff guidance for launching Codex, Goose, or another agent through wt switch -x, with gh-dash, gh-enhance, lazygit, and Neovim treated as optional human-facing entrypoints
• Standalone skills CLI install support via skills/worktrunk-agent-handoff/SKILL.md
• Copyable shell and TUI examples under examples/

Install

Add the marketplace:

codex plugin marketplace add adrianmross/worktrunk-codex

Or from a local checkout:

codex plugin marketplace add /mnt/data/dev/adrianmross/worktrunk-codex

Or sync the current checkout directly into Codex's local plugin cache:

./scripts/install-local.sh

Enable the plugin in ~/.codex/config.toml:

[features]
plugins = true

[plugins."worktrunk@worktrunk-codex"]
enabled = true

Install as a Standalone Skill

If you want the agent handoff guidance without installing the full Codex plugin, install the standalone skill with the open skills CLI:

npx skills add https://github.com/adrianmross/worktrunk-codex --skill worktrunk-agent-handoff

Useful variants:

# Install globally for Codex
npx skills add https://github.com/adrianmross/worktrunk-codex --skill worktrunk-agent-handoff -g -a codex

# Install globally for Goose
npx skills add https://github.com/adrianmross/worktrunk-codex --skill worktrunk-agent-handoff -g -a goose

# List skills exposed by this repo without installing
npx skills add https://github.com/adrianmross/worktrunk-codex --list

The skill source lives at skills/worktrunk-agent-handoff/SKILL.md. For skills.sh compatibility, the important pieces are a public repository, a discoverable skills/<name>/SKILL.md, and YAML frontmatter with name and description.

Examples

• examples/dev-handoff — thin helper for repo resolution and wt/agent/TUI handoff
• examples/zsh/worktrunk-codex.zsh — linked-worktree Codex profile wrapper plus wtcodex and wtreview
• examples/gh-dash/config.yml — PR row actions for wt, Codex, lazygit, and Neovim review
• examples/lazygit/config.yml — local-branch actions for wt, Codex, and Neovim review

Docs

• docs/commands.md — canonical command reference
• docs/github-tuis.md — how gh-dash, gh-enhance, lazygit, Diffview, and Octo fit around the agent flow

Requirements

• wt on PATH
• git on PATH
• jq if you use the bundled Codex commit-generation example

Notes

• This repo vendors WorkTrunk reference docs from max-sixty/worktrunk under MIT OR Apache-2.0.
• Codex does not expose Claude-style worktree lifecycle hooks, so this plugin enforces wt through a Bash guard hook plus skills and commands.

Agent Handoff

For agent-native task starts, use WorkTrunk's execute path instead of driving a TUI:

wt switch pr:123 -x codex
wt switch --create fix-login --base=@ -x codex -- "Fix the login regression"
wt switch pr:123 -x goose

The bundled skill documents this in skills/worktrunk/reference/agent-handoff.md, and the start-agent-task command prompt gives Codex a concise workflow for PR, branch, and stacked-task handoffs.

Linked Worktree Git Writes

Codex's default workspace-write sandbox keeps .git and the resolved gitdir: target read-only. In a linked git worktree, git writes land in the shared common git dir, so commands like git commit, git branch -m, and git worktree lock can fail even when the worktree itself is writable.

Use a dedicated profile for linked worktrees:

[profiles.worktree-git]
model = "oca/gpt-5-codex"
model_provider = "oca_responses"
approval_policy = "on-request"
model_reasoning_effort = "medium"
sandbox_mode = "danger-full-access"

Then launch Codex through a worktree-aware shell wrapper:

codex_is_linked_worktree() {
  command -v git >/dev/null 2>&1 || return 1
  git rev-parse --is-inside-work-tree >/dev/null 2>&1 || return 1

  local -a git_paths
  git_paths=("${(@f)$(git rev-parse --path-format=absolute --git-dir --git-common-dir 2>/dev/null)}")

  [[ ${#git_paths[@]} -ge 2 ]] || return 1
  [[ -n "${git_paths[1]}" && -n "${git_paths[2]}" ]] || return 1
  [[ "${git_paths[1]}" != "${git_paths[2]}" ]]
}

codex() {
  if codex_is_linked_worktree; then
    command codex -p worktree-git "$@"
    return $?
  fi

  command codex "$@"
}

If you do not want an automatic wrapper, the manual fallback is:

codex -p worktree-git