Shell helper implementations and dependency boundaries

Complete zsh helper examples for Codex launch, Prompt Builder handoff, function discovery, Fusion-first fixes, visible orchestration, and process cleanup; unavailable helper implementations are identified.

These examples show exact helper boundaries and implementation choices. They are reference code: review dependencies, permissions, and installed-tool contracts before adapting them.

Safety and completeness boundaries

  • x explicitly bypasses approvals and sandboxing; xi does not. The bypass is a high-trust, separately isolated option, not a prerequisite for loading the environment marker.
  • _codex_app_server_fork_latest and _codex_app_server_fork_compact_latest are guard stubs returning 64. A compatible app-server implementation is required before fork/compact helpers can work.
  • agent_chain, ghost-save, and aicm are lazy-loader shapes, not bundled implementations of those workflows. Check their dependencies instead of treating function presence as proof.
  • pksk and ksk are destructive process-cleanup examples. Their broad process matching and process-group signals can stop unrelated work; inspect targets and ownership before adapting them.
  • Prompt Builder handoff preserves argument boundaries only if the receiving helper also avoids reparsing the prompt as shell code.

zsh/functions/codex-launch-and-prompt-builder.zsh

# Focused Codex + Prompt Builder helper snippets.
# These are excerpts for workshop discussion, not a full private shell config.

unalias x 2>/dev/null
x() {
  codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' \
    --dangerously-bypass-approvals-and-sandbox "$@"
}

xi() {
  codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' "$@"
}

_codex_app_server_fork_latest() {
  echo "_codex_app_server_fork_latest is not bundled in this package." >&2
  echo "Install the local Codex app-server helper or replace this guard with a reviewed snippet." >&2
  return 64
}

_codex_app_server_fork_compact_latest() {
  echo "_codex_app_server_fork_compact_latest is not bundled in this package." >&2
  echo "Install the local Codex app-server compact helper or replace this guard with a reviewed snippet." >&2
  return 64
}

_codex_cmux_current_session_id() {
  local helper="$HOME/.codex/hooks/cmux-codex-session-registry.py"
  [[ -n "${CODEX_FORK_SESSION_ID:-}" ]] && {
    print -r -- "$CODEX_FORK_SESSION_ID"
    return 0
  }
  local surface="${CMUX_SURFACE_ID:-}"
  [[ -n "$surface" && -f "$helper" ]] || return 1
  python3 "$helper" --resolve-surface "$surface" --allow-screen 2>/dev/null
}

_codex_cmux_name_current_tab() {
  local name="${CODEX_THREAD_NAME:-}"
  [[ -n "${name//[[:space:]]/}" ]] || return 0
  local cmux_bin="${CMUX_BIN:-/Applications/cmux.app/Contents/Resources/bin/cmux}"
  [[ -x "$cmux_bin" ]] || return 0
  "$cmux_bin" rename-tab "$name" >/dev/null 2>&1 || true
}

_codex_prompt_builder_fork() {
  local fork_from=""
  local compact=0
  local fork_id

  while (( $# )); do
    case "$1" in
      --fork-from)
        [[ $# -ge 2 ]] || { print -u2 -- "missing value for --fork-from"; return 2; }
        fork_from="$2"
        shift 2
        ;;
      --compact)
        compact=1
        shift
        ;;
      --)
        shift
        break
        ;;
      *)
        break
        ;;
    esac
  done

  if (( compact )); then
    if [[ -n "$fork_from" && "$fork_from" != "last" ]]; then
      fork_id="$(_codex_app_server_fork_compact_latest "$fork_from")" || return 1
    else
      fork_id="$(_codex_app_server_fork_compact_latest)" || return 1
    fi
  else
    if [[ -n "$fork_from" && "$fork_from" != "last" ]]; then
      fork_id="$(_codex_app_server_fork_latest "$fork_from")" || return 1
    else
      fork_id="$(_codex_app_server_fork_latest)" || return 1
    fi
  fi

  print -r -- "$fork_id"
  _codex_cmux_name_current_tab
  x resume "$fork_id" "$@"
}

xfl() {
  local session_id
  local fork_id
  session_id="$(_codex_cmux_current_session_id)" && [[ -n "$session_id" ]] && {
    fork_id="$(_codex_app_server_fork_latest "$session_id")" || return 1
    print -r -- "$fork_id"
    _codex_cmux_name_current_tab
    x resume "$fork_id" "$@"
    return
  }
  fork_id="$(_codex_app_server_fork_latest)" || return 1
  print -r -- "$fork_id"
  _codex_cmux_name_current_tab
  x resume "$fork_id" "$@"
}

