{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-shell-helper-files",
  "slug": "shell-helper-files",
  "title": "Shell helper implementations and dependency boundaries",
  "summary": "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.",
  "category": "Tools",
  "tags": [
    "zsh",
    "helpers",
    "prompt-builder"
  ],
  "sources": [
    {
      "label": "Portable Codex workflow resources",
      "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
    }
  ],
  "sourceUnits": [
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/functions/codex-launch-and-prompt-builder.zsh",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/functions/fusion-fix.zsh",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/functions/orchestration-helpers.zsh",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/functions/script-kit-process-helpers.zsh",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/functions/shell-introspection.zsh",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "tools",
  "wordCount": 1494,
  "url": "/topics/codex-shell-helper-files/",
  "markdownUrl": "/markdown/codex-shell-helper-files.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-shell-helper-files.json",
  "headings": [
    {
      "id": "safety-and-completeness-boundaries",
      "text": "Safety and completeness boundaries",
      "level": 2
    },
    {
      "id": "zsh-functions-codex-launch-and-prompt-builder-zsh",
      "text": "zsh/functions/codex-launch-and-prompt-builder.zsh",
      "level": 2
    },
    {
      "id": "zsh-functions-fusion-fix-zsh",
      "text": "zsh/functions/fusion-fix.zsh",
      "level": 2
    },
    {
      "id": "zsh-functions-orchestration-helpers-zsh",
      "text": "zsh/functions/orchestration-helpers.zsh",
      "level": 2
    },
    {
      "id": "zsh-functions-script-kit-process-helpers-zsh",
      "text": "zsh/functions/script-kit-process-helpers.zsh",
      "level": 2
    },
    {
      "id": "zsh-functions-shell-introspection-zsh",
      "text": "zsh/functions/shell-introspection.zsh",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Shell helper implementations and dependency boundaries\n\nThese examples show exact helper boundaries and implementation choices. They are reference code: review dependencies, permissions, and installed-tool contracts before adapting them.\n\n## Safety and completeness boundaries\n\n- `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.\n- `_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.\n- `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.\n- `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.\n- Prompt Builder handoff preserves argument boundaries only if the receiving helper also avoids reparsing the prompt as shell code.\n\n## zsh/functions/codex-launch-and-prompt-builder.zsh\n\n```zsh\n# Focused Codex + Prompt Builder helper snippets.\n# These are excerpts for workshop discussion, not a full private shell config.\n\nunalias x 2>/dev/null\nx() {\n  codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' \\\n    --dangerously-bypass-approvals-and-sandbox \"$@\"\n}\n\nxi() {\n  codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' \"$@\"\n}\n\n_codex_app_server_fork_latest() {\n  echo \"_codex_app_server_fork_latest is not bundled in this package.\" >&2\n  echo \"Install the local Codex app-server helper or replace this guard with a reviewed snippet.\" >&2\n  return 64\n}\n\n_codex_app_server_fork_compact_latest() {\n  echo \"_codex_app_server_fork_compact_latest is not bundled in this package.\" >&2\n  echo \"Install the local Codex app-server compact helper or replace this guard with a reviewed snippet.\" >&2\n  return 64\n}\n\n_codex_cmux_current_session_id() {\n  local helper=\"$HOME/.codex/hooks/cmux-codex-session-registry.py\"\n  [[ -n \"${CODEX_FORK_SESSION_ID:-}\" ]] && {\n    print -r -- \"$CODEX_FORK_SESSION_ID\"\n    return 0\n  }\n  local surface=\"${CMUX_SURFACE_ID:-}\"\n  [[ -n \"$surface\" && -f \"$helper\" ]] || return 1\n  python3 \"$helper\" --resolve-surface \"$surface\" --allow-screen 2>/dev/null\n}\n\n_codex_cmux_name_current_tab() {\n  local name=\"${CODEX_THREAD_NAME:-}\"\n  [[ -n \"${name//[[:space:]]/}\" ]] || return 0\n  local cmux_bin=\"${CMUX_BIN:-/Applications/cmux.app/Contents/Resources/bin/cmux}\"\n  [[ -x \"$cmux_bin\" ]] || return 0\n  \"$cmux_bin\" rename-tab \"$name\" >/dev/null 2>&1 || true\n}\n\n_codex_prompt_builder_fork() {\n  local fork_from=\"\"\n  local compact=0\n  local fork_id\n\n  while (( $# )); do\n    case \"$1\" in\n      --fork-from)\n        [[ $# -ge 2 ]] || { print -u2 -- \"missing value for --fork-from\"; return 2; }\n        fork_from=\"$2\"\n        shift 2\n        ;;\n      --compact)\n        compact=1\n        shift\n        ;;\n      --)\n        shift\n        break\n        ;;\n      *)\n        break\n        ;;\n    esac\n  done\n\n  if (( compact )); then\n    if [[ -n \"$fork_from\" && \"$fork_from\" != \"last\" ]]; then\n      fork_id=\"$(_codex_app_server_fork_compact_latest \"$fork_from\")\" || return 1\n    else\n      fork_id=\"$(_codex_app_server_fork_compact_latest)\" || return 1\n    fi\n  else\n    if [[ -n \"$fork_from\" && \"$fork_from\" != \"last\" ]]; then\n      fork_id=\"$(_codex_app_server_fork_latest \"$fork_from\")\" || return 1\n    else\n      fork_id=\"$(_codex_app_server_fork_latest)\" || return 1\n    fi\n  fi\n\n  print -r -- \"$fork_id\"\n  _codex_cmux_name_current_tab\n  x resume \"$fork_id\" \"$@\"\n}\n\nxfl() {\n  local session_id\n  local fork_id\n  session_id=\"$(_codex_cmux_current_session_id)\" && [[ -n \"$session_id\" ]] && {\n    fork_id=\"$(_codex_app_server_fork_latest \"$session_id\")\" || return 1\n    print -r -- \"$fork_id\"\n    _codex_cmux_name_current_tab\n    x resume \"$fork_id\" \"$@\"\n    return\n  }\n  fork_id=\"$(_codex_app_server_fork_latest)\" || return 1\n  print -r -- \"$fork_id\"\n  _codex_cmux_name_current_tab\n  x resume \"$fork_id\" \"$@\"\n}\n\nxfc() {\n  local session_id\n  local fork_id\n  session_id=\"$(_codex_cmux_current_session_id 2>/dev/null)\" || session_id=\"\"\n  if [[ -n \"$session_id\" ]]; then\n    fork_id=\"$(_codex_app_server_fork_compact_latest \"$session_id\")\" || return 1\n  else\n    fork_id=\"$(_codex_app_server_fork_compact_latest)\" || return 1\n  fi\n  print -r -- \"$fork_id\"\n  _codex_cmux_name_current_tab\n  x resume \"$fork_id\" \"$@\"\n}\n\n_p_handoff_zsh() {\n  local fn=\"${1:?Usage: _p_handoff_zsh <function> [p-args...]}\"\n  shift\n  p \\\n    --handoff-command zsh \\\n    --handoff-arg -lc \\\n    --handoff-arg \"source \\\"\\$HOME/.config/zsh/conf.d/40-ai.zsh\\\" >/dev/null 2>&1; ${fn} \\\"\\$@\\\"\" \\\n    --handoff-arg \"$fn\" \\\n    \"$@\"\n}\n\np-f() {\n  local source=\"${CODEX_FORK_SESSION_ID:-last}\"\n  _p_handoff_zsh _codex_prompt_builder_fork --fork-from \"$source\" \"$@\"\n}\n\np-c() {\n  local source=\"${CODEX_FORK_SESSION_ID:-last}\"\n  _p_handoff_zsh _codex_prompt_builder_fork --fork-from \"$source\" --compact \"$@\"\n}\n\np-cm() {\n  _p_handoff_zsh _codex_prompt_builder_fork --fork-from m --compact \"$@\"\n}\n```\n\n## zsh/functions/fusion-fix.zsh\n\n```zsh\n# Fusion-first fixer prompt for terse bug reports.\n\nunalias fix 2>/dev/null\n\nfix() {\n  local bug=\"$*\"\n  local template_description=\"Run Fusion on the terse bug, implement the selected fix, and verify it.\"\n  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.\"\n  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.\"\n\n  if [[ -n \"$bug\" ]]; then\n    p \\\n      --instructions \"$system_prompt\" \\\n      --developer-instructions \"$developer_prompt\" \\\n      --template-label \"Fix\" \\\n      --template-description \"$template_description\" \\\n      \"$bug\"\n  else\n    p \\\n      --instructions \"$system_prompt\" \\\n      --developer-instructions \"$developer_prompt\" \\\n      --template-label \"Fix\" \\\n      --template-description \"$template_description\"\n  fi\n}\n```\n\n## zsh/functions/orchestration-helpers.zsh\n\n```zsh\n# Focused orchestration helper snippets.\n\nmuxai() {\n  local session=\"${1:-ai}\"\n  local window=\"${2:-bots}\"\n  local -a cmds=(claude gemini copilot codex)\n\n  command -v tmux >/dev/null 2>&1 || {\n    echo \"tmux not found\"\n    return 1\n  }\n\n  local win_id pane_id win_info\n  if [[ -n \"$TMUX\" ]]; then\n    win_info=$(tmux new-window -P -F \"#{window_id}|#{pane_id}\" -n \"$window\")\n  elif tmux has-session -t \"$session\" 2>/dev/null; then\n    win_info=$(tmux new-window -t \"$session\" -P -F \"#{window_id}|#{pane_id}\" -n \"$window\")\n  else\n    tmux new-session -d -s \"$session\" -n \"$window\"\n    win_info=\"$(tmux display-message -p -t \"$session:$window\" \"#{window_id}\")|$(tmux list-panes -t \"$session:$window\" -F \"#{pane_id}\" | head -n1)\"\n  fi\n\n  win_id=\"${win_info%%|*}\"\n  pane_id=\"${win_info##*|}\"\n  tmux set-window-option -t \"$win_id\" remain-on-exit on >/dev/null\n  tmux send-keys -t \"$pane_id\" \"${cmds[1]}\" C-m\n\n  local current=\"$pane_id\" new_pane i\n  for (( i=2; i<=${#cmds[@]}; i++ )); do\n    if (( i % 2 == 0 )); then\n      new_pane=$(tmux split-window -P -F \"#{pane_id}\" -t \"$current\" -h)\n    else\n      new_pane=$(tmux split-window -P -F \"#{pane_id}\" -t \"$current\" -v)\n    fi\n    tmux send-keys -t \"$new_pane\" \"${cmds[i]}\" C-m\n    current=\"$new_pane\"\n  done\n\n  tmux select-layout -t \"$win_id\" tiled >/dev/null\n  [[ -z \"$TMUX\" ]] && tmux attach -t \"$session\"\n}\n\nagent_chain() {\n  # Lazy-loader shape only. Keep the full pipeline implementation in the local\n  # zsh source and copy in only the reviewed command surface needed for a demo.\n  unfunction agent_chain 2>/dev/null || true\n  for file in \\\n    \"$HOME/.config/zsh/conf.d/47-ai-pipeline-agent-chain-dsl.zsh\" \\\n    \"$HOME/.config/zsh/conf.d/49-ai-pipeline-wrappers.zsh\"\n  do\n    [[ -r \"$file\" ]] && source \"$file\"\n  done\n  agent_chain \"$@\"\n}\n\nghost-save() {\n  unfunction ghost-save 2>/dev/null || true\n  for file in \\\n    \"$HOME/.config/zsh/conf.d/38-git-ghost-checkpoint-dsl.zsh\" \\\n    \"$HOME/.config/zsh/conf.d/39-git-ghost-maintenance-dsl.zsh\"\n  do\n    [[ -r \"$file\" ]] && source \"$file\"\n  done\n  ghost-save \"$@\"\n}\n\naicm() {\n  local file=\"$HOME/.config/zsh/conf.d/43-ai-commit.zsh\"\n  [[ -r \"$file\" ]] || {\n    echo \"Missing $file\" >&2\n    return 1\n  }\n  source \"$file\"\n  aicm \"$@\"\n}\n```\n\n## zsh/functions/script-kit-process-helpers.zsh\n\n```zsh\n# Process cleanup helpers mentioned in the zsh helper inventory.\n\npksk() {\n  local pgids\n  pgids=(\"${(@f)$(ps -axo pgid=,command= | awk '\n    /\\/bin\\/bash \\.\\/dev\\.sh/ || /cargo-watch watch .*script-kit-gpui/ { print $1 }\n  ' | sort -u)}\")\n\n  if (( ${#pgids[@]} )); then\n    local pgid\n    for pgid in \"${pgids[@]}\"; do\n      [[ -n \"$pgid\" ]] && kill -TERM \"-$pgid\" 2>/dev/null || true\n    done\n    sleep 0.5\n    for pgid in \"${pgids[@]}\"; do\n      [[ -n \"$pgid\" ]] && kill -KILL \"-$pgid\" 2>/dev/null || true\n    done\n  fi\n\n  pkill -9 -f '[s]cript-kit-gpui' 2>/dev/null || true\n}\n\nalias ksk='pkill -9 -f \"[s]cript-kit-gpui\"'\n```\n\n## zsh/functions/shell-introspection.zsh\n\n```zsh\n# Zsh function discovery helpers.\n\nfunclist() {\n  setopt localoptions no_xtrace no_verbose\n  local show_all=false verbose=false pattern=\"\"\n\n  while [[ $# -gt 0 ]]; do\n    case \"$1\" in\n      -a|--all) show_all=true; shift ;;\n      -v|--verbose) verbose=true; shift ;;\n      *) pattern=\"$1\"; shift ;;\n    esac\n  done\n\n  local funcs\n  if $show_all; then\n    funcs=$(print -l ${(k)functions} | sort)\n  else\n    funcs=$(print -l ${(k)functions} | grep -v '^_' | sort)\n  fi\n\n  [[ -n \"$pattern\" ]] && funcs=$(echo \"$funcs\" | grep -i \"$pattern\")\n  if ! $verbose; then\n    echo \"$funcs\"\n    return\n  fi\n\n  local func file line_num\n  while IFS= read -r func; do\n    [[ -z \"$func\" ]] && continue\n    file=\"${functions_source[$func]}\"\n    if [[ -z \"$file\" || ! -f \"$file\" ]]; then\n      printf '\\e[1;36m%s\\e[0m\\n' \"$func\"\n      continue\n    fi\n    line_num=$(grep -n -m1 -E \"^\\s*(function\\s+)?${func}\\s*\\(\" \"$file\" 2>/dev/null | cut -d: -f1)\n    printf '\\e[1;36m%s\\e[0m\\n' \"$func\"\n    [[ -n \"$line_num\" ]] && printf '  %s:%s\\n' \"$file\" \"$line_num\"\n  done <<< \"$funcs\"\n}\n\nfuncwhere() {\n  [[ -z \"$1\" ]] && {\n    echo \"Usage: funcwhere <function_name>\"\n    return 1\n  }\n  local func=\"$1\"\n  [[ $(whence -w \"$func\" 2>/dev/null) != *function* ]] && {\n    echo \"'$func' is not a function\" >&2\n    return 1\n  }\n  local file=\"${functions_source[$func]}\"\n  [[ -z \"$file\" || ! -f \"$file\" ]] && {\n    echo \"Can't find source file for '$func'\" >&2\n    return 1\n  }\n  local line\n  line=$(grep -n -m1 -E \"^\\s*(function\\s+)?${func}\\s*\\(|eval\\s+[\\\"']${func}\\s*\\(\" \"$file\" | cut -d: -f1)\n  [[ -z \"$line\" ]] && line=1\n  echo \"$file:$line\"\n}\n\nfunced() {\n  [[ -z \"$1\" ]] && {\n    echo \"Usage: funced <function_name>\"\n    return 1\n  }\n  local func=\"$1\"\n  [[ $(whence -w \"$func\" 2>/dev/null) != *function* ]] && {\n    echo \"'$func' is not a function\"\n    return 1\n  }\n  local file=\"${functions_source[$func]}\"\n  [[ -z \"$file\" || ! -f \"$file\" ]] && {\n    echo \"Can't find source file for '$func'\"\n    return 1\n  }\n  local line\n  line=$(grep -n -m1 -E \"^\\s*(function\\s+)?${func}\\s*\\(|eval\\s+[\\\"']${func}\\s*\\(\" \"$file\" | cut -d: -f1)\n  [[ -z \"$line\" ]] && line=1\n  local editor_cmd=\"${EDITOR_CMD:-${EDITOR:-vi}}\"\n  local editor_name=\"${editor_cmd:t}\"\n  case \"$editor_name\" in\n    zed) \"$editor_cmd\" \"$file:$line\" ;;\n    cursor|code|code-insiders) \"$editor_cmd\" -g \"$file:$line\" ;;\n    micro|vim|nvim) \"$editor_cmd\" \"+$line\" \"$file\" ;;\n    *) \"$editor_cmd\" \"$file:$line\" ;;\n  esac\n}\n```\n\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
}
