Reusable Codex AGENTS.md worktree bootstrap instructions and scripts

README.md

Fast-Moving Repo Worktree Instructions for Codex

This gist is a reusable pattern for repositories where agents often work in multiple git worktrees and where the main branch moves quickly.

It gives you:

• An AGENTS.md snippet that tells Codex how to create and prepare worktrees.
• A worktree-bootstrap script that creates new worktrees from freshly fetched origin/main.
• Safe linking of local-only files such as node_modules and .env files without overwriting real files in the worktree.
• Drift reporting against origin/main instead of rebasing agent branches.

The important behavior is this:

1. New worktrees are created from a fresh remote main.
2. Existing worktrees are prepared before dependency installs or tests.
3. Local-only shared files are symlinked only when missing.
4. Existing branches are not rebased unless the human explicitly asks.

Files

• AGENTS.md - reusable global or repo-level instructions.
• worktree-bootstrap - generic bootstrap helper.
• install-worktree-bootstrap - optional installer that copies the helper into ~/.codex/bin.

Quick Start

Install the helper:

chmod +x install-worktree-bootstrap worktree-bootstrap
./install-worktree-bootstrap myapp

Then configure the canonical checkout for your repo:

export MYAPP_MAIN_REPO="$HOME/code/work/myapp"

Create a new worktree:

myapp-worktree-bootstrap create fix-example "$HOME/.codex/worktrees/fix-example/myapp"

Prepare an existing worktree:

myapp-worktree-bootstrap prepare "$HOME/.codex/worktrees/fix-example/myapp"

Configuration

The installed command name is <repo-slug>-worktree-bootstrap, for example myapp-worktree-bootstrap.

Configuration can be passed either through repo-specific environment variables or through generic ones:

export MYAPP_MAIN_REPO="$HOME/code/work/myapp"
export MYAPP_BASE_REMOTE="origin"
export MYAPP_BASE_BRANCH="main"
export MYAPP_SHARED_LINKS="node_modules .env.development.local"

Generic equivalents are also supported:

export WORKTREE_BOOTSTRAP_MAIN_REPO="$HOME/code/work/myapp"
export WORKTREE_BOOTSTRAP_BASE_REMOTE="origin"
export WORKTREE_BOOTSTRAP_BASE_BRANCH="main"
export WORKTREE_BOOTSTRAP_SHARED_LINKS="node_modules .env.development.local"

Repo-specific variables win over generic variables.

AGENTS.md Usage

Copy AGENTS.md into your global Codex instructions or adapt the relevant section into a repo-local AGENTS.md.

Replace:

• /path/to/main/repo
• /path/to/worktrees/*/repo-name
• repo-name-worktree-bootstrap
• REPO_NAME_MAIN_REPO

with values for your project.

Safety Notes

The helper does not overwrite existing files or symlinks. If a destination already exists, it keeps it and reports that it was kept.

The helper does not rebase branches. It fetches the base branch and reports how far the current worktree is ahead or behind.

AGENTS.md

Global Codex Instructions

Fast-Moving Repo Worktrees

For work in /path/to/main/repo or /path/to/worktrees/*/repo-name:

• Before creating a new worktree, run:

repo-name-worktree-bootstrap create <branch-name> <absolute-worktree-path>

This fetches the configured base branch, usually origin/main, and creates the branch from the freshly fetched remote ref.

• When starting in an existing worktree, run:

repo-name-worktree-bootstrap prepare <worktree-root>

before installing dependencies or running tests.

• Do not rebase existing worktree branches unless the user explicitly asks. This repo is fast-moving; fetch the base branch and report drift instead of rewriting branch history.

• The bootstrap script may link local-only shared files from the canonical checkout, such as node_modules or .env.development.local, when those paths are missing in the worktree.

• Do not overwrite real files or directories at those paths.

Example Configuration

export REPO_NAME_MAIN_REPO="/path/to/main/repo"
export REPO_NAME_SHARED_LINKS="node_modules .env.development.local"