xfc() {
  local session_id
  local fork_id
  session_id="$(_codex_cmux_current_session_id 2>/dev/null)" || session_id=""
  if [[ -n "$session_id" ]]; then
    fork_id="$(_codex_app_server_fork_compact_latest "$session_id")" || return 1
  else
    fork_id="$(_codex_app_server_fork_compact_latest)" || return 1
  fi
  print -r -- "$fork_id"
  _codex_cmux_name_current_tab
  x resume "$fork_id" "$@"
}

_p_handoff_zsh() {
  local fn="${1:?Usage: _p_handoff_zsh <function> [p-args...]}"
  shift
  p \
    --handoff-command zsh \
    --handoff-arg -lc \
    --handoff-arg "source \"\$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; ${fn} \"\$@\"" \
    --handoff-arg "$fn" \
    "$@"
}

p-f() {
  local source="${CODEX_FORK_SESSION_ID:-last}"
  _p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" "$@"
}

p-c() {
  local source="${CODEX_FORK_SESSION_ID:-last}"
  _p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" --compact "$@"
}

p-cm() {
  _p_handoff_zsh _codex_prompt_builder_fork --fork-from m --compact "$@"
}

zsh/functions/fusion-fix.zsh

# Fusion-first fixer prompt for terse bug reports.

unalias fix 2>/dev/null

fix() {
  local bug="$*"
  local template_description="Run Fusion on the terse bug, implement the selected fix, and verify it."
  local system_prompt="You are an expert fixer. The user will provide an extremely terse bug report, broken behavior, failing command, or vague fix request. Treat that terse input as the full task brief and turn it into a concrete repair plan by inspecting the current repository."
  local developer_prompt="You are launched by the zsh fix helper. The user input may be only a few words. First clarify the likely defect from local repo evidence, then use the \$fusion skill before implementing: consult the local Fusion workflow against the bug, wait for terminal Fusion results and read its final artifacts, reconcile the recommendation with source evidence, then implement the fix. Keep changes scoped to the bug, preserve unrelated user work, run focused verification, and report what changed. Do not skip Fusion unless the bug is impossible to evaluate locally or Fusion itself is unavailable; if Fusion is unavailable, state that and continue with source-backed debugging."

  if [[ -n "$bug" ]]; then
    p \
      --instructions "$system_prompt" \
      --developer-instructions "$developer_prompt" \
      --template-label "Fix" \
      --template-description "$template_description" \
      "$bug"
  else
    p \
      --instructions "$system_prompt" \
      --developer-instructions "$developer_prompt" \
      --template-label "Fix" \
      --template-description "$template_description"
  fi
}

zsh/functions/orchestration-helpers.zsh

# Focused orchestration helper snippets.

muxai() {
  local session="${1:-ai}"
  local window="${2:-bots}"
  local -a cmds=(claude gemini copilot codex)

  command -v tmux >/dev/null 2>&1 || {
    echo "tmux not found"
    return 1
  }

  local win_id pane_id win_info
  if [[ -n "$TMUX" ]]; then
    win_info=$(tmux new-window -P -F "#{window_id}|#{pane_id}" -n "$window")
  elif tmux has-session -t "$session" 2>/dev/null; then
    win_info=$(tmux new-window -t "$session" -P -F "#{window_id}|#{pane_id}" -n "$window")
  else
    tmux new-session -d -s "$session" -n "$window"
    win_info="$(tmux display-message -p -t "$session:$window" "#{window_id}")|$(tmux list-panes -t "$session:$window" -F "#{pane_id}" | head -n1)"
  fi

  win_id="${win_info%%|*}"
  pane_id="${win_info##*|}"
  tmux set-window-option -t "$win_id" remain-on-exit on >/dev/null
  tmux send-keys -t "$pane_id" "${cmds[1]}" C-m

  local current="$pane_id" new_pane i
  for (( i=2; i<=${#cmds[@]}; i++ )); do
    if (( i % 2 == 0 )); then
      new_pane=$(tmux split-window -P -F "#{pane_id}" -t "$current" -h)
    else
      new_pane=$(tmux split-window -P -F "#{pane_id}" -t "$current" -v)
    fi
    tmux send-keys -t "$new_pane" "${cmds[i]}" C-m
    current="$new_pane"
  done

  tmux select-layout -t "$win_id" tiled >/dev/null
  [[ -z "$TMUX" ]] && tmux attach -t "$session"
}

agent_chain() {
  # Lazy-loader shape only. Keep the full pipeline implementation in the local
  # zsh source and copy in only the reviewed command surface needed for a demo.
  unfunction agent_chain 2>/dev/null || true
  for file in \
    "$HOME/.config/zsh/conf.d/47-ai-pipeline-agent-chain-dsl.zsh" \
    "$HOME/.config/zsh/conf.d/49-ai-pipeline-wrappers.zsh"
  do
    [[ -r "$file" ]] && source "$file"
  done
  agent_chain "$@"
}

ghost-save() {
  unfunction ghost-save 2>/dev/null || true
  for file in \
    "$HOME/.config/zsh/conf.d/38-git-ghost-checkpoint-dsl.zsh" \
    "$HOME/.config/zsh/conf.d/39-git-ghost-maintenance-dsl.zsh"
  do
    [[ -r "$file" ]] && source "$file"
  done
  ghost-save "$@"
}

aicm() {
  local file="$HOME/.config/zsh/conf.d/43-ai-commit.zsh"
  [[ -r "$file" ]] || {
    echo "Missing $file" >&2
    return 1
  }
  source "$file"
  aicm "$@"
}

zsh/functions/script-kit-process-helpers.zsh

# Process cleanup helpers mentioned in the zsh helper inventory.

pksk() {
  local pgids
  pgids=("${(@f)$(ps -axo pgid=,command= | awk '
    /\/bin\/bash \.\/dev\.sh/ || /cargo-watch watch .*script-kit-gpui/ { print $1 }
  ' | sort -u)}")

  if (( ${#pgids[@]} )); then
    local pgid
    for pgid in "${pgids[@]}"; do
      [[ -n "$pgid" ]] && kill -TERM "-$pgid" 2>/dev/null || true
    done
    sleep 0.5
    for pgid in "${pgids[@]}"; do
      [[ -n "$pgid" ]] && kill -KILL "-$pgid" 2>/dev/null || true
    done
  fi

  pkill -9 -f '[s]cript-kit-gpui' 2>/dev/null || true
}

alias ksk='pkill -9 -f "[s]cript-kit-gpui"'

zsh/functions/shell-introspection.zsh

# Zsh function discovery helpers.

funclist() {
  setopt localoptions no_xtrace no_verbose
  local show_all=false verbose=false pattern=""

  while [[ $# -gt 0 ]]; do
    case "$1" in
      -a|--all) show_all=true; shift ;;
      -v|--verbose) verbose=true; shift ;;
      *) pattern="$1"; shift ;;
    esac
  done

  local funcs
  if $show_all; then
    funcs=$(print -l ${(k)functions} | sort)
  else
    funcs=$(print -l ${(k)functions} | grep -v '^_' | sort)
  fi

  [[ -n "$pattern" ]] && funcs=$(echo "$funcs" | grep -i "$pattern")
  if ! $verbose; then
    echo "$funcs"
    return
  fi

  local func file line_num
  while IFS= read -r func; do
    [[ -z "$func" ]] && continue
    file="${functions_source[$func]}"
    if [[ -z "$file" || ! -f "$file" ]]; then
      printf '\e[1;36m%s\e[0m\n' "$func"
      continue
    fi
    line_num=$(grep -n -m1 -E "^\s*(function\s+)?${func}\s*\(" "$file" 2>/dev/null | cut -d: -f1)
    printf '\e[1;36m%s\e[0m\n' "$func"
    [[ -n "$line_num" ]] && printf '  %s:%s\n' "$file" "$line_num"
  done <<< "$funcs"
}

funcwhere() {
  [[ -z "$1" ]] && {
    echo "Usage: funcwhere <function_name>"
    return 1
  }
  local func="$1"
  [[ $(whence -w "$func" 2>/dev/null) != *function* ]] && {
    echo "'$func' is not a function" >&2
    return 1
  }
  local file="${functions_source[$func]}"
  [[ -z "$file" || ! -f "$file" ]] && {
    echo "Can't find source file for '$func'" >&2
    return 1
  }
  local line
  line=$(grep -n -m1 -E "^\s*(function\s+)?${func}\s*\(|eval\s+[\"']${func}\s*\(" "$file" | cut -d: -f1)
  [[ -z "$line" ]] && line=1
  echo "$file:$line"
}

funced() {
  [[ -z "$1" ]] && {
    echo "Usage: funced <function_name>"
    return 1
  }
  local func="$1"
  [[ $(whence -w "$func" 2>/dev/null) != *function* ]] && {
    echo "'$func' is not a function"
    return 1
  }
  local file="${functions_source[$func]}"
  [[ -z "$file" || ! -f "$file" ]] && {
    echo "Can't find source file for '$func'"
    return 1
  }
  local line
  line=$(grep -n -m1 -E "^\s*(function\s+)?${func}\s*\(|eval\s+[\"']${func}\s*\(" "$file" | cut -d: -f1)
  [[ -z "$line" ]] && line=1
  local editor_cmd="${EDITOR_CMD:-${EDITOR:-vi}}"
  local editor_name="${editor_cmd:t}"
  case "$editor_name" in
    zed) "$editor_cmd" "$file:$line" ;;
    cursor|code|code-insiders) "$editor_cmd" -g "$file:$line" ;;
    micro|vim|nvim) "$editor_cmd" "+$line" "$file" ;;
    *) "$editor_cmd" "$file:$line" ;;
  esac
}

Source references