If your installed helper is named repo-name-worktree-bootstrap, the script will look for uppercase, dash-normalized variables prefixed with REPO_NAME_.

install-worktree-bootstrap

#!/usr/bin/env bash
set -euo pipefail

usage() {
  cat <<'USAGE'
Usage:
  ./install-worktree-bootstrap <repo-slug> [install-dir]

Example:
  ./install-worktree-bootstrap myapp

Installs:
  ~/.codex/bin/myapp-worktree-bootstrap

The installed command derives repo-specific environment variables from the
repo slug. For "myapp", set MYAPP_MAIN_REPO.
USAGE
}

die() {
  echo "error: $*" >&2
  exit 1
}

repo_slug="${1:-}"
install_dir="${2:-$HOME/.codex/bin}"

[[ -n "$repo_slug" ]] || {
  usage >&2
  exit 1
}

case "$repo_slug" in
  *[!a-zA-Z0-9_.-]*)
    die "repo slug may only contain letters, numbers, dots, underscores, and dashes"
    ;;
esac

script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source_script="$script_dir/worktree-bootstrap"
target="$install_dir/$repo_slug-worktree-bootstrap"

[[ -f "$source_script" ]] || die "missing source script: $source_script"

mkdir -p "$install_dir"
cp "$source_script" "$target"
chmod +x "$target"

echo "installed $target"
echo
echo "Next, configure your canonical checkout:"
echo "  export $(printf '%s' "$repo_slug" | tr '[:lower:].-' '[:upper:]__')_MAIN_REPO=\"\$HOME/code/work/$repo_slug\""

worktree-bootstrap

#!/usr/bin/env bash
set -euo pipefail

SCRIPT_NAME="$(basename "$0")"
PREFIX="${WORKTREE_BOOTSTRAP_PREFIX:-}"

if [[ -z "$PREFIX" && "$SCRIPT_NAME" == *-worktree-bootstrap ]]; then
  PREFIX="${SCRIPT_NAME%-worktree-bootstrap}"
fi

env_prefix() {
  local raw="${PREFIX:-WORKTREE_BOOTSTRAP}"
  raw="${raw//-/_}"
  raw="${raw//./_}"
  printf '%s' "$raw" | tr '[:lower:]' '[:upper:]'
}

read_config() {
  local key="$1"
  local fallback="$2"
  local prefix
  prefix="$(env_prefix)"

  local repo_specific="${prefix}_${key}"
  local generic="WORKTREE_BOOTSTRAP_${key}"

  if [[ -n "${!repo_specific:-}" ]]; then
    printf '%s' "${!repo_specific}"
  elif [[ -n "${!generic:-}" ]]; then
    printf '%s' "${!generic}"
  else
    printf '%s' "$fallback"
  fi
}

BASE_REMOTE="$(read_config BASE_REMOTE origin)"
BASE_BRANCH="$(read_config BASE_BRANCH main)"
MAIN_REPO="$(read_config MAIN_REPO "")"
SHARED_LINKS="$(read_config SHARED_LINKS "node_modules .env.development.local")"

usage() {
  local prefix_name
  prefix_name="$(env_prefix)"

  cat <<USAGE
Usage:
  $SCRIPT_NAME prepare [worktree-path]
  $SCRIPT_NAME create <branch-name> <worktree-path>

prepare:
  Fetches $BASE_REMOTE/$BASE_BRANCH and links configured local-only files into
  an existing worktree when they are missing.

create:
  Fetches $BASE_REMOTE/$BASE_BRANCH, creates a new worktree branch from that
  fresh remote ref, then runs prepare for the new worktree.

Configuration:
USAGE

  if [[ "$prefix_name" == "WORKTREE_BOOTSTRAP" ]]; then
    cat <<USAGE
  MAIN_REPO:
    WORKTREE_BOOTSTRAP_MAIN_REPO

  Optional configuration:
    WORKTREE_BOOTSTRAP_BASE_REMOTE="$BASE_REMOTE"
    WORKTREE_BOOTSTRAP_BASE_BRANCH="$BASE_BRANCH"
    WORKTREE_BOOTSTRAP_SHARED_LINKS="$SHARED_LINKS"

USAGE
  else
    cat <<USAGE
  MAIN_REPO can be configured with either:
    ${prefix_name}_MAIN_REPO
    WORKTREE_BOOTSTRAP_MAIN_REPO

  Optional configuration:
    ${prefix_name}_BASE_REMOTE="$BASE_REMOTE"
    ${prefix_name}_BASE_BRANCH="$BASE_BRANCH"
    ${prefix_name}_SHARED_LINKS="$SHARED_LINKS"

USAGE
  fi

  cat <<USAGE
Example:
  export ${prefix_name}_MAIN_REPO="\$HOME/code/work/${PREFIX:-repo-name}"
  $SCRIPT_NAME create fix-example "\$HOME/.codex/worktrees/fix-example/${PREFIX:-repo-name}"
USAGE
}

die() {
  echo "error: $*" >&2
  exit 1
}

repo_root() {
  local path="${1:-}"

  if [[ -n "$path" ]]; then
    git -C "$path" rev-parse --show-toplevel
  else
    git rev-parse --show-toplevel
  fi
}

detect_main_repo() {
  if [[ -n "$MAIN_REPO" ]]; then
    printf '%s' "$MAIN_REPO"
    return
  fi

  repo_root ""
}

fetch_base() {
  local main_repo="$1"

  git -C "$main_repo" rev-parse --is-inside-work-tree >/dev/null ||
    die "main repo is not a git worktree: $main_repo"

  git -C "$main_repo" fetch --prune "$BASE_REMOTE" "$BASE_BRANCH"
}

link_if_missing() {
  local src="$1"
  local dst="$2"

  if [[ -e "$dst" || -L "$dst" ]]; then
    echo "kept existing $dst"
    return
  fi

  if [[ ! -e "$src" ]]; then
    echo "skipped missing source $src"
    return
  fi

  ln -s "$src" "$dst"
  echo "linked $dst -> $src"
}

prepare_worktree() {
  local requested_path="${1:-}"
  local main_repo
  local worktree_root

  main_repo="$(detect_main_repo)"
  worktree_root="$(repo_root "$requested_path")"

  fetch_base "$main_repo"
  git -C "$worktree_root" fetch --prune "$BASE_REMOTE" "$BASE_BRANCH"

  if [[ "$worktree_root" != "$main_repo" ]]; then
    local shared_path
    for shared_path in $SHARED_LINKS; do
      link_if_missing "$main_repo/$shared_path" "$worktree_root/$shared_path"
    done
  fi

  local relation
  relation="$(git -C "$worktree_root" rev-list --left-right --count "$BASE_REMOTE/$BASE_BRANCH"...HEAD 2>/dev/null || true)"
  if [[ -n "$relation" ]]; then
    local behind ahead
    read -r behind ahead <<<"$relation"
    echo "$BASE_REMOTE/$BASE_BRANCH relation: behind=$behind ahead=$ahead"
  fi
}

create_worktree() {
  local branch="${1:-}"
  local worktree_path="${2:-}"
  local main_repo

  [[ -n "$branch" ]] || die "branch name is required"
  [[ -n "$worktree_path" ]] || die "worktree path is required"

  main_repo="$(detect_main_repo)"
  fetch_base "$main_repo"

  if git -C "$main_repo" show-ref --verify --quiet "refs/heads/$branch"; then
    die "local branch already exists: $branch"
  fi

  mkdir -p "$(dirname "$worktree_path")"
  git -C "$main_repo" worktree add -b "$branch" "$worktree_path" "$BASE_REMOTE/$BASE_BRANCH"
  prepare_worktree "$worktree_path"
}

case "${1:-prepare}" in
  prepare)
    shift || true
    prepare_worktree "${1:-}"
    ;;
  create)
    shift || true
    create_worktree "${1:-}" "${2:-}"
    ;;
  -h|--help|help)
    usage
    ;;
  *)
    prepare_worktree "$1"
    ;;
esac